Hono.js (DNUM-SocialGouv)

Use this skill when adding or changing backend endpoints built with Hono in this repo.

Project Structure

• Features live in apps/backend/src/features/<feature-name>/
• Files are named <feature-name>.<file-type>.ts
• Common file types: route, controller, service, schema, type, test

Routes (OpenAPI)

• Route files only declare OpenAPI metadata (responses), not params.
• Use helpers from @sirena/backend-utils/helpers.

Example:

ts
1export const getUserRoute = openApiProtectedRoute({
2  description: 'Get user by id',
3  responses: {
4    ...openApiResponse(GetUserResponseSchema),
5    ...openApi404NotFound('User not found'),
6  },
7});

Schemas

• Define request/response schemas (params, query, body, response).
• Use paginationQueryParamsSchema for search/limit/offset/order.

Example:

ts
1export const UserSchema = z.object({
2  id: z.cuid(),
3  email: z.email({ message: 'Invalid email address' }),
4  prenom: z.string(),
5  nom: z.string(),
6  uid: z.string(),
7  sub: z.string(),
8  pcData: z.record(z.string(), z.string()),
9  roleId: z.string(),
10  statutId: z.string(),
11  entiteId: z.string().nullable(),
12  createdAt: z.coerce.date(),
13  updatedAt: z.coerce.date(),
14});
15
16const columns = [
17  Prisma.UserScalarFieldEnum.email,
18  Prisma.UserScalarFieldEnum.prenom,
19  Prisma.UserScalarFieldEnum.nom,
20] as const;
21
22export const GetUsersQuerySchema = paginationQueryParamsSchema(columns).extend({
23  roleId: z
24    .string()
25    .transform((val) => val.split(',').map((id) => id.trim()))
26    .optional(),
27  statutId: z
28    .string()
29    .transform((val) => val.split(',').map((id) => id.trim()))
30    .optional(),
31});

Types

• Prefer z.infer from schemas.

Example:

ts
1export type GetUsersQuery = z.infer<typeof GetUsersQuerySchema>;

Controllers

• Build controllers from factoryWithLogs.createApp() for typed context.
• Chain middleware and routes in order.
• Use zValidator for query/body validation.
• Return c.json({ data: ... }, status).

Common Middleware

• authMiddleware (auth cookie/session)
• userStatusMiddleware (active user checks)
• roleMiddleware([ROLES...]) (RBAC guard)
• entitesMiddleware (entite context)
• pino.middleware (logging)
• sentry.middleware (error context)
• upload.middleware (multipart handling)
• logout.middleware
• changelog/* (entity change tracking)

Example:

ts
1const app = factoryWithLogs
2  .createApp()
3  .use(authMiddleware)
4  .use(userStatusMiddleware)
5  .use(roleMiddleware([ROLES.SUPER_ADMIN, ROLES.ENTITY_ADMIN]))
6  .use(entitesMiddleware)
7  .get('/:id', getUsersRoute, zValidator('query', GetUsersQuerySchema), async (c) => {
8    // ...
9    return c.json({ data: users }, 200);
10  })
11  .get('/:id', getUserRoute, async (c) => {
12    // ...
13    return c.json({ data: user }, 200);
14  });

Services

• Prisma calls live in service files.
• Keep logic small and composable.

Example:

ts
1export const getUsers = async (entiteIds: string[] | null, query: GetUsersQuery = {}) => {
2  const { offset = 0, limit, sort = 'nom', order = 'asc', roleId, statutId, search } = query;
3
4  const entiteFilter = filterByEntities(entiteIds);
5  const roleFilter = filterByRoles(roleId ?? null);
6
7  const searchConditions: Prisma.UserWhereInput[] | undefined = search?.trim()
8    ? [
9        { prenom: { contains: search, mode: 'insensitive' } },
10        { nom: { contains: search, mode: 'insensitive' } },
11        { email: { contains: search, mode: 'insensitive' } },
12      ]
13    : undefined;
14
15  const where: Prisma.UserWhereInput = {
16    ...(entiteFilter ?? {}),
17    ...(roleFilter ?? {}),
18    ...(statutId !== undefined ? { statutId: { in: statutId } } : {}),
19    ...(searchConditions ? { OR: searchConditions } : {}),
20  };
21
22  const [data, total] = await Promise.all([
23    prisma.user.findMany({
24      where,
25      skip: offset,
26      ...(typeof limit === 'number' ? { take: limit } : {}),
27      orderBy: { [sort]: order },
28      include: { role: true },
29    }),
30    prisma.user.count({ where }),
31  ]);
32
33  return { data, total };
34};

Tests

Controller Tests (Hono)

• Prefer controller tests for endpoint behavior.
• Use testClient from hono/testing.
• Build app with appWithLogs.createApp().use(pinoLogger()).route('/', Controller).onError(errorHandler).
• Use client.index.$get() or client[':id'].$get() with query/param/json.
• Keep test data minimal and focus on response status + body.
• Always cover success payload + at least one error case, with services mocked.

Example:

ts
1describe('Users endpoints: /users', () => {
2  const app = appWithLogs.createApp().use(pinoLogger()).route('/', UsersController).onError(errorHandler);
3  const client = testClient(app);
4
5  describe('GET /', () => {
6    it('returns filtered users', async () => {
7      const res = await client.index.$get({
8        query: { roleId: ROLES.NATIONAL_STEERING, statutId: 'ACTIF' },
9      });
10      // assert status + payload
11    });
12    it('returns 404 when user not found', async () => {
13      // mock service to return null, assert 404 payload
14    });
15  });
16});

Reference: apps/backend/src/features/users/users.controller.test.ts.