New version: 3.1.2.

- HEAD→GET promote
- body-always-parsed invariant
- byte-accurate body cap
- Tier-A rest-core extractions

Author: uhop

README.md

@@ -85,12 +85,12 @@ The handler ships a standard route pack — `GET / POST /`, `GET PUT PATCH DELET
 
 The bundled `dynamodb-toolkit/handler` is a pure `node:http` handler. Framework-specific bindings live in separate packages so the core stays zero-dep — each adapter is a thin wrapper that translates its framework's request/response shape into the toolkit's `rest-core` parsers + standard route pack. The wire contract (routes, query parameters, envelope keys, error mapping) is identical across all four.
 
-| Package | Runtime / framework | Notes |
-| --- | --- | --- |
-| [`dynamodb-toolkit-koa`](https://www.npmjs.com/package/dynamodb-toolkit-koa) | [Koa](https://koajs.com/) 2.x | Middleware; `koa` as peer dep |
-| [`dynamodb-toolkit-express`](https://www.npmjs.com/package/dynamodb-toolkit-express) | [Express](https://expressjs.com/) 4.x / 5.x | Middleware / Router; `express` as peer dep |
-| [`dynamodb-toolkit-fetch`](https://www.npmjs.com/package/dynamodb-toolkit-fetch) | Fetch API — `(Request) => Promise<Response>` | Zero-framework; runs on Cloudflare Workers, Deno Deploy, Bun.serve, Hono, Node native fetch server |
-| [`dynamodb-toolkit-lambda`](https://www.npmjs.com/package/dynamodb-toolkit-lambda) | AWS Lambda handler | Four event shapes (API Gateway REST / HTTP, Function URL, ALB); ships local-debug bridges for running the handler on real HTTP without `sam local` |
+| Package                                                                              | Runtime / framework                          | Notes                                                                                                                                              |
+| ------------------------------------------------------------------------------------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`dynamodb-toolkit-koa`](https://www.npmjs.com/package/dynamodb-toolkit-koa)         | [Koa](https://koajs.com/) 2.x                | Middleware; `koa` as peer dep                                                                                                                      |
+| [`dynamodb-toolkit-express`](https://www.npmjs.com/package/dynamodb-toolkit-express) | [Express](https://expressjs.com/) 4.x / 5.x  | Middleware / Router; `express` as peer dep                                                                                                         |
+| [`dynamodb-toolkit-fetch`](https://www.npmjs.com/package/dynamodb-toolkit-fetch)     | Fetch API — `(Request) => Promise<Response>` | Zero-framework; runs on Cloudflare Workers, Deno Deploy, Bun.serve, Hono, Node native fetch server                                                 |
+| [`dynamodb-toolkit-lambda`](https://www.npmjs.com/package/dynamodb-toolkit-lambda)   | AWS Lambda handler                           | Four event shapes (API Gateway REST / HTTP, Function URL, ALB); ships local-debug bridges for running the handler on real HTTP without `sam local` |
 
 ## Sub-exports
 

llms-full.txt

@@ -258,12 +258,17 @@ Framework-agnostic helpers. Each parser accepts the raw query value (string or a
 - `parseNames(input, {maxItems?})` → `string[]`. `maxItems` default `1000`.
 - `parsePaging(input, {defaultLimit?, maxLimit?, maxOffset?})` → `{offset, limit}` (clamped). `maxOffset` default `100_000` — caps `?offset=` to prevent DoS via `?offset=1e15` driving `paginateList` into astronomical skip-page SDK calls.
 - `parseFlag(input)` → `boolean` — accepts `yes` / `true` / `1` / `on` (case-insensitive)
+- `coerceStringQuery(query)` → `Record<string, string>` — filters framework query bag to string values only (drops nested objects / numbers; picks first string from arrays). Null-prototype accumulator defends against `?constructor=…` / `?__proto__=…` shadowing.
 
 ### 6.2 Builders
 
 - `buildEnvelope(result, {keys?, links?})` → wraps `{data, offset, limit, total?}` with configurable key names; optionally embeds `links`.
 - `buildErrorBody(err, {includeDebug?, errorId?})` → `{code, message, errorId?, stack?}`
 - `paginationLinks(offset, limit, total, urlBuilder?)` → `{prev: string | null, next: string | null}` — `urlBuilder` is `({offset, limit}) => string`.
+- `buildListOptions(query, policy)` → `ListOptionsBase` — composes `parseFields` / `parseFilter` / `parsePaging` / `parseFlag` under policy's pagination caps. Returns `{offset, limit, consistent, needTotal, fields?, filter?}` ready for `adapter.getAll`.
+- `resolveSort(query, sortableIndices?)` → `{index, descending}` — resolves `?sort=-name` to `{index: 'name-gsi', descending: true}` via the passed GSI mapping. Unmapped / missing fields → `{index: undefined, descending: false}`.
+- `stripMount(pathname, mountPath?)` → `string | null` — returns the pathname tail when the request is under `mountPath`, else `null`. Normalizes trailing slash on `mountPath` so `'/planets/'` and `'/planets'` behave identically. Empty / missing `mountPath` means "mount at root."
+- `validateWriteBody(body, {allowEmpty?, allowArray?}?)` → `body` — throws `{status: 400, code: 'BadBody'}` when `body` is non-object (or null/array without the matching option). Use on write-shaped routes where `{...body, ...key}` would silently accept `null` (writes key-only) or arrays (writes `{"0": …}`).
 
 ### 6.3 Policy
 
@@ -304,6 +309,14 @@ const handler = createHandler(adapter, {
 createServer(handler).listen(3000);
 ```
 
