@molecule/api-resource 1.0.3 → 1.0.4

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-16T00:47:45.548Z
+Generated: 2026-10-16T20:59:23.498Z
 -->
 
 # @molecule/api-resource
@@ -18,6 +18,22 @@ 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.
+
 ## Quick Start
 
 ```typescript

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.4",
   "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",