@emeryld/rrroutes-server 2.6.1 → 2.6.2

package/README.md

@@ -1,7 +1,7 @@
 <!--
 Summary:
 - Added full quick start for binding finalized contracts to Express with typed controllers, ctx builders, derived upload middleware, and output validation.
-- Documented debug options, per-route overrides, partial/complete registration helpers, missing-controller warnings, and socket server helpers (typed events, heartbeat, room hooks).
+- Documented debug options, per-route overrides, partial/complete registration helpers, batch endpoint registration (`batchLeaf`), missing-controller warnings, and socket server helpers (typed events, heartbeat, room hooks).
 - Missing: cluster/multi-process Socket.IO deployment notes and an end-to-end auth example (ctx + room allow/deny) to add later.
 -->
 
@@ -167,6 +167,49 @@ const server = createRRRoute(app, {
 - `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.
 
+### Batch endpoint helper (`batchLeaf`)
+
+Use `batchLeaf` to register one endpoint that dispatches multiple already-registered controllers by encoded route keys.
+
+```ts
+import { batchLeaf } from '@emeryld/rrroutes-server'
+
+const server = createRRRoute(app, { buildCtx })
+server.registerControllers(registry, controllers)
+
+// Defaults to POST. You can override with { method: 'put' } etc.
+batchLeaf(server, '/v1/batch', registry)
+```
+
+Client request body shape:
+
+```ts
+{
+  [encodeURIComponent('GET /v1/users/:userId')]: {
+    params: { userId: 'u_1' },
+  },
+  [encodeURIComponent('PATCH /v1/users/:userId')]: {
+    params: { userId: 'u_1' },
+    body: { name: 'Emery' },
+  },
+}
+```
+
+Response shape (same encoded keys):
+
+```ts
+{
+  [encodeURIComponent('GET /v1/users/:userId')]: { out: { ... }, meta: ... },
+  [encodeURIComponent('PATCH /v1/users/:userId')]: { out: { ... }, meta: ... },
+}
+```
+
+Notes:
+
+- Register controllers before calling `batchLeaf(...)`; unknown keys fail at runtime.
+- Dispatch uses `server.invoke(...)` for each entry, so each sub-call runs per-leaf parsing, `buildCtx`, `route.before`, handler execution, and output validation.
+- Batch dispatch does not replay the full global middleware chain of the original route registration (`sanitizer`, `preCtx`, `postCtx`, Multer).
+
 ### Middleware order and ctx usage
 
 Order: `sanitizer` → `preCtx` → `resolve` → `ctx` → `postCtx` → `route.before` → handler.

package/dist/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CTX_SYMBOL: () => CTX_SYMBOL,
+  batchLeaf: () => batchLeaf,
   bindAll: () => bindAll,
   bindExpressRoutes: () => bindExpressRoutes,
   buildLowProfileLeaf: () => import_rrroutes_contract.buildLowProfileLeaf,
@@ -383,6 +384,44 @@ function adaptRouteBeforeMw(mw) {
     }
   };
 }
+function runRouteBeforeHandler(mw, args) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const next = (err) => {
+      if (settled) return;
+      settled = true;
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve();
+    };
+    try {
+      const result = mw({ ...args, next });
+      if (result && typeof result.then === "function") {
+        ;
+        result.then(() => {
+          if (settled) return;
+          settled = true;
+          resolve();
+        }).catch((err) => {
+          if (settled) return;
+          settled = true;
+          reject(err);
+        });
+        return;
+      }
+      if (!settled) {
+        settled = true;
+        resolve();
+      }
+    } catch (err) {
+      if (settled) return;
+      settled = true;
+      reject(err);
+    }
+  });
+}
 function logHandlerDebugWithRoutesLogger(logger, event) {
   if (!logger || event.type !== "handler") return;
   const payload = [
@@ -435,6 +474,7 @@ function createRRRoute(router, config) {
   const send = config.send ?? defaultSend;
   const { emit: defaultEmitDebug, mode: defaultDebugMode } = createServerDebugEmitter(config.debug);
   const knownLeaves = /* @__PURE__ */ new Map();
+  const registeredDefs = /* @__PURE__ */ new Map();
   const decorateDebugEvent = (isVerbose, event, details) => {
     if (!isVerbose || !details) return event;
     return { ...event, ...details };
@@ -736,6 +776,71 @@ function createRRRoute(router, config) {
     };
     router[method](path, ...before, wrapped);
     registered.add(key);
+    registeredDefs.set(key, {
+      leaf,
+      def
+    });
+  }
+  async function invoke(key, args) {
+    const registration = registeredDefs.get(key);
+    if (!registration) {
+      throw new Error(`No controller registered for route: ${key}`);
+    }
+    const { leaf, def } = registration;
+    const req = args.req;
+    const res = args.res;
+    const next = args.next ?? (() => void 0);
+    const parsedParams = leaf.cfg.paramsSchema ? (0, import_rrroutes_contract.lowProfileParse)(leaf.cfg.paramsSchema, args.params) : args.params;
+    const parsedQueryInput = leaf.cfg.querySchema ? decodeJsonLikeQueryValue(args.query) : args.query;
+    let parsedQuery = parsedQueryInput;
+    if (leaf.cfg.querySchema) {
+      try {
+        parsedQuery = (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(args.query);
+        parseError.cause = err;
+        throw parseError;
+      }
+    }
+    const parsedBody = leaf.cfg.bodySchema ? (0, import_rrroutes_contract.lowProfileParse)(leaf.cfg.bodySchema, args.body) : args.body;
+    const payload = {
+      params: parsedParams,
+      query: parsedQuery,
+      body: parsedBody,
+      bodyFiles: args.bodyFiles
+    };
+    setRouteRequestPayload(res, payload);
+    const ctx = args.ctx ?? await config.buildCtx({
+      req,
+      res
+    });
+    res.locals[CTX_SYMBOL] = ctx;
+    for (const before of def.before ?? []) {
+      await runRouteBeforeHandler(before, {
+        req,
+        res,
+        ctx,
+        ...payload
+      });
+    }
+    const result = await def.handler({
+      req,
+      res,
+      next,
+      ctx,
+      params: payload.params,
+      query: payload.query,
+      body: payload.body,
+      bodyFiles: payload.bodyFiles
+    });
+    const output = validateOutput && leaf.cfg.outputSchema ? (0, import_rrroutes_contract.lowProfileParse)(leaf.cfg.outputSchema, result) : result;
+    return output;
   }
   function registerControllers(registry, controllers, all) {
     for (const leaf of registry.all) {
@@ -780,6 +885,7 @@ function createRRRoute(router, config) {
     register,
     registerControllers,
     warnMissingControllers: warnMissing,
+    invoke,
     getRegisteredKeys: () => Array.from(registered)
   };
 }
@@ -793,6 +899,51 @@ function bindAll(router, registry, controllers, config) {
   server.registerControllers(registry, controllers);
   return router;
 }
+function batchLeaf(server, path, registry, options) {
+  const method = String(options?.method ?? "post").toLowerCase();
+  const allowedMethods = ["get", "post", "put", "patch", "delete"];
+  if (!allowedMethods.includes(method)) {
+    throw new Error(
+      `Invalid batch method "${String(options?.method)}". Expected one of: ${allowedMethods.join(", ")}.`
+    );
+  }
+  ;
+  server.router[method](
+    path,
+    async (req, res, next) => {
+      try {
+        const body = req.body;
+        if (!isPlainObject2(body)) {
+          throw new Error(
+            "Batch request body must be a plain object keyed by encoded route identifiers."
+          );
+        }
+        const output = {};
+        for (const [encodedKey, value] of Object.entries(body)) {
+          const decodedKey = decodeURIComponent(encodedKey);
+          const leaf = registry.byKey[decodedKey];
+          if (!leaf) {
+            throw new Error(`Unknown batch route key: ${decodedKey}`);
+          }
+          const payload = isPlainObject2(value) ? value : {};
+          output[encodedKey] = await server.invoke(decodedKey, {
+            req,
+            res,
+            next,
+            params: payload.params,
+            query: payload.query,
+            body: payload.body,
+            bodyFiles: payload.bodyFiles
+          });
+        }
+        res.json(output);
+      } catch (err) {
+        next(err);
+      }
+    }
+  );
+  return server.router;
+}
 var defineControllers = () => (m) => m;
 function warnMissingControllers(router, registry, logger) {
   const registeredStore = router[REGISTERED_ROUTES_SYMBOL];
@@ -1621,6 +1772,7 @@ var createConnectionLoggingMiddleware = (options = {}) => {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CTX_SYMBOL,
+  batchLeaf,
   bindAll,
   bindExpressRoutes,
   buildLowProfileLeaf,