@mionjs/router 0.8.10 → 0.13.0

package/.dist/esm/src/lib/dispatchError.js

@@ -1,39 +1,75 @@
-import { MION_ROUTES, SerializerModes, StatusCodes, RpcError } from "@mionjs/core";
+import { JSON_CONTENT_TYPE } from "../constants.js";
+import { FatalError, MION_ROUTES, RpcError, StatusCodes, markFatal } from "@mionjs/core";
+//#region src/lib/dispatchError.ts
+/** The response for an error raised outside the router by any adapter; it goes in `@thrownErrors` like a route error. */
 function getRouterFatalErrorResponse(returnErr, respHeaders) {
-  const body = {
-    "@thrownErrors": { [MION_ROUTES.platformError]: returnErr }
-  };
-  respHeaders.set("content-type", "application/json; charset=utf-8");
-  const response = {
-    statusCode: returnErr.statusCode || StatusCodes.SERVER_ERROR,
-    // Global errors are always unexpected
-    hasErrors: true,
-    headers: respHeaders,
-    body,
-    rawBody: JSON.stringify(body),
-    serializer: SerializerModes.json
-    // global errors are always json
-  };
-  return response;
+	markFatal(returnErr);
+	const body = { "@thrownErrors": { [MION_ROUTES.platformError]: returnErr } };
+	respHeaders.set("x-rpc-error", errorHeaderValue(returnErr.type));
+	return {
+		statusCode: returnErr.statusCode || StatusCodes.SERVER_ERROR,
+		contentType: JSON_CONTENT_TYPE,
+		hasErrors: true,
+		fatalError: returnErr,
+		headers: respHeaders,
+		body
+	};
 }
