@molecule/api-resource 1.0.7 → 1.1.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-26T04:23:42.740Z
+Generated: 2026-11-06T22:08:33.809Z
 -->
 
 # @molecule/api-resource
@@ -30,6 +30,33 @@ res.status(statusCode).send(body)
 Monkey-patching `res.json` (or `res.send`/`res.end`) to re-shape a handler's answer intercepts
 nothing the handler produces, so the request it was meant to answer is left unanswered and hangs.
 
+**A different request or response envelope is configuration.** Pass
+`mapRequest` and/or `mapResponse` as the second argument to `createRequestHandler`.
+Both may be asynchronous. The existing handler still validates and authorizes
+the adapted input. A response mapper sees the handler's errors and partial
+responses too: preserve them and its headers instead of treating every result
+as a success. `adaptHandler(handler, options)` offers the same mappings when
+another HTTP adapter will send the structured response.
+A request mapper can return `{ response: { statusCode, body } }` to answer
+before calling the handler, for example when extra validation fails or a
+filter lookup finds nothing. That response still passes through mapResponse.
+
+```typescript
+import { createRequestHandler } from '@molecule/api-resource'
+import { handlers } from '@molecule/api-resource-user'
+
+const register = createRequestHandler(handlers.create({ name: 'User', tableName: 'users' }), {
+  // Return overrides. The adapter retains framework methods and getters.
+  mapRequest: (req) => ({ body: req.body?.account }),
+  mapResponse: (result) =>
+    result.statusCode === 201
+      ? { ...result, body: { account: result.body.props, accessToken: result.body.accessToken } }
+      : result,
+})
+// Keep the route's existing rate limiter and authorization around register.
+// No mapping is inferred: a flat-body API keeps createRequestHandler(handler).
+```
+
 > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
 > It is written to be read by coding agents as much as by people, and is generated from this
 > package's source — edit `src/index.ts` JSDoc, not this file.
