From f15f06203ce2b4d44f7936fd1f3e22ee67863997 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Thu, 27 Aug 2026 14:33:17 -0600 Subject: [PATCH 1/2] docs(http): remove unimplemented deserializeStream handler property The content-type handler interface table documented a `deserializeStream(stream)` property that Harper does not implement. The `ContentTypeHandler` interface in the core repo declares only `serialize`, `serializeStream`, `deserialize`, and `q`. Removes the `deserializeStream` row and drops the now-dangling "Used when `deserializeStream` is absent." clause from the `deserialize(buffer)` description. Co-Authored-By: Claude Opus 5 --- reference/http/api.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/reference/http/api.md b/reference/http/api.md index d4c40047..6c5baf6e 100644 --- a/reference/http/api.md +++ b/reference/http/api.md @@ -434,13 +434,12 @@ contentTypes.set('text/xml', { ### Handler Interface -| Property | Type | Description | -| --------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `serialize(data)` | `(any) => Buffer \| Uint8Array \| string` | Serialize data for a response | -| `serializeStream(data)` | `(any) => ReadableStream` | Serialize as a stream (for async iterables or large data) | -| `deserialize(buffer)` | `(Buffer \| string) => any` | Deserialize an incoming request body. Used when `deserializeStream` is absent. String for `text/*` types, Buffer for binary types. | -| `deserializeStream(stream)` | `(ReadableStream) => any` | Deserialize an incoming request stream | -| `q` | number (0–1) | Quality indicator for content negotiation. Defaults to `1`. | +| Property | Type | Description | +| ----------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------- | +| `serialize(data)` | `(any) => Buffer \| Uint8Array \| string` | Serialize data for a response | +| `serializeStream(data)` | `(any) => ReadableStream` | Serialize as a stream (for async iterables or large data) | +| `deserialize(buffer)` | `(Buffer \| string) => any` | Deserialize an incoming request body. String for `text/*` types, Buffer for binary types. | +| `q` | number (0–1) | Quality indicator for content negotiation. Defaults to `1`. | --- From f65c77cdd444f7794a3ec35221e19fbdcc5b69b2 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Thu, 27 Aug 2026 15:39:43 -0600 Subject: [PATCH 2/2] docs(http): clarify serializeStream return type and granularity The Handler Interface table typed `serializeStream` as returning a WHATWG `ReadableStream`. Verified against harper origin/main: every built-in handler returns a Node.js `Readable` (`streamAsJSON` -> `JSONStream extends Readable`, `Readable.from(...)`, `EncoderStream`, `toCsvStream`), and the call site in `server/serverHelpers/contentTypes.ts` pipes the return value through `createBrotliCompress()` and hands it to the HTTP layer as the response body. Also record the granularity: `serializeStream` is invoked once per response with the entire iterable, and only when the response body is an iterable or async iterable. Per-chunk serialization is `serialize`, which the streaming handlers call for each message. Co-Authored-By: Claude Opus 5 --- reference/http/api.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/reference/http/api.md b/reference/http/api.md index 6c5baf6e..7256fd88 100644 --- a/reference/http/api.md +++ b/reference/http/api.md @@ -434,12 +434,12 @@ contentTypes.set('text/xml', { ### Handler Interface -| Property | Type | Description | -| ----------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------- | -| `serialize(data)` | `(any) => Buffer \| Uint8Array \| string` | Serialize data for a response | -| `serializeStream(data)` | `(any) => ReadableStream` | Serialize as a stream (for async iterables or large data) | -| `deserialize(buffer)` | `(Buffer \| string) => any` | Deserialize an incoming request body. String for `text/*` types, Buffer for binary types. | -| `q` | number (0–1) | Quality indicator for content negotiation. Defaults to `1`. | +| Property | Type | Description | +| ----------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `serialize(data)` | `(any) => Buffer \| Uint8Array \| string` | Serialize data for a response | +| `serializeStream(data)` | `(any) => Readable` | Serialize a streaming response body. Called once per response with the whole iterable (not once per chunk), and only when the response body is an iterable or async iterable. Returns a Node.js [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable). | +| `deserialize(buffer)` | `(Buffer \| string) => any` | Deserialize an incoming request body. String for `text/*` types, Buffer for binary types. | +| `q` | number (0–1) | Quality indicator for content negotiation. Defaults to `1`. | ---