-function onExecutableError(context, executable, err) {
-  const response = context.response;
-  const path = executable.id;
-  const rpcError = err instanceof RpcError ? err : new RpcError({
-    statusCode: StatusCodes.UNEXPECTED_ERROR,
-    publicMessage: `Unknown error in handler "${path}" of route ExecutionChain.`,
-    originalError: err,
-    type: "unknown-error"
-  });
-  if (!response.hasErrors) response.headers.set("x-rpc-error", rpcError.type);
-  response.statusCode = rpcError.statusCode ?? StatusCodes.UNEXPECTED_ERROR;
-  response.hasErrors = true;
-  const thrownErrors = context.request.thrownErrors || {};
-  thrownErrors[path] = rpcError;
-  context.request.thrownErrors = thrownErrors;
+/** An app-thrown RpcError may carry any string as its `type`, and a CR or LF there is header injection on
+*  adapters that write headers unchecked (or an ERR_INVALID_CHAR throw on node). Anything outside the token
+*  alphabet reports as `unknown-error` on the header; the body still carries the full type. */
+var HEADER_SAFE_TYPE = /^[A-Za-z0-9_.:@-]{1,128}$/;
+function errorHeaderValue(type) {
+	return HEADER_SAFE_TYPE.test(type) ? type : "unknown-error";
 }
-export {
-  getRouterFatalErrorResponse,
-  onExecutableError
-};
-//# sourceMappingURL=dispatchError.js.map
+/** Marks the response as ended by `rpcError`: the error header (first error only), the status code,
+*  `hasErrors` (what the dispatcher's skip rule reads) and `fatalError` (first one wins). Shared by the
+*  thrown path and a returned FatalError; where the error itself lands is the caller's decision.
+*  `fallbackStatus` answers when the error carries no statusCode: a thrown one is unexpected (422), a
+*  returned FatalError a declared application error (400). */
+function markResponseFailed(context, rpcError, fallbackStatus) {
+	const response = context.response;
+	if (!response.hasErrors) {
+		response.headers.set("x-rpc-error", errorHeaderValue(rpcError.type));
+		response.fatalError = rpcError;
+	}
+	response.statusCode = rpcError.statusCode ?? fallbackStatus;
+	response.hasErrors = true;
+}
+/** Whatever an adapter caught, as the mion error the wire carries. */
+function toRpcError(err) {
+	return err instanceof RpcError ? err : new FatalError({
+		publicMessage: "Unknown Error",
+		type: "unknown-error",
+		originalError: err
+	});
+}
+/** Records an undeclared error under `key` and ends the request: it lands in `@thrownErrors` untyped, sets
+*  the status and the error header, and stops every later member that does not declare `alwaysRun`.
+*  Undeclared means thrown, or returned by a raw middleware, which cannot declare a return type; a declared
+*  error is returned from a handler and goes straight into `response.body`. The key is normally the member
+*  that failed; an adapter passes its own (`mion@platformError`) for a request no member could run. */
+function recordUndeclaredError(context, key, err) {
+	const rpcError = markFatal(err instanceof RpcError ? err : new FatalError({
+		statusCode: StatusCodes.UNEXPECTED_ERROR,
+		publicMessage: `Unknown error in handler "${key}" of route ExecutionChain.`,
+		originalError: err,
+		type: "unknown-error"
+	}));
+	markResponseFailed(context, rpcError, StatusCodes.UNEXPECTED_ERROR);
+	addThrownError(context, key, rpcError);
+}
+/** Unlike recordUndeclaredError, does not end the request. */
+function addThrownError(context, key, rpcError) {
+	const thrownErrors = context.request.thrownErrors || {};
+	thrownErrors[key] = rpcError;
+	context.request.thrownErrors = thrownErrors;
+}
+function hasThrownError(context, key) {
+	const thrownErrors = context.request.thrownErrors;
+	return !!thrownErrors && Object.hasOwn(thrownErrors, key);
+}
+//#endregion
+export { addThrownError, errorHeaderValue, getRouterFatalErrorResponse, hasThrownError, markResponseFailed, recordUndeclaredError, toRpcError };
+
+//# sourceMappingURL=dispatchError.js.map

package/.dist/esm/src/lib/dispatchError.js.map

@@ -1 +1 @@
-{"version":3,"file":"dispatchError.js","sources":["../../../../src/lib/dispatchError.ts"],"sourcesContent":["import {RpcError, MION_ROUTES, Mutable, StatusCodes, SerializerModes} from '@mionjs/core';\nimport type {CallContext, MionHeaders, MionRequest, MionResponse, ResponseBody} from '../types/context.ts';\nimport type {RemoteMethod} from '../types/remoteMethods.ts';\n\n/**\n * Return a Response mion response for any error that happens before or outside the router.\n * to be used by any adapter layer. ie: node/http, aws/lambda, bun, etc.\n * Uses thrownErrors with a special platformError key to maintain consistency with route errors.\n * @param returnErr\n * @param respHeaders\n * @returns\n */\n\nexport function getRouterFatalErrorResponse(returnErr: RpcError<string>, respHeaders: MionHeaders): MionResponse {\n    // Store platform error in thrownErrors with special platformError key\n    const body: ResponseBody = {\n        '@thrownErrors': {[MION_ROUTES.platformError]: returnErr},\n    };\n    respHeaders.set('content-type', 'application/json; charset=utf-8');\n    const response: Mutable<MionResponse> = {\n        statusCode: returnErr.statusCode || StatusCodes.SERVER_ERROR, // Global errors are always unexpected\n        hasErrors: true,\n        headers: respHeaders,\n        body,\n        rawBody: JSON.stringify(body),\n        serializer: SerializerModes.json, // global errors are always json\n    };\n    return response;\n}\n\n/**\n * Handles errors during route dispatch.\n * All errors passed to this function are unexpected (thrown errors).\n * Expected errors are returned from handlers and added directly to response.body.\n * @param context\n * @param executable\n * @param err\n * @returns\n */\nexport function onExecutableError(context: CallContext, executable: RemoteMethod, err: any | RpcError<string> | Error) {\n    const response = context.response as Mutable<MionResponse>;\n    const path = executable.id;\n    const rpcError: RpcError<string> =\n        err instanceof RpcError\n            ? err\n            : new RpcError({\n                  statusCode: StatusCodes.UNEXPECTED_ERROR,\n                  publicMessage: `Unknown error in handler \"${path}\" of route ExecutionChain.`,\n                  originalError: err,\n                  type: 'unknown-error',\n              });\n    // only first error sets the error header\n    if (!response.hasErrors) response.headers.set('x-rpc-error', rpcError.type);\n    response.statusCode = rpcError.statusCode ?? StatusCodes.UNEXPECTED_ERROR;\n    response.hasErrors = true;\n    // Store unexpected errors for serialization\n    const thrownErrors = context.request.thrownErrors || ({} as Record<string, RpcError<string>>);\n    thrownErrors[path] = rpcError;\n    (context.request as Mutable<MionRequest>).thrownErrors = thrownErrors;\n}\n"],"names":[],"mappings":";AAaO,SAAS,4BAA4B,WAA6B,aAAwC;AAE7G,QAAM,OAAqB;AAAA,IACvB,iBAAiB,EAAC,CAAC,YAAY,aAAa,GAAG,UAAA;AAAA,EAAS;AAE5D,cAAY,IAAI,gBAAgB,iCAAiC;AACjE,QAAM,WAAkC;AAAA,IACpC,YAAY,UAAU,cAAc,YAAY;AAAA;AAAA,IAChD,WAAW;AAAA,IACX,SAAS;AAAA,IACT;AAAA,IACA,SAAS,KAAK,UAAU,IAAI;AAAA,IAC5B,YAAY,gBAAgB;AAAA;AAAA,EAAA;AAEhC,SAAO;AACX;AAWO,SAAS,kBAAkB,SAAsB,YAA0B,KAAqC;AACnH,QAAM,WAAW,QAAQ;AACzB,QAAM,OAAO,WAAW;AACxB,QAAM,WACF,eAAe,WACT,MACA,IAAI,SAAS;AAAA,IACT,YAAY,YAAY;AAAA,IACxB,eAAe,6BAA6B,IAAI;AAAA,IAChD,eAAe;AAAA,IACf,MAAM;AAAA,EAAA,CACT;AAEX,MAAI,CAAC,SAAS,UAAW,UAAS,QAAQ,IAAI,eAAe,SAAS,IAAI;AAC1E,WAAS,aAAa,SAAS,cAAc,YAAY;AACzD,WAAS,YAAY;AAErB,QAAM,eAAe,QAAQ,QAAQ,gBAAiB,CAAA;AACtD,eAAa,IAAI,IAAI;AACpB,UAAQ,QAAiC,eAAe;AAC7D;"}
+{"version":3,"file":"dispatchError.js","names":[],"sources":["../../../../src/lib/dispatchError.ts"],"sourcesContent":["import {RpcError, FatalError, MION_ROUTES, Mutable, StatusCodes, markFatal} from '@mionjs/core';\nimport {JSON_CONTENT_TYPE} from '../constants.ts';\nimport type {CallContext, MionHeaders, MionRequest, MionResponse, ResponseBody} from '../types/context.ts';\n\n/** The response for an error raised outside the router by any adapter; it goes in `@thrownErrors` like a route error. */\n\nexport function getRouterFatalErrorResponse(returnErr: RpcError<string>, respHeaders: MionHeaders): MionResponse {\n  // a platform error ends the request before any handler runs, so it is fatal by definition\n  markFatal(returnErr);\n  const body: ResponseBody = {\n    '@thrownErrors': {[MION_ROUTES.platformError]: returnErr},\n  };\n  respHeaders.set('x-rpc-error', errorHeaderValue(returnErr.type));\n  const response: Mutable<MionResponse> = {\n    statusCode: returnErr.statusCode || StatusCodes.SERVER_ERROR, // Global errors are always unexpected\n    contentType: JSON_CONTENT_TYPE,\n    hasErrors: true,\n    fatalError: returnErr,\n    headers: respHeaders,\n    body,\n  };\n  return response;\n}\n\n/** An app-thrown RpcError may carry any string as its `type`, and a CR or LF there is header injection on\n *  adapters that write headers unchecked (or an ERR_INVALID_CHAR throw on node). Anything outside the token\n *  alphabet reports as `unknown-error` on the header; the body still carries the full type. */\nconst HEADER_SAFE_TYPE = /^[A-Za-z0-9_.:@-]{1,128}$/;\nexport function errorHeaderValue(type: string): string {\n  return HEADER_SAFE_TYPE.test(type) ? type : 'unknown-error';\n}\n\n/** Marks the response as ended by `rpcError`: the error header (first error only), the status code,\n *  `hasErrors` (what the dispatcher's skip rule reads) and `fatalError` (first one wins). Shared by the\n *  thrown path and a returned FatalError; where the error itself lands is the caller's decision.\n *  `fallbackStatus` answers when the error carries no statusCode: a thrown one is unexpected (422), a\n *  returned FatalError a declared application error (400). */\nexport function markResponseFailed(context: CallContext, rpcError: RpcError<string>, fallbackStatus: number) {\n  const response = context.response as Mutable<MionResponse>;\n  if (!response.hasErrors) {\n    response.headers.set('x-rpc-error', errorHeaderValue(rpcError.type));\n    response.fatalError = rpcError;\n  }\n  response.statusCode = rpcError.statusCode ?? fallbackStatus;\n  response.hasErrors = true;\n}\n\n/** Whatever an adapter caught, as the mion error the wire carries. */\nexport function toRpcError(err: unknown): RpcError<string> {\n  return err instanceof RpcError\n    ? err\n    : new FatalError({publicMessage: 'Unknown Error', type: 'unknown-error', originalError: err as Error});\n}\n\n/** Records an undeclared error under `key` and ends the request: it lands in `@thrownErrors` untyped, sets\n *  the status and the error header, and stops every later member that does not declare `alwaysRun`.\n *  Undeclared means thrown, or returned by a raw middleware, which cannot declare a return type; a declared\n *  error is returned from a handler and goes straight into `response.body`. The key is normally the member\n *  that failed; an adapter passes its own (`mion@platformError`) for a request no member could run. */\nexport function recordUndeclaredError(context: CallContext, key: string, err: any) {\n  const rpcError: RpcError<string> = markFatal(\n    err instanceof RpcError\n      ? err\n      : new FatalError({\n          statusCode: StatusCodes.UNEXPECTED_ERROR,\n          publicMessage: `Unknown error in handler \"${key}\" of route ExecutionChain.`,\n          originalError: err,\n          type: 'unknown-error',\n        })\n  );\n  markResponseFailed(context, rpcError, StatusCodes.UNEXPECTED_ERROR);\n  addThrownError(context, key, rpcError);\n}\n\n/** Unlike recordUndeclaredError, does not end the request. */\nexport function addThrownError(context: CallContext, key: string, rpcError: RpcError<string>) {\n  // tsgo types `readonly || mutable` as readonly, so casting only the `{}` fallback still forbids the write.\n  const thrownErrors = (context.request.thrownErrors || {}) as Record<string, RpcError<string>>;\n  thrownErrors[key] = rpcError;\n  (context.request as Mutable<MionRequest>).thrownErrors = thrownErrors;\n}\n\nexport function hasThrownError(context: CallContext, key: string): boolean {\n  const thrownErrors = context.request.thrownErrors;\n  return !!thrownErrors && Object.hasOwn(thrownErrors, key);\n}\n"],"mappings":";;;;AAMA,SAAgB,4BAA4B,WAA6B,aAAwC;CAE/G,UAAU,SAAS;CACnB,MAAM,OAAqB,EACzB,iBAAiB,GAAE,YAAY,gBAAgB,UAAS,EAC1D;CACA,YAAY,IAAI,eAAe,iBAAiB,UAAU,IAAI,CAAC;CAS/D,OAAO;EAPL,YAAY,UAAU,cAAc,YAAY;EAChD,aAAa;EACb,WAAW;EACX,YAAY;EACZ,SAAS;EACT;CAEK;AACT;;;;AAKA,IAAM,mBAAmB;AACzB,SAAgB,iBAAiB,MAAsB;CACrD,OAAO,iBAAiB,KAAK,IAAI,IAAI,OAAO;AAC9C;;;;;;AAOA,SAAgB,mBAAmB,SAAsB,UAA4B,gBAAwB;CAC3G,MAAM,WAAW,QAAQ;CACzB,IAAI,CAAC,SAAS,WAAW;EACvB,SAAS,QAAQ,IAAI,eAAe,iBAAiB,SAAS,IAAI,CAAC;EACnE,SAAS,aAAa;CACxB;CACA,SAAS,aAAa,SAAS,cAAc;CAC7C,SAAS,YAAY;AACvB;;AAGA,SAAgB,WAAW,KAAgC;CACzD,OAAO,eAAe,WAClB,MACA,IAAI,WAAW;EAAC,eAAe;EAAiB,MAAM;EAAiB,eAAe;CAAY,CAAC;AACzG;;;;;;AAOA,SAAgB,sBAAsB,SAAsB,KAAa,KAAU;CACjF,MAAM,WAA6B,UACjC,eAAe,WACX,MACA,IAAI,WAAW;EACb,YAAY,YAAY;EACxB,eAAe,6BAA6B,IAAI;EAChD,eAAe;EACf,MAAM;CACR,CAAC,CACP;CACA,mBAAmB,SAAS,UAAU,YAAY,gBAAgB;CAClE,eAAe,SAAS,KAAK,QAAQ;AACvC;;AAGA,SAAgB,eAAe,SAAsB,KAAa,UAA4B;CAE5F,MAAM,eAAgB,QAAQ,QAAQ,gBAAgB,CAAC;CACvD,aAAa,OAAO;CACpB,QAAS,QAAiC,eAAe;AAC3D;AAEA,SAAgB,eAAe,SAAsB,KAAsB;CACzE,MAAM,eAAe,QAAQ,QAAQ;CACrC,OAAO,CAAC,CAAC,gBAAgB,OAAO,OAAO,cAAc,GAAG;AAC1D"}

package/.dist/esm/src/lib/handlers.d.ts

@@ -1,10 +1,15 @@
-import { HeadersMiddleFnOptions, MiddleFnOptions, RawMiddleFnOptions, RouteOptions } from '../types/remoteMethods.ts';
-import { Handler, HeaderHandler, RawMiddleFnHandler } from '../types/handlers.ts';
-import { HeadersMiddleFnDef, MiddleFnDef, RawMiddleFnDef, RouteDef } from '../types/definitions.ts';
-export declare function route<H extends Handler>(handler: H, opts?: RouteOptions): RouteDef<H>;
-export declare function query<H extends Handler>(handler: H, opts?: RouteOptions): RouteDef<H>;
-export declare function mutation<H extends Handler>(handler: H, opts?: RouteOptions): RouteDef<H>;
-export declare function middleFn<H extends Handler>(handler: H, opts?: MiddleFnOptions): MiddleFnDef<H>;
-export declare function headersFn<H extends HeaderHandler>(handler: H, opts?: HeadersMiddleFnOptions): HeadersMiddleFnDef<H>;
-export declare function rawMiddleFn<H extends RawMiddleFnHandler>(handler: H, opts?: RawMiddleFnOptions): RawMiddleFnDef<H>;
+import { HeadersMiddlewareHelper, MiddlewareHelper, RawMiddlewareHelper, RouteHelper, RouterOptionsInput } from '../types/mionRouter.ts';
+import { CallContext } from '../types/context.ts';
+export declare const route: RouteHelper<RouterOptionsInput>;
+export declare const query: RouteHelper<Partial<import('../types/general.ts').RouterOptions<any, any>>, false>;
+export declare const mutation: RouteHelper<Partial<import('../types/general.ts').RouterOptions<any, any>>, true>;
+export declare const middleware: MiddlewareHelper<RouterOptionsInput>;
+export declare const headersMiddleware: HeadersMiddlewareHelper<RouterOptionsInput>;
+export declare const rawMiddleware: RawMiddlewareHelper<RouterOptionsInput>;
+type OnEveryCall = (ctx: CallContext) => void;
+export declare function markOnDemand<Def extends object>(def: Def, onEveryCall?: OnEveryCall): Def;
+export declare function isOnDemandMiddleware(def: object): boolean;
+export declare function getOnEveryCall(def: object): OnEveryCall | undefined;
+export declare const mionInternalRouteIds: ReadonlySet<string>;
+export {};
 //# sourceMappingURL=handlers.d.ts.map

package/.dist/esm/src/lib/handlers.js

@@ -1,52 +1,89 @@
-import { HandlerType } from "@mionjs/core";
-function route(handler, opts) {
-  return {
-    type: HandlerType.route,
-    handler,
-    options: opts
-  };
+import { HandlerType, MION_ROUTES } from "@mionjs/core";
+//#region src/lib/handlers.ts
+var route = (handler, opts, paramsFns, returnFns, paramsId, returnId, isAsyncId, syncId) => ({
+	type: HandlerType.route,
+	handler,
+	options: opts,
+	rtFns: {
+		paramsFns,
+		returnFns,
+		paramsId,
+		returnId,
+		isAsyncId,
+		syncId
+	}
+});
+/** Typed as the same helper as `route()`, so both keep the marker signature the scanner reads at the call site. */
+function routeWithMutation(isMutation) {
+	return (handler, opts, paramsFns, returnFns, paramsId, returnId, isAsyncId, syncId) => ({
+		type: HandlerType.route,
+		handler,
+		options: {
+			...opts,
+			isMutation
+		},
+		rtFns: {
+			paramsFns,
+			returnFns,
+			paramsId,
+			returnId,
+			isAsyncId,
+			syncId
+		}
+	});
 }
-function query(handler, opts) {
-  return {
-    type: HandlerType.route,
-    handler,
-    options: { ...opts, isMutation: false }
-  };
+/** Route handler for read-only queries. Uses GET with ?data=base64url on the client when payload fits. */
+var query = routeWithMutation(false);
+var mutation = routeWithMutation(true);
+var middleware = (handler, opts, paramsFns, returnFns, paramsId, returnId, isAsyncId, syncId) => ({
+	type: HandlerType.middleware,
+	handler,
+	options: opts,
+	rtFns: {
+		paramsFns,
+		returnFns,
+		paramsId,
+		returnId,
+		isAsyncId,
+		syncId
+	}
+});
+var headersMiddleware = (handler, opts, headersFns, paramsFns, returnFns, headersId, paramsId, returnId, isAsyncId, syncId) => ({
+	type: HandlerType.headersMiddleware,
+	handler,
+	options: opts,
+	rtFns: {
+		paramsFns,
+		returnFns,
+		paramsId,
+		returnId,
+		isAsyncId,
+		syncId,
+		headersFns,
+		headersId
+	}
+});
+var rawMiddleware = (handler, opts) => ({
+	type: HandlerType.rawMiddleware,
+	handler,
+	options: opts
+});
+/** Each on-demand middleware, with what it does on every call even without its slot. */
+var onDemandMiddlewares = /* @__PURE__ */ new WeakMap();
+/** Internal: the middleware runs only when the request body carries its slot, so an absent slot costs nothing */
+function markOnDemand(def, onEveryCall) {
+	onDemandMiddlewares.set(def, onEveryCall);
+	return def;
 }
-function mutation(handler, opts) {
-  return {
-    type: HandlerType.route,
-    handler,
-    options: { ...opts, isMutation: true }
-  };
+function isOnDemandMiddleware(def) {
+	return onDemandMiddlewares.has(def);
 }
-function middleFn(handler, opts) {
-  return {
-    type: HandlerType.middleFn,
-    handler,
-    options: opts
-  };
+function getOnEveryCall(def) {
+	return onDemandMiddlewares.get(def);
 }
-function headersFn(handler, opts) {
-  return {
-    type: HandlerType.headersMiddleFn,
-    handler,
-    options: opts
-  };
-}
-function rawMiddleFn(handler, opts) {
-  return {
-    type: HandlerType.rawMiddleFn,
-    handler,
-    options: opts
-  };
-}
-export {
-  headersFn,
-  middleFn,
-  mutation,
-  query,
-  rawMiddleFn,
-  route
-};
-//# sourceMappingURL=handlers.js.map
+/** mion's own ids, never exposed to clients */
+var mionInternalRouteIds = new Set(Object.values(MION_ROUTES));
+//#endregion
+export { getOnEveryCall, headersMiddleware, isOnDemandMiddleware, markOnDemand, middleware, mionInternalRouteIds, mutation, query, rawMiddleware, route };
+
+//# sourceMappingURL=handlers.js.map

package/.dist/esm/src/lib/handlers.js.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.js","sources":["../../../../src/lib/handlers.ts"],"sourcesContent":["/* ########\n * 2024 mion\n * Author: Ma-jerez\n * License: MIT\n * The software is provided \"as is\", without warranty of any kind.\n * ######## */\n\nimport {HeadersMiddleFnOptions, MiddleFnOptions, RawMiddleFnOptions, RouteOptions} from '../types/remoteMethods.ts';\nimport {HandlerType} from '@mionjs/core';\nimport {Handler, HeaderHandler, RawMiddleFnHandler} from '../types/handlers.ts';\nimport {HeadersMiddleFnDef, MiddleFnDef, RawMiddleFnDef, RouteDef} from '../types/definitions.ts';\n\n// ############# Route & MiddleFns initialization #############\n// these functions are just helpers to initialize the route & middleFns objects and keep route definitions clean\n\nexport function route<H extends Handler>(handler: H, opts?: RouteOptions): RouteDef<H> {\n    return {\n        type: HandlerType.route,\n        handler,\n        options: opts,\n    };\n}\n\n/** Route handler for read-only queries. Uses GET with ?data=base64url on the client when payload fits. */\nexport function query<H extends Handler>(handler: H, opts?: RouteOptions): RouteDef<H> {\n    return {\n        type: HandlerType.route,\n        handler,\n        options: {...opts, isMutation: false},\n    };\n}\n\n/** Route handler for mutations. Explicit alias for route() with isMutation: true. */\nexport function mutation<H extends Handler>(handler: H, opts?: RouteOptions): RouteDef<H> {\n    return {\n        type: HandlerType.route,\n        handler,\n        options: {...opts, isMutation: true},\n    };\n}\n\nexport function middleFn<H extends Handler>(handler: H, opts?: MiddleFnOptions): MiddleFnDef<H> {\n    return {\n        type: HandlerType.middleFn,\n        handler,\n        options: opts,\n    };\n}\n\n/**\n * MiddleFn for handling HTTP header parameters\n * Used to define middleFns that receive values from HTTP headers\n *\n * @example\n * ```ts\n * headersFn(['authorization'], (ctx, token: string): void => {\n *   // token contains the value of the 'authorization' header\n * })\n * ```\n */\nexport function headersFn<H extends HeaderHandler>(handler: H, opts?: HeadersMiddleFnOptions): HeadersMiddleFnDef<H> {\n    return {\n        type: HandlerType.headersMiddleFn,\n        handler,\n        options: opts,\n    };\n}\n\nexport function rawMiddleFn<H extends RawMiddleFnHandler>(handler: H, opts?: RawMiddleFnOptions): RawMiddleFnDef<H> {\n    return {\n        type: HandlerType.rawMiddleFn,\n        handler,\n        options: opts,\n    };\n}\n"],"names":[],"mappings":";AAeO,SAAS,MAAyB,SAAY,MAAkC;AACnF,SAAO;AAAA,IACH,MAAM,YAAY;AAAA,IAClB;AAAA,IACA,SAAS;AAAA,EAAA;AAEjB;AAGO,SAAS,MAAyB,SAAY,MAAkC;AACnF,SAAO;AAAA,IACH,MAAM,YAAY;AAAA,IAClB;AAAA,IACA,SAAS,EAAC,GAAG,MAAM,YAAY,MAAA;AAAA,EAAK;AAE5C;AAGO,SAAS,SAA4B,SAAY,MAAkC;AACtF,SAAO;AAAA,IACH,MAAM,YAAY;AAAA,IAClB;AAAA,IACA,SAAS,EAAC,GAAG,MAAM,YAAY,KAAA;AAAA,EAAI;AAE3C;AAEO,SAAS,SAA4B,SAAY,MAAwC;AAC5F,SAAO;AAAA,IACH,MAAM,YAAY;AAAA,IAClB;AAAA,IACA,SAAS;AAAA,EAAA;AAEjB;AAaO,SAAS,UAAmC,SAAY,MAAsD;AACjH,SAAO;AAAA,IACH,MAAM,YAAY;AAAA,IAClB;AAAA,IACA,SAAS;AAAA,EAAA;AAEjB;AAEO,SAAS,YAA0C,SAAY,MAA8C;AAChH,SAAO;AAAA,IACH,MAAM,YAAY;AAAA,IAClB;AAAA,IACA,SAAS;AAAA,EAAA;AAEjB;"}
+{"version":3,"file":"handlers.js","names":[],"sources":["../../../../src/lib/handlers.ts"],"sourcesContent":["/* ########\n * 2024 mion\n * Author: Ma-jerez\n * License: MIT\n * The software is provided \"as is\", without warranty of any kind.\n * ######## */\n\nimport {HandlerType, MION_ROUTES} from '@mionjs/core';\nimport type {\n  HeadersMiddlewareHelper,\n  MiddlewareHelper,\n  PinnedMutation,\n  RawMiddlewareHelper,\n  RouteHelper,\n  RouterOptionsInput,\n} from '../types/mionRouter.ts';\nimport type {CallContext} from '../types/context.ts';\n\n// ############# Route & Middlewares initialization (INTERNAL) #############\n// These bodies initialize the definition objects AND are the mion injection points: the trailing marker\n// params are filled at BUILD TIME by @mionjs/devtools. Not exported from the package, consumers reach\n// them as the closures `createMionRouter()` returns; only mion's own middlewares and its error / serializer routes\n// call them directly, each pinning its own `encoder`.\n// ⚠️ There is NO signature here on purpose: each body is TYPED BY its helper interface in\n// types/mionRouter.ts, the one place a helper signature is written, so there is no second surface to keep\n// in step. `RouterOptionsInput` is the widest options shape; `createMionRouter` narrows each helper to\n// its own `O` so a declaration reads the factory's options.\n\nexport const route: RouteHelper<RouterOptionsInput> = (\n  handler,\n  opts,\n  paramsFns,\n  returnFns,\n  paramsId,\n  returnId,\n  isAsyncId,\n  syncId\n) => ({\n  type: HandlerType.route,\n  handler,\n  options: opts,\n  rtFns: {paramsFns, returnFns, paramsId, returnId, isAsyncId, syncId},\n});\n\n/** Typed as the same helper as `route()`, so both keep the marker signature the scanner reads at the call site. */\nfunction routeWithMutation<M extends boolean>(isMutation: M): RouteHelper<RouterOptionsInput, M> {\n  return (handler, opts, paramsFns, returnFns, paramsId, returnId, isAsyncId, syncId) => ({\n    type: HandlerType.route,\n    handler,\n    options: {...opts, isMutation} as PinnedMutation<typeof opts & object, M>,\n    rtFns: {paramsFns, returnFns, paramsId, returnId, isAsyncId, syncId},\n  });\n}\n\n/** Route handler for read-only queries. Uses GET with ?data=base64url on the client when payload fits. */\nexport const query = routeWithMutation(false);\n\nexport const mutation = routeWithMutation(true);\n\nexport const middleware: MiddlewareHelper<RouterOptionsInput> = (\n  handler,\n  opts,\n  paramsFns,\n  returnFns,\n  paramsId,\n  returnId,\n  isAsyncId,\n  syncId\n) => ({\n  type: HandlerType.middleware,\n  handler,\n  options: opts,\n  rtFns: {paramsFns, returnFns, paramsId, returnId, isAsyncId, syncId},\n});\n\nexport const headersMiddleware: HeadersMiddlewareHelper<RouterOptionsInput> = (\n  handler,\n  opts,\n  headersFns,\n  paramsFns,\n  returnFns,\n  headersId,\n  paramsId,\n  returnId,\n  isAsyncId,\n  syncId\n) => ({\n  type: HandlerType.headersMiddleware,\n  handler,\n  options: opts,\n  rtFns: {paramsFns, returnFns, paramsId, returnId, isAsyncId, syncId, headersFns, headersId},\n});\n\nexport const rawMiddleware: RawMiddlewareHelper<RouterOptionsInput> = (handler, opts) => ({\n  type: HandlerType.rawMiddleware,\n  handler,\n  options: opts,\n});\n\n/** Each on-demand middleware, with what it does on every call even without its slot. */\nconst onDemandMiddlewares = new WeakMap<object, OnEveryCall | undefined>();\ntype OnEveryCall = (ctx: CallContext) => void;\n\n/** Internal: the middleware runs only when the request body carries its slot, so an absent slot costs nothing */\nexport function markOnDemand<Def extends object>(def: Def, onEveryCall?: OnEveryCall): Def {\n  onDemandMiddlewares.set(def, onEveryCall);\n  return def;\n}\n\nexport function isOnDemandMiddleware(def: object): boolean {\n  return onDemandMiddlewares.has(def);\n}\n\nexport function getOnEveryCall(def: object): OnEveryCall | undefined {\n  return onDemandMiddlewares.get(def);\n}\n\n/** mion's own ids, never exposed to clients */\nexport const mionInternalRouteIds: ReadonlySet<string> = new Set(Object.values(MION_ROUTES));\n"],"mappings":";;AA4BA,IAAa,SACX,SACA,MACA,WACA,WACA,UACA,UACA,WACA,YACI;CACJ,MAAM,YAAY;CAClB;CACA,SAAS;CACT,OAAO;EAAC;EAAW;EAAW;EAAU;EAAU;EAAW;CAAM;AACrE;;AAGA,SAAS,kBAAqC,YAAmD;CAC/F,QAAQ,SAAS,MAAM,WAAW,WAAW,UAAU,UAAU,WAAW,YAAY;EACtF,MAAM,YAAY;EAClB;EACA,SAAS;GAAC,GAAG;GAAM;EAAU;EAC7B,OAAO;GAAC;GAAW;GAAW;GAAU;GAAU;GAAW;EAAM;CACrE;AACF;;AAGA,IAAa,QAAQ,kBAAkB,KAAK;AAE5C,IAAa,WAAW,kBAAkB,IAAI;AAE9C,IAAa,cACX,SACA,MACA,WACA,WACA,UACA,UACA,WACA,YACI;CACJ,MAAM,YAAY;CAClB;CACA,SAAS;CACT,OAAO;EAAC;EAAW;EAAW;EAAU;EAAU;EAAW;CAAM;AACrE;AAEA,IAAa,qBACX,SACA,MACA,YACA,WACA,WACA,WACA,UACA,UACA,WACA,YACI;CACJ,MAAM,YAAY;CAClB;CACA,SAAS;CACT,OAAO;EAAC;EAAW;EAAW;EAAU;EAAU;EAAW;EAAQ;EAAY;CAAS;AAC5F;AAEA,IAAa,iBAA0D,SAAS,UAAU;CACxF,MAAM,YAAY;CAClB;CACA,SAAS;AACX;;AAGA,IAAM,sCAAsB,IAAI,QAAyC;;AAIzE,SAAgB,aAAiC,KAAU,aAAgC;CACzF,oBAAoB,IAAI,KAAK,WAAW;CACxC,OAAO;AACT;AAEA,SAAgB,qBAAqB,KAAsB;CACzD,OAAO,oBAAoB,IAAI,GAAG;AACpC;AAEA,SAAgB,eAAe,KAAsC;CACnE,OAAO,oBAAoB,IAAI,GAAG;AACpC;;AAGA,IAAa,uBAA4C,IAAI,IAAI,OAAO,OAAO,WAAW,CAAC"}

package/.dist/esm/src/lib/headers.d.ts

@@ -1,3 +1,42 @@
-import { MionHeaders } from '../types/context.ts';
+import { MionHeaders, MionResponse, PooledHeaders, ResponseDefaults } from '../types/context.ts';
+type HeadersRecord = Record<string, string | string[]>;
+declare class MionHeadersImpl implements MionHeaders {
+    protected headers: HeadersRecord;
+    unused: boolean;
+    constructor(headers: HeadersRecord);
+    append(name: string, value: string): void;
+    delete(name: string): void;
+    get(name: string): string | undefined | null;
+    set(name: string, value: string): void;
+    has(name: string): boolean;
+    entries(): IterableIterator<[string, string]>;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<string>;
+}
+export declare class RecordResponseHeaders extends MionHeadersImpl implements PooledHeaders {
+    readonly defaults: ResponseDefaults;
+    constructor(defaults: ResponseDefaults);
+    append(name: string, value: string): void;
+    forEach(visit: (name: string, value: string | string[]) => void): void;
+}
+export declare class FetchResponseHeaders implements PooledHeaders {
+    readonly defaults: ResponseDefaults;
+    readonly native: import('undici-types').Headers;
+    unused: boolean;
+    constructor(defaults: ResponseDefaults);
+    set(name: string, value: string): void;
+    append(name: string, value: string): void;
+    delete(name: string): void;
+    get(name: string): string | null;
+    has(name: string): boolean;
+    entries(): IterableIterator<[string, string]>;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<string>;
+}
+export declare const getDefaultHeaders: () => RecordResponseHeaders;
+export declare const getDefaultFetchHeaders: () => FetchResponseHeaders;
+export declare const releaseHeaders: (headers: RecordResponseHeaders) => void;
+export declare function replyFetch(mionResp: MionResponse, headers: FetchResponseHeaders): Response;
 export declare function headersFromRecord(headersObj: Record<string, string>, skipToLower?: boolean): MionHeaders;
+export {};
 //# sourceMappingURL=headers.d.ts.map

package/.dist/esm/src/lib/headers.js

@@ -1,64 +1,174 @@
-class MionHeadersImpl {
-  constructor(headers) {
-    this.headers = headers;
-  }
-  append(name, value) {
-    const nl = name.toLowerCase();
-    const existing = this.headers[nl];
-    const headerValue = toSingleHeader(value);
-    if (existing) {
-      this.headers[nl] = `${existing}, ${headerValue}`;
-    } else {
-      this.headers[nl] = headerValue;
-    }
-  }
-  delete(name) {
-    const nl = name.toLowerCase();
-    delete this.headers[nl];
-  }
-  get(name) {
-    const nl = name.toLowerCase();
-    return this.headers[nl];
-  }
-  set(name, value) {
-    const ln = name.toLowerCase();
-    this.headers[ln] = value;
-  }
-  has(name) {
-    const nl = name.toLowerCase();
-    return !!this.headers[nl];
-  }
-  entries() {
-    return new Map(Object.entries(this.headers)).entries();
-  }
-  keys() {
-    return new Map(Object.entries(this.headers)).keys();
-  }
-  values() {
-    return new Map(Object.entries(this.headers)).values();
-  }
+import "../constants.js";
+import { getResponseDefaults } from "../router.js";
+//#region src/lib/headers.ts
+var PROTO_KEY = "__proto__";
+/** Case-insensitive HTTP headers, like the fetch Headers API but optimized for performance.
+*  https://developer.mozilla.org/en-US/docs/Web/API/Headers */
+var MionHeadersImpl = class {
+	headers;
+	/** Read by the response headers pool only; request headers ignore it. */
+	unused = true;
+	constructor(headers) {
+		this.headers = headers;
+	}
+	append(name, value) {
+		this.unused = false;
+		const nl = name.toLowerCase();
+		if (nl === PROTO_KEY) return;
+		const existing = readHeader(this.headers, nl);
+		const headerValue = toSingleHeader(value);
+		if (existing) this.headers[nl] = `${existing}, ${headerValue}`;
+		else this.headers[nl] = headerValue;
+	}
+	delete(name) {
+		this.unused = false;
+		delete this.headers[name.toLowerCase()];
+	}
+	get(name) {
+		return readHeader(this.headers, name.toLowerCase());
+	}
+	set(name, value) {
+		this.unused = false;
+		const ln = name.toLowerCase();
+		if (ln === PROTO_KEY) return;
+		this.headers[ln] = value;
+	}
+	has(name) {
+		return !!readHeader(this.headers, name.toLowerCase());
+	}
+	entries() {
+		return Object.entries(this.headers).map(([name, value]) => [name, joined(value)]).values();
+	}
+	keys() {
+		return new Map(Object.entries(this.headers)).keys();
+	}
+	values() {
+		return Object.values(this.headers).map(joined).values();
+	}
+};
+/** Response headers over a copy of the defaults, for an adapter that answers from a header record (uws, aws). */
+var RecordResponseHeaders = class extends MionHeadersImpl {
+	defaults;
+	constructor(defaults) {
+		super({ ...defaults });
+		this.defaults = defaults;
+	}
+	/** Keeps a repeated name's values apart, never joined: the adapter writes them its own way. */
+	append(name, value) {
+		this.unused = false;
+		const key = name.toLowerCase();
+		if (key === PROTO_KEY) return;
+		const current = this.headers[key];
+		if (Array.isArray(current)) current.push(value);
+		else if (typeof current === "string" && current) this.headers[key] = [current, value];
+		else this.headers[key] = value;
+	}
+	/** Walks the headers with no pair array per header; a repeated name gives its values apart. */
+	forEach(visit) {
+		for (const name in this.headers) visit(name, this.headers[name]);
+	}
+};
+/** The response headers of the fetch adapters (bun, cloudflare, vercel). */
+var FetchResponseHeaders = class {
+	defaults;
+	/** What the reply hands to `Response`, which copies it. */
+	native = new Headers();
+	unused = true;
+	constructor(defaults) {
+		this.defaults = defaults;
+		for (const name in defaults) this.native.set(name, defaults[name]);
+	}
+	set(name, value) {
+		this.unused = false;
+		this.native.set(name, value);
+	}
+	append(name, value) {
+		this.unused = false;
+		this.native.append(name, value);
+	}
+	delete(name) {
+		this.unused = false;
+		this.native.delete(name);
+	}
+	get(name) {
+		return this.native.get(name);
+	}
+	has(name) {
+		return this.native.has(name);
+	}
+	entries() {
+		return this.native.entries();
+	}
+	keys() {
+		return this.native.keys();
+	}
+	values() {
+		return this.native.values();
+	}
+};
+var MAX_UNUSED_HEADERS = 256;
+var unusedRecordHeaders = [];
+var unusedFetchHeaders = [];
+var newRecordHeaders = (defaults) => new RecordResponseHeaders(defaults);
+var newFetchHeaders = (defaults) => new FetchResponseHeaders(defaults);
+/** Response headers holding the defaults and nothing else, from the pool or new. */
+var getDefaultHeaders = () => takeUnused(unusedRecordHeaders, newRecordHeaders);
+/** Like `getDefaultHeaders`, over a native `Headers` for the fetch adapters. */
+var getDefaultFetchHeaders = () => takeUnused(unusedFetchHeaders, newFetchHeaders);
+/** Gives headers back once the reply is sent; written ones are dropped. */
+var releaseHeaders = (headers) => giveBackUnused(unusedRecordHeaders, headers);
+function takeUnused(pool, create) {
+	const defaults = getResponseDefaults();
+	const headers = pool.pop();
+	if (headers?.defaults === defaults) return headers;
+	pool.length = 0;
+	return create(defaults);
+}
+function giveBackUnused(pool, headers) {
+	if (headers.unused && pool.length < MAX_UNUSED_HEADERS) pool.push(headers);
 }
+function replyFetch(mionResp, headers) {
+	if (!headers.unused || mionResp.contentType !== "application/json; charset=utf-8") headers.set("content-type", mionResp.contentType);
+	const response = Response.json(mionResp.body, {
+		status: mionResp.statusCode,
+		headers: headers.native
+	});
+	giveBackUnused(unusedFetchHeaders, headers);
+	return response;
+}
+/** A fetch-like (not identical) Headers object over a header record, for an incoming request carrying its
+*  headers as an object: IncomingMessage.headers, ApiGatewayEvent.headers.
+*  https://developer.mozilla.org/en-US/docs/Web/API/Headers */
 function headersFromRecord(headersObj, skipToLower = false) {
-  const headers = parseHeaders(headersObj, skipToLower);
-  return new MionHeadersImpl(headers);
+	return new MionHeadersImpl(parseHeaders(headersObj, skipToLower));
+}
+/** A header value, or undefined for a name the record does not carry as an own string (a prototype
+*  hit is a function or an object). A platform record may hold an array (node's `set-cookie`). */
+function readHeader(headers, lowerName) {
+	const value = headers[lowerName];
+	if (typeof value === "string") return value;
+	return Array.isArray(value) ? value.join(", ") : void 0;
+}
+function joined(value) {
+	return Array.isArray(value) ? value.join(", ") : value;
 }
 function toSingleHeader(value) {
-  if (Array.isArray(value)) return value.join(", ");
-  return value;
+	if (Array.isArray(value)) return value.join(", ");
+	return value;
 }
 function parseHeaders(headersObj, skipToLower = false) {
-  if (skipToLower) return headersObj;
-  const entries = Object.entries(headersObj);
-  const headers = {};
-  for (let i = 0; i < entries.length; i++) {
-    const [name, value] = entries[i];
-    if (!value) continue;
-    const ln = name.toLowerCase();
-    headers[ln] = toSingleHeader(value);
-  }
-  return headers;
+	if (skipToLower) return headersObj;
+	const entries = Object.entries(headersObj);
+	const headers = Object.create(null);
+	for (let i = 0; i < entries.length; i++) {
+		const [name, value] = entries[i];
+		if (!value) continue;
+		const ln = name.toLowerCase();
+		headers[ln] = toSingleHeader(value);
+	}
+	return headers;
 }
-export {
-  headersFromRecord
-};
-//# sourceMappingURL=headers.js.map
+//#endregion
+export { FetchResponseHeaders, RecordResponseHeaders, getDefaultFetchHeaders, getDefaultHeaders, headersFromRecord, releaseHeaders, replyFetch };
+
+//# sourceMappingURL=headers.js.map