@zudojs/http 0.1.0 → 1.1.0

package/dist/httpRequest/http.request.js

@@ -0,0 +1,313 @@
+import { HTTP_HEADERS } from "../httpConstants/http.constants.js";
+import { InvalidJSONError } from "../httpErrors/httpError.helper.js";
+/* -------------------------------------------------------------------------- */
+/* Request Headers                                                            */
+/* -------------------------------------------------------------------------- */
+export class NodeHTTPHeaders {
+    headers;
+    constructor(source) {
+        this.headers = new Headers();
+        if (source instanceof Headers) {
+            source.forEach((value, name) => {
+                this.headers.set(name, value);
+            });
+            return;
+        }
+        if (source) {
+            for (const [name, value] of Object.entries(source)) {
+                if (Array.isArray(value)) {
+                    this.headers.set(name, value.join(", "));
+                }
+                else if (value !== undefined) {
+                    this.headers.set(name, value);
+                }
+            }
+        }
+    }
+    get(name) {
+        return this.headers.get(name);
+    }
+    set(name, value) {
+        this.headers.set(name, value);
+    }
+    append(name, value) {
+        this.headers.append(name, value);
+    }
+    has(name) {
+        return this.headers.has(name);
+    }
+    delete(name) {
+        this.headers.delete(name);
+    }
+    entries() {
+        return this.headers.entries();
+    }
+    keys() {
+        return this.headers.keys();
+    }
+    values() {
+        return this.headers.values();
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Node Request                                                               */
+/* -------------------------------------------------------------------------- */
+export class NodeHTTPRequest {
+    method;
+    url;
+    path;
+    originalUrl;
+    headers;
+    query;
+    params;
+    protocol;
+    hostname;
+    ip;
+    ips;
+    secure;
+    rawBody;
+    body;
+    signal;
+    cachedText;
+    cachedJSON;
+    jsonParsed = false;
+    constructor(request, options = {}) {
+        const protocol = getRequestProtocol(request);
+        const host = getRequestHost(request);
+        const path = getRequestPath(request);
+        this.method = normalizeHTTPMethod(request.method);
+        this.url = request.url ?? path;
+        this.path = path;
+        this.originalUrl = this.url;
+        this.headers = new NodeHTTPHeaders(request.headers);
+        this.query = options.query ?? parseQueryString(this.url);
+        this.params = options.params ?? {};
+        this.protocol = protocol;
+        this.hostname = getHostname(host);
+        this.ip = options.ip ?? getRequestIP(request);
+        this.ips = options.ips;
+        this.secure = protocol === "https" || protocol === "wss";
+        this.rawBody = options.rawBody;
+        this.body = options.body;
+        this.signal = options.signal;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Headers                                                                  */
+    /* ------------------------------------------------------------------------ */
+    getHeader(name) {
+        return this.headers.get(name) ?? undefined;
+    }
+    get(name) {
+        return this.getHeader(name);
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Content Negotiation                                                      */
+    /* ------------------------------------------------------------------------ */
+    accepts(...types) {
+        if (types.length === 0) {
+            return false;
+        }
+        const accept = this.getHeader(HTTP_HEADERS.ACCEPT);
+        if (!accept || accept.trim() === "*/*") {
+            return types[0] ?? false;
+        }
+        const accepted = parseAcceptHeader(accept);
+        for (const type of types) {
+            if (accepted.some((candidate) => candidate === "*/*" ||
+                candidate === type.toLowerCase() ||
+                mediaTypeMatches(candidate, type))) {
+                return type;
+            }
+        }
+        return false;
+    }
+    is(...types) {
+        const contentType = this.getHeader(HTTP_HEADERS.CONTENT_TYPE);
+        if (!contentType) {
+            return false;
+        }
+        const normalized = (contentType.split(";", 1)[0] ?? "")
+            .trim()
+            .toLowerCase();
+        for (const type of types) {
+            const normalizedType = (type.split(";", 1)[0] ?? "").trim().toLowerCase();
+            if (normalized === normalizedType ||
+                mediaTypeMatches(normalized, normalizedType)) {
+                return type;
+            }
+        }
+        return false;
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Body                                                                      */
+    /* ------------------------------------------------------------------------ */
+    async json() {
+        if (this.jsonParsed) {
+            return this.cachedJSON;
+        }
+        const text = await this.text();
+        try {
+            const parsed = JSON.parse(text);
+            this.cachedJSON = parsed;
+            this.jsonParsed = true;
+            return parsed;
+        }
+        catch (error) {
+            throw new InvalidJSONError("Request body contains invalid JSON.", {
+                cause: error,
+            });
+        }
+    }
+    async text() {
+        if (this.cachedText !== undefined) {
+            return this.cachedText;
+        }
+        if (!this.rawBody) {
+            this.cachedText = "";
+            return "";
+        }
+        this.cachedText = Buffer.from(this.rawBody).toString("utf8");
+        return this.cachedText;
+    }
+    async buffer() {
+        return this.rawBody ?? new Uint8Array();
+    }
+    /* ------------------------------------------------------------------------ */
+    /* State                                                                     */
+    /* ------------------------------------------------------------------------ */
+    get signalAborted() {
+        return this.signal?.aborted ?? false;
+    }
+    get abortedBySignal() {
+        return this.signalAborted;
+    }
+    /**
+     * Whether the request has been aborted.
+     *
+     * This was previously a declared-but-never-assigned field, so it read as
+     * `undefined` on every instance and no abort check against it ever fired.
+     */
+    get aborted() {
+        return this.signalAborted;
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Factory                                                                    */
+/* -------------------------------------------------------------------------- */
+export function createHTTPRequest(request, options = {}) {
+    return new NodeHTTPRequest(request, options);
+}
+/* -------------------------------------------------------------------------- */
+/* Request URL                                                                */
+/* -------------------------------------------------------------------------- */
+export function getRequestPath(request) {
+    const raw = request.url ?? "/";
+    const queryIndex = raw.indexOf("?");
+    if (queryIndex < 0) {
+        return raw || "/";
+    }
+    return raw.slice(0, queryIndex) || "/";
+}
+export function getRequestHost(request) {
+    const host = request.headers[HTTP_HEADERS.HOST];
+    if (Array.isArray(host)) {
+        return host[0] ?? "";
+    }
+    return host ?? "";
+}
+export function getHostname(host) {
+    if (host.startsWith("[")) {
+        const end = host.indexOf("]", 1);
+        return end >= 0 ? host.slice(1, end) : host;
+    }
+    const separator = host.lastIndexOf(":");
+    if (separator > 0 && host.indexOf(":") === separator) {
+        return host.slice(0, separator);
+    }
+    return host;
+}
+/* -------------------------------------------------------------------------- */
+/* Protocol                                                                   */
+/* -------------------------------------------------------------------------- */
+export function getRequestProtocol(request) {
+    const forwarded = request.headers[HTTP_HEADERS.X_FORWARDED_PROTO];
+    if (typeof forwarded === "string") {
+        return (forwarded.split(",", 1)[0] ?? "").trim().toLowerCase();
+    }
+    if ("encrypted" in request.socket &&
+        request.socket.encrypted) {
+        return "https";
+    }
+    return "http";
+}
+/* -------------------------------------------------------------------------- */
+/* IP                                                                         */
+/* -------------------------------------------------------------------------- */
+export function getRequestIP(request) {
+    const forwarded = request.headers[HTTP_HEADERS.X_FORWARDED_FOR];
+    if (typeof forwarded === "string") {
+        const first = forwarded.split(",", 1)[0]?.trim();
+        if (first) {
+            return first;
+        }
+    }
+    return request.socket.remoteAddress ?? undefined;
+}
+/* -------------------------------------------------------------------------- */
+/* Query                                                                      */
+/* -------------------------------------------------------------------------- */
+export function parseQueryString(url) {
+    const queryIndex = url.indexOf("?");
+    if (queryIndex < 0) {
+        return {};
+    }
+    const queryString = url.slice(queryIndex + 1);
+    if (!queryString) {
+        return {};
+    }
+    const searchParams = new URLSearchParams(queryString);
+    const result = {};
+    for (const [key, value] of searchParams.entries()) {
+        const existing = result[key];
+        if (existing === undefined) {
+            result[key] = value;
+            continue;
+        }
+        if (Array.isArray(existing)) {
+            result[key] = [...existing, value];
+            continue;
+        }
+        result[key] = [existing, value];
+    }
+    return result;
+}
+/* -------------------------------------------------------------------------- */
+/* Method                                                                     */
+/* -------------------------------------------------------------------------- */
+export function normalizeHTTPMethod(method) {
+    const normalized = (method ?? "GET").toUpperCase();
+    return normalized;
+}
+/* -------------------------------------------------------------------------- */
+/* Accept Header                                                              */
+/* -------------------------------------------------------------------------- */
+export function parseAcceptHeader(value) {
+    return value
+        .split(",")
+        .map((part) => (part.split(";", 1)[0] ?? "").trim().toLowerCase())
+        .filter(Boolean);
+}
+export function mediaTypeMatches(candidate, requested) {
+    const candidateParts = candidate.toLowerCase().split("/");
+    const requestedParts = requested.toLowerCase().split("/");
+    if (candidateParts.length !== 2 || requestedParts.length !== 2) {
+        return false;
+    }
+    return ((candidateParts[0] === "*" ||
+        requestedParts[0] === "*" ||
+        candidateParts[0] === requestedParts[0]) &&
+        (candidateParts[1] === "*" ||
+            requestedParts[1] === "*" ||
+            candidateParts[1] === requestedParts[1]));
+}
+//# sourceMappingURL=http.request.js.map

package/dist/httpRequest/httpRequest.context.constant.d.ts

@@ -0,0 +1,8 @@
+/**
+ * HTTP request context constants.
+ *
+ * DI token and well-known header name for request identification.
+ */
+export declare const REQUEST_CONTEXT: unique symbol;
+export declare const REQUEST_ID_HEADER = "x-request-id";
+//# sourceMappingURL=httpRequest.context.constant.d.ts.map

package/dist/httpRequest/httpRequest.context.d.ts

@@ -0,0 +1,122 @@
+/**
+ * HTTP request context.
+ *
+ * Provides a request-scoped container for HTTP metadata, headers, body,
+ * parameters, state, and lifecycle information.
+ *
+ * The context is intentionally framework-agnostic so adapters can populate it
+ * from Node.js, Bun, Deno, or another HTTP runtime.
+ */
+export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "CONNECT" | "TRACE" | string;
+export type RequestHeaders = Readonly<Record<string, string>>;
+export type RequestQuery = Readonly<Record<string, string | readonly string[] | undefined>>;
+export type RequestParams = Readonly<Record<string, string | undefined>>;
+export type RequestBody = unknown;
+export type RequestState = Record<string | symbol, unknown>;
+export interface RequestContextInit {
+    readonly id?: string;
+    readonly method: HttpMethod;
+    readonly url: string;
+    readonly headers?: RequestHeaders;
+    readonly query?: RequestQuery;
+    readonly params?: RequestParams;
+    readonly body?: RequestBody;
+    readonly remoteAddress?: string;
+    readonly protocol?: string;
+    readonly hostname?: string;
+    readonly port?: number;
+    readonly path?: string;
+    readonly signal?: AbortSignal;
+    readonly state?: RequestState;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface RequestContextSnapshot {
+    readonly id: string;
+    readonly method: HttpMethod;
+    readonly url: string;
+    readonly path: string;
+    readonly headers: RequestHeaders;
+    readonly query: RequestQuery;
+    readonly params: RequestParams;
+    readonly body: RequestBody;
+    readonly remoteAddress: string | undefined;
+    readonly protocol: string | undefined;
+    readonly hostname: string | undefined;
+    readonly port: number | undefined;
+    readonly state: Readonly<RequestState>;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly createdAt: number;
+}
+export declare const REQUEST_CONTEXT: unique symbol;
+export declare const REQUEST_ID_HEADER = "x-request-id";
+export declare function generateRequestId(): string;
+export declare class HttpRequestContext {
+    readonly id: string;
+    readonly method: HttpMethod;
+    readonly url: string;
+    readonly path: string;
+    readonly createdAt: number;
+    private readonly headersMap;
+    private readonly queryMap;
+    private readonly paramsMap;
+    private readonly stateMap;
+    private readonly metadataMap;
+    private requestBody;
+    private remoteAddressValue;
+    private protocolValue;
+    private hostnameValue;
+    private portValue;
+    constructor(init: RequestContextInit);
+    get headers(): RequestHeaders;
+    hasHeader(name: string): boolean;
+    getHeader(name: string): string | undefined;
+    setHeader(name: string, value: string): this;
+    appendHeader(name: string, value: string): this;
+    removeHeader(name: string): boolean;
+    get query(): RequestQuery;
+    hasQuery(name: string): boolean;
+    getQuery(name: string): string | readonly string[] | undefined;
+    setQuery(name: string, value: string | readonly string[] | undefined): this;
+    removeQuery(name: string): boolean;
+    get params(): RequestParams;
+    hasParam(name: string): boolean;
+    getParam(name: string): string | undefined;
+    setParam(name: string, value: string | undefined): this;
+    removeParam(name: string): boolean;
+    get body(): unknown;
+    setBody(body: unknown): this;
+    get remoteAddress(): string | undefined;
+    setRemoteAddress(address: string | undefined): this;
+    get protocol(): string | undefined;
+    setProtocol(protocol: string | undefined): this;
+    get hostname(): string | undefined;
+    setHostname(hostname: string | undefined): this;
+    get port(): number | undefined;
+    setPort(port: number | undefined): this;
+    get secure(): boolean;
+    get state(): Readonly<RequestState>;
+    hasState(key: string | symbol): boolean;
+    getState<T = unknown>(key: string | symbol): T | undefined;
+    setState<T>(key: string | symbol, value: T): this;
+    removeState(key: string | symbol): boolean;
+    get metadata(): Readonly<Record<string, unknown>>;
+    hasMetadata(key: string): boolean;
+    getMetadata<T = unknown>(key: string): T | undefined;
+    setMetadata<T>(key: string, value: T): this;
+    removeMetadata(key: string): boolean;
+    get origin(): string | undefined;
+    get userAgent(): string | undefined;
+    get contentType(): string | undefined;
+    get contentLength(): number | undefined;
+    get requestId(): string;
+    snapshot(): RequestContextSnapshot;
+    clone(): HttpRequestContext;
+}
+export declare function createRequestContext(init: RequestContextInit): HttpRequestContext;
+export declare function runWithRequestContext<T>(context: HttpRequestContext, callback: () => T): T;
+export declare function getCurrentRequestContext(): HttpRequestContext | undefined;
+export declare function assertRequestContext(context: HttpRequestContext | undefined | null): asserts context is HttpRequestContext;
+export declare function isRequestContext(value: unknown): value is HttpRequestContext;
+export declare function getPathname(url: string): string;
+export declare function getSearchParams(url: string): URLSearchParams;
+//# sourceMappingURL=httpRequest.context.d.ts.map

package/dist/httpRequest/httpRequest.context.id.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Request ID generation.
+ *
+ * Generates unique request identifiers using the Web Crypto API
+ * with a fallback to timestamp-based generation.
+ */
+export declare function generateRequestId(): string;
+//# sourceMappingURL=httpRequest.context.id.d.ts.map

package/dist/httpRequest/httpRequest.context.id.js

@@ -0,0 +1,16 @@
+/**
+ * Request ID generation.
+ *
+ * Generates unique request identifiers using the Web Crypto API
+ * with a fallback to timestamp-based generation.
+ */
+export function generateRequestId() {
+    const cryptoObject = globalThis.crypto;
+    if (cryptoObject && typeof cryptoObject.randomUUID === "function") {
+        return cryptoObject.randomUUID();
+    }
+    return `${Date.now().toString(36)}-${Math.random()
+        .toString(36)
+        .slice(2, 14)}`;
+}
+//# sourceMappingURL=httpRequest.context.id.js.map

package/dist/httpRequest/httpRequest.context.type.d.ts

@@ -0,0 +1,47 @@
+/**
+ * HTTP request context type definitions.
+ *
+ * Types for HTTP method, headers, query, params, body, state,
+ * init options, and snapshot shape.
+ */
+export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "CONNECT" | "TRACE" | string;
+export type RequestHeaders = Readonly<Record<string, string>>;
+export type RequestQuery = Readonly<Record<string, string | readonly string[] | undefined>>;
+export type RequestParams = Readonly<Record<string, string | undefined>>;
+export type RequestBody = unknown;
+export type RequestState = Record<string | symbol, unknown>;
+export interface RequestContextInit {
+    readonly id?: string;
+    readonly method: HttpMethod;
+    readonly url: string;
+    readonly headers?: RequestHeaders;
+    readonly query?: RequestQuery;
+    readonly params?: RequestParams;
+    readonly body?: RequestBody;
+    readonly remoteAddress?: string;
+    readonly protocol?: string;
+    readonly hostname?: string;
+    readonly port?: number;
+    readonly path?: string;
+    readonly signal?: AbortSignal;
+    readonly state?: RequestState;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface RequestContextSnapshot {
+    readonly id: string;
+    readonly method: HttpMethod;
+    readonly url: string;
+    readonly path: string;
+    readonly headers: RequestHeaders;
+    readonly query: RequestQuery;
+    readonly params: RequestParams;
+    readonly body: RequestBody;
+    readonly remoteAddress: string | undefined;
+    readonly protocol: string | undefined;
+    readonly hostname: string | undefined;
+    readonly port: number | undefined;
+    readonly state: Readonly<RequestState>;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly createdAt: number;
+}
+//# sourceMappingURL=httpRequest.context.type.d.ts.map

package/dist/httpRequest/httpRequest.context.type.js

@@ -0,0 +1,8 @@
+/**
+ * HTTP request context type definitions.
+ *
+ * Types for HTTP method, headers, query, params, body, state,
+ * init options, and snapshot shape.
+ */
+export {};
+//# sourceMappingURL=httpRequest.context.type.js.map

package/dist/httpResponse/core/httpResponse.statusText.d.ts

@@ -0,0 +1,10 @@
+/**
+ * HTTP status text mappings.
+ *
+ * @module httpResponse/statusTexts
+ */
+/**
+ * Gets the status text for an HTTP status code.
+ */
+export declare function getStatusText(status: number): string;
+//# sourceMappingURL=httpResponse.statusText.d.ts.map

package/dist/httpResponse/core/httpResponse.statusText.js

@@ -0,0 +1,76 @@
+/**
+ * HTTP status text mappings.
+ *
+ * @module httpResponse/statusTexts
+ */
+const STATUS_TEXTS = {
+    100: "Continue",
+    101: "Switching Protocols",
+    102: "Processing",
+    103: "Early Hints",
+    200: "OK",
+    201: "Created",
+    202: "Accepted",
+    203: "Non-Authoritative Information",
+    204: "No Content",
+    205: "Reset Content",
+    206: "Partial Content",
+    207: "Multi-Status",
+    208: "Already Reported",
+    226: "IM Used",
+    300: "Multiple Choices",
+    301: "Moved Permanently",
+    302: "Found",
+    303: "See Other",
+    304: "Not Modified",
+    305: "Use Proxy",
+    307: "Temporary Redirect",
+    308: "Permanent Redirect",
+    400: "Bad Request",
+    401: "Unauthorized",
+    402: "Payment Required",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    406: "Not Acceptable",
+    407: "Proxy Authentication Required",
+    408: "Request Timeout",
+    409: "Conflict",
+    410: "Gone",
+    411: "Length Required",
+    412: "Precondition Failed",
+    413: "Content Too Large",
+    414: "URI Too Long",
+    415: "Unsupported Media Type",
+    416: "Range Not Satisfiable",
+    417: "Expectation Failed",
+    418: "I'm a Teapot",
+    421: "Misdirected Request",
+    422: "Unprocessable Content",
+    423: "Locked",
+    424: "Failed Dependency",
+    425: "Too Early",
+    426: "Upgrade Required",
+    428: "Precondition Required",
+    429: "Too Many Requests",
+    431: "Request Header Fields Too Large",
+    451: "Unavailable For Legal Reasons",
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+    505: "HTTP Version Not Supported",
+    506: "Variant Also Negotiates",
+    507: "Insufficient Storage",
+    508: "Loop Detected",
+    510: "Not Extended",
+    511: "Network Authentication Required",
+};
+/**
+ * Gets the status text for an HTTP status code.
+ */
+export function getStatusText(status) {
+    return STATUS_TEXTS[status] ?? "Unknown Status";
+}
+//# sourceMappingURL=httpResponse.statusText.js.map

package/dist/httpResponse/core/httpResponse.type.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Response context types.
+ *
+ * @module httpResponse/types
+ */
+export type ResponseBody = string | Buffer | Uint8Array | object | null | undefined;
+export type ResponseHeaders = Record<string, string | string[] | undefined>;
+export interface ResponseContextInit {
+    readonly status?: number;
+    readonly statusText?: string;
+    readonly headers?: ResponseHeaders;
+    readonly body?: ResponseBody;
+    readonly cookies?: readonly ResponseCookie[];
+}
+export interface ResponseCookie {
+    readonly name: string;
+    readonly value: string;
+    readonly options?: CookieOptions;
+}
+export interface CookieOptions {
+    readonly domain?: string;
+    readonly path?: string;
+    readonly expires?: Date;
+    readonly maxAge?: number;
+    readonly httpOnly?: boolean;
+    readonly secure?: boolean;
+    readonly sameSite?: SameSite;
+    readonly priority?: CookiePriority;
+    readonly partitioned?: boolean;
+}
+export type SameSite = "Strict" | "Lax" | "None";
+export type CookiePriority = "Low" | "Medium" | "High";
+export interface ResponseContextSnapshot {
+    readonly status: number;
+    readonly statusText: string;
+    readonly headers: ResponseHeaders;
+    readonly body: ResponseBody;
+    readonly cookies: readonly ResponseCookie[];
+    readonly sent: boolean;
+    readonly timestamp: number;
+}
+export declare const DEFAULT_RESPONSE_STATUS = 200;
+export declare const DEFAULT_RESPONSE_STATUS_TEXT = "OK";
+//# sourceMappingURL=httpResponse.type.d.ts.map

package/dist/httpResponse/core/httpResponse.type.js

@@ -0,0 +1,8 @@
+/**
+ * Response context types.
+ *
+ * @module httpResponse/types
+ */
+export const DEFAULT_RESPONSE_STATUS = 200;
+export const DEFAULT_RESPONSE_STATUS_TEXT = "OK";
+//# sourceMappingURL=httpResponse.type.js.map

package/dist/httpResponse/core/index.d.ts

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