@emeryld/rrroutes-server 2.2.16 → 2.3.0

package/README.md

@@ -22,18 +22,20 @@ This package peers with `@emeryld/rrroutes-contract` and bundles `zod`.
 ## Quick start: HTTP routes
 
 ```ts
-import express from 'express';
-import { finalize, resource } from '@emeryld/rrroutes-contract';
-import { createRRRoute, defineControllers } from '@emeryld/rrroutes-server';
-import multer from 'multer';
-import { z } from 'zod';
+import express from 'express'
+import { finalize, resource } from '@emeryld/rrroutes-contract'
+import { createRRRoute, defineControllers } from '@emeryld/rrroutes-server'
+import multer from 'multer'
+import { z } from 'zod'
 
 // 1) Build & finalize contracts (usually elsewhere in your app)
 const leaves = resource('/api')
   .sub('profiles', (r) =>
     r
       .get({
-        outputSchema: z.array(z.object({ id: z.string().uuid(), name: z.string() })),
+        outputSchema: z.array(
+          z.object({ id: z.string().uuid(), name: z.string() }),
+        ),
         description: 'List profiles',
       })
       .routeParameter('profileId', z.string().uuid(), (p) =>
@@ -55,56 +57,73 @@ const leaves = resource('/api')
       )
       .done(),
   )
-  .done();
+  .done()
 
-const registry = finalize(leaves);
+const registry = finalize(leaves)
 
 // 2) Wire Express with ctx + derived upload middleware
-const upload = multer({ storage: multer.memoryStorage() });
-const app = express();
+const upload = multer({ storage: multer.memoryStorage() })
+const app = express()
 const server = createRRRoute(app, {
-  buildCtx: async (req) => ({ user: await loadUser(req), routesLogger: console }), // ctx lives on res.locals[CTX_SYMBOL]
+  buildCtx: async (req) => ({
+    user: await loadUser(req),
+    routesLogger: console,
+  }), // ctx lives on res.locals[CTX_SYMBOL]
   globalMiddleware: {
     before: [
       ({ ctx, next }) => {
-        if (!ctx.user) throw new Error('unauthorized');
-        next();
+        if (!ctx.user) throw new Error('unauthorized')
+        next()
       },
     ],
   },
   fromCfg: {
-    upload: (files) => (files && files.length > 0 ? [upload.fields(files)] : []),
+    upload: (files) =>
+      files && files.length > 0 ? [upload.fields(files)] : [],
   },
   validateOutput: true, // parse handler returns with outputSchema (default true)
-  debug: { request: true, handler: true, verbose: true, logger: (e) => console.debug(e) },
-});
+  debug: {
+    request: true,
+    handler: true,
+    verbose: true,
+    logger: (e) => console.debug(e),
+  },
+})
 
 // 3) Author controllers with enforced keys/types
-const controllers = defineControllers<typeof registry, { user: { id: string } }>()({
+const controllers = defineControllers<
+  typeof registry,
+  { user: { id: string } }
+>()({
   'GET /api/profiles': {
     handler: async ({ ctx }) => {
-      return fetchProfilesFor(ctx.user.id);
+      return fetchProfilesFor(ctx.user.id)
     },
   },
   'PATCH /api/profiles/:profileId': {
-    before: [({ ctx, params, next }) => (params.profileId === ctx.user.id ? next() : next(new Error('Forbidden')))],
+    before: [
+      ({ ctx, params, next }) =>
+        params.profileId === ctx.user.id
+          ? next()
+          : next(new Error('Forbidden')),
+    ],
     handler: async ({ params, body }) => {
-      return updateProfile(params.profileId, body);
+      return updateProfile(params.profileId, body)
     },
   },
   'PUT /api/profiles/:profileId/avatar': {
     handler: async ({ req, params }) => {
-      const avatar = (req.files as any)?.avatar?.[0];
-      await storeAvatar(params.profileId, avatar?.buffer);
-      return { ok: true };
+      const avatar = (req.files as any)?.avatar?.[0]
+      await storeAvatar(params.profileId, avatar?.buffer)
+      return { ok: true }
     },
   },
-});
+})
 
-server.registerControllers(registry, controllers);
-server.warnMissingControllers(registry, console); // warns in dev about unhandled leaves
+server.registerControllers(registry, controllers)
+server.warnMissingControllers(registry, console) // warns in dev about unhandled leaves
 
-app.listen(3000);
+app.listen(3000)
 ```
 
 ## Detailed usage (HTTP)
