@lovrozagar/honey 0.7.3 → 1.0.0-rc.1

package/dist/response/out-headers.js

@@ -0,0 +1,130 @@
+/**
+ * `HoneyOutHeaders`: a `Headers` view over the plain map a buffered response was built with.
+ * `get`/`has`/`getSetCookie`, plain iteration, `set` and `delete` use the map; a real `Headers` is
+ * built only when something appends or walks it through the native API. The map keys are lower-case, as Fetch keeps them.
+ */
+/** Copy native `Headers` into a map, keeping each `Set-Cookie` as its own entry. */
+export function headersToRecord(headers) {
+    const out = {};
+    headers.forEach((value, key) => {
+        if (key !== "set-cookie")
+            out[key] = value;
+    });
+    const cookies = headers.getSetCookie();
+    if (cookies.length > 0)
+        out["set-cookie"] = cookies;
+    return out;
+}
+function* iterateMap(map) {
+    for (const key in map) {
+        const value = map[key];
+        if (Array.isArray(value))
+            for (const item of value)
+                yield [key, item];
+        else if (value !== undefined)
+            yield [key, value];
+    }
+}
+/* what Fetch accepts: a token name, and a value without CR, LF or NUL once its edges are trimmed */
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const FORBIDDEN_IN_VALUE = /[\r\n\0]/;
+const EDGE_WHITESPACE = /^[\t\n\r ]+|[\t\n\r ]+$/g;
+function checkedName(name) {
+    if (!TOKEN.test(name))
+        throw new TypeError(`Headers: invalid header name "${name}"`);
+    return name.toLowerCase();
+}
+export class HoneyOutHeaders {
+    #map;
+    #native = null;
+    /* the map may be shared (a frozen base the response was built from): the first write copies it */
+    #owned = false;
+    constructor(map) {
+        this.#map = map;
+    }
+    append(name, value) {
+        this.#ensureNative().append(name, value);
+    }
+    /** Removes `name`; on the plain map until something used the native API. */
+    delete(name) {
+        if (this.#native)
+            return this.#native.delete(name);
+        const key = checkedName(name);
+        if (Object.hasOwn(this.#map, key))
+            delete this.#writable()[key];
+    }
+    get(name) {
+        if (this.#native)
+            return this.#native.get(name);
+        const key = name.toLowerCase();
+        /* own keys only: `get("constructor")` must not return Object */
+        const raw = Object.hasOwn(this.#map, key) ? this.#map[key] : undefined;
+        if (raw === undefined)
+            return null;
+        return Array.isArray(raw) ? raw.join(", ") : raw;
+    }
+    getSetCookie() {
+        if (this.#native)
+            return this.#native.getSetCookie();
+        const raw = Object.hasOwn(this.#map, "set-cookie") ? this.#map["set-cookie"] : undefined;
+        if (raw === undefined)
+            return [];
+        return Array.isArray(raw) ? raw : [raw];
+    }
+    has(name) {
+        return this.get(name) !== null;
+    }
+    /**
+     * Sets `name` on the plain map, validated and normalized as Fetch does, until something used the
+     * native API: a middleware's header write never builds native Headers.
+     */
+    set(name, value) {
+        if (this.#native)
+            return this.#native.set(name, value);
+        const key = checkedName(name);
+        const normalized = value.replace(EDGE_WHITESPACE, "");
+        if (FORBIDDEN_IN_VALUE.test(normalized))
+            throw new TypeError(`Headers: invalid value for "${name}"`);
+        this.#writable()[key] = normalized;
+    }
+    forEach(callback, thisArg) {
+        this.#ensureNative().forEach(callback, thisArg);
+    }
+    keys() {
+        return this.#ensureNative().keys();
+    }
+    values() {
+        return this.#ensureNative().values();
+    }
+    entries() {
+        return this.#ensureNative().entries();
+    }
+    [Symbol.iterator]() {
+        if (this.#native)
+            return this.#native[Symbol.iterator]();
+        return iterateMap(this.#map);
+    }
+    get [Symbol.toStringTag]() {
+        return "Headers";
+    }
+    /** The headers as a plain map: the original map until something wrote through the native API. */
+    toRecord() {
+        return this.#native ? headersToRecord(this.#native) : this.#map;
+    }
+    #writable() {
+        if (!this.#owned) {
+            this.#map = { ...this.#map };
+            this.#owned = true;
+        }
+        return this.#map;
+    }
+    #ensureNative() {
+        if (this.#native)
+            return this.#native;
+        const headers = new Headers();
+        for (const [name, value] of iterateMap(this.#map))
+            headers.append(name, value);
+        this.#native = headers;
+        return headers;
+    }
+}

package/dist/response/pretty-json.d.ts

@@ -0,0 +1,10 @@
+import { type MiddlewareFn } from "../middleware/middleware.ts";
+export type PrettyJsonOptions = {
+    /** The query parameter that asks for it; default `pretty`. */
+    query?: string;
+    /** The indent; default 2. */
+    space?: number;
+};
+export declare function prettyJson(options?: PrettyJsonOptions): MiddlewareFn<{
+    readonly search: Readonly<Record<string, string>>;
+}>;

package/dist/response/pretty-json.js

@@ -0,0 +1,44 @@
+/**
+ * `prettyJson()`: a JSON answer indented when the query asks for it (`?pretty`). JSON is read from
+ * the parsed media type (`application/json` or a `+json` suffix), never a prefix (H18.2); only a
+ * buffered body is touched, and one that does not parse goes out as it came.
+ */
+import { bodyKind } from "../input/body-kind.js";
+import { namedMiddleware } from "../middleware/middleware.js";
+import { rawBodyOf, replaceResponse } from "./builder.js";
+import { isJsonMediaType, parseMediaType } from "./media-type.js";
+// per-process-constant: text-codec
+const decoder = /* @__PURE__ */ new TextDecoder();
+/** `text` indented, or `null` when it is empty or not JSON. */
+function indented(text, space) {
+    if (text.trim().length === 0)
+        return null;
+    try {
+        return JSON.stringify(JSON.parse(text), null, space);
+    }
+    catch {
+        /* JSON in name only: the answer goes out as it came */
+        return null;
+    }
+}
+export function prettyJson(options = {}) {
+    const query = options.query ?? "pretty";
+    const space = options.space ?? 2;
+    return namedMiddleware("prettyJson", async (ctx, next) => {
+        if (!Object.hasOwn(ctx.search, query))
+            return next();
+        const response = await next();
+        if (!isJsonMediaType(parseMediaType(response.headers.get("content-type"))) || bodyKind(response) !== "buffered") {
+            return response;
+        }
+        const raw = rawBodyOf(response);
+        const text = raw === null ? await response.text() : typeof raw === "string" ? raw : decoder.decode(raw);
+        const formatted = indented(text, space);
+        /* a foreign body was read: it goes on as a fresh one, changed or not */
+        if (formatted === null)
+            return raw === null ? replaceResponse(response, { body: text }) : response;
+        const headers = new Headers(response.headers);
+        headers.delete("content-length");
+        return replaceResponse(response, { body: formatted, headers });
+    });
+}

package/dist/response/range.d.ts

@@ -0,0 +1,19 @@
+/** A body that can hand out any byte span without reading the rest. */
+export type RangeSource = {
+    readonly size: number;
+    slice(start: number, endInclusive: number): Blob | ReadableStream<Uint8Array> | Uint8Array<ArrayBuffer>;
+};
+/** Bytes backed by a plain ArrayBuffer: a shared one cannot be a response body. */
+export type RangeBody = Blob | RangeSource | Uint8Array<ArrayBuffer>;
+export type RangeInit = {
+    /** Default: a Blob's own type, else `application/octet-stream`. */
+    contentType?: string;
+    headers?: Record<string, string>;
+};
+/**
+ * Answer `request` from `body` honoring its `Range` header. Only GET carries a range (RFC 9110
+ * §14.2); one satisfiable range is 206 with `Content-Range`, one past the end is 416, and several
+ * ranges, a malformed header or an `If-Range` (until validators exist, A4) get the whole body.
+ * Every answer says `Accept-Ranges: bytes`.
+ */
+export declare function rangeResponse(request: Request, body: RangeBody, init?: RangeInit): Response;

package/dist/response/range.js

@@ -0,0 +1,98 @@
+/**
+ * Range requests (A3, RFC 9110 §14): `rangeResponse` answers one satisfiable byte range with 206,
+ * a range past the end with 416, and everything else with the whole body. A plain helper:
+ * `staticFiles` and routes call it with the request. On the Node bridge each answer is a
+ * HoneyResponse, so the header middleware in front of it stay on the plain map.
+ */
+import { dict } from "../routing/tree.js";
+import { createHoneyResponse, isNodeOutbound, withRawBody } from "./builder.js";
+/** One range spec: two digit runs around a dash, each at most 15 digits (beyond that it names no real offset). */
+const SPEC = /^(\d{0,15})-(\d{0,15})$/;
+const UNIT = /^bytes=/i;
+function sizeOf(body) {
+    return body instanceof Uint8Array ? body.byteLength : body.size;
+}
+/**
+ * The span one `Range` header asks for: a Span, `"unsatisfiable"` when it lies past the end, or
+ * `null` when the header is not one byte range (malformed, another unit, several ranges) and is
+ * ignored (RFC 9110 §14.2). Linear in the header's length.
+ */
+function spanOf(header, size) {
+    if (!UNIT.test(header) || header.includes(","))
+        return null;
+    const match = SPEC.exec(header.slice(6));
+    if (match === null)
+        return null;
+    const [, first = "", last = ""] = match;
+    if (first === "" && last === "")
+        return null;
+    if (first === "") {
+        const suffix = Number(last);
+        return suffix === 0 || size === 0 ? "unsatisfiable" : { end: size - 1, start: Math.max(0, size - suffix) };
+    }
+    const start = Number(first);
+    if (last !== "" && Number(last) < start)
+        return null;
+    if (start >= size)
+        return "unsatisfiable";
+    return { end: last === "" ? size - 1 : Math.min(Number(last), size - 1), start };
+}
+function slice(body, span) {
+    if (body instanceof Uint8Array)
+        return body.subarray(span.start, span.end + 1);
+    if (body instanceof Blob)
+        return body.slice(span.start, span.end + 1);
+    return body.slice(span.start, span.end);
+}
+/** The answer's headers as a plain map, names lower-cased; no key can reach a prototype. */
+function headersFor(body, init) {
+    const headers = dict();
+    for (const [name, value] of Object.entries(init?.headers ?? {}))
+        headers[name.toLowerCase()] = value;
+    const own = body instanceof Blob && body.type !== "" ? body.type : "application/octet-stream";
+    headers["content-type"] = init?.contentType ?? own;
+    headers["accept-ranges"] = "bytes";
+    return headers;
+}
+/** One answer, built the way the bridge it goes out over writes it fastest; bytes are kept as its raw body. */
+function answer(request, part, headers, status) {
+    if (isNodeOutbound(request)) {
+        if (part === null || part instanceof Uint8Array)
+            return createHoneyResponse({ headers, raw: part, status });
+        return createHoneyResponse({ headers, status, stream: part instanceof Blob ? part.stream() : part });
+    }
+    /* as pairs, not a record: Node's Headers drops a record key named __proto__ */
+    const response = new Response(part, { headers: Object.entries(headers), status });
+    return part instanceof Uint8Array ? withRawBody(response, part) : response;
+}
+/** The whole body, 200; a HEAD gets the head alone, with the length GET would send. */
+function whole(request, body, headers) {
+    const size = sizeOf(body);
+    headers["content-length"] = String(size);
+    if (request.method === "HEAD" || size === 0)
+        return answer(request, null, headers, 200);
+    return answer(request, body instanceof Uint8Array ? body : slice(body, { end: size - 1, start: 0 }), headers, 200);
+}
+/**
+ * Answer `request` from `body` honoring its `Range` header. Only GET carries a range (RFC 9110
+ * §14.2); one satisfiable range is 206 with `Content-Range`, one past the end is 416, and several
+ * ranges, a malformed header or an `If-Range` (until validators exist, A4) get the whole body.
+ * Every answer says `Accept-Ranges: bytes`.
+ */
+export function rangeResponse(request, body, init) {
+    const headers = headersFor(body, init);
+    const header = request.headers.get("range");
+    if (request.method !== "GET" || header === null || request.headers.has("if-range"))
+        return whole(request, body, headers);
+    const size = sizeOf(body);
+    const span = spanOf(header, size);
+    if (span === null)
+        return whole(request, body, headers);
+    if (span === "unsatisfiable") {
+        headers["content-range"] = `bytes */${size}`;
+        return answer(request, null, headers, 416);
+    }
+    headers["content-range"] = `bytes ${span.start}-${span.end}/${size}`;
+    headers["content-length"] = String(span.end - span.start + 1);
+    return answer(request, slice(body, span), headers, 206);
+}

package/dist/response/response-headers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Declared response headers (A2): `.output({ headers: { [statusKey]: schema } })` checked against
+ * what an answer carries, when the app checks its answers. The schema sees the answer's headers by
+ * lowercased name, as `.input({ headers })` sees a request's. A failure is a 500 naming the status
+ * key and nothing of the issues.
+ */
+import type { HeaderSchemas } from "../routing/output-types.ts";
+/** A route's compiled header check: nothing back when it passes, a promise only for an async validator. */
+export type HeadersCheck = (response: Response) => Promise<void> | undefined;
+/** The check for a route declaring `schemas`, or `null` when no status declares headers. */
+export declare function compileResponseHeaders(schemas: HeaderSchemas | undefined): HeadersCheck | null;

package/dist/response/response-headers.js

@@ -0,0 +1,21 @@
+import { dict } from "../routing/tree.js";
+import { validateOutput } from "../validation/validate-output.js";
+import { codeToStatusKey } from "./status.js";
+/** The answer's headers as a record by lowercased name, repeated values joined as Fetch joins them. */
+function recordOf(headers) {
+    const record = dict();
+    headers.forEach((value, name) => {
+        record[name] = value;
+    });
+    return record;
+}
+/** The check for a route declaring `schemas`, or `null` when no status declares headers. */
+export function compileResponseHeaders(schemas) {
+    if (schemas === undefined || Object.keys(schemas).length === 0)
+        return null;
+    return (response) => {
+        const statusKey = codeToStatusKey[response.status];
+        const schema = statusKey === undefined ? undefined : schemas[statusKey];
+        return schema === undefined ? undefined : validateOutput(schema, statusKey, recordOf(response.headers));
+    };
+}

package/dist/response/response.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `HoneyRes`: the `ctx.res` helpers. Each builds a buffered response from a status key, records
+ * its raw body for later readers, and types it with a phantom content type and status key. On
+ * Node it builds the `HoneyResponse` bag instead of a Fetch `Response`.
+ */
+import { type CookieOptions } from "../context/cookie.ts";
+import type { Logger } from "../telemetry/logger.ts";
+import { type BinaryBody, type BinaryOptions } from "./binary.ts";
+import { type SSEOptions, type SSEStream } from "./sse.ts";
+import { type StatusKey } from "./status.ts";
+export type ResponseOptions = {
+    cookies?: Record<string, CookieOptions>;
+    headers?: Record<string, string>;
+    status?: number;
+};
+/** What `ctx.res` reads from its request, only when a stream needs it: the context itself is one. */
+export type ResLink = {
+    readonly log: Logger;
+    readonly req: Request;
+    readonly signal: AbortSignal;
+};
+export type GenerateOptions = ResponseOptions & {
+    contentType?: string;
+};
+type Generated = AsyncGenerator<string | Uint8Array, void, unknown> | Generator<string | Uint8Array, void, unknown>;
+declare const CONTENT_TYPE: unique symbol;
+declare const STATUS_KEY: unique symbol;
+/** A native Response branded with its content type and status key at the type level. */
+export type TypedResponse<CT extends string = string, SK extends string = string> = Response & {
+    readonly [CONTENT_TYPE]: CT;
+    readonly [STATUS_KEY]: SK;
+};
+export declare class HoneyRes {
+    #private;
+    protected readonly nodeOut: boolean;
+    /** `link` is the request a per-request res streams for; a bare res has none (no signal, no Last-Event-ID). */
+    constructor(nodeOut?: boolean, link?: ResLink);
+    /** Bytes as `opts.contentType` (`application/octet-stream` by default), kept as the raw body. */
+    binary<SK extends StatusKey, CT extends string = "application/octet-stream">(statusKey: SK, body: BinaryBody, opts?: BinaryOptions<CT>): TypedResponse<CT, SK>;
+    csv<SK extends StatusKey>(statusKey: SK, body: string, opts?: ResponseOptions): TypedResponse<"text/csv", SK>;
+    html<SK extends StatusKey>(statusKey: SK, body: string, opts?: ResponseOptions): TypedResponse<"text/html", SK>;
+    json<SK extends StatusKey>(statusKey: SK, data: unknown, opts?: ResponseOptions): TypedResponse<"application/json", SK>;
+    noContent(opts?: ResponseOptions): TypedResponse<"none", "no_content">;
+    /**
+     * Return a native Response. `fetch()`, `Fetcher.fetch`, `cache.match`, and `Response.redirect`
+     * return guarded headers that throw on `set`, which breaks response middleware. Copy status and
+     * headers into a new Response; the body streams through unread. WebSocket upgrades and responses
+     * Honey built pass through as-is. A response whose body was already read is a bug, usually one
+     * kept across requests: it throws instead of answering 200 with an unreadable body (H18.18).
+     */
+    raw(response: Response): TypedResponse;
+    /**
+     * Stream a generator's values. A disconnect or the request ending calls `generator.return()`,
+     * so its `finally` runs; a throw mid-stream breaks the body instead of ending it cleanly.
+     */
+    generate(generator: Generated, opts?: GenerateOptions): TypedResponse<string, "ok">;
+    /** An event stream; the client resumes from its `Last-Event-ID` unless `lastEventId` is given. */
+    sse(callback: (stream: SSEStream) => Promise<void>, opts?: ResponseOptions & SSEOptions): TypedResponse<"text/event-stream", "ok">;
+    /**
+     * Write the body through a `WritableStream`. The callback starts when the body is first read
+     * (never for HEAD); `signal` aborts when the client leaves or the request ends. Returning ends
+     * the body once queued writes flush, closed or not; throwing breaks it, even with a writer held.
+     */
+    stream(callback: (writable: WritableStream, signal: AbortSignal) => Promise<void>, opts?: ResponseOptions): TypedResponse<"application/octet-stream", "ok">;
+    redirect(url: string, opts?: ResponseOptions): TypedResponse<"none", "found">;
+    text<SK extends StatusKey>(statusKey: SK, body: string, opts?: ResponseOptions): TypedResponse<"text/plain", SK>;
+    xml<SK extends StatusKey>(statusKey: SK, body: string, opts?: ResponseOptions): TypedResponse<"application/xml", SK>;
+}
+export {};

package/dist/response/response.js

@@ -0,0 +1,208 @@
+/**
+ * `HoneyRes`: the `ctx.res` helpers. Each builds a buffered response from a status key, records
+ * its raw body for later readers, and types it with a phantom content type and status key. On
+ * Node it builds the `HoneyResponse` bag instead of a Fetch `Response`.
+ */
+import { serializeCookie } from "../context/cookie.js";
+import { generatorStream, producerStream } from "../streaming/producer-stream.js";
+import { createHoneyResponse, isHoneyResponse, isProducedStream, rawBodyOf, withProducedBody, withRawBody, } from "./builder.js";
+import { BINARY_HEADERS, binaryBytes, binaryHeaders } from "./binary.js";
+import { SSE_HEADERS, sseBody } from "./sse.js";
+import { statusKeyToCode } from "./status.js";
+/** Cast a Response to a TypedResponse: no runtime cost. */
+function typed(response) {
+    return response;
+}
+/* frozen: the Node path hands the map to the bag as its header map */
+const JSON_HEADERS = /* @__PURE__ */ Object.freeze({ "content-type": "application/json" });
+const TEXT_HEADERS = /* @__PURE__ */ Object.freeze({ "content-type": "text/plain; charset=utf-8" });
+const HTML_HEADERS = /* @__PURE__ */ Object.freeze({ "content-type": "text/html; charset=utf-8" });
+const CSV_HEADERS = /* @__PURE__ */ Object.freeze({ "content-type": "text/csv; charset=utf-8" });
+const XML_HEADERS = /* @__PURE__ */ Object.freeze({ "content-type": "application/xml" });
+function hasOptions(opts) {
+    return opts?.headers !== undefined || opts?.cookies !== undefined;
+}
+function applyNative(headers, opts) {
+    for (const [name, value] of Object.entries(opts?.headers ?? {}))
+        headers.set(name, value);
+    for (const [name, cookie] of Object.entries(opts?.cookies ?? {}))
+        headers.append("set-cookie", serializeCookie(name, cookie));
+    return headers;
+}
+function applyPlain(headers, opts) {
+    for (const [name, value] of Object.entries(opts?.headers ?? {}))
+        headers[name.toLowerCase()] = value;
+    if (opts?.cookies) {
+        /* append, as `Headers.append` does on the native path: a `set-cookie` in `opts.headers` stays */
+        const existing = headers["set-cookie"];
+        const cookies = existing === undefined ? [] : [existing].flat();
+        for (const [name, cookie] of Object.entries(opts.cookies))
+            cookies.push(serializeCookie(name, cookie));
+        headers["set-cookie"] = cookies;
+    }
+    return headers;
+}
+/** Statuses whose responses never carry a body (Fetch "null body status"). */
+function isNullBodyStatus(status) {
+    return status === 101 || status === 103 || status === 204 || status === 205 || status === 304;
+}
+// per-process-constant: text-codec
+const encoder = /* @__PURE__ */ new TextEncoder();
+function toBytes(chunk) {
+    if (chunk instanceof Uint8Array)
+        return chunk;
+    if (typeof chunk === "string")
+        return encoder.encode(chunk);
+    if (chunk instanceof ArrayBuffer)
+        return new Uint8Array(chunk);
+    if (ArrayBuffer.isView(chunk))
+        return new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+    throw new TypeError("ctx.res.stream() chunks must be strings, ArrayBuffers or typed arrays");
+}
+/**
+ * A WritableStream over a producer sink. `size()` counts each write as it enters the queue, so
+ * `flushed()` waits for every queued write even when the callback returned without closing.
+ */
+function writableOver(write, end) {
+    let queued = 0;
+    let written = 0;
+    let onDrained;
+    const writable = new WritableStream({
+        abort: (reason) => end.error(reason),
+        close: () => end.close(),
+        write: async (chunk) => {
+            try {
+                await write(toBytes(chunk));
+            }
+            finally {
+                written++;
+                if (written === queued)
+                    onDrained?.();
+            }
+        },
+    }, {
+        highWaterMark: 1,
+        size: () => {
+            queued++;
+            return 1;
+        },
+    });
+    /* a promise only when writes are still queued: most callbacks close or await their writes */
+    const pending = () => written === queued ? undefined : new Promise((resolve) => (onDrained = resolve));
+    return { pending, writable };
+}
+export class HoneyRes {
+    nodeOut;
+    #link;
+    /** `link` is the request a per-request res streams for; a bare res has none (no signal, no Last-Event-ID). */
+    constructor(nodeOut = false, link) {
+        this.nodeOut = nodeOut;
+        this.#link = link;
+    }
+    /** Producers end with the request; a failure breaks the body and goes to the request's logger. */
+    #producer() {
+        const link = this.#link;
+        if (link === undefined)
+            return {};
+        return {
+            report: (error) => link.log.error({ err: error }, "stream producer failed"),
+            signal: () => link.signal,
+        };
+    }
+    /** A streamed body under `base` headers plus the options' headers and cookies. */
+    #streamed(body, base, opts) {
+        const headers = hasOptions(opts) ? applyNative(new Headers(base), opts) : base;
+        return withProducedBody(new Response(body, { headers, status: opts?.status ?? 200 }));
+    }
+    /** A response with a body and no extra headers. */
+    #known(code, headers, raw, opts) {
+        const status = opts?.status ?? code;
+        /* `new Response(body, { status: 204 })` throws on the native path; fail the same way everywhere */
+        if (isNullBodyStatus(status)) {
+            throw new TypeError(`A ${status} response cannot have a body; use ctx.res.noContent() or another status`);
+        }
+        if (this.nodeOut) {
+            const map = hasOptions(opts) ? applyPlain({ ...headers }, opts) : headers;
+            return typed(createHoneyResponse({ headers: map, raw, status }));
+        }
+        const init = hasOptions(opts) ? applyNative(new Headers(headers), opts) : headers;
+        return typed(withRawBody(new Response(raw, { headers: init, status }), raw));
+    }
+    /** A response with no body. */
+    #empty(status, headers, opts) {
+        if (this.nodeOut)
+            return createHoneyResponse({ headers: applyPlain(headers, opts), raw: null, status });
+        return new Response(null, { headers: applyNative(new Headers(headers), opts), status });
+    }
+    /** Bytes as `opts.contentType` (`application/octet-stream` by default), kept as the raw body. */
+    binary(statusKey, body, opts) {
+        return this.#known(statusKeyToCode[statusKey], binaryHeaders(opts?.contentType), binaryBytes(body), opts);
+    }
+    csv(statusKey, body, opts) {
+        return this.#known(statusKeyToCode[statusKey], CSV_HEADERS, body, opts);
+    }
+    html(statusKey, body, opts) {
+        return this.#known(statusKeyToCode[statusKey], HTML_HEADERS, body, opts);
+    }
+    json(statusKey, data, opts) {
+        /* JSON.stringify answers undefined for undefined, a function or a symbol: an empty body, kept as one */
+        const body = JSON.stringify(data);
+        return this.#known(statusKeyToCode[statusKey], JSON_HEADERS, body ?? "", opts);
+    }
+    noContent(opts) {
+        return typed(this.#empty(204, {}, opts));
+    }
+    /**
+     * Return a native Response. `fetch()`, `Fetcher.fetch`, `cache.match`, and `Response.redirect`
+     * return guarded headers that throw on `set`, which breaks response middleware. Copy status and
+     * headers into a new Response; the body streams through unread. WebSocket upgrades and responses
+     * Honey built pass through as-is. A response whose body was already read is a bug, usually one
+     * kept across requests: it throws instead of answering 200 with an unreadable body (H18.18).
+     */
+    raw(response) {
+        if (response.bodyUsed)
+            throw new TypeError("raw(): this response's body was already read — build a new Response per request");
+        const built = isHoneyResponse(response) || rawBodyOf(response) !== null || isProducedStream(response);
+        if (response.status === 101 || built)
+            return typed(response);
+        return typed(new Response(response.body, response));
+    }
+    /**
+     * Stream a generator's values. A disconnect or the request ending calls `generator.return()`,
+     * so its `finally` runs; a throw mid-stream breaks the body instead of ending it cleanly.
+     */
+    generate(generator, opts) {
+        const base = binaryHeaders(opts?.contentType);
+        return typed(this.#streamed(generatorStream(generator, this.#producer()), base, opts));
+    }
+    /** An event stream; the client resumes from its `Last-Event-ID` unless `lastEventId` is given. */
+    sse(callback, opts) {
+        const lastEventId = opts?.lastEventId ?? this.#link?.req.headers.get("last-event-id") ?? undefined;
+        const body = sseBody(callback, { ...opts, lastEventId }, this.#producer());
+        return typed(this.#streamed(body, SSE_HEADERS, opts));
+    }
+    /**
+     * Write the body through a `WritableStream`. The callback starts when the body is first read
+     * (never for HEAD); `signal` aborts when the client leaves or the request ends. Returning ends
+     * the body once queued writes flush, closed or not; throwing breaks it, even with a writer held.
+     */
+    stream(callback, opts) {
+        const body = producerStream(async (sink) => {
+            const { pending, writable } = writableOver((bytes) => sink.write(bytes), sink);
+            await callback(writable, sink.signal);
+            const flushing = pending();
+            if (flushing !== undefined)
+                await Promise.race([flushing, new Promise((resolve) => sink.onEnd(resolve))]);
+        }, this.#producer());
+        return typed(this.#streamed(body, BINARY_HEADERS, opts));
+    }
+    redirect(url, opts) {
+        return typed(this.#empty(opts?.status ?? 302, { location: url }, opts));
+    }
+    text(statusKey, body, opts) {
+        return this.#known(statusKeyToCode[statusKey], TEXT_HEADERS, body, opts);
+    }
+    xml(statusKey, body, opts) {
+        return this.#known(statusKeyToCode[statusKey], XML_HEADERS, body, opts);
+    }
+}

package/dist/response/sse.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The `text/event-stream` emitter behind `ctx.res.sse()`: event framing, the retry and id
+ * directives, keepalive heartbeats, and the stream a callback writes events into.
+ */
+import { type ProducerOptions } from "../streaming/producer-stream.ts";
+export type SSEEvent = {
+    data: object | string;
+    event: string;
+    /** The id a reconnecting client sends back as `Last-Event-ID`; `""` tells it to forget its last one. */
+    id?: string;
+    /** Reconnect delay in ms; anything but a non-negative finite number is left out. */
+    retry?: number;
+};
+export type SSEOptions = {
+    /** A `retry:` directive sent before any event. */
+    defaultRetry?: number;
+    /** Send a heartbeat comment every this many ms while the stream is open. */
+    keepalive?: number;
+    /** The id the client resumes from. Default: its `Last-Event-ID` header. */
+    lastEventId?: string;
+};
+export type SSEStream = {
+    /** End the stream. Idempotent and synchronous: safe in a `finally`. */
+    close(): void;
+    /** True once the stream ended: closed, or the client went away. */
+    readonly closed: boolean;
+    readonly lastEventId: string | undefined;
+    /**
+     * Queue an event. Resolves when the client is ready for more. After the stream ended it
+     * rejects with an `AbortError`, which ends an awaiting loop; an unawaited one never surfaces
+     * as an unhandled rejection.
+     */
+    send(event: SSEEvent): Promise<void>;
+    /** Aborts when the client disconnects or the request ends. */
+    readonly signal: AbortSignal;
+};
+export declare const SSE_HEADERS: Readonly<Record<string, string>>;
+/** One event on the wire. A newline in the name or the id would start another field: it throws. */
+export declare function encodeEvent(event: SSEEvent): string;
+/** The body an SSE callback writes into; it ends when the callback settles, the client leaves, or the request ends. */
+export declare function sseBody(callback: (stream: SSEStream) => Promise<void>, options: SSEOptions, producer: ProducerOptions): ReadableStream<Uint8Array>;