+**HEAD → GET auto-promote.** `matchRoute` treats `HEAD` as `GET` for dispatch, annotates the result with `head: true`, and the bundled handler returns headers + `Content-Length` with an empty body. Consumers get the expected REST semantics on every resource endpoint without extra configuration.
+
+**Body-always-parsed invariant.** For clone-all / move-all routes (`PUT /-clone`, `PUT /-move`), the parsed body flows into `exampleFromContext(query, body)` alongside the query — consumers can key their tenant/ownership scope on either. (Earlier versions passed `null` on these routes.)
+
+**Body cap measures bytes, not UTF-16 code units.** As of 3.1.2, the built-in body reader accumulates `Buffer` chunks and enforces `maxBodyBytes` in bytes. Multi-byte payloads (CJK, emoji) are now bounded by the advertised cap; earlier versions let ~2-4× through because `String.length` counts code units.
+
+**`readJsonBody(req, maxBodyBytes, {destroy?})`.** Exported helper for adapter-style code that needs the same Node-stream reader as the bundled handler. Pass `{destroy: false}` when the framework needs the socket alive to write the 413 response (Koa, Express — both hand body serialization to the framework response object).
+
 ### 7.1 Standard route pack
 
 | Method | URL | Adapter call |

llms.txt

@@ -39,8 +39,8 @@ await adapter.delete({name: 'Alderaan'});
 - `dynamodb-toolkit/batch` — `applyBatch`, `applyTransaction`, `explainTransactionCancellation`, `getBatch`, `getTransaction`, `backoff`, `TRANSACTION_LIMIT`
 - `dynamodb-toolkit/mass` — `paginateList`, `iterateList`, `iterateItems`, `readList`, `readListByKeys`, `readOrderedListByKeys`, `writeList`, `deleteList`, `deleteListByKeys`, `copyList`, `moveList`, `getTotal`
 - `dynamodb-toolkit/paths` — `getPath`, `setPath`, `deletePath`, `applyPatch`, `normalizeFields`, `subsetObject`
-- `dynamodb-toolkit/rest-core` — `parseFields`, `parseSort`, `parseFilter`, `parsePatch`, `parseNames`, `parsePaging`, `parseFlag`, `buildEnvelope`, `buildErrorBody`, `paginationLinks`, `defaultPolicy`, `mapErrorStatus`, `mergePolicy`
-- `dynamodb-toolkit/handler` — `createHandler`, `matchRoute`
+- `dynamodb-toolkit/rest-core` — `parseFields`, `parseSort`, `parseFilter`, `parsePatch`, `parseNames`, `parsePaging`, `parseFlag`, `coerceStringQuery`, `buildEnvelope`, `buildErrorBody`, `paginationLinks`, `buildListOptions`, `resolveSort`, `stripMount`, `validateWriteBody`, `defaultPolicy`, `mapErrorStatus`, `mergePolicy`
+- `dynamodb-toolkit/handler` — `createHandler`, `matchRoute`, `readJsonBody`
 
 ## Adapter constructor options
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "dynamodb-toolkit",
-  "version": "3.1.1",
+  "version": "3.1.2",
   "description": "Zero-dependency DynamoDB toolkit (AWS SDK v3) — Adapter with hooks, expression builders, batch/transaction chunking, mass operations, REST handler.",
   "type": "module",
   "main": "./src/index.js",