@@ -112,19 +131,26 @@ app.listen(3000);
 ### Controller maps and typing
 
 ```ts
-import { defineControllers, bindExpressRoutes } from '@emeryld/rrroutes-server';
+import { defineControllers, bindExpressRoutes } from '@emeryld/rrroutes-server'
 
 const controllers = defineControllers<typeof registry, Ctx>()({
-  'POST /v1/articles': { handler: async ({ body, ctx }) => createArticle(ctx.user.id, body) },
-});
+  'POST /v1/articles': {
+    handler: async ({ body, ctx }) => createArticle(ctx.user.id, body),
+  },
+})
 
 // register only the controllers provided (missing keys are ignored)
 bindExpressRoutes(app, registry, controllers, {
   buildCtx: () => ({ user: { id: '123' } }),
-});
+})
 
 // or enforce every key is present at compile time
-bindExpressRoutes(app, registry, controllers as { [K in keyof typeof registry.byKey]: any }, { buildCtx });
+bindExpressRoutes(
+  app,
+  registry,
+  controllers as { [K in keyof typeof registry.byKey]: any },
+  { buildCtx },
+)
 ```
 
 - `defineControllers<Registry, Ctx>()(map)` keeps literal `"METHOD /path"` keys accurate and infers params/query/body/output types per leaf.
