@emeryld/rrroutes-server 1.1.0

package/README.md

@@ -0,0 +1,52 @@
+# @emeryld/rrroutes-server
+
+Express bindings for RRRoutes contracts. This package maps finalized leaves to an Express router, validating params/query/body/output with Zod, wiring ctx-aware middleware, and warning about missing controllers.
+
+## Installation
+
+```sh
+pnpm add @emeryld/rrroutes-server express
+# or
+npm install @emeryld/rrroutes-server express
+```
+
+The server package depends on `@emeryld/rrroutes-contract` and `zod` internally.
+
+## Usage
+
+```ts
+import express from 'express';
+import { createRouteServer } from '@emeryld/rrroutes-server';
+import { registry } from '../routes';
+import { controllers } from './controllers';
+
+const router = express.Router();
+
+const server = createRouteServer(router, {
+  baseUrl: '/api',
+  buildCtx: async (req) => ({ user: await loadUser(req) }),
+  fromCfg: {
+    auth: (leaf) => (req, res, next) => ensureAuth(leaf, req, res, next),
+  },
+});
+
+server.registerControllers(registry, controllers);
+server.warnMissingControllers(registry, console);
+```
+
+## Scripts
+
+```sh
+pnpm install
+pnpm --filter @emeryld/rrroutes-server build
+pnpm --filter @emeryld/rrroutes-server test
+```
+
+## Publishing
+
+```sh
+cd packages/server
+npm publish --access public
+```
+
+Double-check `packages/server/package.json` for the version bump and ensure the bundled `dist/` output is up to date before publishing.

package/dist/index.cjs

