@emeryld/rrroutes-server 2.4.2 → 2.4.4

package/README.md

@@ -62,7 +62,6 @@ const leaves = resource('/api')
 const registry = finalize(leaves)
 
 // 2) Wire Express with ctx + derived upload middleware
-const upload = multer({ storage: multer.memoryStorage() })
 const app = express()
 const server = createRRRoute(app, {
   buildCtx: async (req) => ({
@@ -77,10 +76,8 @@ const server = createRRRoute(app, {
       },
     ],
   },
-  fromCfg: {
-    upload: (files) =>
-      files && files.length > 0 ? [upload.fields(files)] : [],
-  },
+  multerOptions: (files) =>
+    files && files.length > 0 ? { storage: multer.memoryStorage() } : undefined,
   validateOutput: true, // parse handler returns with outputSchema (default true)
   debug: {
     request: true,
@@ -153,13 +150,26 @@ bindExpressRoutes(
 )
 ```
 
+If you need access to the parsed params/query/body inside `buildCtx`, destructure them from the single argument:
+
+```ts
+const server = createRRRoute(app, {
+  buildCtx: ({ params, query, body }) => ({
+    user: lookupUser(params.id),
+    verbose: query?.verbose === 'yes',
+  }),
+})
+```
+
+> `buildCtx` now receives the `{ req, res, params, query, body }` object; the legacy `(req, res)` signature is no longer supported.
+
 - `defineControllers<Registry, Ctx>()(map)` keeps literal `"METHOD /path"` keys accurate and infers params/query/body/output types per leaf.
 - `registerControllers` accepts partial maps (missing routes are skipped); `bindAll` enforces completeness at compile time.
 - `warnMissingControllers(router, registry, logger)` inspects the Express stack and warns for any leaf without a handler.
 
 ### Middleware order and ctx usage
 
-Order: `buildCtx` → `global.before` → `fromCfg` (derived) → `route.before` → handler.
+Order: `resolve` → `ctx` → `global.before` → `route.before` → handler.
 
 ```ts
 import { getCtx, CtxRequestHandler } from '@emeryld/rrroutes-server'
@@ -174,6 +184,11 @@ const server = createRRRoute(app, {
   globalMiddleware: { before: [audit] },
 })
 
+const routeBefore = ({ params, query, body, ctx, next }) => {
+  ctx.routesLogger?.debug?.('route.before payload', { params, query, body })
+  next()
+}
+
 // Inside any Express middleware (even outside route.before), use getCtx to retrieve typed ctx:
 app.use((req, res, next) => {
   const ctx = getCtx<Ctx>(res)
@@ -183,27 +198,36 @@ app.use((req, res, next) => {
 ```
 
 - `CtxRequestHandler` receives `{ req, res, next, ctx }` with your typed ctx.
+- `route.before` handlers now receive the same parsed `params`, `query`, and `body` payload as the handler, alongside `req`, `res`, and `ctx`.
 - Need post-response hooks? Register a middleware that wires `res.on('finish', handler)` inside `route.before`/`global.before` instead of relying on a dedicated "after" stage.
 
-### Derived middleware from route cfg (uploads)
+### Upload parsing
 
-Use `fromCfg.upload` to attach middleware when a leaf declares `bodyFiles`.
+Routes that declare `bodyFiles` automatically run Multer before `ctx` using shared memory storage. Override or disable that behavior with `multerOptions`.
 
 ```ts
 import multer from 'multer'
 import { FileField } from '@emeryld/rrroutes-contract'
 
-const upload = multer({ storage: multer.memoryStorage() })
+const diskStorage = multer.diskStorage({
+  destination: 'tmp/uploads',
+  filename: (_req, file, cb) => cb(null, `${Date.now()}-${file.originalname}`),
+})
 
 const server = createRRRoute(app, {
   buildCtx,
-  fromCfg: {
-    upload: (files: FileField[] | undefined) =>
-      files?.length ? [upload.fields(files)] : [],
-  },
+  multerOptions: (files: FileField[] | undefined) =>
+    files?.length
+      ? {
+          storage: diskStorage,
+          limits: { fileSize: 5 * 1024 * 1024 },
+        }
+      : false,
 })
 ```
 
+Return `false` from `multerOptions` when you want to skip Multer for a specific route even if `bodyFiles` are declared.
+
 ### Output validation and custom responders
 
 - `validateOutput: true` parses handler return values with the leaf `outputSchema`. Set to `false` to skip.
@@ -330,7 +354,7 @@ process.on('SIGTERM', () => sockets.destroy())
 - Post-response work should hook into `res.on('finish', handler)` from a middleware in the normal pipeline if you need to observe completed responses.
 - `compilePath`/param parsing exceptions bubble to Express error handlers; wrap `buildCtx`/middleware in try/catch if you need custom error shapes.
 - When `validateOutput` is true and no `outputSchema` exists, raw handler output is passed through.
-- `fromCfg.upload` runs only when `leaf.cfg.bodyFiles` is a non-empty array.
+- `multerOptions` runs only when `leaf.cfg.bodyFiles` is a non-empty array; return `false` to disable the upload middleware for that route.
 - Socket `emit` will throw on invalid payloads; handle errors around broadcast loops.
 
 ## Scripts

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -36,6 +46,7 @@ var import_rrroutes_contract2 = require("@emeryld/rrroutes-contract");
 
 // src/routesV3.server.ts
 var import_rrroutes_contract = require("@emeryld/rrroutes-contract");
+var import_multer = __toESM(require("multer"), 1);
 var serverDebugEventTypes = [
   "register",
   "request",
@@ -94,6 +105,59 @@ var decodeJsonLikeQueryValue = (value) => {
   return value;
 };
 var CTX_SYMBOL = /* @__PURE__ */ Symbol.for("typedLeaves.ctx");
+var REQUEST_PAYLOAD_SYMBOL = /* @__PURE__ */ Symbol.for(
+  "typedLeaves.requestPayload"
+);
+function isMulterFile(value) {
+  if (!isPlainObject(value)) return false;
+  const candidate = value;
+  return typeof candidate.fieldname === "string";
+}
+function collectMulterFiles(req) {
+  const files = [];
+  const pushValue = (value) => {
+    if (value === void 0 || value === null) return;
+    if (Array.isArray(value)) {
+      value.forEach(pushValue);
+      return;
+    }
+    if (isMulterFile(value)) {
+      files.push(value);
+      return;
+    }
+    if (isPlainObject(value)) {
+      Object.values(value).forEach(pushValue);
+    }
+  };
+  pushValue(req.files);
+  pushValue(req.file);
+  return files;
+}
+function resolveBodyFilesFromRequest(req, fields) {
+  if (!fields?.length) return void 0;
+  const allowedNames = new Set(fields.map((field) => field.name));
+  const collected = collectMulterFiles(req);
+  if (collected.length === 0) return void 0;
+  const result = {};
+  for (const file of collected) {
+    if (!allowedNames.has(file.fieldname)) continue;
+    const bucket = result[file.fieldname] ?? [];
+    bucket.push(file);
+    result[file.fieldname] = bucket;
+  }
+  return Object.keys(result).length ? result : void 0;
+}
+function getRouteRequestPayload(res) {
+  const payload = res.locals[REQUEST_PAYLOAD_SYMBOL];
+  if (payload) {
+    return payload;
+  }
+  throw new Error("Request payload was not initialized before middleware");
+}
+function setRouteRequestPayload(res, payload) {
+  ;
+  res.locals[REQUEST_PAYLOAD_SYMBOL] = payload;
+}
 function getCtx(res) {
   return res.locals[CTX_SYMBOL];
 }
@@ -111,6 +175,26 @@ function adaptCtxMw(mw) {
     }
   };
 }
+function adaptRouteBeforeMw(mw) {
+  return (req, res, next) => {
+    try {
+      const result = mw({
+        req,
+        res,
+        next,
+        ctx: getCtx(res),
+        ...getRouteRequestPayload(res)
+      });
+      if (result && typeof result.then === "function") {
+        return result.catch((err) => next(err));
+      }
+      return result;
+    } catch (err) {
+      next(err);
+      return void 0;
+    }
+  };
+}
 function logHandlerDebugWithRoutesLogger(logger, event) {
   if (!logger || event.type !== "handler") return;
   const payload = [
@@ -125,6 +209,9 @@ function logHandlerDebugWithRoutesLogger(logger, event) {
   ;
   (logger.debug ?? logger.verbose ?? logger.info ?? logger.log ?? logger.system)?.call(logger, ...payload);
 }
+var defaultMulterOptions = {
+  storage: import_multer.default.memoryStorage()
+};
 var defaultSend = (res, data) => {
   res.json(data);
 };
@@ -168,12 +255,22 @@ function createRRRoute(router, config) {
     (mw) => adaptCtxMw(mw)
   );
   const registered = getRegisteredRouteStore(router);
-  const buildDerived = (leaf) => {
-    const derived = [];
-    if (config.fromCfg?.upload && Array.isArray(leaf.cfg.bodyFiles) && leaf.cfg.bodyFiles.length > 0) {
-      derived.push(...config.fromCfg.upload(leaf.cfg.bodyFiles));
-    }
-    return derived;
+  const getMulterOptions = (fields) => {
+    if (!fields || fields.length === 0) return void 0;
+    const resolved = typeof config.multerOptions === "function" ? config.multerOptions(fields) : config.multerOptions;
+    if (resolved === false) return void 0;
+    return resolved ?? defaultMulterOptions;
+  };
+  const runMulterHandler = (handler, req, res) => {
+    return new Promise((resolve, reject) => {
+      handler(req, res, (err) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        resolve();
+      });
+    });
   };
   function register(leaf, def) {
     const method = leaf.method;
@@ -201,8 +298,84 @@ function createRRRoute(router, config) {
     const emit = (event) => activeEmit(event, debugName);
     const isVerboseDebug = activeDebugMode === "complete";
     emit({ type: "register", method: methodUpper, path });
-    const routeSpecific = (def?.before ?? []).map((mw) => adaptCtxMw(mw));
-    const derived = buildDerived(leaf);
+    const routeSpecific = (def?.before ?? []).map(
+      (mw) => adaptRouteBeforeMw(mw)
+    );
+    const resolvePayloadMw = async (req, res, next) => {
+      const requestUrl = req.originalUrl ?? path;
+      const startedAt = Date.now();
+      let params;
+      let query;
+      let body;
+      let bodyFiles;
+      try {
+        if (leaf.cfg.bodyFiles && leaf.cfg.bodyFiles.length > 0) {
+          const uploadOptions = getMulterOptions(leaf.cfg.bodyFiles);
+          if (uploadOptions) {
+            const fieldDefs = leaf.cfg.bodyFiles.map(({ name, maxCount }) => ({
+              name,
+              maxCount
+            }));
+            const uploader = (0, import_multer.default)(uploadOptions).fields(fieldDefs);
+            await runMulterHandler(uploader, req, res);
+          }
+        }
+        bodyFiles = resolveBodyFilesFromRequest(req, leaf.cfg.bodyFiles);
+        params = leaf.cfg.paramsSchema ? (0, import_rrroutes_contract.lowProfileParse)(leaf.cfg.paramsSchema, req.params) : Object.keys(req.params || {}).length ? req.params : void 0;
+        const hasQueryKeys = req.query && Object.keys(req.query || {}).length > 0;
+        const parsedQueryInput = leaf.cfg.querySchema && hasQueryKeys ? decodeJsonLikeQueryValue(req.query) : req.query;
+        if (leaf.cfg.querySchema) {
+          try {
+            query = (0, import_rrroutes_contract.lowProfileParse)(
+              leaf.cfg.querySchema,
+              parsedQueryInput
+            );
+          } catch (err) {
+            const parseError = new Error(
+              `Query parsing error: ${err.message ?? String(err)}`
+            );
+            parseError.raw = JSON.stringify(req.query);
+            parseError.cause = err;
+            throw parseError;
+          }
+        } else {
+          query = hasQueryKeys ? req.query : void 0;
+        }
+        body = leaf.cfg.bodySchema ? (0, import_rrroutes_contract.lowProfileParse)(leaf.cfg.bodySchema, req.body) : req.body !== void 0 ? req.body : void 0;
+      } catch (err) {
+        const payloadError = {
+          params,
+          query,
+          body,
+          bodyFiles
+        };
+        emit(
+          decorateDebugEvent(
+            isVerboseDebug,
+            {
+              type: "request",
+              stage: "error",
+              method: methodUpper,
+              path,
+              url: requestUrl,
+              durationMs: Date.now() - startedAt,
+              error: err
+            },
+            isVerboseDebug ? payloadError : void 0
+          )
+        );
+        next(err);
+        return;
+      }
+      const requestPayload = {
+        params,
+        query,
+        body,
+        bodyFiles
+      };
+      setRouteRequestPayload(res, requestPayload);
+      next();
+    };
     const ctxMw = async (req, res, next) => {
       const requestUrl = req.originalUrl ?? path;
       const startedAt = Date.now();
@@ -214,7 +387,10 @@ function createRRRoute(router, config) {
         url: requestUrl
       });
       try {
-        const ctx = await config.buildCtx(req, res);
+        const ctx = await config.buildCtx({
+          req,
+          res
+        });
         res.locals[CTX_SYMBOL] = ctx;
         emit({
           type: "buildCtx",
@@ -239,9 +415,9 @@ function createRRRoute(router, config) {
       }
     };
     const before = [
+      resolvePayloadMw,
       ctxMw,
       ...globalBeforeMws,
-      ...derived,
       ...routeSpecific
     ];
     const wrapped = async (req, res, next) => {
@@ -254,9 +430,11 @@ function createRRRoute(router, config) {
         path,
         url: requestUrl
       });
-      let params;
-      let query;
-      let body;
+      const requestPayload = getRouteRequestPayload(res);
+      const params = requestPayload.params;
+      const query = requestPayload.query;
+      const body = requestPayload.body;
+      const bodyFiles = requestPayload.bodyFiles;
       let responsePayload;
       let hasResponsePayload = false;
       const downstreamNext = next;
@@ -274,26 +452,6 @@ function createRRRoute(router, config) {
         }
       };
       try {
-        params = leaf.cfg.paramsSchema ? (0, import_rrroutes_contract.lowProfileParse)(leaf.cfg.paramsSchema, req.params) : Object.keys(req.params || {}).length ? req.params : void 0;
-        try {
-          const parsedQueryInput = leaf.cfg.querySchema && req.query ? decodeJsonLikeQueryValue(req.query) : req.query;
-          query = leaf.cfg.querySchema ? (0, import_rrroutes_contract.lowProfileParse)(leaf.cfg.querySchema, parsedQueryInput) : Object.keys(req.query || {}).length ? req.query : void 0;
-        } catch (e) {
-          emitWithCtx({
-            type: "request",
-            stage: "error",
-            method: methodUpper,
-            path,
-            url: requestUrl,
-            error: {
-              ...e,
-              raw: JSON.stringify(req.query),
-              message: `Query parsing error: ${e.message}`
-            }
-          });
-          throw e;
-        }
-        body = leaf.cfg.bodySchema ? (0, import_rrroutes_contract.lowProfileParse)(leaf.cfg.bodySchema, req.body) : req.body !== void 0 ? req.body : void 0;
         const handlerStartedAt = Date.now();
         emitWithCtx(
           {
@@ -302,7 +460,7 @@ function createRRRoute(router, config) {
             method: methodUpper,
             path
           },
-          isVerboseDebug ? { params, query, body } : void 0
+          isVerboseDebug ? { params, query, body, bodyFiles } : void 0
         );
         let result;
         try {
@@ -313,7 +471,8 @@ function createRRRoute(router, config) {
             ctx,
             params,
             query,
-            body
+            body,
+            bodyFiles
           });
           emitWithCtx(
             {
@@ -327,6 +486,7 @@ function createRRRoute(router, config) {
               params,
               query,
               body,
+              bodyFiles,
               ...result !== void 0 ? { output: result } : {}
             } : void 0
           );
@@ -340,7 +500,7 @@ function createRRRoute(router, config) {
               durationMs: Date.now() - handlerStartedAt,
               error: e
             },
-            isVerboseDebug ? { params, query, body } : void 0
+            isVerboseDebug ? { params, query, body, bodyFiles } : void 0
           );
           throw e;
         }
@@ -361,6 +521,7 @@ function createRRRoute(router, config) {
             params,
             query,
             body,
+            bodyFiles,
             ...hasResponsePayload ? { output: responsePayload } : {}
           } : void 0
         );
@@ -375,7 +536,7 @@ function createRRRoute(router, config) {
             durationMs: Date.now() - startedAt,
             error: err
           },
-          isVerboseDebug ? { params, query, body } : void 0
+          isVerboseDebug ? { params, query, body, bodyFiles } : void 0
         );
         next(err);
       }
@@ -502,8 +663,12 @@ function createBuiltInConnectionHandlers(opts) {
   const pingEvent = "sys:ping";
   const pongEvent = "sys:pong";
   const heartbeatEnabled = heartbeat?.enabled !== false;
-  const joinPayloadSchema = buildRoomPayloadSchema(config.joinMetaMessage);
-  const leavePayloadSchema = buildRoomPayloadSchema(config.leaveMetaMessage);
+  const joinPayloadSchema = buildRoomPayloadSchema(
+    config.joinMetaMessage
+  );
+  const leavePayloadSchema = buildRoomPayloadSchema(
+    config.leaveMetaMessage
+  );
   const pingPayloadSchema = config.pingPayload;
   const pongPayloadSchema = config.pongPayload;
   const sysEvents = sys;