@@ -136,24 +162,24 @@ bindExpressRoutes(app, registry, controllers as { [K in keyof typeof registry.by
 Order: `buildCtx` → `global.before` → `fromCfg` (derived) → `route.before` → handler → `route.after` → `global.after`.
 
 ```ts
-import { getCtx, CtxRequestHandler } from '@emeryld/rrroutes-server';
+import { getCtx, CtxRequestHandler } from '@emeryld/rrroutes-server'
 
 const audit: CtxRequestHandler<Ctx> = ({ ctx, req, next }) => {
-  ctx.routesLogger?.info?.('audit', { user: ctx.user?.id, path: req.path });
-  next();
-};
+  ctx.routesLogger?.info?.('audit', { user: ctx.user?.id, path: req.path })
+  next()
+}
 
 const server = createRRRoute(app, {
   buildCtx: (req, res) => ({ user: res.locals.user, routesLogger: console }),
   globalMiddleware: { before: [audit] },
-});
+})
 
 // Inside any Express middleware (even outside route.before/after), use getCtx to retrieve typed ctx:
 app.use((req, res, next) => {
-  const ctx = getCtx<Ctx>(res);
-  ctx?.routesLogger?.debug?.('in arbitrary middleware');
-  next();
-});
+  const ctx = getCtx<Ctx>(res)
+  ctx?.routesLogger?.debug?.('in arbitrary middleware')
+  next()
+})
 ```
 
 - `CtxRequestHandler` receives `{ req, res, next, ctx }` with your typed ctx.
@@ -164,17 +190,18 @@ app.use((req, res, next) => {
 Use `fromCfg.upload` to attach middleware when a leaf declares `bodyFiles`.
 
 ```ts
-import multer from 'multer';
-import { FileField } from '@emeryld/rrroutes-contract';
+import multer from 'multer'
+import { FileField } from '@emeryld/rrroutes-contract'
 
-const upload = multer({ storage: multer.memoryStorage() });
+const upload = multer({ storage: multer.memoryStorage() })
 
 const server = createRRRoute(app, {
   buildCtx,
   fromCfg: {
-    upload: (files: FileField[] | undefined) => (files?.length ? [upload.fields(files)] : []),
+    upload: (files: FileField[] | undefined) =>
+      files?.length ? [upload.fields(files)] : [],
   },
-});
+})
 ```
 
 ### Output validation and custom responders
@@ -186,7 +213,7 @@ const server = createRRRoute(app, {
 const server = createRRRoute(app, {
   buildCtx,
   send: (res, data) => res.status(201).json({ data }),
-});
+})
 ```
 
 ### Debug logging
@@ -203,7 +230,7 @@ const server = createRRRoute(app, {
     only: ['users:list'], // filter by RouteDef.debug?.debugName
     logger: (event) => console.log('[route-debug]', event),
   },
-});
+})
 ```
 
 Per-route overrides:
@@ -212,7 +239,7 @@ Per-route overrides:
 server.register(registry.byKey['GET /api/profiles'], {
   debug: { handler: true, debugName: 'profiles:list' },
   handler: async () => [],
-});
+})
 ```
 
 Context logger passthrough: if `buildCtx` provides `routesLogger`, handler debug events also flow to that logger (useful for request-scoped loggers).
@@ -228,33 +255,45 @@ Context logger passthrough: if `buildCtx` provides `routesLogger`, handler debug
 `@emeryld/rrroutes-server` also ships a typed Socket.IO wrapper that pairs with `defineSocketEvents` from the contract package.
 
 ```ts
-import { Server } from 'socket.io';
-import { defineSocketEvents } from '@emeryld/rrroutes-contract';
-import { createSocketConnections, createConnectionLoggingMiddleware } from '@emeryld/rrroutes-server';
-import { z } from 'zod';
+import { Server } from 'socket.io'
+import { defineSocketEvents } from '@emeryld/rrroutes-contract'
+import {
+  createSocketConnections,
+  createConnectionLoggingMiddleware,
+} from '@emeryld/rrroutes-server'
+import { z } from 'zod'
 
 const { config, events } = defineSocketEvents(
   {
     joinMetaMessage: z.object({ room: z.string() }),
     leaveMetaMessage: z.object({ room: z.string() }),
     pingPayload: z.object({ sentAt: z.string() }),
-    pongPayload: z.object({ sentAt: z.string(), sinceMs: z.number().optional() }),
+    pongPayload: z.object({
+      sentAt: z.string(),
+      sinceMs: z.number().optional(),
+    }),
   },
   {
-    'chat:message': { message: z.object({ roomId: z.string(), text: z.string(), userId: z.string() }) },
+    'chat:message': {
+      message: z.object({
+        roomId: z.string(),
+        text: z.string(),
+        userId: z.string(),
+      }),
+    },
   },
-);
+)
 
-const io = new Server(3000, { cors: { origin: '*', credentials: true } });
-io.use(createConnectionLoggingMiddleware({ includeHeaders: false }));
+const io = new Server(3000, { cors: { origin: '*', credentials: true } })
+io.use(createConnectionLoggingMiddleware({ includeHeaders: false }))
 
 const sockets = createSocketConnections(io, events, {
   config,
   heartbeat: { enabled: true }, // enables sys:ping/sys:pong using config schemas
   sys: {
     'sys:connect': async ({ socket, complete }) => {
-      socket.data.user = await loadUserFromHandshake(socket.handshake);
-      await complete(); // attach built-ins (ping/pong, join/leave)
+      socket.data.user = await loadUserFromHandshake(socket.handshake)
+      await complete() // attach built-ins (ping/pong, join/leave)
     },
     'sys:ping': async ({ socket, ping }) => ({
       sentAt: ping.sentAt,
@@ -268,17 +307,17 @@ const sockets = createSocketConnections(io, events, {
     verbose: true,
     logger: (e) => console.debug('[socket-debug]', e),
   },
-});
+})
 
 // Validate inbound payloads + emit envelopes
 sockets.on('chat:message', async (payload, ctx) => {
-  await saveMessage(payload, ctx.user);
+  await saveMessage(payload, ctx.user)
   // broadcast to room participants
-  sockets.emit('chat:message', payload, payload.roomId);
-});
+  sockets.emit('chat:message', payload, payload.roomId)
+})
 
 // Graceful shutdown
-process.on('SIGTERM', () => sockets.destroy());
+process.on('SIGTERM', () => sockets.destroy())
 ```
 
 - Payloads are validated on both emit and receive; invalid payloads trigger `<event>:error` with Zod issues.

package/dist/index.cjs

@@ -43,7 +43,10 @@ var serverDebugEventTypes = [
 var noopServerEmit = () => {
 };
 function createServerDebugEmitter(option) {
-  const disabled = { emit: noopServerEmit, mode: "minimal" };
+  const disabled = {
+    emit: noopServerEmit,
+    mode: "minimal"
+  };
   if (!option) return disabled;
   if (typeof option === "object") {
     const toggles = option;
@@ -66,8 +69,11 @@ function createServerDebugEmitter(option) {
 }
 var keyOf = (leaf) => `${leaf.method.toUpperCase()} ${leaf.path}`;
 var CTX_SYMBOL = Symbol.for("typedLeaves.ctx");
-var AFTER_HANDLER_NEXT_SYMBOL = Symbol.for("typedLeaves.afterHandlerNext");
+var AFTER_HANDLER_NEXT_SYMBOL = Symbol.for(
+  "typedLeaves.afterHandlerNext"
+);
 function setAfterHandlerNext(res, value) {
+  ;
   res.locals[AFTER_HANDLER_NEXT_SYMBOL] = value;
 }
 function handlerInvokedNext(res) {
@@ -110,9 +116,11 @@ function logHandlerDebugWithRoutesLogger(logger, event) {
     event
   ];
   if (event.stage === "error") {
+    ;
     (logger.error ?? logger.warn ?? logger.debug ?? logger.info ?? logger.log ?? logger.system)?.call(logger, ...payload);
     return;
   }
+  ;
   (logger.debug ?? logger.verbose ?? logger.info ?? logger.log ?? logger.system)?.call(logger, ...payload);
 }
 var defaultSend = (res, data) => {
@@ -134,7 +142,9 @@ function collectRoutesFromStack(appOrRouter) {
     const route = layer && layer.route;
     if (!route) continue;
     const paths = Array.isArray(route.path) ? route.path : [route.path];
-    const methodEntries = Object.entries(route.methods ?? {}).filter(([, enabled]) => enabled);
+    const methodEntries = Object.entries(route.methods ?? {}).filter(
+      ([, enabled]) => enabled
+    );
     for (const path of paths) {
       for (const [method] of methodEntries) {
         result.push(`${method.toUpperCase()} ${path}`);
@@ -175,11 +185,14 @@ function createRRRoute(router, config) {
     let routeDebugEmitter;
     if (defDebug) {
       const { debugName: overrideName, ...rest } = defDebug;
-      const hasOverrides = Object.values(rest).some((value) => value !== void 0);
+      const hasOverrides = Object.values(rest).some(
+        (value) => value !== void 0
+      );
       if (hasOverrides) {
-        routeDebugEmitter = createServerDebugEmitter(
-          { ...config.debug, ...rest }
-        );
+        routeDebugEmitter = createServerDebugEmitter({
+          ...config.debug,
+          ...rest
+        });
       }
       debugName = overrideName ?? debugName;
     }
@@ -193,7 +206,13 @@ function createRRRoute(router, config) {
     const ctxMw = async (req, res, next) => {
       const requestUrl = req.originalUrl ?? path;
       const startedAt = Date.now();
-      emit({ type: "buildCtx", stage: "start", method: methodUpper, path, url: requestUrl });
+      emit({
+        type: "buildCtx",
+        stage: "start",
+        method: methodUpper,
+        path,
+        url: requestUrl
+      });
       try {
         const ctx = await config.buildCtx(req, res);
         res.locals[CTX_SYMBOL] = ctx;
@@ -220,11 +239,22 @@ function createRRRoute(router, config) {
         next(err);
       }
     };
-    const before = [ctxMw, ...globalBeforeMws, ...derived, ...routeSpecific];
+    const before = [
+      ctxMw,
+      ...globalBeforeMws,
+      ...derived,
+      ...routeSpecific
+    ];
     const wrapped = async (req, res, next) => {
       const requestUrl = req.originalUrl.split("?")[0] ?? path;
       const startedAt = Date.now();
-      emit({ type: "request", stage: "start", method: methodUpper, path, url: requestUrl });
+      emit({
+        type: "request",
+        stage: "start",
+        method: methodUpper,
+        path,
+        url: requestUrl
+      });
       let params;
       let query;
       let body;
@@ -371,10 +401,13 @@ function createRRRoute(router, config) {
       const key = keyOf(leaf);
       knownLeaves.set(key, leaf);
     }
+    ;
     Object.keys(controllers).forEach((key) => {
       const leaf = registry.byKey[key];
       if (!leaf) {
-        logger?.warn?.(`No leaf found for controller key: ${key}. Not registering route.`);
+        logger?.warn?.(
+          `No leaf found for controller key: ${key}. Not registering route.`
+        );
         return;
       }
       const def = controllers[key];
@@ -399,7 +432,9 @@ function createRRRoute(router, config) {
   function warnMissing(registry, warnLogger) {
     const registeredFromStore = new Set(Array.from(registered));
     if (registeredFromStore.size === 0) {
-      collectRoutesFromStack(router).forEach((key) => registeredFromStore.add(key));
+      collectRoutesFromStack(router).forEach(
+        (key) => registeredFromStore.add(key)
+      );
     }
     for (const leaf of registry.all) {
       const key = keyOf(leaf);
@@ -543,7 +578,12 @@ function createBuiltInConnectionHandlers(opts) {
         const list = toArray(parsed.data.rooms);
         const join = async (room) => {
           await socket.join(room);
-          dbg(null, { type: "rooms", action: "join", rooms: room, socketId: socket.id });
+          dbg(null, {
+            type: "rooms",
+            action: "join",
+            rooms: room,
+            socketId: socket.id
+          });
         };
         const run = async () => {
           await getSysEvent("sys:room_join")({
@@ -557,7 +597,9 @@ function createBuiltInConnectionHandlers(opts) {
         try {
           await run();
         } catch (error) {
-          socket.emit(`${roomJoinEvent}:error`, { error: normalizeError(error) });
+          socket.emit(`${roomJoinEvent}:error`, {
+            error: normalizeError(error)
+          });
           dbg(roomJoinEvent, {
             type: "rooms",
             action: "join",
@@ -595,7 +637,12 @@ function createBuiltInConnectionHandlers(opts) {
         const list = toArray(parsed.data.rooms);
         const leave = async (room) => {
           await socket.leave(room);
-          dbg(null, { type: "rooms", action: "leave", rooms: room, socketId: socket.id });
+          dbg(null, {
+            type: "rooms",
+            action: "leave",
+            rooms: room,
+            socketId: socket.id
+          });
         };
         const run = async () => {
           await getSysEvent("sys:room_leave")({
@@ -609,7 +656,9 @@ function createBuiltInConnectionHandlers(opts) {
         try {
           await run();
         } catch (error) {
-          socket.emit(`${roomLeaveEvent}:error`, { error: normalizeError(error) });
+          socket.emit(`${roomLeaveEvent}:error`, {
+            error: normalizeError(error)
+          });
           dbg(roomJoinEvent, {
             type: "rooms",
             phase: "handler_error",
@@ -658,7 +707,12 @@ function createBuiltInConnectionHandlers(opts) {
         });
         let pongPayload;
         try {
-          pongPayload = await getSysEvent("sys:ping")({ ping: parsedPing.data, ctx, socket, helper });
+          pongPayload = await getSysEvent("sys:ping")({
+            ping: parsedPing.data,
+            ctx,
+            socket,
+            helper
+          });
         } catch (error) {
           socket.emit(`${pingEvent}:error`, { error: normalizeError(error) });
           dbg(null, {
@@ -823,7 +877,9 @@ function createSocketConnections(io, events, opts) {
         },
         metadata
       });
-      throw new Error(`Invalid payload for "${String(eventName)}": ${check.error.message}`);
+      throw new Error(
+        `Invalid payload for "${String(eventName)}": ${check.error.message}`
+      );
     }
     const envelope = {
       eventName,
@@ -884,7 +940,12 @@ function createSocketConnections(io, events, opts) {
       }
     }
     registrations.delete(eventName);
-    dbg(eventName, { type: "register", action: "unregister", event: eventName, msg: "unregistered" });
+    dbg(eventName, {
+      type: "register",
+      action: "unregister",
+      event: eventName,
+      msg: "unregistered"
+    });
   };
   const {
     builtInConnectionListener,
@@ -970,7 +1031,10 @@ function createSocketConnections(io, events, opts) {
         });
       };
       io.on("connection", connectionListener);
-      addRegistration(String(eventName), { connectionListener, socketListeners });
+      addRegistration(String(eventName), {
+        connectionListener,
+        socketListeners
+      });
       dbg(String(eventName), {
         type: "register",
         action: "register",
@@ -1116,7 +1180,9 @@ var createConnectionLoggingMiddleware = (options = {}) => {
   const logger = options.logger ?? defaultLogger;
   const includeHeaders = options.includeHeaders ?? false;
   const redactKeys = new Set(
-    (options.redactAuthKeys ?? ["authorization", "token"]).map((key) => key.toLowerCase())
+    (options.redactAuthKeys ?? ["authorization", "token"]).map(
+      (key) => key.toLowerCase()
+    )
   );
   return (socket, next) => {
     const context = buildContext(socket, includeHeaders, redactKeys);