@@ -114,6 +141,38 @@ interface Response {
 }
 ```
 
+#### `RequestHandlerOptions`
+
+Per-route wire-format adapters. Validation and authorization still belong to
+the original handler. Omit these options to retain its native contract.
+
+```typescript
+interface RequestHandlerOptions {
+  /**
+   * Return the fields to replace before the handler validates the request.
+   * The adapter preserves the original request's methods and getters, and does
+   * not mutate it. Returning `{ body }` or `{ query }` is sufficient, including
+   * frameworks whose request properties have read-only accessors.
+   * Return `{ response: { statusCode, headers?, body } }` to answer before the
+   * handler runs. That result still goes through mapResponse, with the original request.
+   */
+  mapRequest?: (
+    req: MoleculeRequest,
+    res: MoleculeResponse,
+  ) => RequestMappingResult | Promise<RequestMappingResult>
+  /**
+   * Adapt the returned status, headers or body. This sees error and partial
+   * responses too: narrow the success shape before changing it, and preserve
+   * headers with `{ ...response, body }`. It never runs for fall-through.
+   */
+  mapResponse?: (
+    response: Response,
+    req: MoleculeRequest,
+    res: MoleculeResponse,
+  ) => Response | Promise<Response>
+}
+```
+
 #### `MoleculeRequest`
 
 Framework-agnostic HTTP request interface. Structurally compatible with Express's
@@ -258,6 +317,16 @@ type Handler = (
 - `req` — The incoming HTTP request.
 - `res` — The HTTP response (available but handlers should return a Response instead of calling `res` directly).
 
+#### `RequestMappingResult`
+
+Request overrides, or an explicit response that stops before the handler.
+The response form supports extra validation and unresolved external filters
+without writing data or inventing a placeholder identifier.
+
+```typescript
+type RequestMappingResult = Partial<MoleculeRequest> | { response: Response }
+```
+
 #### `MoleculeNextFunction`
 
 Framework-agnostic next function. Call with no arguments to pass to the next
@@ -333,7 +402,22 @@ function create<
 
 **Returns:** A curried async function that accepts `{ props, id? }` and returns a `{ statusCode, body }` response.
 
-#### `createRequestHandler(handler)`
+#### `adaptHandler(handler, options)`
+
+Compose wire-format adapters around a structured resource handler without
+sending its response. The response mapper receives the adapted request.
+Exceptions propagate to the caller's normal error boundary.
+
+```typescript
+function adaptHandler(handler: Handler, options?: RequestHandlerOptions): Handler
+```
+
+- `handler` — The existing resource handler, including its checks.
+- `options` — Request and response mappings for this route only.
+
+**Returns:** A structured handler that keeps null/undefined fall-through intact.
+
+#### `createRequestHandler(handler, options)`
 
 Wraps a resource handler into Express-compatible middleware. Calls the handler,
 then applies `statusCode`, `headers`, and `body` to the response. If the handler
@@ -343,10 +427,12 @@ i18n-translated error messages.
 ```typescript
 function createRequestHandler(
   handler: Handler,
+  options?: RequestHandlerOptions,
 ): (req: MoleculeRequest, res: MoleculeResponse, next: MoleculeNextFunction) => Promise<void>
 ```
 
 - `handler` — The resource handler function to wrap.
+- `options` — Optional wire-format mappings; neither mutates the shared handler.
 
 **Returns:** An Express-compatible middleware function `(req, res, next) => void`.
 

package/dist/createRequestHandler.d.ts

@@ -35,6 +35,45 @@ export interface Response {
      */
     body: any;
 }
+/**
+ * Request overrides, or an explicit response that stops before the handler.
+ * The response form supports extra validation and unresolved external filters
+ * without writing data or inventing a placeholder identifier.
+ */
+export type RequestMappingResult = Partial<MoleculeRequest> | {
+    response: Response;
+};
+/**
+ * Per-route wire-format adapters. Validation and authorization still belong to
+ * the original handler. Omit these options to retain its native contract.
+ */
+export interface RequestHandlerOptions {
+    /**
+     * Return the fields to replace before the handler validates the request.
+     * The adapter preserves the original request's methods and getters, and does
+     * not mutate it. Returning `{ body }` or `{ query }` is sufficient, including
+     * frameworks whose request properties have read-only accessors.
+     * Return `{ response: { statusCode, headers?, body } }` to answer before the
+     * handler runs. That result still goes through mapResponse, with the original request.
+     */
+    mapRequest?: (req: MoleculeRequest, res: MoleculeResponse) => RequestMappingResult | Promise<RequestMappingResult>;
+    /**
+     * Adapt the returned status, headers or body. This sees error and partial
+     * responses too: narrow the success shape before changing it, and preserve
+     * headers with `{ ...response, body }`. It never runs for fall-through.
+     */
+    mapResponse?: (response: Response, req: MoleculeRequest, res: MoleculeResponse) => Response | Promise<Response>;
+}
+/**
+ * Compose wire-format adapters around a structured resource handler without
+ * sending its response. The response mapper receives the adapted request.
+ * Exceptions propagate to the caller's normal error boundary.
+ *
+ * @param handler - The existing resource handler, including its checks.
+ * @param options - Request and response mappings for this route only.
+ * @returns A structured handler that keeps null/undefined fall-through intact.
+ */
+export declare const adaptHandler: (handler: Handler, options?: RequestHandlerOptions) => Handler;
 /**
  * Wraps a resource handler into Express-compatible middleware. Calls the handler,
  * then applies `statusCode`, `headers`, and `body` to the response. If the handler
@@ -42,7 +81,8 @@ export interface Response {
  * i18n-translated error messages.
  *
  * @param handler - The resource handler function to wrap.
+ * @param options - Optional wire-format mappings; neither mutates the shared handler.
  * @returns An Express-compatible middleware function `(req, res, next) => void`.
  */
-export declare const createRequestHandler: (handler: Handler) => (req: MoleculeRequest, res: MoleculeResponse, next: MoleculeNextFunction) => Promise<void>;
+export declare const createRequestHandler: (handler: Handler, options?: RequestHandlerOptions) => (req: MoleculeRequest, res: MoleculeResponse, next: MoleculeNextFunction) => Promise<void>;
 //# sourceMappingURL=createRequestHandler.d.ts.map

package/dist/createRequestHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createRequestHandler.d.ts","sourceRoot":"","sources":["../src/createRequestHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAI9F;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,GAAG,CACpB,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,gBAAgB,KAClB,OAAO,CAAC,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAA;AAEvE;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC;;OAEG;IACH,IAAI,EAAE,GAAG,CAAA;CACV;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAC9B,SAAS,OAAO,MACV,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,kBAkB7E,CAAA"}
+{"version":3,"file":"createRequestHandler.d.ts","sourceRoot":"","sources":["../src/createRequestHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAI9F;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,GAAG,CACpB,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,gBAAgB,KAClB,OAAO,CAAC,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAA;AAEvE;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC;;OAEG;IACH,IAAI,EAAE,GAAG,CAAA;CACV;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAA;AAEpF;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,CACX,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,gBAAgB,KAClB,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACzD;;;;OAIG;IACH,WAAW,CAAC,EAAE,CACZ,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,gBAAgB,KAClB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CAClC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GACtB,SAAS,OAAO,EAAE,UAAS,qBAA0B,KAAG,OAYxD,CAAA;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,OAAO,EAAE,UAAS,qBAA0B,MAE1E,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,kBAmBtF,CAAA"}

package/dist/createRequestHandler.js

@@ -11,6 +11,26 @@
 import { getLogger } from '@molecule/api-bond';
 const logger = getLogger();
 import { t } from '@molecule/api-i18n';
+/**
+ * Compose wire-format adapters around a structured resource handler without
+ * sending its response. The response mapper receives the adapted request.
+ * Exceptions propagate to the caller's normal error boundary.
+ *
+ * @param handler - The existing resource handler, including its checks.
+ * @param options - Request and response mappings for this route only.
+ * @returns A structured handler that keeps null/undefined fall-through intact.
+ */
+export const adaptHandler = (handler, options = {}) => async (req, res) => {
+    const overrides = options.mapRequest ? await options.mapRequest(req, res) : undefined;
+    const earlyResponse = overrides && 'response' in overrides ? overrides.response : undefined;
+    const request = overrides && !earlyResponse
+        ? Object.create(req, Object.getOwnPropertyDescriptors(overrides))
+        : req;
+    const response = earlyResponse ?? (await handler(request, res));
+    return response && options.mapResponse
+        ? await options.mapResponse(response, request, res)
+        : response;
+};
 /**
  * Wraps a resource handler into Express-compatible middleware. Calls the handler,
  * then applies `statusCode`, `headers`, and `body` to the response. If the handler
@@ -18,25 +38,29 @@ import { t } from '@molecule/api-i18n';
  * i18n-translated error messages.
  *
  * @param handler - The resource handler function to wrap.
+ * @param options - Optional wire-format mappings; neither mutates the shared handler.
  * @returns An Express-compatible middleware function `(req, res, next) => void`.
  */
-export const createRequestHandler = (handler) => async (req, res, next) => {
-    try {
-        const response = await handler(req, res);
-        if (response) {
-            if (response.headers) {
-                res.set(response.headers);
+export const createRequestHandler = (handler, options = {}) => {
+    const adapted = adaptHandler(handler, options);
+    return async (req, res, next) => {
+        try {
+            const response = await adapted(req, res);
+            if (response) {
+                if (response.headers) {
+                    res.set(response.headers);
+                }
+                res.status(response.statusCode);
+                res.send(response.body);
+            }
+            else {
+                next();
             }
-            res.status(response.statusCode);
-            res.send(response.body);
         }
-        else {
-            next();
+        catch (error) {
+            logger.error(error);
+            next(t('resource.error.unknownError', undefined, { defaultValue: 'Something went wrong.' }));
         }
-    }
-    catch (error) {
-        logger.error(error);
-        next(t('resource.error.unknownError', undefined, { defaultValue: 'Something went wrong.' }));
-    }
+    };
 };
 //# sourceMappingURL=createRequestHandler.js.map

package/dist/createRequestHandler.js.map

@@ -1 +1 @@
-{"version":3,"file":"createRequestHandler.js","sourceRoot":"","sources":["../src/createRequestHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,uDAAuD;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAG9C,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;AAC1B,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAkCtC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAC/B,CAAC,OAAgB,EAAE,EAAE,CACrB,KAAK,EAAE,GAAoB,EAAE,GAAqB,EAAE,IAA0B,EAAE,EAAE;IAChF,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;QAExC,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACrB,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;YAC3B,CAAC;YAED,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;YAC/B,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;QACzB,CAAC;aAAM,CAAC;YACN,IAAI,EAAE,CAAA;QACR,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QACnB,IAAI,CAAC,CAAC,CAAC,6BAA6B,EAAE,SAAS,EAAE,EAAE,YAAY,EAAE,uBAAuB,EAAE,CAAC,CAAC,CAAA;IAC9F,CAAC;AACH,CAAC,CAAA"}
+{"version":3,"file":"createRequestHandler.js","sourceRoot":"","sources":["../src/createRequestHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,uDAAuD;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAG9C,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;AAC1B,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAsEtC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,YAAY,GACvB,CAAC,OAAgB,EAAE,UAAiC,EAAE,EAAW,EAAE,CACnE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;IACjB,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IACrF,MAAM,aAAa,GAAG,SAAS,IAAI,UAAU,IAAI,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAA;IAC3F,MAAM,OAAO,GACX,SAAS,IAAI,CAAC,aAAa;QACzB,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,yBAAyB,CAAC,SAAS,CAAC,CAAC;QACjE,CAAC,CAAC,GAAG,CAAA;IACT,MAAM,QAAQ,GAAG,aAAa,IAAI,CAAC,MAAM,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAA;IAC/D,OAAO,QAAQ,IAAI,OAAO,CAAC,WAAW;QACpC,CAAC,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC;QACnD,CAAC,CAAC,QAAQ,CAAA;AACd,CAAC,CAAA;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,OAAgB,EAAE,UAAiC,EAAE,EAAE,EAAE;IAC5F,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IAC9C,OAAO,KAAK,EAAE,GAAoB,EAAE,GAAqB,EAAE,IAA0B,EAAE,EAAE;QACvF,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;YAExC,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;oBACrB,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;gBAC3B,CAAC;gBAED,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;gBAC/B,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;YACzB,CAAC;iBAAM,CAAC;gBACN,IAAI,EAAE,CAAA;YACR,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;YACnB,IAAI,CAAC,CAAC,CAAC,6BAA6B,EAAE,SAAS,EAAE,EAAE,YAAY,EAAE,uBAAuB,EAAE,CAAC,CAAC,CAAA;QAC9F,CAAC;IACH,CAAC,CAAA;AACH,CAAC,CAAA"}

package/dist/index.d.ts

@@ -21,6 +21,32 @@
  * Monkey-patching `res.json` (or `res.send`/`res.end`) to re-shape a handler's answer intercepts
  * nothing the handler produces, so the request it was meant to answer is left unanswered and hangs.
  *
+ * **A different request or response envelope is configuration.** Pass
+ * `mapRequest` and/or `mapResponse` as the second argument to `createRequestHandler`.
+ * Both may be asynchronous. The existing handler still validates and authorizes
+ * the adapted input. A response mapper sees the handler's errors and partial
+ * responses too: preserve them and its headers instead of treating every result
+ * as a success. `adaptHandler(handler, options)` offers the same mappings when
+ * another HTTP adapter will send the structured response.
+ * A request mapper can return `{ response: { statusCode, body } }` to answer
+ * before calling the handler, for example when extra validation fails or a
+ * filter lookup finds nothing. That response still passes through mapResponse.
+ *
+ * ```typescript
+ * import { createRequestHandler } from '@molecule/api-resource'
+ * import { handlers } from '@molecule/api-resource-user'
+ *
+ * const register = createRequestHandler(handlers.create({ name: 'User', tableName: 'users' }), {
+ *   // Return overrides. The adapter retains framework methods and getters.
+ *   mapRequest: (req) => ({ body: req.body?.account }),
+ *   mapResponse: (result) => result.statusCode === 201
+ *     ? { ...result, body: { account: result.body.props, accessToken: result.body.accessToken } }
+ *     : result,
+ * })
+ * // Keep the route's existing rate limiter and authorization around register.
+ * // No mapping is inferred: a flat-body API keeps createRequestHandler(handler).
+ * ```
+ *
  * @example
  * ```typescript
  * import { z } from 'zod'

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,2BAA2B,CAAA;AACzC,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,oBAAoB,CAAA;AAClC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+HG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,2BAA2B,CAAA;AACzC,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,oBAAoB,CAAA;AAClC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -21,6 +21,32 @@
  * Monkey-patching `res.json` (or `res.send`/`res.end`) to re-shape a handler's answer intercepts
  * nothing the handler produces, so the request it was meant to answer is left unanswered and hangs.
  *
