@molecule/api-resource 1.0.3 → 1.0.5

package/README.md

@@ -3,21 +3,37 @@ 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-16T00:47:45.548Z
+Generated: 2026-10-17T04:45:43.913Z
 -->
 
 # @molecule/api-resource
 
-> **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.
-
 Base resource patterns for molecule.dev.
 
 Provides CRUD operation factories and request handler utilities for
 building RESTful API resources. Every `@molecule/api-resource-*` package
 (user, project, device, ...) is built on these factories.
 
+**A handler returns `{ statusCode, headers?, body }` and NEVER writes to `res`** — not through
+`res.json`, not through `res.send`, not through `res.end`. `createRequestHandler` is the wrapper
+that applies the returned object (`res.set(headers)`, `res.status(statusCode)`, `res.send(body)`),
+and a handler returns `null` only when the request should fall through to `next()`. Calling a
+handler directly from your own route is therefore only correct if you apply that return value
+yourself:
+
+```typescript
+const { statusCode, headers, body } = await handler(req, res)
+if (headers) res.set(headers)
+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.
+
+> **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.
+
 ## Quick Start
 
 ```typescript
@@ -104,10 +120,21 @@ Framework-agnostic HTTP request interface. Structurally compatible with Express'
 `Request` — Express objects satisfy this interface without adapters, but the type
 doesn't depend on Express, allowing use with Fastify, Hono, or Lambda.
 
+`params` is `Record<string, any>` on purpose. Express 5 declares
+`ParamsDictionary` as `{ [key: string]: string | string[] }` — a wildcard or a
+repeated parameter yields an array — so `Record<string, string>` is NOT a
+supertype of it, and every Express handler passing its own `Request` to a
+function declared on this interface (`authorization.set(req, …)`) failed with
+TS2345 and was told to cast. This is the same shape `body` and `query` already
+use. A reader that needs one segment as a string checks it
+(`typeof req.params.id === 'string'`) rather than trusting the annotation;
+the packages that own the routes do exactly that where it matters (see
+`@molecule/api-bonds-default-express`'s `getParamId`).
+
 ```typescript
 interface MoleculeRequest {
   body: any
-  params: Record<string, string>
+  params: Record<string, any>
   query: Record<string, any>
   headers: Record<string, string | string[] | undefined>
   cookies?: Record<string, string>

package/dist/http-types.d.ts

@@ -11,10 +11,21 @@
  * Framework-agnostic HTTP request interface. Structurally compatible with Express's
  * `Request` — Express objects satisfy this interface without adapters, but the type
  * doesn't depend on Express, allowing use with Fastify, Hono, or Lambda.
+ *
+ * `params` is `Record<string, any>` on purpose. Express 5 declares
+ * `ParamsDictionary` as `{ [key: string]: string | string[] }` — a wildcard or a
+ * repeated parameter yields an array — so `Record<string, string>` is NOT a
+ * supertype of it, and every Express handler passing its own `Request` to a
+ * function declared on this interface (`authorization.set(req, …)`) failed with
+ * TS2345 and was told to cast. This is the same shape `body` and `query` already
+ * use. A reader that needs one segment as a string checks it
+ * (`typeof req.params.id === 'string'`) rather than trusting the annotation;
+ * the packages that own the routes do exactly that where it matters (see
+ * `@molecule/api-bonds-default-express`'s `getParamId`).
  */
 export interface MoleculeRequest {
     body: any;
-    params: Record<string, string>;
+    params: Record<string, any>;
     query: Record<string, any>;
     headers: Record<string, string | string[] | undefined>;
     cookies?: Record<string, string>;

package/dist/http-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-types.d.ts","sourceRoot":"","sources":["../src/http-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,GAAG,CAAA;IACT,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAA;CACjE;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IACzB,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IACzB,GAAG,IAAI,IAAI,CAAA;IACX,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAC1C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC5E,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;IACtC,YAAY,CAAC,IAAI,IAAI,CAAA;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC5B;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;AAE1D;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,CACnC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,oBAAoB,KACvB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA"}
+{"version":3,"file":"http-types.d.ts","sourceRoot":"","sources":["../src/http-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,GAAG,CAAA;IACT,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAA;CACjE;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IACzB,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IACzB,GAAG,IAAI,IAAI,CAAA;IACX,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAC1C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC5E,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;IACtC,YAAY,CAAC,IAAI,IAAI,CAAA;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC5B;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;AAE1D;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,CACnC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,oBAAoB,KACvB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA"}

package/dist/index.d.ts

@@ -5,6 +5,22 @@
  * building RESTful API resources. Every `@molecule/api-resource-*` package
  * (user, project, device, ...) is built on these factories.
  *
+ * **A handler returns `{ statusCode, headers?, body }` and NEVER writes to `res`** — not through
+ * `res.json`, not through `res.send`, not through `res.end`. `createRequestHandler` is the wrapper
+ * that applies the returned object (`res.set(headers)`, `res.status(statusCode)`, `res.send(body)`),
+ * and a handler returns `null` only when the request should fall through to `next()`. Calling a
+ * handler directly from your own route is therefore only correct if you apply that return value
+ * yourself:
+ *
+ * ```typescript
+ * const { statusCode, headers, body } = await handler(req, res)
+ * if (headers) res.set(headers)
+ * 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.
+ *
  * @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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

package/dist/index.js

@@ -5,6 +5,22 @@
  * building RESTful API resources. Every `@molecule/api-resource-*` package
  * (user, project, device, ...) is built on these factories.
  *
+ * **A handler returns `{ statusCode, headers?, body }` and NEVER writes to `res`** — not through
+ * `res.json`, not through `res.send`, not through `res.end`. `createRequestHandler` is the wrapper
+ * that applies the returned object (`res.set(headers)`, `res.status(statusCode)`, `res.send(body)`),
+ * and a handler returns `null` only when the request should fall through to `next()`. Calling a
+ * handler directly from your own route is therefore only correct if you apply that return value
+ * yourself:
+ *
+ * ```typescript
+ * const { statusCode, headers, body } = await handler(req, res)
+ * if (headers) res.set(headers)
+ * 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.
+ *
  * @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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-resource",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "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.2",
-    "@molecule/api-database": "1.1.1",
+    "@molecule/api-database": "1.1.3",
     "@molecule/api-locales-resource": "1.0.2",
     "@molecule/api-utilities-validation": "1.0.2",
     "@types/node": "26.1.2",