@zudojs/http 0.1.0 → 1.0.0

package/dist/httpResponse/core/index.js

@@ -0,0 +1,8 @@
+/**
+ * Core response utilities.
+ *
+ * @module httpResponse/core
+ */
+export * from "./httpResponse.type.js";
+export * from "./httpResponse.statusText.js";
+//# sourceMappingURL=index.js.map

package/dist/httpResponse/http.response.d.ts

@@ -0,0 +1,34 @@
+import type { ServerResponse } from "node:http";
+import type { HTTPResponse, HTTPStatusCode } from "../httpTypes/http.types.js";
+export interface HTTPResponseOptions {
+    readonly defaultStatusCode?: HTTPStatusCode;
+}
+export declare class NodeHTTPResponse implements HTTPResponse {
+    private readonly response;
+    private readonly defaultStatusCode;
+    statusCode: HTTPStatusCode;
+    constructor(response: ServerResponse, options?: HTTPResponseOptions);
+    get headersSent(): boolean;
+    get finished(): boolean;
+    setHeader(name: string, value: string | readonly string[]): this;
+    getHeader(name: string): string | string[] | undefined;
+    removeHeader(name: string): this;
+    set(name: string, value: string | readonly string[]): this;
+    header(name: string, value: string | readonly string[]): this;
+    status(code: HTTPStatusCode): this;
+    type(contentType: string): this;
+    json<T = unknown>(data: T): Promise<void>;
+    send(body?: unknown): Promise<void>;
+    text(body: string): Promise<void>;
+    html(body: string): Promise<void>;
+    redirect(url: string, statusCode?: HTTPStatusCode | undefined): Promise<void>;
+    end(body?: Uint8Array): Promise<void>;
+    private writeBody;
+    private assertMutable;
+}
+export declare function createHTTPResponse(response: ServerResponse, options?: HTTPResponseOptions): NodeHTTPResponse;
+export declare function sendJSON(response: HTTPResponse, data: unknown, statusCode?: HTTPStatusCode): Promise<void>;
+export declare function sendText(response: HTTPResponse, body: string, statusCode?: HTTPStatusCode): Promise<void>;
+export declare function sendHTML(response: HTTPResponse, body: string, statusCode?: HTTPStatusCode): Promise<void>;
+export declare function redirect(response: HTTPResponse, url: string, statusCode?: HTTPStatusCode | undefined): Promise<void>;
+//# sourceMappingURL=http.response.d.ts.map

package/dist/httpResponse/http.response.js