+ * **A different request or response envelope is configuration.** Pass
+ * `mapRequest` and/or `mapResponse` as the second argument to `createRequestHandler`.
+ * Both may be asynchronous. The existing handler still validates and authorizes
+ * the adapted input. A response mapper sees the handler's errors and partial
+ * responses too: preserve them and its headers instead of treating every result
+ * as a success. `adaptHandler(handler, options)` offers the same mappings when
+ * another HTTP adapter will send the structured response.
+ * A request mapper can return `{ response: { statusCode, body } }` to answer
+ * before calling the handler, for example when extra validation fails or a
+ * filter lookup finds nothing. That response still passes through mapResponse.
+ *
+ * ```typescript
+ * import { createRequestHandler } from '@molecule/api-resource'
+ * import { handlers } from '@molecule/api-resource-user'
+ *
+ * const register = createRequestHandler(handlers.create({ name: 'User', tableName: 'users' }), {
+ *   // Return overrides. The adapter retains framework methods and getters.
+ *   mapRequest: (req) => ({ body: req.body?.account }),
+ *   mapResponse: (result) => result.statusCode === 201
+ *     ? { ...result, body: { account: result.body.props, accessToken: result.body.accessToken } }
+ *     : result,
+ * })
+ * // Keep the route's existing rate limiter and authorization around register.
+ * // No mapping is inferred: a flat-body API keeps createRequestHandler(handler).
+ * ```
+ *
  * @example
  * ```typescript
  * import { z } from 'zod'

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,2BAA2B,CAAA;AACzC,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,oBAAoB,CAAA;AAClC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+HG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,2BAA2B,CAAA;AACzC,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,oBAAoB,CAAA;AAClC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-resource",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "Resource CRUD operations and utilities for molecule.dev.",
   "type": "module",
   "main": "dist/index.js",
@@ -40,7 +40,7 @@
   },
   "devDependencies": {
     "@molecule/api-bond": "1.0.4",
-    "@molecule/api-database": "1.2.1",
+    "@molecule/api-database": "1.2.2",
     "@molecule/api-locales-resource": "1.0.2",
     "@molecule/api-utilities-validation": "1.0.4",
     "@types/node": "26.6.5",