@@ -0,0 +1,228 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CTX_SYMBOL: () => CTX_SYMBOL,
+  asLeafAuth: () => asLeafAuth,
+  bindAll: () => bindAll,
+  bindExpressRoutes: () => bindExpressRoutes,
+  createRouteServer: () => createRouteServer,
+  defineControllers: () => defineControllers,
+  getCtx: () => getCtx,
+  keyOf: () => keyOf,
+  warnMissingControllers: () => warnMissingControllers
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/routesV3.server.ts
+var keyOf = (leaf) => `${leaf.method.toUpperCase()} ${leaf.path}`;
+var CTX_SYMBOL = Symbol.for("typedLeaves.ctx");
+function getCtx(res) {
+  return res.locals[CTX_SYMBOL];
+}
+function adaptCtxMw(mw) {
+  return (req, res, next) => mw({ req, res, next, ctx: getCtx(res) });
+}
+var defaultSend = (res, data) => {
+  res.json(data);
+};
+function resolveAuth(auth, leaf) {
+  if (!auth) return void 0;
+  return auth.length === 1 ? auth(leaf) : auth;
+}
+var REGISTERED_ROUTES_SYMBOL = Symbol.for("routesV3.registeredRoutes");
+function getRegisteredRouteStore(router) {
+  const existing = router[REGISTERED_ROUTES_SYMBOL];
+  if (existing) return existing;
+  const store = /* @__PURE__ */ new Set();
+  router[REGISTERED_ROUTES_SYMBOL] = store;
+  return store;
+}
+function collectRoutesFromStack(appOrRouter) {
+  const result = [];
+  const stack = appOrRouter.stack ?? (appOrRouter._router ? appOrRouter._router.stack : void 0) ?? [];
+  if (!Array.isArray(stack)) return result;
+  for (const layer of stack) {
+    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);
+    for (const path of paths) {
+      for (const [method] of methodEntries) {
+        result.push(`${method.toUpperCase()} ${path}`);
+      }
+    }
+  }
+  return result;
+}
+function createRouteServer(router, config) {
+  const validateOutput = config?.validateOutput ?? true;
+  const send = config?.send ?? defaultSend;
+  const logger = config?.logger;
+  const ctxMw = config?.buildCtx ? async (req, res, next) => {
+    try {
+      const ctx = await config.buildCtx(req, res);
+      res.locals[CTX_SYMBOL] = ctx;
+      next();
+    } catch (err) {
+      logger?.error?.("buildCtx error", err);
+      next(err);
+    }
+  } : void 0;
+  const globalMws = (config?.global ?? []).map((mw) => adaptCtxMw(mw));
+  const registered = getRegisteredRouteStore(router);
+  const buildDerived = (leaf) => {
+    const derived = [];
+    const decision = config?.fromCfg?.when?.(leaf.cfg, leaf) ?? {};
+    const needsAuth = typeof decision.auth === "boolean" ? decision.auth : !!leaf.cfg.authenticated;
+    if (needsAuth && config?.fromCfg?.auth) {
+      const authMw = resolveAuth(config.fromCfg.auth, leaf);
+      if (authMw) derived.push(authMw);
+    }
+    if (config?.fromCfg?.upload && Array.isArray(leaf.cfg.bodyFiles) && leaf.cfg.bodyFiles.length > 0) {
+      derived.push(...config.fromCfg.upload(leaf.cfg.bodyFiles, leaf));
+    }
+    return derived;
+  };
+  function register(leaf, def) {
+    const method = leaf.method;
+    const path = leaf.path;
+    const key = keyOf(leaf);
+    const routeSpecific = (def?.use ?? []).map((mw) => adaptCtxMw(mw));
+    const derived = buildDerived(leaf);
+    const before = [
+      ...ctxMw ? [ctxMw] : [],
+      ...globalMws,
+      ...derived,
+      ...routeSpecific
+    ];
+    const wrapped = async (req, res, next) => {
+      try {
+        logger?.info?.(`${method.toUpperCase()}@${path} (${req.originalUrl})`);
+        const ctx = res.locals[CTX_SYMBOL];
+        const params = leaf.cfg.paramsSchema ? leaf.cfg.paramsSchema.parse(req.params) : Object.keys(req.params || {}).length ? req.params : void 0;
+        let query;
+        try {
+          query = leaf.cfg.querySchema ? leaf.cfg.querySchema.parse(req.query) : Object.keys(req.query || {}).length ? req.query : void 0;
+        } catch (e) {
+          logger?.error?.("Query parsing error", {
+            path,
+            method,
+            error: e,
+            raw: JSON.stringify(req.query)
+          });
+          throw e;
+        }
+        const body = leaf.cfg.bodySchema ? leaf.cfg.bodySchema.parse(req.body) : req.body !== void 0 ? req.body : void 0;
+        logger?.verbose?.(`${method.toUpperCase()}@${path} (${req.originalUrl})`, {
+          params,
+          query,
+          body
+        });
+        let result;
+        try {
+          result = await def.handler({ req, res, next, ctx, params, query, body });
+        } catch (e) {
+          logger?.error?.("Handler error", e);
+          throw e;
+        }
+        if (!res.headersSent && result !== void 0) {
+          const out = validateOutput && leaf.cfg.outputSchema ? leaf.cfg.outputSchema.parse(result) : result;
+          logger?.verbose?.(`${method.toUpperCase()}@${path} result`, out);
+          send(res, out);
+        }
+      } catch (err) {
+        logger?.error?.("Route error", err);
+        next(err);
+      }
+    };
+    const after = (def?.after ?? []).map((mw) => adaptCtxMw(mw));
+    router[method](path, ...before, wrapped, ...after);
+    registered.add(key);
+  }
+  function registerControllers(registry, controllers) {
+    Object.keys(controllers).forEach((key) => {
+      const leaf = registry.byKey[key];
+      if (!leaf) {
+        logger?.warn?.(`No leaf found for controller key: ${key}. Not registering route.`);
+        return;
+      }
+      const def = controllers[key];
+      if (!def) return;
+      register(leaf, def);
+    });
+  }
+  function warnMissing(registry, warnLogger) {
+    const registeredFromStore = new Set(Array.from(registered));
+    if (registeredFromStore.size === 0) {
+      collectRoutesFromStack(router).forEach((key) => registeredFromStore.add(key));
+    }
+    for (const leaf of registry.all) {
+      const key = keyOf(leaf);
+      if (!registeredFromStore.has(key)) {
+        warnLogger.warn(`No controller registered for route: ${key}`);
+      }
+    }
+  }
+  return {
+    router,
+    register,
+    registerControllers,
+    warnMissingControllers: warnMissing,
+    getRegisteredKeys: () => Array.from(registered)
+  };
+}
+function bindExpressRoutes(router, registry, controllers, config) {
+  const server = createRouteServer(router, config);
+  server.registerControllers(registry, controllers);
+  return router;
+}
+function bindAll(router, registry, controllers, config) {
+  const server = createRouteServer(router, config);
+  server.registerControllers(registry, controllers);
+  return router;
+}
+var defineControllers = () => (m) => m;
+var asLeafAuth = (mw) => (_leaf) => mw;
+function warnMissingControllers(router, registry, logger) {
+  const registeredStore = router[REGISTERED_ROUTES_SYMBOL];
+  const initial = registeredStore ? Array.from(registeredStore) : collectRoutesFromStack(router);
+  const registeredKeys = new Set(initial);
+  for (const leaf of registry.all) {
+    const k = keyOf(leaf);
+    if (!registeredKeys.has(k)) {
+      logger.warn(`No controller registered for route: ${k}`);
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CTX_SYMBOL,
+  asLeafAuth,
+  bindAll,
+  bindExpressRoutes,
+  createRouteServer,
+  defineControllers,
+  getCtx,
+  keyOf,
+  warnMissingControllers
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/routesV3.server.ts"],"sourcesContent":["export * from './routesV3.server';\n","/**\n * routesV3.server.ts\n * -----------------------------------------------------------------------------\n * Bind an Express router/app to a `finalize(...)` registry of AnyLeafs.\n * - Fully typed handlers (params/query/body/output)\n * - Zod parsing + optional output validation\n * - buildCtx runs as a middleware *first*, before all other middlewares\n * - Global, per-route, and cfg-derived middlewares (auth, uploads)\n * - Helper to warn about unimplemented routes\n * - DX helpers to use `ctx` in any middleware with proper types\n */\n\nimport type * as express from 'express';\nimport type { RequestHandler, Router } from 'express';\nimport type { ZodType } from 'zod';\nimport {\n  FileField,\n  HttpMethod,\n  MethodCfg,\n} from '@emeryld/rrroutes-contract';\nimport type {\n  AnyLeaf,\n  InferBody,\n  InferOutput,\n  InferParams,\n  InferQuery,\n} from '@emeryld/rrroutes-contract';\n\nexport type { AnyLeaf } from '@emeryld/rrroutes-contract';\n\n/** Shape expected from optional logger implementations. */\nexport type LoggerLike = {\n  info?: (...args: any[]) => void;\n  warn?: (...args: any[]) => void;\n  error?: (...args: any[]) => void;\n  debug?: (...args: any[]) => void;\n  verbose?: (...args: any[]) => void;\n  system?: (...args: any[]) => void;\n  log?: (...args: any[]) => void;\n};\n\n// ──────────────────────────────────────────────────────────────────────────────\n// Keys + leaf helpers (derive keys from byKey to avoid template-literal pitfalls)\n// ──────────────────────────────────────────────────────────────────────────────\n\n/** Keys like \"GET /v1/foo\" that *actually* exist in the registry */\nexport type KeysOfRegistry<R extends { byKey: Record<string, AnyLeaf> }> = keyof R['byKey'] &\n  string;\n\ntype MethodFromKey<K extends string> = K extends `${infer M} ${string}` ? Lowercase<M> : never;\ntype PathFromKey<K extends string> = K extends `${string} ${infer P}` ? P : never;\n\n/** Given a registry and a key, pick the exact leaf for that method+path */\nexport type LeafFromKey<R extends { all: readonly AnyLeaf[] }, K extends string> = Extract<\n  R['all'][number],\n  { method: MethodFromKey<K> & HttpMethod; path: PathFromKey<K> }\n>;\n\n/** Optional-ify types if your core returns `never` when a schema isn't defined */\ntype Maybe<T> = [T] extends [never] ? undefined : T;\n\n/** Typed params argument exposed to handlers. */\nexport type ArgParams<L extends AnyLeaf> = Maybe<InferParams<L>>;\n/** Typed query argument exposed to handlers. */\nexport type ArgQuery<L extends AnyLeaf> = Maybe<InferQuery<L>>;\n/** Typed body argument exposed to handlers. */\nexport type ArgBody<L extends AnyLeaf> = Maybe<InferBody<L>>;\n\n/**\n * Convenience to compute a `\"METHOD /path\"` key from a leaf.\n * @param leaf Leaf describing the route.\n * @returns Uppercase method + path key.\n */\nexport const keyOf = (leaf: AnyLeaf) => `${leaf.method.toUpperCase()} ${leaf.path}` as const;\n\n// ──────────────────────────────────────────────────────────────────────────────\n// Context typing & DX helpers (so ctx is usable in *any* middleware)\n// ──────────────────────────────────────────────────────────────────────────────\n\n/**\n * Unique symbol used to stash ctx on res.locals.\n * (Symbols are safer than string keys against collisions.)\n */\nexport const CTX_SYMBOL: unique symbol = Symbol.for('typedLeaves.ctx');\n\n/** Response type that *has* a ctx on locals for DX in middlewares */\nexport type ResponseWithCtx<Ctx> =\n  // Replace locals with an intersection that guarantees CTX_SYMBOL exists\n  Omit<express.Response, 'locals'> & {\n    locals: express.Response['locals'] & { [CTX_SYMBOL]: Ctx };\n  };\n\n/** A middleware signature that can *use* ctx via `res.locals[CTX_SYMBOL]` */\nexport type CtxRequestHandler<Ctx> = (args: {\n  req: express.Request;\n  res: express.Response;\n  next: express.NextFunction;\n  ctx: Ctx;\n}) => any;\n\n/**\n * Safely read ctx from any Response.\n * @param res Express response whose locals contain the ctx symbol.\n * @returns Strongly typed context object.\n */\nexport function getCtx<Ctx = unknown>(res: express.Response): Ctx {\n  return (res.locals as any)[CTX_SYMBOL] as Ctx;\n}\n\n/**\n * Wrap a ctx-typed middleware to a plain RequestHandler (for arrays, etc.).\n * @param mw Middleware that expects a typed response with ctx available.\n * @returns Standard Express request handler.\n */\nfunction adaptCtxMw<Ctx>(mw: CtxRequestHandler<Ctx>): RequestHandler {\n  return (req, res, next) => mw({ req, res, next, ctx: getCtx<Ctx>(res) });\n}\n\n// ──────────────────────────────────────────────────────────────────────────────\n// Controller types — object form only (simpler, clearer typings)\n// ──────────────────────────────────────────────────────────────────────────────\n\n/** Typed route handler for a specific leaf */\nexport type Handler<L extends AnyLeaf, Ctx = unknown> = (args: {\n  req: express.Request;\n  res: express.Response;\n  next: express.NextFunction;\n  ctx: Ctx;\n  params: ArgParams<L>;\n  query: ArgQuery<L>;\n  body: ArgBody<L>;\n}) => Promise<InferOutput<L>> | InferOutput<L>;\n\n/** Route definition for one key */\nexport type RouteDef<L extends AnyLeaf, Ctx = unknown> = {\n  /** Middlewares before the handler (run after buildCtx/global/derived) */\n  use?: Array<CtxRequestHandler<Ctx>>;\n  /** Middlewares after the handler *if* it calls next() */\n  after?: Array<CtxRequestHandler<Ctx>>;\n  /** Your business logic */\n  handler: Handler<L, Ctx>;\n};\n\n/** Map of registry keys -> route defs */\nexport type ControllerMap<\n  R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> },\n  Ctx = unknown,\n> = {\n  [P in KeysOfRegistry<R>]: RouteDef<LeafFromKey<R, P>, Ctx>;\n};\n\nexport type PartialControllerMap<\n  R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> },\n  Ctx = unknown,\n> = Partial<ControllerMap<R, Ctx>>;\n\n// ──────────────────────────────────────────────────────────────────────────────\n/** Options + derivation helpers */\n// ──────────────────────────────────────────────────────────────────────────────\n\nexport type RouteServerConfig<Ctx = unknown> = {\n  /**\n   * Build a request-scoped context. We wrap this in a middleware that runs\n   * *first* (before global/derived/route middlewares), and stash it on\n   * `res.locals[CTX_SYMBOL]` so *all* later middlewares can use it.\n   */\n  buildCtx?: (req: express.Request, res: express.Response) => Ctx | Promise<Ctx>;\n\n  /**\n   * Global middlewares for every bound route (run *after* buildCtx).\n   * You can write them as ctx-aware middlewares for great DX.\n   */\n  global?: Array<CtxRequestHandler<Ctx>>;\n\n  /**\n   * Derive middleware from MethodCfg.\n   *  - `auth` runs when cfg.authenticated === true (or `when` overrides)\n   *  - `upload` runs when cfg.bodyFiles has entries\n   */\n  fromCfg?: {\n    auth?: RequestHandler | ((leaf: AnyLeaf) => RequestHandler);\n    when?: (cfg: MethodCfg, leaf: AnyLeaf) => { auth?: boolean } | void;\n    upload?: (files: FileField[] | undefined, leaf: AnyLeaf) => RequestHandler[];\n  };\n\n  /** Validate handler return values with outputSchema (default: true) */\n  validateOutput?: boolean;\n\n  /** Custom responder (default: res.json(data)) */\n  send?: (res: express.Response, data: unknown) => void;\n\n  /** Optional logger hooks */\n  logger?: LoggerLike;\n};\n\n/** Default JSON responder (typed to avoid implicit-any diagnostics) */\nconst defaultSend: (res: express.Response, data: unknown) => void = (res, data) => {\n  res.json(data as any);\n};\n\n/**\n * Normalize `auth` into a RequestHandler (avoids union-narrowing issues).\n * @param auth Static middleware or factory returning one for the current leaf.\n * @param leaf Leaf being registered.\n * @returns Request handler or undefined when no auth is required.\n */\nfunction resolveAuth(\n  auth: RequestHandler | ((leaf: AnyLeaf) => RequestHandler) | undefined,\n  leaf: AnyLeaf,\n): RequestHandler | undefined {\n  if (!auth) return undefined;\n  return (auth as (l: AnyLeaf) => RequestHandler).length === 1\n    ? (auth as (l: AnyLeaf) => RequestHandler)(leaf)\n    : (auth as RequestHandler);\n}\n\n// ──────────────────────────────────────────────────────────────────────────────\n// Core builder\n// ──────────────────────────────────────────────────────────────────────────────\n\nconst REGISTERED_ROUTES_SYMBOL = Symbol.for('routesV3.registeredRoutes');\n\ntype RegisteredRouteStore = Set<string>;\n\n/**\n * Retrieve or initialize the shared store of registered route keys.\n * @param router Express router/application that carries previously registered keys.\n * @returns Set of string keys describing registered routes.\n */\nfunction getRegisteredRouteStore(router: Router | express.Application): RegisteredRouteStore {\n  const existing = (router as any)[REGISTERED_ROUTES_SYMBOL] as RegisteredRouteStore | undefined;\n  if (existing) return existing;\n  const store: RegisteredRouteStore = new Set();\n  (router as any)[REGISTERED_ROUTES_SYMBOL] = store;\n  return store;\n}\n\n/**\n * Inspect the Express layer stack to discover already-registered routes.\n * @param appOrRouter Express application or router to inspect.\n * @returns All keys in the form `\"METHOD /path\"` found on the stack.\n */\nfunction collectRoutesFromStack(appOrRouter: Router | express.Application): string[] {\n  const result: string[] = [];\n  const stack: any[] =\n    (appOrRouter as any).stack ??\n    ((appOrRouter as any)._router ? (appOrRouter as any)._router.stack : undefined) ??\n    [];\n\n  if (!Array.isArray(stack)) return result;\n\n  for (const layer of stack) {\n    const route = layer && layer.route;\n    if (!route) continue;\n\n    const paths = Array.isArray(route.path) ? route.path : [route.path];\n    const methodEntries = Object.entries(route.methods ?? {}).filter(([, enabled]) => enabled);\n\n    for (const path of paths) {\n      for (const [method] of methodEntries) {\n        result.push(`${method.toUpperCase()} ${path}`);\n      }\n    }\n  }\n\n  return result;\n}\n\n/** Runtime helpers returned by `createRouteServer`. */\nexport type RouteServer<Ctx = unknown> = {\n  router: Router | express.Application;\n  register<L extends AnyLeaf>(leaf: L, def: RouteDef<L, Ctx>): void;\n  registerControllers<R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> }>(\n    registry: R,\n    controllers: PartialControllerMap<R, Ctx>,\n  ): void;\n  warnMissingControllers<R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> }>(\n    registry: R,\n    logger: { warn: (...args: any[]) => void },\n  ): void;\n  getRegisteredKeys(): string[];\n};\n\n/**\n * Create an Express binding helper that keeps routes and controllers in sync.\n * @param router Express router or app to register handlers on.\n * @param config Optional configuration controlling ctx building, auth, uploads, etc.\n * @returns Object with helpers to register controllers and inspect registered keys.\n */\nexport function createRouteServer<Ctx = unknown>(\n  router: Router | express.Application,\n  config?: RouteServerConfig<Ctx>,\n): RouteServer<Ctx> {\n  const validateOutput = config?.validateOutput ?? true;\n  const send = config?.send ?? defaultSend;\n  const logger = config?.logger;\n\n  const ctxMw: RequestHandler | undefined = config?.buildCtx\n    ? async (req, res, next) => {\n        try {\n          const ctx = await config.buildCtx!(req, res);\n          (res.locals as any)[CTX_SYMBOL] = ctx;\n          next();\n        } catch (err) {\n          logger?.error?.('buildCtx error', err);\n          next(err as any);\n        }\n      }\n    : undefined;\n\n  const globalMws = (config?.global ?? []).map((mw) => adaptCtxMw<Ctx>(mw));\n  const registered = getRegisteredRouteStore(router);\n\n  const buildDerived = (leaf: AnyLeaf): RequestHandler[] => {\n    const derived: RequestHandler[] = [];\n    const decision = config?.fromCfg?.when?.(leaf.cfg, leaf) ?? {};\n    const needsAuth = typeof decision.auth === 'boolean' ? decision.auth : !!leaf.cfg.authenticated;\n\n    if (needsAuth && config?.fromCfg?.auth) {\n      const authMw = resolveAuth(config.fromCfg.auth, leaf);\n      if (authMw) derived.push(authMw);\n    }\n\n    if (\n      config?.fromCfg?.upload &&\n      Array.isArray(leaf.cfg.bodyFiles) &&\n      leaf.cfg.bodyFiles.length > 0\n    ) {\n      derived.push(...config.fromCfg.upload(leaf.cfg.bodyFiles, leaf));\n    }\n\n    return derived;\n  };\n\n  /** Register a single leaf/controller pair on the underlying router. */\n  function register<L extends AnyLeaf>(leaf: L, def: RouteDef<L, Ctx>) {\n    const method = leaf.method as HttpMethod;\n    const path = leaf.path as string;\n    const key = keyOf(leaf);\n\n    const routeSpecific = (def?.use ?? []).map((mw) => adaptCtxMw<Ctx>(mw));\n    const derived = buildDerived(leaf);\n    const before: RequestHandler[] = [\n      ...(ctxMw ? [ctxMw] : []),\n      ...globalMws,\n      ...derived,\n      ...routeSpecific,\n    ];\n\n    const wrapped: RequestHandler = async (req, res, next) => {\n      try {\n        logger?.info?.(`${method.toUpperCase()}@${path} (${req.originalUrl})`);\n\n        const ctx = (res.locals as any)[CTX_SYMBOL] as Ctx;\n\n        const params = (\n          leaf.cfg.paramsSchema\n            ? (leaf.cfg.paramsSchema as ZodType).parse(req.params)\n            : Object.keys(req.params || {}).length\n              ? (req.params as any)\n              : undefined\n        ) as ArgParams<typeof leaf>;\n\n        let query: ArgQuery<typeof leaf>;\n        try {\n          query = leaf.cfg.querySchema\n            ? (leaf.cfg.querySchema as ZodType).parse(req.query)\n            : Object.keys(req.query || {}).length\n              ? (req.query as any)\n              : undefined;\n        } catch (e) {\n          logger?.error?.('Query parsing error', {\n            path,\n            method,\n            error: e,\n            raw: JSON.stringify(req.query),\n          });\n          throw e;\n        }\n\n        const body = (\n          leaf.cfg.bodySchema\n            ? (leaf.cfg.bodySchema as ZodType).parse(req.body)\n            : req.body !== undefined\n              ? (req.body as any)\n              : undefined\n        ) as ArgBody<typeof leaf>;\n\n        logger?.verbose?.(`${method.toUpperCase()}@${path} (${req.originalUrl})`, {\n          params,\n          query,\n          body,\n        });\n\n        let result;\n        try {\n          result = await def.handler({ req, res, next, ctx, params, query, body });\n        } catch (e) {\n          logger?.error?.('Handler error', e);\n          throw e;\n        }\n\n        if (!res.headersSent && result !== undefined) {\n          const out =\n            validateOutput && leaf.cfg.outputSchema\n              ? (leaf.cfg.outputSchema as ZodType).parse(result)\n              : result;\n          logger?.verbose?.(`${method.toUpperCase()}@${path} result`, out);\n          send(res, out);\n        }\n      } catch (err) {\n        logger?.error?.('Route error', err);\n        next(err as any);\n      }\n    };\n\n    const after = (def?.after ?? []).map((mw) => adaptCtxMw<Ctx>(mw));\n    (router as any)[method](path, ...before, wrapped, ...after);\n    registered.add(key);\n  }\n\n  /**\n   * Register controller definitions for the provided keys.\n   * @param registry Finalized registry of leaves.\n   * @param controllers Partial controller map keyed by `\"METHOD /path\"`.\n   */\n  function registerControllers<\n    R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> },\n  >(registry: R, controllers: PartialControllerMap<R, Ctx>) {\n    (Object.keys(controllers) as Array<KeysOfRegistry<R>>).forEach((key) => {\n      const leaf = registry.byKey[key] as unknown as LeafFromKey<R, typeof key> | undefined;\n      if (!leaf) {\n        logger?.warn?.(`No leaf found for controller key: ${key}. Not registering route.`);\n        return;\n      }\n      const def = controllers[key];\n      if (!def) return;\n      register(leaf as LeafFromKey<R, typeof key>, def);\n    });\n  }\n\n  /**\n   * Warn about leaves that do not have a registered controller.\n   * @param registry Finalized registry of leaves.\n   * @param warnLogger Logger used for warning output.\n   */\n  function warnMissing<R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> }>(\n    registry: R,\n    warnLogger: { warn: (...args: any[]) => void },\n  ) {\n    const registeredFromStore = new Set<string>(Array.from(registered));\n    if (registeredFromStore.size === 0) {\n      collectRoutesFromStack(router).forEach((key) => registeredFromStore.add(key));\n    }\n    for (const leaf of registry.all) {\n      const key = keyOf(leaf);\n      if (!registeredFromStore.has(key)) {\n        warnLogger.warn(`No controller registered for route: ${key}`);\n      }\n    }\n  }\n\n  return {\n    router,\n    register,\n    registerControllers,\n    warnMissingControllers: warnMissing,\n    getRegisteredKeys: () => Array.from(registered),\n  };\n}\n\n/**\n * Bind only the controllers that are present in the provided map.\n * @param router Express router or app.\n * @param registry Finalized registry produced by `finalize(...)`.\n * @param controllers Partial map of controllers keyed by `\"METHOD /path\"`.\n * @param config Optional route server configuration.\n * @returns The same router instance for chaining.\n */\nexport function bindExpressRoutes<\n  R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> },\n  Ctx = unknown,\n>(\n  router: Router | express.Application,\n  registry: R,\n  controllers: PartialControllerMap<R, Ctx>,\n  config?: RouteServerConfig<Ctx>,\n) {\n  const server = createRouteServer<Ctx>(router, config);\n  server.registerControllers(registry, controllers);\n  return router;\n}\n\n/**\n * Bind controllers for every leaf. Missing entries fail at compile time.\n * @param router Express router or app.\n * @param registry Finalized registry produced by `finalize(...)`.\n * @param controllers Complete map of controllers keyed by `\"METHOD /path\"`.\n * @param config Optional route server configuration.\n * @returns The same router instance for chaining.\n */\nexport function bindAll<\n  R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> },\n  Ctx = unknown,\n>(\n  router: Router | express.Application,\n  registry: R,\n  controllers: { [K in KeysOfRegistry<R>]: RouteDef<LeafFromKey<R, K>, Ctx> },\n  config?: RouteServerConfig<Ctx>,\n) {\n  const server = createRouteServer<Ctx>(router, config);\n  server.registerControllers(registry, controllers);\n  return router;\n}\n\n// ──────────────────────────────────────────────────────────────────────────────\n// DX helpers\n// ──────────────────────────────────────────────────────────────────────────────\n\n/**\n * Helper for great IntelliSense when authoring controller maps.\n * @returns Function that enforces key names while preserving partial flexibility.\n */\nexport const defineControllers =\n  <R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> }, Ctx = unknown>() =>\n  <M extends PartialControllerMap<R, Ctx>>(m: M) =>\n    m;\n\n/**\n * Wrap a plain RequestHandler as an auth factory compatible with `fromCfg.auth`.\n * @param mw Middleware invoked for any leaf that requires authentication.\n * @param _leaf Leaf metadata (ignored, but provided to match factory signature).\n * @returns Factory that ignores the leaf and returns the same middleware.\n */\nexport const asLeafAuth =\n  (mw: RequestHandler) =>\n  (_leaf: AnyLeaf): RequestHandler =>\n    mw;\n\n/**\n * Warn about leaves that don't have controllers.\n * Call this during startup to surface missing routes.\n * @param router Express router or app to inspect.\n * @param registry Finalized registry produced by `finalize(...)`.\n * @param logger Logger where warnings are emitted.\n */\nexport function warnMissingControllers<\n  R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> },\n>(router: Router | express.Application, registry: R, logger: { warn: (...args: any[]) => void }) {\n  const registeredStore = (router as any)[REGISTERED_ROUTES_SYMBOL] as Set<string> | undefined;\n  const initial = registeredStore ? Array.from(registeredStore) : collectRoutesFromStack(router);\n  const registeredKeys = new Set<string>(initial);\n\n  for (const leaf of registry.all) {\n    const k = keyOf(leaf);\n    if (!registeredKeys.has(k)) {\n      logger.warn(`No controller registered for route: ${k}`);\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './routesV3.server';

package/dist/index.js

@@ -0,0 +1,193 @@
+// src/routesV3.server.ts
+var keyOf = (leaf) => `${leaf.method.toUpperCase()} ${leaf.path}`;
+var CTX_SYMBOL = Symbol.for("typedLeaves.ctx");
+function getCtx(res) {
+  return res.locals[CTX_SYMBOL];
+}
+function adaptCtxMw(mw) {
+  return (req, res, next) => mw({ req, res, next, ctx: getCtx(res) });
+}
+var defaultSend = (res, data) => {
+  res.json(data);
+};
+function resolveAuth(auth, leaf) {
+  if (!auth) return void 0;
+  return auth.length === 1 ? auth(leaf) : auth;
+}
+var REGISTERED_ROUTES_SYMBOL = Symbol.for("routesV3.registeredRoutes");
+function getRegisteredRouteStore(router) {
+  const existing = router[REGISTERED_ROUTES_SYMBOL];
+  if (existing) return existing;
+  const store = /* @__PURE__ */ new Set();
+  router[REGISTERED_ROUTES_SYMBOL] = store;
+  return store;
+}
+function collectRoutesFromStack(appOrRouter) {
+  const result = [];
+  const stack = appOrRouter.stack ?? (appOrRouter._router ? appOrRouter._router.stack : void 0) ?? [];
+  if (!Array.isArray(stack)) return result;
+  for (const layer of stack) {
+    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);
+    for (const path of paths) {
+      for (const [method] of methodEntries) {
+        result.push(`${method.toUpperCase()} ${path}`);
+      }
+    }
+  }
+  return result;
+}
+function createRouteServer(router, config) {
+  const validateOutput = config?.validateOutput ?? true;
+  const send = config?.send ?? defaultSend;
+  const logger = config?.logger;
+  const ctxMw = config?.buildCtx ? async (req, res, next) => {
+    try {
+      const ctx = await config.buildCtx(req, res);
+      res.locals[CTX_SYMBOL] = ctx;
+      next();
+    } catch (err) {
+      logger?.error?.("buildCtx error", err);
+      next(err);
+    }
+  } : void 0;
+  const globalMws = (config?.global ?? []).map((mw) => adaptCtxMw(mw));
+  const registered = getRegisteredRouteStore(router);
+  const buildDerived = (leaf) => {
+    const derived = [];
+    const decision = config?.fromCfg?.when?.(leaf.cfg, leaf) ?? {};
+    const needsAuth = typeof decision.auth === "boolean" ? decision.auth : !!leaf.cfg.authenticated;
+    if (needsAuth && config?.fromCfg?.auth) {
+      const authMw = resolveAuth(config.fromCfg.auth, leaf);
+      if (authMw) derived.push(authMw);
+    }
+    if (config?.fromCfg?.upload && Array.isArray(leaf.cfg.bodyFiles) && leaf.cfg.bodyFiles.length > 0) {
+      derived.push(...config.fromCfg.upload(leaf.cfg.bodyFiles, leaf));
+    }
+    return derived;
+  };
+  function register(leaf, def) {
+    const method = leaf.method;
+    const path = leaf.path;
+    const key = keyOf(leaf);
+    const routeSpecific = (def?.use ?? []).map((mw) => adaptCtxMw(mw));
+    const derived = buildDerived(leaf);
+    const before = [
+      ...ctxMw ? [ctxMw] : [],
+      ...globalMws,
+      ...derived,
+      ...routeSpecific
+    ];
+    const wrapped = async (req, res, next) => {
+      try {
+        logger?.info?.(`${method.toUpperCase()}@${path} (${req.originalUrl})`);
+        const ctx = res.locals[CTX_SYMBOL];
+        const params = leaf.cfg.paramsSchema ? leaf.cfg.paramsSchema.parse(req.params) : Object.keys(req.params || {}).length ? req.params : void 0;
+        let query;
+        try {
+          query = leaf.cfg.querySchema ? leaf.cfg.querySchema.parse(req.query) : Object.keys(req.query || {}).length ? req.query : void 0;
+        } catch (e) {
+          logger?.error?.("Query parsing error", {
+            path,
+            method,
+            error: e,
+            raw: JSON.stringify(req.query)
+          });
+          throw e;
+        }
+        const body = leaf.cfg.bodySchema ? leaf.cfg.bodySchema.parse(req.body) : req.body !== void 0 ? req.body : void 0;
+        logger?.verbose?.(`${method.toUpperCase()}@${path} (${req.originalUrl})`, {
+          params,
+          query,
+          body
+        });
+        let result;
+        try {
+          result = await def.handler({ req, res, next, ctx, params, query, body });
+        } catch (e) {
+          logger?.error?.("Handler error", e);
+          throw e;
+        }
+        if (!res.headersSent && result !== void 0) {
+          const out = validateOutput && leaf.cfg.outputSchema ? leaf.cfg.outputSchema.parse(result) : result;
+          logger?.verbose?.(`${method.toUpperCase()}@${path} result`, out);
+          send(res, out);
+        }
+      } catch (err) {
+        logger?.error?.("Route error", err);
+        next(err);
+      }
+    };
+    const after = (def?.after ?? []).map((mw) => adaptCtxMw(mw));
+    router[method](path, ...before, wrapped, ...after);
+    registered.add(key);
+  }
+  function registerControllers(registry, controllers) {
+    Object.keys(controllers).forEach((key) => {
+      const leaf = registry.byKey[key];
+      if (!leaf) {
+        logger?.warn?.(`No leaf found for controller key: ${key}. Not registering route.`);
+        return;
+      }
+      const def = controllers[key];
+      if (!def) return;
+      register(leaf, def);
+    });
+  }
+  function warnMissing(registry, warnLogger) {
+    const registeredFromStore = new Set(Array.from(registered));
+    if (registeredFromStore.size === 0) {
+      collectRoutesFromStack(router).forEach((key) => registeredFromStore.add(key));
+    }
+    for (const leaf of registry.all) {
+      const key = keyOf(leaf);
+      if (!registeredFromStore.has(key)) {
+        warnLogger.warn(`No controller registered for route: ${key}`);
+      }
+    }
+  }
+  return {
+    router,
+    register,
+    registerControllers,
+    warnMissingControllers: warnMissing,
+    getRegisteredKeys: () => Array.from(registered)
+  };
+}
+function bindExpressRoutes(router, registry, controllers, config) {
+  const server = createRouteServer(router, config);
+  server.registerControllers(registry, controllers);
+  return router;
+}
+function bindAll(router, registry, controllers, config) {
+  const server = createRouteServer(router, config);
+  server.registerControllers(registry, controllers);
+  return router;
+}
+var defineControllers = () => (m) => m;
+var asLeafAuth = (mw) => (_leaf) => mw;
+function warnMissingControllers(router, registry, logger) {
+  const registeredStore = router[REGISTERED_ROUTES_SYMBOL];
+  const initial = registeredStore ? Array.from(registeredStore) : collectRoutesFromStack(router);
+  const registeredKeys = new Set(initial);
+  for (const leaf of registry.all) {
+    const k = keyOf(leaf);
+    if (!registeredKeys.has(k)) {
+      logger.warn(`No controller registered for route: ${k}`);
+    }
+  }
+}
+export {
+  CTX_SYMBOL,
+  asLeafAuth,
+  bindAll,
+  bindExpressRoutes,
+  createRouteServer,
+  defineControllers,
+  getCtx,
+  keyOf,
+  warnMissingControllers
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/routesV3.server.ts"],"sourcesContent":["/**\n * routesV3.server.ts\n * -----------------------------------------------------------------------------\n * Bind an Express router/app to a `finalize(...)` registry of AnyLeafs.\n * - Fully typed handlers (params/query/body/output)\n * - Zod parsing + optional output validation\n * - buildCtx runs as a middleware *first*, before all other middlewares\n * - Global, per-route, and cfg-derived middlewares (auth, uploads)\n * - Helper to warn about unimplemented routes\n * - DX helpers to use `ctx` in any middleware with proper types\n */\n\nimport type * as express from 'express';\nimport type { RequestHandler, Router } from 'express';\nimport type { ZodType } from 'zod';\nimport {\n  FileField,\n  HttpMethod,\n  MethodCfg,\n} from '@emeryld/rrroutes-contract';\nimport type {\n  AnyLeaf,\n  InferBody,\n  InferOutput,\n  InferParams,\n  InferQuery,\n} from '@emeryld/rrroutes-contract';\n\nexport type { AnyLeaf } from '@emeryld/rrroutes-contract';\n\n/** Shape expected from optional logger implementations. */\nexport type LoggerLike = {\n  info?: (...args: any[]) => void;\n  warn?: (...args: any[]) => void;\n  error?: (...args: any[]) => void;\n  debug?: (...args: any[]) => void;\n  verbose?: (...args: any[]) => void;\n  system?: (...args: any[]) => void;\n  log?: (...args: any[]) => void;\n};\n\n// ──────────────────────────────────────────────────────────────────────────────\n// Keys + leaf helpers (derive keys from byKey to avoid template-literal pitfalls)\n// ──────────────────────────────────────────────────────────────────────────────\n\n/** Keys like \"GET /v1/foo\" that *actually* exist in the registry */\nexport type KeysOfRegistry<R extends { byKey: Record<string, AnyLeaf> }> = keyof R['byKey'] &\n  string;\n\ntype MethodFromKey<K extends string> = K extends `${infer M} ${string}` ? Lowercase<M> : never;\ntype PathFromKey<K extends string> = K extends `${string} ${infer P}` ? P : never;\n\n/** Given a registry and a key, pick the exact leaf for that method+path */\nexport type LeafFromKey<R extends { all: readonly AnyLeaf[] }, K extends string> = Extract<\n  R['all'][number],\n  { method: MethodFromKey<K> & HttpMethod; path: PathFromKey<K> }\n>;\n\n/** Optional-ify types if your core returns `never` when a schema isn't defined */\ntype Maybe<T> = [T] extends [never] ? undefined : T;\n\n/** Typed params argument exposed to handlers. */\nexport type ArgParams<L extends AnyLeaf> = Maybe<InferParams<L>>;\n/** Typed query argument exposed to handlers. */\nexport type ArgQuery<L extends AnyLeaf> = Maybe<InferQuery<L>>;\n/** Typed body argument exposed to handlers. */\nexport type ArgBody<L extends AnyLeaf> = Maybe<InferBody<L>>;\n\n/**\n * Convenience to compute a `\"METHOD /path\"` key from a leaf.\n * @param leaf Leaf describing the route.\n * @returns Uppercase method + path key.\n */\nexport const keyOf = (leaf: AnyLeaf) => `${leaf.method.toUpperCase()} ${leaf.path}` as const;\n\n// ──────────────────────────────────────────────────────────────────────────────\n// Context typing & DX helpers (so ctx is usable in *any* middleware)\n// ──────────────────────────────────────────────────────────────────────────────\n\n/**\n * Unique symbol used to stash ctx on res.locals.\n * (Symbols are safer than string keys against collisions.)\n */\nexport const CTX_SYMBOL: unique symbol = Symbol.for('typedLeaves.ctx');\n\n/** Response type that *has* a ctx on locals for DX in middlewares */\nexport type ResponseWithCtx<Ctx> =\n  // Replace locals with an intersection that guarantees CTX_SYMBOL exists\n  Omit<express.Response, 'locals'> & {\n    locals: express.Response['locals'] & { [CTX_SYMBOL]: Ctx };\n  };\n\n/** A middleware signature that can *use* ctx via `res.locals[CTX_SYMBOL]` */\nexport type CtxRequestHandler<Ctx> = (args: {\n  req: express.Request;\n  res: express.Response;\n  next: express.NextFunction;\n  ctx: Ctx;\n}) => any;\n\n/**\n * Safely read ctx from any Response.\n * @param res Express response whose locals contain the ctx symbol.\n * @returns Strongly typed context object.\n */\nexport function getCtx<Ctx = unknown>(res: express.Response): Ctx {\n  return (res.locals as any)[CTX_SYMBOL] as Ctx;\n}\n\n/**\n * Wrap a ctx-typed middleware to a plain RequestHandler (for arrays, etc.).\n * @param mw Middleware that expects a typed response with ctx available.\n * @returns Standard Express request handler.\n */\nfunction adaptCtxMw<Ctx>(mw: CtxRequestHandler<Ctx>): RequestHandler {\n  return (req, res, next) => mw({ req, res, next, ctx: getCtx<Ctx>(res) });\n}\n\n// ──────────────────────────────────────────────────────────────────────────────\n// Controller types — object form only (simpler, clearer typings)\n// ──────────────────────────────────────────────────────────────────────────────\n\n/** Typed route handler for a specific leaf */\nexport type Handler<L extends AnyLeaf, Ctx = unknown> = (args: {\n  req: express.Request;\n  res: express.Response;\n  next: express.NextFunction;\n  ctx: Ctx;\n  params: ArgParams<L>;\n  query: ArgQuery<L>;\n  body: ArgBody<L>;\n}) => Promise<InferOutput<L>> | InferOutput<L>;\n\n/** Route definition for one key */\nexport type RouteDef<L extends AnyLeaf, Ctx = unknown> = {\n  /** Middlewares before the handler (run after buildCtx/global/derived) */\n  use?: Array<CtxRequestHandler<Ctx>>;\n  /** Middlewares after the handler *if* it calls next() */\n  after?: Array<CtxRequestHandler<Ctx>>;\n  /** Your business logic */\n  handler: Handler<L, Ctx>;\n};\n\n/** Map of registry keys -> route defs */\nexport type ControllerMap<\n  R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> },\n  Ctx = unknown,\n> = {\n  [P in KeysOfRegistry<R>]: RouteDef<LeafFromKey<R, P>, Ctx>;\n};\n\nexport type PartialControllerMap<\n  R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> },\n  Ctx = unknown,\n> = Partial<ControllerMap<R, Ctx>>;\n\n// ──────────────────────────────────────────────────────────────────────────────\n/** Options + derivation helpers */\n// ──────────────────────────────────────────────────────────────────────────────\n\nexport type RouteServerConfig<Ctx = unknown> = {\n  /**\n   * Build a request-scoped context. We wrap this in a middleware that runs\n   * *first* (before global/derived/route middlewares), and stash it on\n   * `res.locals[CTX_SYMBOL]` so *all* later middlewares can use it.\n   */\n  buildCtx?: (req: express.Request, res: express.Response) => Ctx | Promise<Ctx>;\n\n  /**\n   * Global middlewares for every bound route (run *after* buildCtx).\n   * You can write them as ctx-aware middlewares for great DX.\n   */\n  global?: Array<CtxRequestHandler<Ctx>>;\n\n  /**\n   * Derive middleware from MethodCfg.\n   *  - `auth` runs when cfg.authenticated === true (or `when` overrides)\n   *  - `upload` runs when cfg.bodyFiles has entries\n   */\n  fromCfg?: {\n    auth?: RequestHandler | ((leaf: AnyLeaf) => RequestHandler);\n    when?: (cfg: MethodCfg, leaf: AnyLeaf) => { auth?: boolean } | void;\n    upload?: (files: FileField[] | undefined, leaf: AnyLeaf) => RequestHandler[];\n  };\n\n  /** Validate handler return values with outputSchema (default: true) */\n  validateOutput?: boolean;\n\n  /** Custom responder (default: res.json(data)) */\n  send?: (res: express.Response, data: unknown) => void;\n\n  /** Optional logger hooks */\n  logger?: LoggerLike;\n};\n\n/** Default JSON responder (typed to avoid implicit-any diagnostics) */\nconst defaultSend: (res: express.Response, data: unknown) => void = (res, data) => {\n  res.json(data as any);\n};\n\n/**\n * Normalize `auth` into a RequestHandler (avoids union-narrowing issues).\n * @param auth Static middleware or factory returning one for the current leaf.\n * @param leaf Leaf being registered.\n * @returns Request handler or undefined when no auth is required.\n */\nfunction resolveAuth(\n  auth: RequestHandler | ((leaf: AnyLeaf) => RequestHandler) | undefined,\n  leaf: AnyLeaf,\n): RequestHandler | undefined {\n  if (!auth) return undefined;\n  return (auth as (l: AnyLeaf) => RequestHandler).length === 1\n    ? (auth as (l: AnyLeaf) => RequestHandler)(leaf)\n    : (auth as RequestHandler);\n}\n\n// ──────────────────────────────────────────────────────────────────────────────\n// Core builder\n// ──────────────────────────────────────────────────────────────────────────────\n\nconst REGISTERED_ROUTES_SYMBOL = Symbol.for('routesV3.registeredRoutes');\n\ntype RegisteredRouteStore = Set<string>;\n\n/**\n * Retrieve or initialize the shared store of registered route keys.\n * @param router Express router/application that carries previously registered keys.\n * @returns Set of string keys describing registered routes.\n */\nfunction getRegisteredRouteStore(router: Router | express.Application): RegisteredRouteStore {\n  const existing = (router as any)[REGISTERED_ROUTES_SYMBOL] as RegisteredRouteStore | undefined;\n  if (existing) return existing;\n  const store: RegisteredRouteStore = new Set();\n  (router as any)[REGISTERED_ROUTES_SYMBOL] = store;\n  return store;\n}\n\n/**\n * Inspect the Express layer stack to discover already-registered routes.\n * @param appOrRouter Express application or router to inspect.\n * @returns All keys in the form `\"METHOD /path\"` found on the stack.\n */\nfunction collectRoutesFromStack(appOrRouter: Router | express.Application): string[] {\n  const result: string[] = [];\n  const stack: any[] =\n    (appOrRouter as any).stack ??\n    ((appOrRouter as any)._router ? (appOrRouter as any)._router.stack : undefined) ??\n    [];\n\n  if (!Array.isArray(stack)) return result;\n\n  for (const layer of stack) {\n    const route = layer && layer.route;\n    if (!route) continue;\n\n    const paths = Array.isArray(route.path) ? route.path : [route.path];\n    const methodEntries = Object.entries(route.methods ?? {}).filter(([, enabled]) => enabled);\n\n    for (const path of paths) {\n      for (const [method] of methodEntries) {\n        result.push(`${method.toUpperCase()} ${path}`);\n      }\n    }\n  }\n\n  return result;\n}\n\n/** Runtime helpers returned by `createRouteServer`. */\nexport type RouteServer<Ctx = unknown> = {\n  router: Router | express.Application;\n  register<L extends AnyLeaf>(leaf: L, def: RouteDef<L, Ctx>): void;\n  registerControllers<R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> }>(\n    registry: R,\n    controllers: PartialControllerMap<R, Ctx>,\n  ): void;\n  warnMissingControllers<R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> }>(\n    registry: R,\n    logger: { warn: (...args: any[]) => void },\n  ): void;\n  getRegisteredKeys(): string[];\n};\n\n/**\n * Create an Express binding helper that keeps routes and controllers in sync.\n * @param router Express router or app to register handlers on.\n * @param config Optional configuration controlling ctx building, auth, uploads, etc.\n * @returns Object with helpers to register controllers and inspect registered keys.\n */\nexport function createRouteServer<Ctx = unknown>(\n  router: Router | express.Application,\n  config?: RouteServerConfig<Ctx>,\n): RouteServer<Ctx> {\n  const validateOutput = config?.validateOutput ?? true;\n  const send = config?.send ?? defaultSend;\n  const logger = config?.logger;\n\n  const ctxMw: RequestHandler | undefined = config?.buildCtx\n    ? async (req, res, next) => {\n        try {\n          const ctx = await config.buildCtx!(req, res);\n          (res.locals as any)[CTX_SYMBOL] = ctx;\n          next();\n        } catch (err) {\n          logger?.error?.('buildCtx error', err);\n          next(err as any);\n        }\n      }\n    : undefined;\n\n  const globalMws = (config?.global ?? []).map((mw) => adaptCtxMw<Ctx>(mw));\n  const registered = getRegisteredRouteStore(router);\n\n  const buildDerived = (leaf: AnyLeaf): RequestHandler[] => {\n    const derived: RequestHandler[] = [];\n    const decision = config?.fromCfg?.when?.(leaf.cfg, leaf) ?? {};\n    const needsAuth = typeof decision.auth === 'boolean' ? decision.auth : !!leaf.cfg.authenticated;\n\n    if (needsAuth && config?.fromCfg?.auth) {\n      const authMw = resolveAuth(config.fromCfg.auth, leaf);\n      if (authMw) derived.push(authMw);\n    }\n\n    if (\n      config?.fromCfg?.upload &&\n      Array.isArray(leaf.cfg.bodyFiles) &&\n      leaf.cfg.bodyFiles.length > 0\n    ) {\n      derived.push(...config.fromCfg.upload(leaf.cfg.bodyFiles, leaf));\n    }\n\n    return derived;\n  };\n\n  /** Register a single leaf/controller pair on the underlying router. */\n  function register<L extends AnyLeaf>(leaf: L, def: RouteDef<L, Ctx>) {\n    const method = leaf.method as HttpMethod;\n    const path = leaf.path as string;\n    const key = keyOf(leaf);\n\n    const routeSpecific = (def?.use ?? []).map((mw) => adaptCtxMw<Ctx>(mw));\n    const derived = buildDerived(leaf);\n    const before: RequestHandler[] = [\n      ...(ctxMw ? [ctxMw] : []),\n      ...globalMws,\n      ...derived,\n      ...routeSpecific,\n    ];\n\n    const wrapped: RequestHandler = async (req, res, next) => {\n      try {\n        logger?.info?.(`${method.toUpperCase()}@${path} (${req.originalUrl})`);\n\n        const ctx = (res.locals as any)[CTX_SYMBOL] as Ctx;\n\n        const params = (\n          leaf.cfg.paramsSchema\n            ? (leaf.cfg.paramsSchema as ZodType).parse(req.params)\n            : Object.keys(req.params || {}).length\n              ? (req.params as any)\n              : undefined\n        ) as ArgParams<typeof leaf>;\n\n        let query: ArgQuery<typeof leaf>;\n        try {\n          query = leaf.cfg.querySchema\n            ? (leaf.cfg.querySchema as ZodType).parse(req.query)\n            : Object.keys(req.query || {}).length\n              ? (req.query as any)\n              : undefined;\n        } catch (e) {\n          logger?.error?.('Query parsing error', {\n            path,\n            method,\n            error: e,\n            raw: JSON.stringify(req.query),\n          });\n          throw e;\n        }\n\n        const body = (\n          leaf.cfg.bodySchema\n            ? (leaf.cfg.bodySchema as ZodType).parse(req.body)\n            : req.body !== undefined\n              ? (req.body as any)\n              : undefined\n        ) as ArgBody<typeof leaf>;\n\n        logger?.verbose?.(`${method.toUpperCase()}@${path} (${req.originalUrl})`, {\n          params,\n          query,\n          body,\n        });\n\n        let result;\n        try {\n          result = await def.handler({ req, res, next, ctx, params, query, body });\n        } catch (e) {\n          logger?.error?.('Handler error', e);\n          throw e;\n        }\n\n        if (!res.headersSent && result !== undefined) {\n          const out =\n            validateOutput && leaf.cfg.outputSchema\n              ? (leaf.cfg.outputSchema as ZodType).parse(result)\n              : result;\n          logger?.verbose?.(`${method.toUpperCase()}@${path} result`, out);\n          send(res, out);\n        }\n      } catch (err) {\n        logger?.error?.('Route error', err);\n        next(err as any);\n      }\n    };\n\n    const after = (def?.after ?? []).map((mw) => adaptCtxMw<Ctx>(mw));\n    (router as any)[method](path, ...before, wrapped, ...after);\n    registered.add(key);\n  }\n\n  /**\n   * Register controller definitions for the provided keys.\n   * @param registry Finalized registry of leaves.\n   * @param controllers Partial controller map keyed by `\"METHOD /path\"`.\n   */\n  function registerControllers<\n    R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> },\n  >(registry: R, controllers: PartialControllerMap<R, Ctx>) {\n    (Object.keys(controllers) as Array<KeysOfRegistry<R>>).forEach((key) => {\n      const leaf = registry.byKey[key] as unknown as LeafFromKey<R, typeof key> | undefined;\n      if (!leaf) {\n        logger?.warn?.(`No leaf found for controller key: ${key}. Not registering route.`);\n        return;\n      }\n      const def = controllers[key];\n      if (!def) return;\n      register(leaf as LeafFromKey<R, typeof key>, def);\n    });\n  }\n\n  /**\n   * Warn about leaves that do not have a registered controller.\n   * @param registry Finalized registry of leaves.\n   * @param warnLogger Logger used for warning output.\n   */\n  function warnMissing<R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> }>(\n    registry: R,\n    warnLogger: { warn: (...args: any[]) => void },\n  ) {\n    const registeredFromStore = new Set<string>(Array.from(registered));\n    if (registeredFromStore.size === 0) {\n      collectRoutesFromStack(router).forEach((key) => registeredFromStore.add(key));\n    }\n    for (const leaf of registry.all) {\n      const key = keyOf(leaf);\n      if (!registeredFromStore.has(key)) {\n        warnLogger.warn(`No controller registered for route: ${key}`);\n      }\n    }\n  }\n\n  return {\n    router,\n    register,\n    registerControllers,\n    warnMissingControllers: warnMissing,\n    getRegisteredKeys: () => Array.from(registered),\n  };\n}\n\n/**\n * Bind only the controllers that are present in the provided map.\n * @param router Express router or app.\n * @param registry Finalized registry produced by `finalize(...)`.\n * @param controllers Partial map of controllers keyed by `\"METHOD /path\"`.\n * @param config Optional route server configuration.\n * @returns The same router instance for chaining.\n */\nexport function bindExpressRoutes<\n  R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> },\n  Ctx = unknown,\n>(\n  router: Router | express.Application,\n  registry: R,\n  controllers: PartialControllerMap<R, Ctx>,\n  config?: RouteServerConfig<Ctx>,\n) {\n  const server = createRouteServer<Ctx>(router, config);\n  server.registerControllers(registry, controllers);\n  return router;\n}\n\n/**\n * Bind controllers for every leaf. Missing entries fail at compile time.\n * @param router Express router or app.\n * @param registry Finalized registry produced by `finalize(...)`.\n * @param controllers Complete map of controllers keyed by `\"METHOD /path\"`.\n * @param config Optional route server configuration.\n * @returns The same router instance for chaining.\n */\nexport function bindAll<\n  R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> },\n  Ctx = unknown,\n>(\n  router: Router | express.Application,\n  registry: R,\n  controllers: { [K in KeysOfRegistry<R>]: RouteDef<LeafFromKey<R, K>, Ctx> },\n  config?: RouteServerConfig<Ctx>,\n) {\n  const server = createRouteServer<Ctx>(router, config);\n  server.registerControllers(registry, controllers);\n  return router;\n}\n\n// ──────────────────────────────────────────────────────────────────────────────\n// DX helpers\n// ──────────────────────────────────────────────────────────────────────────────\n\n/**\n * Helper for great IntelliSense when authoring controller maps.\n * @returns Function that enforces key names while preserving partial flexibility.\n */\nexport const defineControllers =\n  <R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> }, Ctx = unknown>() =>\n  <M extends PartialControllerMap<R, Ctx>>(m: M) =>\n    m;\n\n/**\n * Wrap a plain RequestHandler as an auth factory compatible with `fromCfg.auth`.\n * @param mw Middleware invoked for any leaf that requires authentication.\n * @param _leaf Leaf metadata (ignored, but provided to match factory signature).\n * @returns Factory that ignores the leaf and returns the same middleware.\n */\nexport const asLeafAuth =\n  (mw: RequestHandler) =>\n  (_leaf: AnyLeaf): RequestHandler =>\n    mw;\n\n/**\n * Warn about leaves that don't have controllers.\n * Call this during startup to surface missing routes.\n * @param router Express router or app to inspect.\n * @param registry Finalized registry produced by `finalize(...)`.\n * @param logger Logger where warnings are emitted.\n */\nexport function warnMissingControllers<\n  R extends { all: readonly AnyLeaf[]; byKey: Record<string, AnyLeaf> },\n>(router: Router | express.Application, registry: R, logger: { warn: (...args: any[]) => void }) {\n  const registeredStore = (router as any)[REGISTERED_ROUTES_SYMBOL] as Set<string> | undefined;\n  const initial = registeredStore ? Array.from(registeredStore) : collectRoutesFromStack(router);\n  const registeredKeys = new Set<string>(initial);\n\n  for (const leaf of registry.all) {\n    const k = keyOf(leaf);\n    if (!registeredKeys.has(k)) {\n      logger.warn(`No controller registered for route: ${k}`);\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/routesV3.server.d.ts

@@ -0,0 +1,216 @@
+/**
+ * routesV3.server.ts
+ * -----------------------------------------------------------------------------
+ * Bind an Express router/app to a `finalize(...)` registry of AnyLeafs.
+ * - Fully typed handlers (params/query/body/output)
+ * - Zod parsing + optional output validation
+ * - buildCtx runs as a middleware *first*, before all other middlewares
+ * - Global, per-route, and cfg-derived middlewares (auth, uploads)
+ * - Helper to warn about unimplemented routes
+ * - DX helpers to use `ctx` in any middleware with proper types
+ */
+import type * as express from 'express';
+import type { RequestHandler, Router } from 'express';
+import { FileField, HttpMethod, MethodCfg } from '@emeryld/rrroutes-contract';
+import type { AnyLeaf, InferBody, InferOutput, InferParams, InferQuery } from '@emeryld/rrroutes-contract';
+export type { AnyLeaf } from '@emeryld/rrroutes-contract';
+/** Shape expected from optional logger implementations. */
+export type LoggerLike = {
+    info?: (...args: any[]) => void;
+    warn?: (...args: any[]) => void;
+    error?: (...args: any[]) => void;
+    debug?: (...args: any[]) => void;
+    verbose?: (...args: any[]) => void;
+    system?: (...args: any[]) => void;
+    log?: (...args: any[]) => void;
+};
+/** Keys like "GET /v1/foo" that *actually* exist in the registry */
+export type KeysOfRegistry<R extends {
+    byKey: Record<string, AnyLeaf>;
+}> = keyof R['byKey'] & string;
+type MethodFromKey<K extends string> = K extends `${infer M} ${string}` ? Lowercase<M> : never;
+type PathFromKey<K extends string> = K extends `${string} ${infer P}` ? P : never;
+/** Given a registry and a key, pick the exact leaf for that method+path */
+export type LeafFromKey<R extends {
+    all: readonly AnyLeaf[];
+}, K extends string> = Extract<R['all'][number], {
+    method: MethodFromKey<K> & HttpMethod;
+    path: PathFromKey<K>;
+}>;
+/** Optional-ify types if your core returns `never` when a schema isn't defined */
+type Maybe<T> = [T] extends [never] ? undefined : T;
+/** Typed params argument exposed to handlers. */
+export type ArgParams<L extends AnyLeaf> = Maybe<InferParams<L>>;
+/** Typed query argument exposed to handlers. */
+export type ArgQuery<L extends AnyLeaf> = Maybe<InferQuery<L>>;
+/** Typed body argument exposed to handlers. */
+export type ArgBody<L extends AnyLeaf> = Maybe<InferBody<L>>;
+/**
+ * Convenience to compute a `"METHOD /path"` key from a leaf.
+ * @param leaf Leaf describing the route.
+ * @returns Uppercase method + path key.
+ */
+export declare const keyOf: (leaf: AnyLeaf) => `${string} ${string}`;
+/**
+ * Unique symbol used to stash ctx on res.locals.
+ * (Symbols are safer than string keys against collisions.)
+ */
+export declare const CTX_SYMBOL: unique symbol;
+/** Response type that *has* a ctx on locals for DX in middlewares */
+export type ResponseWithCtx<Ctx> = Omit<express.Response, 'locals'> & {
+    locals: express.Response['locals'] & {
+        [CTX_SYMBOL]: Ctx;
+    };
+};
+/** A middleware signature that can *use* ctx via `res.locals[CTX_SYMBOL]` */
+export type CtxRequestHandler<Ctx> = (args: {
+    req: express.Request;
+    res: express.Response;
+    next: express.NextFunction;
+    ctx: Ctx;
+}) => any;
+/**
+ * Safely read ctx from any Response.
+ * @param res Express response whose locals contain the ctx symbol.
+ * @returns Strongly typed context object.
+ */
+export declare function getCtx<Ctx = unknown>(res: express.Response): Ctx;
+/** Typed route handler for a specific leaf */
+export type Handler<L extends AnyLeaf, Ctx = unknown> = (args: {
+    req: express.Request;
+    res: express.Response;
+    next: express.NextFunction;
+    ctx: Ctx;
+    params: ArgParams<L>;
+    query: ArgQuery<L>;
+    body: ArgBody<L>;
+}) => Promise<InferOutput<L>> | InferOutput<L>;
+/** Route definition for one key */
+export type RouteDef<L extends AnyLeaf, Ctx = unknown> = {
+    /** Middlewares before the handler (run after buildCtx/global/derived) */
+    use?: Array<CtxRequestHandler<Ctx>>;
+    /** Middlewares after the handler *if* it calls next() */
+    after?: Array<CtxRequestHandler<Ctx>>;
+    /** Your business logic */
+    handler: Handler<L, Ctx>;
+};
+/** Map of registry keys -> route defs */
+export type ControllerMap<R extends {
+    all: readonly AnyLeaf[];
+    byKey: Record<string, AnyLeaf>;
+}, Ctx = unknown> = {
+    [P in KeysOfRegistry<R>]: RouteDef<LeafFromKey<R, P>, Ctx>;
+};
+export type PartialControllerMap<R extends {
+    all: readonly AnyLeaf[];
+    byKey: Record<string, AnyLeaf>;
+}, Ctx = unknown> = Partial<ControllerMap<R, Ctx>>;
+/** Options + derivation helpers */
+export type RouteServerConfig<Ctx = unknown> = {
+    /**
+     * Build a request-scoped context. We wrap this in a middleware that runs
+     * *first* (before global/derived/route middlewares), and stash it on
+     * `res.locals[CTX_SYMBOL]` so *all* later middlewares can use it.
+     */
+    buildCtx?: (req: express.Request, res: express.Response) => Ctx | Promise<Ctx>;
+    /**
+     * Global middlewares for every bound route (run *after* buildCtx).
+     * You can write them as ctx-aware middlewares for great DX.
+     */
+    global?: Array<CtxRequestHandler<Ctx>>;
+    /**
+     * Derive middleware from MethodCfg.
+     *  - `auth` runs when cfg.authenticated === true (or `when` overrides)
+     *  - `upload` runs when cfg.bodyFiles has entries
+     */
+    fromCfg?: {
+        auth?: RequestHandler | ((leaf: AnyLeaf) => RequestHandler);
+        when?: (cfg: MethodCfg, leaf: AnyLeaf) => {
+            auth?: boolean;
+        } | void;
+        upload?: (files: FileField[] | undefined, leaf: AnyLeaf) => RequestHandler[];
+    };
+    /** Validate handler return values with outputSchema (default: true) */
+    validateOutput?: boolean;
+    /** Custom responder (default: res.json(data)) */
+    send?: (res: express.Response, data: unknown) => void;
+    /** Optional logger hooks */
+    logger?: LoggerLike;
+};
+/** Runtime helpers returned by `createRouteServer`. */
+export type RouteServer<Ctx = unknown> = {
+    router: Router | express.Application;
+    register<L extends AnyLeaf>(leaf: L, def: RouteDef<L, Ctx>): void;
+    registerControllers<R extends {
+        all: readonly AnyLeaf[];
+        byKey: Record<string, AnyLeaf>;
+    }>(registry: R, controllers: PartialControllerMap<R, Ctx>): void;
+    warnMissingControllers<R extends {
+        all: readonly AnyLeaf[];
+        byKey: Record<string, AnyLeaf>;
+    }>(registry: R, logger: {
+        warn: (...args: any[]) => void;
+    }): void;
+    getRegisteredKeys(): string[];
+};
+/**
+ * Create an Express binding helper that keeps routes and controllers in sync.
+ * @param router Express router or app to register handlers on.
+ * @param config Optional configuration controlling ctx building, auth, uploads, etc.
+ * @returns Object with helpers to register controllers and inspect registered keys.
+ */
+export declare function createRouteServer<Ctx = unknown>(router: Router | express.Application, config?: RouteServerConfig<Ctx>): RouteServer<Ctx>;
+/**
+ * Bind only the controllers that are present in the provided map.
+ * @param router Express router or app.
+ * @param registry Finalized registry produced by `finalize(...)`.
+ * @param controllers Partial map of controllers keyed by `"METHOD /path"`.
+ * @param config Optional route server configuration.
+ * @returns The same router instance for chaining.
+ */
+export declare function bindExpressRoutes<R extends {
+    all: readonly AnyLeaf[];
+    byKey: Record<string, AnyLeaf>;
+}, Ctx = unknown>(router: Router | express.Application, registry: R, controllers: PartialControllerMap<R, Ctx>, config?: RouteServerConfig<Ctx>): express.Router | express.Application;
+/**
+ * Bind controllers for every leaf. Missing entries fail at compile time.
+ * @param router Express router or app.
+ * @param registry Finalized registry produced by `finalize(...)`.
+ * @param controllers Complete map of controllers keyed by `"METHOD /path"`.
+ * @param config Optional route server configuration.
+ * @returns The same router instance for chaining.
+ */
+export declare function bindAll<R extends {
+    all: readonly AnyLeaf[];
+    byKey: Record<string, AnyLeaf>;
+}, Ctx = unknown>(router: Router | express.Application, registry: R, controllers: {
+    [K in KeysOfRegistry<R>]: RouteDef<LeafFromKey<R, K>, Ctx>;
+}, config?: RouteServerConfig<Ctx>): express.Router | express.Application;
+/**
+ * Helper for great IntelliSense when authoring controller maps.
+ * @returns Function that enforces key names while preserving partial flexibility.
+ */
+export declare const defineControllers: <R extends {
+    all: readonly AnyLeaf[];
+    byKey: Record<string, AnyLeaf>;
+}, Ctx = unknown>() => <M extends PartialControllerMap<R, Ctx>>(m: M) => M;
+/**
+ * Wrap a plain RequestHandler as an auth factory compatible with `fromCfg.auth`.
+ * @param mw Middleware invoked for any leaf that requires authentication.
+ * @param _leaf Leaf metadata (ignored, but provided to match factory signature).
+ * @returns Factory that ignores the leaf and returns the same middleware.
+ */
+export declare const asLeafAuth: (mw: RequestHandler) => (_leaf: AnyLeaf) => RequestHandler;
+/**
+ * Warn about leaves that don't have controllers.
+ * Call this during startup to surface missing routes.
+ * @param router Express router or app to inspect.
+ * @param registry Finalized registry produced by `finalize(...)`.
+ * @param logger Logger where warnings are emitted.
+ */
+export declare function warnMissingControllers<R extends {
+    all: readonly AnyLeaf[];
+    byKey: Record<string, AnyLeaf>;
+}>(router: Router | express.Application, registry: R, logger: {
+    warn: (...args: any[]) => void;
+}): void;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@emeryld/rrroutes-server",
+  "version": "1.1.0",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@emeryld/rrroutes-contract": "^1.0.1",
+    "zod": "^4.1.8"
+  },
+  "peerDependencies": {
+    "express": "^5.1.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.2.0"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "pnpm run clean && pnpm run build:js && pnpm run build:types",
+    "build:js": "tsup src/index.ts --sourcemap --format esm,cjs --out-dir dist",
+    "build:types": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}