src/handler/handler.js

@@ -16,41 +16,20 @@ import {
 } from '../rest-core/index.js';
 
 import {matchRoute} from './match-route.js';
+import {readJsonBody} from './read-json-body.js';
+import {Buffer} from 'node:buffer';
 
-const readJsonBody = (req, maxBodyBytes) =>
-  new Promise((resolve, reject) => {
-    let body = '';
-    let size = 0;
-    let aborted = false;
-    req.setEncoding?.('utf8');
-    req.on('data', chunk => {
-      if (aborted) return;
-      const s = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
-      size += s.length;
-      if (size > maxBodyBytes) {
-        aborted = true;
-        reject(Object.assign(new Error(`Request body exceeds ${maxBodyBytes} bytes`), {status: 413, code: 'PayloadTooLarge'}));
-        req.destroy?.();
-        return;
-      }
-      body += s;
-    });
-    req.on('end', () => {
-      if (aborted) return;
-      if (!body) return resolve(null);
-      try {
-        resolve(JSON.parse(body));
-      } catch (err) {
-        reject(Object.assign(err, {status: 400, code: 'BadJsonBody'}));
-      }
-    });
-    req.on('error', reject);
-  });
-
-const sendJson = (res, status, body) => {
+const sendJson = (req, res, status, body) => {
   res.statusCode = status;
   res.setHeader('Content-Type', 'application/json; charset=utf-8');
-  res.end(body == null ? '' : JSON.stringify(body));
+  const serialized = body == null ? '' : JSON.stringify(body);
+  if (req.method === 'HEAD') {
+    // HEAD mirrors GET's headers + Content-Length with an empty body.
+    res.setHeader('Content-Length', String(Buffer.byteLength(serialized, 'utf8')));
+    res.end();
+    return;
+  }
+  res.end(serialized);
 };
 
 const sendNoContent = (res, status = 204) => {
@@ -100,9 +79,9 @@ export const createHandler = (adapter, options = {}) => {
     return {index: sortableIndices[sort.field], descending: sort.direction === 'desc'};
   };
 
-  const sendError = (res, err) => {
+  const sendError = (req, res, err) => {
     const status = err?.status && err.status >= 400 && err.status < 600 ? err.status : mapErrorStatus(err, policy.statusCodes);
-    sendJson(res, status, policy.errorBody(err));
+    sendJson(req, res, status, policy.errorBody(err));
   };
 
   // --- collection-level handlers ---
@@ -124,7 +103,7 @@ export const createHandler = (adapter, options = {}) => {
     const links = paginationLinks(result.offset, result.limit, result.total, urlBuilder);
     const envelopeOpts = {keys: policy.envelope};
     if (links.prev || links.next) envelopeOpts.links = links;
-    sendJson(res, 200, buildEnvelope(result, envelopeOpts));
+    sendJson(req, res, 200, buildEnvelope(result, envelopeOpts));
   };
 
   const handlePost = async (req, res) => {
@@ -133,26 +112,26 @@ export const createHandler = (adapter, options = {}) => {
     sendNoContent(res);
   };
 
-  const handleDeleteAll = async (_req, res, query) => {
+  const handleDeleteAll = async (req, res, query) => {
     const opts = buildListOptions(query);
     const {index} = resolveSort(query);
     const example = exampleFromContext(query, null);
     // For deleteAll we need the params built like getAll, but route through deleteAllByParams
     // by re-using the Adapter's internal list-params machinery via getAll-style options
     const params = await adapter._buildListParams(opts, false, example, index);
     const r = await adapter.deleteAllByParams(params);
-    sendJson(res, 200, {processed: r.processed});
+    sendJson(req, res, 200, {processed: r.processed});
   };
 
   // --- /-by-names handlers ---
 
-  const handleGetByNames = async (_req, res, query) => {
+  const handleGetByNames = async (req, res, query) => {
     const names = parseNames(query.names);
     const fields = parseFields(query.fields);
     const consistent = parseFlag(query.consistent);
     const keys = names.map(name => keyFromPath(name, adapter));
     const items = await adapter.getByKeys(keys, fields, {consistent});
-    sendJson(res, 200, items);
+    sendJson(req, res, 200, items);
   };
 
   const handleDeleteByNames = async (req, res, query) => {
@@ -164,7 +143,7 @@ export const createHandler = (adapter, options = {}) => {
     }
     const keys = names.map(name => keyFromPath(name, adapter));
     const r = await adapter.deleteByKeys(keys);
-    sendJson(res, 200, {processed: r.processed});
+    sendJson(req, res, 200, {processed: r.processed});
   };
 
   const handleCloneByNames = async (req, res, query) => {
@@ -175,7 +154,7 @@ export const createHandler = (adapter, options = {}) => {
     const overlay = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
     const keys = names.map(name => keyFromPath(name, adapter));
     const r = await adapter.cloneByKeys(keys, item => ({...item, ...overlay}));
-    sendJson(res, 200, {processed: r.processed});
+    sendJson(req, res, 200, {processed: r.processed});
   };
 
   const handleMoveByNames = async (req, res, query) => {
@@ -186,52 +165,54 @@ export const createHandler = (adapter, options = {}) => {
     const overlay = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
     const keys = names.map(name => keyFromPath(name, adapter));
     const r = await adapter.moveByKeys(keys, item => ({...item, ...overlay}));
-    sendJson(res, 200, {processed: r.processed});
+    sendJson(req, res, 200, {processed: r.processed});
   };
 
   const handleLoad = async (req, res) => {
     const body = await readJsonBody(req, maxBodyBytes);
     if (!Array.isArray(body)) {
-      return sendError(res, Object.assign(new Error('Body must be an array of items'), {status: 400, code: 'BadLoadBody'}));
+      return sendError(req, res, Object.assign(new Error('Body must be an array of items'), {status: 400, code: 'BadLoadBody'}));
     }
     const r = await adapter.putAll(body);
-    sendJson(res, 200, {processed: r.processed});
+    sendJson(req, res, 200, {processed: r.processed});
   };
 
   const handleCloneAll = async (req, res, query) => {
     const body = await readJsonBody(req, maxBodyBytes);
     const overlay = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
     const opts = buildListOptions(query);
     const {index} = resolveSort(query);
-    const example = exampleFromContext(query, null);
+    // Body-always-parsed invariant: pass the parsed body (not null) to
+    // exampleFromContext so consumers can derive scope from both query + body.
+    const example = exampleFromContext(query, body);
     const params = await adapter._buildListParams(opts, false, example, index);
     const r = await adapter.cloneAllByParams(params, item => ({...item, ...overlay}));
-    sendJson(res, 200, {processed: r.processed});
+    sendJson(req, res, 200, {processed: r.processed});
   };
 
   const handleMoveAll = async (req, res, query) => {
     const body = await readJsonBody(req, maxBodyBytes);
     const overlay = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
     const opts = buildListOptions(query);
     const {index} = resolveSort(query);
-    const example = exampleFromContext(query, null);
+    const example = exampleFromContext(query, body);
     const params = await adapter._buildListParams(opts, false, example, index);
     const r = await adapter.moveAllByParams(params, item => ({...item, ...overlay}));
-    sendJson(res, 200, {processed: r.processed});
+    sendJson(req, res, 200, {processed: r.processed});
   };
 
   // --- item-level handlers ---
 
-  const handleItemGet = async (_req, res, key, query) => {
+  const handleItemGet = async (req, res, key, query) => {
     const fields = parseFields(query.fields);
     const consistent = parseFlag(query.consistent);
     const item = await adapter.getByKey(key, fields, {consistent});
     if (item === undefined) return sendNoContent(res, policy.statusCodes.miss);
-    sendJson(res, 200, item);
+    sendJson(req, res, 200, item);
   };
 
   const handleItemPut = async (req, res, key, query) => {
-    const body = await readJsonBody(req, maxBodyBytes);
+    const body = /** @type {Record<string, unknown> | null | undefined} */ (await readJsonBody(req, maxBodyBytes));
     const force = parseFlag(query.force);
     // Merge URL key into body so the user need not repeat it
     const merged = {...body, ...key};
@@ -240,7 +221,7 @@ export const createHandler = (adapter, options = {}) => {
   };
 
   const handleItemPatch = async (req, res, key) => {
-    const body = await readJsonBody(req, maxBodyBytes);
+    const body = /** @type {Record<string, unknown> | null | undefined} */ (await readJsonBody(req, maxBodyBytes));
     const {patch, options} = parsePatch(body, {metaPrefix: policy.metaPrefix});
     await adapter.patch(key, patch, options);
     sendNoContent(res);
@@ -273,6 +254,7 @@ export const createHandler = (adapter, options = {}) => {
     try {
       const url = requestUrl(req);
       const query = Object.fromEntries(url.searchParams);
+      // matchRoute promotes HEAD → GET internally; route.method is effective.
       const route = matchRoute(req.method, url.pathname, policy.methodPrefix);
 
       switch (route.kind) {
@@ -305,9 +287,9 @@ export const createHandler = (adapter, options = {}) => {
           break;
         }
       }
-      return sendError(res, Object.assign(new Error('Method not allowed for this route'), {status: 405, code: 'MethodNotAllowed'}));
+      return sendError(req, res, Object.assign(new Error('Method not allowed for this route'), {status: 405, code: 'MethodNotAllowed'}));
     } catch (err) {
-      sendError(res, err);
+      sendError(req, res, err);
     }
   };
 };

src/handler/index.d.ts

@@ -5,3 +5,4 @@
 
 export {createHandler, type HandlerOptions, type RequestHandler} from './handler.js';
 export {matchRoute, type MatchedRoute} from './match-route.js';
+export {readJsonBody, type ReadJsonBodyOptions} from './read-json-body.js';

src/handler/index.js

@@ -2,3 +2,4 @@
 
 export {createHandler} from './handler.js';
 export {matchRoute} from './match-route.js';
+export {readJsonBody} from './read-json-body.js';

src/handler/match-route.d.ts

@@ -1,20 +1,32 @@
-/** Discriminated union returned by {@link matchRoute}. */
+/**
+ * Discriminated union returned by {@link matchRoute}.
+ *
+ * `method` is the *effective* method after HEAD→GET promotion — HEAD requests
+ * dispatch through the GET handler. `head: true` signals the original was a
+ * HEAD; callers should suppress the response body but keep headers + status.
+ */
 export type MatchedRoute =
   /** Root URL (`/`) for a given method. */
-  | {kind: 'root'; method: string}
+  | {kind: 'root'; method: string; head: boolean}
   /** Method URL on the collection (`/-by-names`, `/-clone`, …). */
-  | {kind: 'collectionMethod'; name: string; method: string}
+  | {kind: 'collectionMethod'; name: string; method: string; head: boolean}
   /** Single item URL (`/<key>`). */
-  | {kind: 'item'; key: string; method: string}
+  | {kind: 'item'; key: string; method: string; head: boolean}
   /** Method URL on a single item (`/<key>/-clone`). */
-  | {kind: 'itemMethod'; key: string; name: string; method: string}
+  | {kind: 'itemMethod'; key: string; name: string; method: string; head: boolean}
   /** No standard route matched (deeper nesting, unexpected prefix). */
-  | {kind: 'unknown'; method: string};
+  | {kind: 'unknown'; method: string; head: boolean};
 
 /**
  * Match an HTTP method + URL pathname against the standard route shapes.
  * URL-decodes key segments. Configurable method prefix.
  *
+ * `HEAD` requests are matched as `GET` (so they dispatch through the same
+ * read-side handler) and annotated with `head: true` on the result so the
+ * caller can skip body writes in the response — the REST convention is that
+ * HEAD returns the same headers + `Content-Length` as the equivalent GET
+ * but an empty body.
+ *
  * @param method Request method (e.g. `'GET'`).
  * @param path URL pathname (no query string).
  * @param methodPrefix Character(s) that mark method URLs. Default `'-'`.