Skip to content

docs(http): remove unimplemented deserializeStream handler property #641

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Ethan-Arrowood merged 2 commits into from
Aug 28, 2026
+6 −7
Merged

docs(http): remove unimplemented deserializeStream handler property #641

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f15f062
docs(http): remove unimplemented deserializeStream handler property
Ethan-Arrowood Aug 27, 2026
f65c77c
docs(http): clarify serializeStream return type and granularity
Ethan-Arrowood Aug 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 6 additions & 7 deletions reference/http/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) => 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). |

@kriszyp kriszyp Aug 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Readable is not the complete return contract. serialize() invokes this method for any iterable response, including a plain array; the built-in MessagePack handler returns pack(data) for arrays, which is a Buffer rather than a stream. The core ContentTypeHandler declaration likewise permits Buffer | string. Please document the supported union (or restrict the statement to handlers that actually stream) so custom handlers are not given a stricter, incorrect contract.

| `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`. |

---

Expand Down
Loading