@molecule/api-resource 1.0.6 → 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-23T21:27:14.472Z
+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
@@ -307,11 +376,14 @@ export const create = ({ name, tableName, schema }: types.Resource) => {
 ```
 
 ```typescript
-function create({
+function create<
+  CreateProps extends Record<string, unknown> = Record<string, unknown>,
+  CreatedProps extends types.Props & CreateProps = types.Props & CreateProps,
+>({
   name,
   tableName,
   schema,
-}: types.Resource<unknown>): ({
+}: types.Resource): ({
   props: createProps,
   id,
 }: {
@@ -330,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
@@ -340,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`.
 
@@ -372,7 +461,13 @@ export const del = ({ name, tableName, schema }: types.Resource) => {
 ```
 
 ```typescript
-function del({ name, tableName }: DeletedResource): ({ id }: { id: Props['id'] }) => Promise<
+function del<
+  Props extends types.Props = types.Props,
+  DeletedResource extends types.Resource<Props> = types.Resource<Props>,
+>({
+  name,
+  tableName,
+}: DeletedResource): ({ id }: { id: Props['id'] }) => Promise<
   | { statusCode: number; body: { error: string; errorKey: string; props?: undefined } }
   | {
       statusCode: number
@@ -394,7 +489,10 @@ Creates a request handler to be used to query resources.
 Uses the bonded DataStore from `@molecule/api-database` for database-agnostic operations.
 
 ```typescript
-function query({
+function query<
+  Props extends types.Props = types.Props,
+  QueriedResource extends types.Resource = types.Resource,
+>({
   tableName,
 }: QueriedResource): (
   req: MoleculeRequest,
@@ -432,7 +530,10 @@ export const read = ({ name, tableName, schema }: types.Resource) => {
 ```
 
 ```typescript
-function read({
+function read<
+  ReadProps extends types.Props = types.Props,
+  ReadResource extends types.Resource<ReadProps> = types.Resource<ReadProps>,
+>({
   tableName,
 }: ReadResource): ({
   id,
@@ -504,11 +605,18 @@ export const update = ({ name, tableName, schema }: types.Resource) => {
 ```
 
 ```typescript
-function update({
+function update<
+  UpdateProps extends Record<string, unknown> = Record<string, unknown>,
+  UpdatedProps extends Pick<types.Props, `updatedAt`> & UpdateProps = Pick<
+    types.Props,
+    `updatedAt`
+  > &
+    UpdateProps,
+>({
   name,
   tableName,
   schema,
-}: types.Resource<unknown>): ({
+}: types.Resource): ({
   id,
   props: updateProps,
 }: {
@@ -597,9 +705,7 @@ Creates a Zod schema for the standard `{ statusCode, body }` response
 returned by resource CRUD operations.
 
 ```typescript
-function responseSchema(
-  propsSchema: T,
-): z.ZodTypeAny<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>
+function responseSchema<T extends z.ZodTypeAny>(propsSchema: T): z.ZodTypeAny
 ```
 
 - `propsSchema` — The Zod schema for the resource's props (e.g. `userPropsSchema`).
@@ -612,9 +718,7 @@ Creates a Zod schema that validates a resource descriptor object
 (`{ name, tableName, schema }`).
 
 ```typescript
-function resourceSchema(
-  _propsSchema: T,
-): z.ZodTypeAny<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>
+function resourceSchema<T extends z.ZodTypeAny>(_propsSchema: T): z.ZodTypeAny
 ```
 
 - `_propsSchema` — The Zod schema for the resource's props (used for type inference only).
@@ -627,10 +731,7 @@ Validates data against a Zod schema, throwing an `Error` with a
 human-readable message listing all validation failures if invalid.
 
 ```typescript
-function validate(
-  schema: z.ZodSchema<T, unknown, z.core.$ZodTypeInternals<T, unknown>>,
-  data: unknown,
-): T
+function validate<T>(schema: z.ZodSchema<T>, data: unknown): T
 ```
 
 - `schema` — The Zod schema to validate against.
@@ -644,8 +745,8 @@ Validates data against a Zod schema without throwing. Returns a discriminated
 union: `{ success: true, data }` on success or `{ success: false, error }` on failure.
 
 ```typescript
-function safeParse(
-  schema: z.ZodSchema<T, unknown, z.core.$ZodTypeInternals<T, unknown>>,
+function safeParse<T>(
+  schema: z.ZodSchema<T>,
   data: unknown,
 ): { success: true; data: T } | { success: false; error: z.ZodError }
 ```
@@ -661,9 +762,9 @@ Creates a schema where all fields are optional, suitable for validating
 partial update payloads where only changed fields are sent.
 
 ```typescript
-function partial(
-  schema: z.ZodObject<T, z.core.$strip>,
-): z.ZodObject<{ [K in keyof T]: z.ZodOptional<T[K]> }, z.core.$strip>
+function partial<T extends z.ZodRawShape>(
+  schema: z.ZodObject<T>,
+): z.ZodObject<{ [K in keyof T]: z.ZodOptional<T[K]> }>
 ```
 
 - `schema` — The Zod object schema to make partial.
@@ -676,10 +777,10 @@ Creates a schema with only the specified fields, useful for create payloads
 where only a subset of the full props should be provided by the client.
 
 ```typescript
-function pick(
-  schema: z.ZodObject<T, z.core.$strip>,
+function pick<T extends z.ZodRawShape, K extends keyof T>(
+  schema: z.ZodObject<T>,
   keys: readonly K[],
-): z.ZodObject<Pick<T, K>, z.core.$strip>
+): z.ZodObject<Pick<T, K>>
 ```
 
 - `schema` — The Zod object schema to pick from.
@@ -839,8 +940,17 @@ const getValidProps: <Props>({
   schema,
   props,
 }: {
+  /**
+   * The name of the resource (used in error messages).
+   */
   name: string
+  /**
+   * The Zod schema used when validating props.
+   */
   schema: ZodSchema<Props>
+  /**
+   * The `props` to be validated.
+   */
   props: unknown
 }) => Props
 ```
@@ -860,7 +970,15 @@ Validates data against a Zod schema without throwing, returning a discriminated
 const safeParse: <T>(
   schema: ZodSchema<T>,
   data: unknown,
-) => { success: true; data: T } | { success: false; error: ZodError }
+) =>
+  | {
+      success: true
+      data: T
+    }
+  | {
+      success: false
+      error: ZodError
+    }
 ```
 
 - `schema` — The Zod schema to validate against.

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.6",
+  "version": "1.1.0",
   "description": "Resource CRUD operations and utilities for molecule.dev.",
   "type": "module",
   "main": "dist/index.js",
@@ -39,10 +39,10 @@
     "zod": "4.6.7"
   },
   "devDependencies": {
-    "@molecule/api-bond": "1.0.3",
-    "@molecule/api-database": "1.1.5",
+    "@molecule/api-bond": "1.0.4",
+    "@molecule/api-database": "1.2.2",
     "@molecule/api-locales-resource": "1.0.2",
-    "@molecule/api-utilities-validation": "1.0.3",
+    "@molecule/api-utilities-validation": "1.0.4",
     "@types/node": "26.6.5",
     "typescript": "6.0.3",
     "vitest": "4.1.12"