@@ -0,0 +1,204 @@
+import { HTTP_CONTENT_TYPES, HTTP_HEADERS, HTTP_STATUS, } from "../httpConstants/http.constants.js";
+/* -------------------------------------------------------------------------- */
+/* Node HTTP Response                                                         */
+/* -------------------------------------------------------------------------- */
+export class NodeHTTPResponse {
+    response;
+    defaultStatusCode;
+    statusCode;
+    constructor(response, options = {}) {
+        this.response = response;
+        this.defaultStatusCode = options.defaultStatusCode ?? HTTP_STATUS.OK;
+        this.statusCode = this.defaultStatusCode;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* State                                                                    */
+    /* ------------------------------------------------------------------------ */
+    get headersSent() {
+        return this.response.headersSent;
+    }
+    get finished() {
+        return this.response.writableFinished;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Headers                                                                  */
+    /* ------------------------------------------------------------------------ */
+    setHeader(name, value) {
+        this.assertMutable();
+        this.response.setHeader(name, value);
+        return this;
+    }
+    getHeader(name) {
+        const value = this.response.getHeader(name);
+        if (Array.isArray(value)) {
+            return value.map(String);
+        }
+        if (value === undefined) {
+            return undefined;
+        }
+        return String(value);
+    }
+    removeHeader(name) {
+        this.assertMutable();
+        this.response.removeHeader(name);
+        return this;
+    }
+    set(name, value) {
+        return this.setHeader(name, value);
+    }
+    header(name, value) {
+        return this.setHeader(name, value);
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Status                                                                   */
+    /* ------------------------------------------------------------------------ */
+    status(code) {
+        this.assertMutable();
+        if (!Number.isInteger(code) || code < 100 || code > 999) {
+            throw new RangeError(`Invalid HTTP status code: ${code}`);
+        }
+        this.statusCode = code;
+        this.response.statusCode = code;
+        return this;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Content Type                                                              */
+    /* ------------------------------------------------------------------------ */
+    type(contentType) {
+        this.setHeader(HTTP_HEADERS.CONTENT_TYPE, contentType);
+        return this;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* JSON                                                                     */
+    /* ------------------------------------------------------------------------ */
+    async json(data) {
+        this.assertMutable();
+        const body = JSON.stringify(data);
+        if (!this.response.hasHeader(HTTP_HEADERS.CONTENT_TYPE)) {
+            this.response.setHeader(HTTP_HEADERS.CONTENT_TYPE, HTTP_CONTENT_TYPES.JSON_UTF8);
+        }
+        this.response.setHeader(HTTP_HEADERS.CONTENT_LENGTH, Buffer.byteLength(body, "utf8"));
+        await this.writeBody(body);
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Generic Send                                                              */
+    /* ------------------------------------------------------------------------ */
+    async send(body) {
+        this.assertMutable();
+        if (body === undefined || body === null) {
+            await this.end();
+            return;
+        }
+        if (typeof body === "string") {
+            if (!this.response.hasHeader(HTTP_HEADERS.CONTENT_TYPE)) {
+                this.response.setHeader(HTTP_HEADERS.CONTENT_TYPE, HTTP_CONTENT_TYPES.TEXT_UTF8);
+            }
+            await this.writeBody(body);
+            return;
+        }
+        if (Buffer.isBuffer(body) || body instanceof Uint8Array) {
+            if (!this.response.hasHeader(HTTP_HEADERS.CONTENT_TYPE)) {
+                this.response.setHeader(HTTP_HEADERS.CONTENT_TYPE, HTTP_CONTENT_TYPES.OCTET_STREAM);
+            }
+            await this.writeBody(Buffer.from(body));
+            return;
+        }
+        await this.json(body);
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Text                                                                     */
+    /* ------------------------------------------------------------------------ */
+    async text(body) {
+        this.assertMutable();
+        if (!this.response.hasHeader(HTTP_HEADERS.CONTENT_TYPE)) {
+            this.response.setHeader(HTTP_HEADERS.CONTENT_TYPE, HTTP_CONTENT_TYPES.TEXT_UTF8);
+        }
+        await this.writeBody(body);
+    }
+    /* ------------------------------------------------------------------------ */
+    /* HTML                                                                     */
+    /* ------------------------------------------------------------------------ */
+    async html(body) {
+        this.assertMutable();
+        if (!this.response.hasHeader(HTTP_HEADERS.CONTENT_TYPE)) {
+            this.response.setHeader(HTTP_HEADERS.CONTENT_TYPE, HTTP_CONTENT_TYPES.HTML_UTF8);
+        }
+        await this.writeBody(body);
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Redirect                                                                 */
+    /* ------------------------------------------------------------------------ */
+    async redirect(url, statusCode = HTTP_STATUS.FOUND) {
+        this.assertMutable();
+        this.status(statusCode);
+        this.setHeader(HTTP_HEADERS.LOCATION, url);
+        await this.end();
+    }
+    /* ------------------------------------------------------------------------ */
+    /* End                                                                      */
+    /* ------------------------------------------------------------------------ */
+    async end(body) {
+        this.assertMutable();
+        if (body && body.byteLength > 0) {
+            await this.writeBody(Buffer.from(body));
+            return;
+        }
+        await new Promise((resolve, reject) => {
+            this.response.end(() => resolve());
+            this.response.once("error", reject);
+        });
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Internal Write                                                           */
+    /* ------------------------------------------------------------------------ */
+    async writeBody(body) {
+        this.assertMutable();
+        const buffer = typeof body === "string" ? Buffer.from(body, "utf8") : Buffer.from(body);
+        if (!this.response.hasHeader(HTTP_HEADERS.CONTENT_LENGTH)) {
+            this.response.setHeader(HTTP_HEADERS.CONTENT_LENGTH, buffer.byteLength);
+        }
+        await new Promise((resolve, reject) => {
+            this.response.end(buffer, () => resolve());
+            this.response.once("error", reject);
+        });
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Validation                                                               */
+    /* ------------------------------------------------------------------------ */
+    assertMutable() {
+        if (this.response.headersSent || this.response.writableEnded) {
+            throw new Error("HTTP response has already been sent.");
+        }
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Factory                                                                    */
+/* -------------------------------------------------------------------------- */
+export function createHTTPResponse(response, options = {}) {
+    return new NodeHTTPResponse(response, options);
+}
+/* -------------------------------------------------------------------------- */
+/* Response Helpers                                                           */
+/* -------------------------------------------------------------------------- */
+export async function sendJSON(response, data, statusCode) {
+    if (statusCode !== undefined) {
+        response.status(statusCode);
+    }
+    await response.json(data);
+}
+export async function sendText(response, body, statusCode) {
+    if (statusCode !== undefined) {
+        response.status(statusCode);
+    }
+    await response.text(body);
+}
+export async function sendHTML(response, body, statusCode) {
+    if (statusCode !== undefined) {
+        response.status(statusCode);
+    }
+    await response.html(body);
+}
+export async function redirect(response, url, statusCode = HTTP_STATUS.FOUND) {
+    await response.redirect(url, statusCode);
+}
+//# sourceMappingURL=http.response.js.map

package/dist/httpResponse/httpResponse.context.d.ts

@@ -0,0 +1,60 @@
+/**
+ * HTTP response context implementation.
+ *
+ * @module httpResponse/context
+ */
+import type { ResponseBody, ResponseHeaders, ResponseContextInit, ResponseCookie, ResponseContextSnapshot } from "./core/httpResponse.type.js";
+export declare class HttpResponseContext {
+    private _status;
+    private _statusText;
+    private _headers;
+    private _body;
+    private _cookies;
+    private _sent;
+    private _timestamp;
+    constructor(init?: ResponseContextInit);
+    get status(): number;
+    get statusText(): string;
+    get headers(): ResponseHeaders;
+    get body(): ResponseBody;
+    get cookies(): readonly ResponseCookie[];
+    get sent(): boolean;
+    get timestamp(): number;
+    status_code(code: number): this;
+    header(name: string, value: string | string[]): this;
+    headers_obj(headers: ResponseHeaders): this;
+    setBody(body: ResponseBody): this;
+    json(data: unknown): this;
+    text(content: string): this;
+    html(content: string): this;
+    cookie(name: string, value: string, options?: ResponseCookie["options"]): this;
+    removeCookie(name: string): this;
+    redirect(url: string, status?: number): this;
+    markSent(): void;
+    assertMutable(): void;
+    commit(): void;
+    get contentType(): string | undefined;
+    set contentType(value: string | undefined);
+    get contentLength(): number | undefined;
+    setContentType(value: string): this;
+    setContentLength(value: number): this;
+    removeHeader(name: string): this;
+    setStatus(code: number, statusText?: string): this;
+    setHeader(name: string, value: string): this;
+    setCookie(cookie: ResponseCookie): this;
+    private _metadata;
+    get metadata(): Readonly<Record<string, unknown>>;
+    setMetadata(key: string, value: unknown): this;
+    internalServerError(): this;
+    snapshot(): ResponseContextSnapshot;
+    clone(): HttpResponseContext;
+}
+/**
+ * Creates a new response context.
+ */
+export declare function createResponseContext(init?: ResponseContextInit): HttpResponseContext;
+export * from "./core/httpResponse.type.js";
+export * from "./core/httpResponse.statusText.js";
+export * from "./httpResponse.helper.js";
+export type { ResponseCookie, CookieOptions, SameSite, CookiePriority, } from "./core/httpResponse.type.js";
+//# sourceMappingURL=httpResponse.context.d.ts.map

package/dist/httpResponse/httpResponse.context.js

@@ -0,0 +1,195 @@
+/**
+ * HTTP response context implementation.
+ *
+ * @module httpResponse/context
+ */
+import { DEFAULT_RESPONSE_STATUS } from "./core/httpResponse.type.js";
+import { getStatusText } from "./core/httpResponse.statusText.js";
+export class HttpResponseContext {
+    _status;
+    _statusText;
+    _headers;
+    _body;
+    _cookies;
+    _sent = false;
+    _timestamp;
+    constructor(init = {}) {
+        this._status = init.status ?? DEFAULT_RESPONSE_STATUS;
+        this._statusText = init.statusText ?? getStatusText(this._status);
+        this._headers = { ...init.headers };
+        this._body = init.body;
+        this._cookies = [...(init.cookies ?? [])];
+        this._timestamp = Date.now();
+    }
+    get status() {
+        return this._status;
+    }
+    get statusText() {
+        return this._statusText;
+    }
+    get headers() {
+        return { ...this._headers };
+    }
+    get body() {
+        return this._body;
+    }
+    get cookies() {
+        return this._cookies;
+    }
+    get sent() {
+        return this._sent;
+    }
+    get timestamp() {
+        return this._timestamp;
+    }
+    status_code(code) {
+        this._status = code;
+        this._statusText = getStatusText(code);
+        return this;
+    }
+    header(name, value) {
+        this._headers[name.toLowerCase()] = value;
+        return this;
+    }
+    headers_obj(headers) {
+        for (const [key, value] of Object.entries(headers)) {
+            if (value !== undefined) {
+                this._headers[key.toLowerCase()] = value;
+            }
+        }
+        return this;
+    }
+    setBody(body) {
+        this._body = body;
+        return this;
+    }
+    json(data) {
+        this._body = JSON.stringify(data);
+        this._headers["content-type"] = "application/json";
+        return this;
+    }
+    text(content) {
+        this._body = content;
+        this._headers["content-type"] = "text/plain";
+        return this;
+    }
+    html(content) {
+        this._body = content;
+        this._headers["content-type"] = "text/html";
+        return this;
+    }
+    cookie(name, value, options) {
+        this._cookies.push({ name, value, options });
+        return this;
+    }
+    removeCookie(name) {
+        this._cookies = this._cookies.filter((c) => c.name !== name);
+        return this;
+    }
+    redirect(url, status = 302) {
+        this._status = status;
+        this._statusText = getStatusText(status);
+        this._headers["location"] = url;
+        return this;
+    }
+    markSent() {
+        this._sent = true;
+    }
+    assertMutable() {
+        if (this._sent) {
+            throw new Error("Response context is already sent");
+        }
+    }
+    commit() {
+        this._sent = true;
+        this._timestamp = Date.now();
+    }
+    get contentType() {
+        const ct = this._headers["content-type"];
+        return typeof ct === "string" ? ct : undefined;
+    }
+    set contentType(value) {
+        if (value !== undefined) {
+            this._headers["content-type"] = value;
+        }
+    }
+    get contentLength() {
+        const cl = this._headers["content-length"];
+        if (typeof cl === "string") {
+            return parseInt(cl, 10);
+        }
+        return undefined;
+    }
+    setContentType(value) {
+        this._headers["content-type"] = value;
+        return this;
+    }
+    setContentLength(value) {
+        this._headers["content-length"] = String(value);
+        return this;
+    }
+    removeHeader(name) {
+        delete this._headers[name.toLowerCase()];
+        return this;
+    }
+    /* ------------------------------------------------------------------ */
+    /* Adapter-compatible setters                                         */
+    /* ------------------------------------------------------------------ */
+    setStatus(code, statusText) {
+        this._status = code;
+        this._statusText = statusText ?? getStatusText(code);
+        return this;
+    }
+    setHeader(name, value) {
+        this._headers[name.toLowerCase()] = value;
+        return this;
+    }
+    setCookie(cookie) {
+        this._cookies.push(cookie);
+        return this;
+    }
+    _metadata = {};
+    get metadata() {
+        return { ...this._metadata };
+    }
+    setMetadata(key, value) {
+        this._metadata[key] = value;
+        return this;
+    }
+    internalServerError() {
+        this._status = 500;
+        this._statusText = getStatusText(500);
+        return this;
+    }
+    snapshot() {
+        return {
+            status: this._status,
+            statusText: this._statusText,
+            headers: { ...this._headers },
+            body: this._body,
+            cookies: [...this._cookies],
+            sent: this._sent,
+            timestamp: this._timestamp,
+        };
+    }
+    clone() {
+        const clone = new HttpResponseContext({
+            status: this._status,
+            statusText: this._statusText,
+            headers: { ...this._headers },
+            body: this._body,
+            cookies: [...this._cookies],
+        });
+        return clone;
+    }
+}
+/**
+ * Creates a new response context.
+ */
+export function createResponseContext(init) {
+    return new HttpResponseContext(init);
+}
+export * from "./core/httpResponse.type.js";
+export * from "./core/httpResponse.statusText.js";
+export * from "./httpResponse.helper.js";
+//# sourceMappingURL=httpResponse.context.js.map

package/dist/httpResponse/httpResponse.fromWeb.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Conversion from a WHATWG `Response` into an {@link HttpResponseContext}.
+ *
+ * @module httpResponse/fromWeb
+ *
+ * Returning a plain web `Response` from a middleware is part of the public
+ * contract (`HttpMiddlewareResult` includes `Response`), but nothing in the
+ * package ever converted one. Both middleware normalizers fabricated
+ * `{ response } as unknown as ResponseContext` — an object with no `status`,
+ * no `headers` and no `body`, which the adapter then read as `undefined`.
+ *
+ * A `Response` is not a response context and cannot be cast into one: its
+ * headers live in a `Headers` instance (no own enumerable properties, so
+ * spreading yields `{}`) and its body is a `ReadableStream`. The conversion
+ * has to be written out, and it is written here once so that the pipeline and
+ * the built-in middleware share it.
+ */
+import { HttpResponseContext } from "./httpResponse.context.js";
+/**
+ * Narrows an unknown value to a WHATWG `Response`.
+ *
+ * @param value - Candidate value.
+ * @returns `true` when `value` is a `Response` instance.
+ */
+export declare function isWebResponse(value: unknown): value is Response;
+/**
+ * Converts a web `Response` into a response context, streaming its body.
+ *
+ * The body is carried across as the `Response`'s own `ReadableStream`; the
+ * response writer already has a streaming branch with backpressure handling,
+ * so nothing is buffered and an unbounded stream stays unbounded. This keeps
+ * the conversion synchronous, which is what lets the middleware normalizer
+ * stay synchronous too.
+ *
+ * The stream can only be consumed once, so this suits a `Response` built for
+ * a single request. For a `Response` value reused across requests use
+ * {@link bufferWebResponse}.
+ *
+ * @param response - The web response to convert.
+ * @returns An equivalent response context.
+ * @throws {TypeError} If the response body has already been consumed.
+ */
+export declare function webResponseToContext(response: Response): HttpResponseContext;
+/**
+ * Converts a web `Response` into a response context, reading its body into
+ * memory.
+ *
+ * Use this for a `Response` that has to survive more than one request: the
+ * resulting context holds bytes rather than a one-shot stream, so it can be
+ * cloned per request.
+ *
+ * @param response - The web response to convert.
+ * @returns An equivalent response context holding a buffered body.
+ * @throws {TypeError} If the response body has already been consumed.
+ */
+export declare function bufferWebResponse(response: Response): Promise<HttpResponseContext>;
+//# sourceMappingURL=httpResponse.fromWeb.d.ts.map

package/dist/httpResponse/httpResponse.fromWeb.js

@@ -0,0 +1,114 @@
+/**
+ * Conversion from a WHATWG `Response` into an {@link HttpResponseContext}.
+ *
+ * @module httpResponse/fromWeb
+ *
+ * Returning a plain web `Response` from a middleware is part of the public
+ * contract (`HttpMiddlewareResult` includes `Response`), but nothing in the
+ * package ever converted one. Both middleware normalizers fabricated
+ * `{ response } as unknown as ResponseContext` — an object with no `status`,
+ * no `headers` and no `body`, which the adapter then read as `undefined`.
+ *
+ * A `Response` is not a response context and cannot be cast into one: its
+ * headers live in a `Headers` instance (no own enumerable properties, so
+ * spreading yields `{}`) and its body is a `ReadableStream`. The conversion
+ * has to be written out, and it is written here once so that the pipeline and
+ * the built-in middleware share it.
+ */
+import { HttpResponseContext } from "./httpResponse.context.js";
+/**
+ * Narrows an unknown value to a WHATWG `Response`.
+ *
+ * @param value - Candidate value.
+ * @returns `true` when `value` is a `Response` instance.
+ */
+export function isWebResponse(value) {
+    return typeof Response !== "undefined" && value instanceof Response;
+}
+/**
+ * Copies a `Response`'s headers into a plain header record.
+ *
+ * `set-cookie` is read through `getSetCookie()` so that multiple cookies stay
+ * separate values; iterating `Headers` alone joins them into one
+ * comma-separated string, which is invalid for that header.
+ */
+function collectHeaders(headers) {
+    const collected = {};
+    for (const [name, value] of headers.entries()) {
+        if (name.toLowerCase() === "set-cookie") {
+            continue;
+        }
+        collected[name.toLowerCase()] = value;
+    }
+    const setCookies = typeof headers.getSetCookie === "function" ? headers.getSetCookie() : [];
+    if (setCookies.length > 0) {
+        collected["set-cookie"] = setCookies;
+    }
+    return collected;
+}
+function assertBodyReadable(response) {
+    if (response.bodyUsed) {
+        /*
+         * Silently producing a body-less context here would drop the payload the
+         * middleware meant to send, which is exactly the failure this module
+         * exists to remove. Fail loudly instead.
+         */
+        throw new TypeError("Cannot convert a Response whose body has already been consumed. " +
+            "Return a fresh Response per request, or clone it before reading.");
+    }
+}
+/**
+ * Converts a web `Response` into a response context, streaming its body.
+ *
+ * The body is carried across as the `Response`'s own `ReadableStream`; the
+ * response writer already has a streaming branch with backpressure handling,
+ * so nothing is buffered and an unbounded stream stays unbounded. This keeps
+ * the conversion synchronous, which is what lets the middleware normalizer
+ * stay synchronous too.
+ *
+ * The stream can only be consumed once, so this suits a `Response` built for
+ * a single request. For a `Response` value reused across requests use
+ * {@link bufferWebResponse}.
+ *
+ * @param response - The web response to convert.
+ * @returns An equivalent response context.
+ * @throws {TypeError} If the response body has already been consumed.
+ */
+export function webResponseToContext(response) {
+    assertBodyReadable(response);
+    return new HttpResponseContext({
+        status: response.status,
+        statusText: response.statusText === "" ? undefined : response.statusText,
+        headers: collectHeaders(response.headers),
+        body: response.body ?? undefined,
+    });
+}
+/**
+ * Converts a web `Response` into a response context, reading its body into
+ * memory.
+ *
+ * Use this for a `Response` that has to survive more than one request: the
+ * resulting context holds bytes rather than a one-shot stream, so it can be
+ * cloned per request.
+ *
+ * @param response - The web response to convert.
+ * @returns An equivalent response context holding a buffered body.
+ * @throws {TypeError} If the response body has already been consumed.
+ */
+export async function bufferWebResponse(response) {
+    assertBodyReadable(response);
+    const headers = collectHeaders(response.headers);
+    const status = response.status;
+    const statusText = response.statusText === "" ? undefined : response.statusText;
+    if (response.body === null) {
+        return new HttpResponseContext({ status, statusText, headers });
+    }
+    const buffer = await response.arrayBuffer();
+    return new HttpResponseContext({
+        status,
+        statusText,
+        headers,
+        body: new Uint8Array(buffer),
+    });
+}
+//# sourceMappingURL=httpResponse.fromWeb.js.map