@zudojs/http 0.0.6 → 1.0.0

package/dist/httpRouter/result/httpRoute.result.factory.js

@@ -0,0 +1,54 @@
+/**
+ * Zudojs HTTP route result factory functions.
+ */
+import { HttpRouteResult } from "./httpRoute.result.class.js";
+/* -------------------------------------------------------------------------- */
+/* Factory Functions                                                          */
+/* -------------------------------------------------------------------------- */
+export function routeResult(init = {}) {
+    return new HttpRouteResult(init);
+}
+export function response(body, init = {}) {
+    return new HttpRouteResult({
+        ...init,
+        body: body ?? null,
+    });
+}
+export function ok(body, init = {}) {
+    return new HttpRouteResult({
+        ...init,
+        status: 200,
+        body: body ?? null,
+    });
+}
+export function created(body, init = {}) {
+    return new HttpRouteResult({
+        ...init,
+        status: 201,
+        body: body ?? null,
+    });
+}
+export function accepted(body, init = {}) {
+    return new HttpRouteResult({
+        ...init,
+        status: 202,
+        body: body ?? null,
+    });
+}
+export function noContent(init = {}) {
+    return new HttpRouteResult({
+        ...init,
+        status: 204,
+        body: null,
+    });
+}
+export function redirect(location, status = 302) {
+    return new HttpRouteResult({
+        status,
+        headers: {
+            Location: location,
+        },
+        body: null,
+    });
+}
+//# sourceMappingURL=httpRoute.result.factory.js.map

package/dist/httpRouter/result/httpRoute.result.guard.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Zudojs HTTP route result type guards.
+ */
+import { HttpRouteResult } from "./httpRoute.result.class.js";
+import type { RouteResultInit, RouteResultBody } from "./httpRoute.result.type.js";
+export declare function isRouteResult(value: unknown): value is HttpRouteResult;
+export declare function isRouteResultInit(value: unknown): value is RouteResultInit;
+export declare function isRouteResultBody(value: unknown): value is RouteResultBody;
+//# sourceMappingURL=httpRoute.result.guard.d.ts.map

package/dist/httpRouter/result/httpRoute.result.guard.js

@@ -0,0 +1,33 @@
+/**
+ * Zudojs HTTP route result type guards.
+ */
+import { HttpRouteResult } from "./httpRoute.result.class.js";
+import { isReadableStream } from "./httpRoute.result.util.js";
+/* -------------------------------------------------------------------------- */
+/* Type Guards                                                                */
+/* -------------------------------------------------------------------------- */
+export function isRouteResult(value) {
+    return value instanceof HttpRouteResult;
+}
+export function isRouteResultInit(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    return ("status" in value ||
+        "headers" in value ||
+        "body" in value ||
+        "contentType" in value);
+}
+export function isRouteResultBody(value) {
+    if (value === null || typeof value === "string") {
+        return true;
+    }
+    if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
+        return true;
+    }
+    if (isReadableStream(value)) {
+        return true;
+    }
+    return typeof value === "object" && value !== null;
+}
+//# sourceMappingURL=httpRoute.result.guard.js.map

package/dist/httpRouter/result/httpRoute.result.js

@@ -0,0 +1,31 @@
+/**
+ * Zudojs HTTP route result.
+ *
+ * Normalizes the different values a route handler may return into a
+ * predictable HTTP response description.
+ *
+ * This file re-exports the public API from the split modules.
+ */
+export { DEFAULT_ROUTE_STATUS, DEFAULT_CONTENT_TYPE, } from "./httpRoute.result.type.js";
+/* -------------------------------------------------------------------------- */
+/* Class                                                                      */
+/* -------------------------------------------------------------------------- */
+export { HttpRouteResult } from "./httpRoute.result.class.js";
+/* -------------------------------------------------------------------------- */
+/* Factory Functions                                                          */
+/* -------------------------------------------------------------------------- */
+export { routeResult, response, ok, created, accepted, noContent, redirect, } from "./httpRoute.result.factory.js";
+/* -------------------------------------------------------------------------- */
+/* Error Results                                                              */
+/* -------------------------------------------------------------------------- */
+export { badRequest, unauthorized, forbidden, notFound, methodNotAllowed, conflict, unprocessableEntity, tooManyRequests, } from "./httpRoute.result.error.4xx.js";
+export { internalServerError, notImplemented, serviceUnavailable, } from "./httpRoute.result.error.5xx.js";
+/* -------------------------------------------------------------------------- */
+/* Normalization                                                              */
+/* -------------------------------------------------------------------------- */
+export { normalizeRouteResult, resultFromContext, } from "./httpRoute.result.normalize.js";
+/* -------------------------------------------------------------------------- */
+/* Type Guards                                                                */
+/* -------------------------------------------------------------------------- */
+export { isRouteResult, isRouteResultInit, isRouteResultBody, } from "./httpRoute.result.guard.js";
+//# sourceMappingURL=httpRoute.result.js.map

package/dist/httpRouter/result/httpRoute.result.normalize.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Zudojs HTTP route result normalization.
+ */
+import { HttpRouteResult } from "./httpRoute.result.class.js";
+import type { RouteResultValue, RouteResultOptions, RouteResultContext } from "./httpRoute.result.type.js";
+export declare function normalizeRouteResult(value: RouteResultValue, options?: RouteResultOptions): HttpRouteResult;
+export declare function resultFromContext(context: RouteResultContext, value: RouteResultValue): HttpRouteResult;
+//# sourceMappingURL=httpRoute.result.normalize.d.ts.map

package/dist/httpRouter/result/httpRoute.result.normalize.js

@@ -0,0 +1,73 @@
+/**
+ * Zudojs HTTP route result normalization.
+ */
+import { HttpRouteResult } from "./httpRoute.result.class.js";
+import { isReadableStream } from "./httpRoute.result.util.js";
+import { valueToJsonObject } from "./httpRoute.result.serialize.js";
+import { DEFAULT_CONTENT_TYPE } from "./httpRoute.result.type.js";
+/* -------------------------------------------------------------------------- */
+/* Handler Result Normalization                                               */
+/* -------------------------------------------------------------------------- */
+export function normalizeRouteResult(value, options = {}) {
+    if (value instanceof HttpRouteResult) {
+        return value;
+    }
+    if (value === undefined || value === null) {
+        return new HttpRouteResult({
+            status: options.defaultStatus ?? 204,
+            body: null,
+        });
+    }
+    if (typeof value === "string") {
+        return new HttpRouteResult({
+            status: options.defaultStatus ?? 200,
+            contentType: "text/plain; charset=utf-8",
+            body: value,
+        });
+    }
+    if (typeof value === "number" ||
+        typeof value === "boolean" ||
+        typeof value === "bigint") {
+        return new HttpRouteResult({
+            status: options.defaultStatus ?? 200,
+            contentType: options.defaultContentType ?? DEFAULT_CONTENT_TYPE,
+            body: valueToJsonObject(value),
+        });
+    }
+    if (value instanceof Uint8Array) {
+        return new HttpRouteResult({
+            status: options.defaultStatus ?? 200,
+            body: value,
+            contentType: "application/octet-stream",
+        });
+    }
+    if (value instanceof ArrayBuffer) {
+        return new HttpRouteResult({
+            status: options.defaultStatus ?? 200,
+            body: new Uint8Array(value),
+            contentType: "application/octet-stream",
+        });
+    }
+    if (isReadableStream(value)) {
+        return new HttpRouteResult({
+            status: options.defaultStatus ?? 200,
+            body: value,
+        });
+    }
+    return new HttpRouteResult({
+        status: options.defaultStatus ?? 200,
+        contentType: options.defaultContentType ?? DEFAULT_CONTENT_TYPE,
+        body: value,
+    });
+}
+/* -------------------------------------------------------------------------- */
+/* Context Helpers                                                            */
+/* -------------------------------------------------------------------------- */
+export function resultFromContext(context, value) {
+    const result = normalizeRouteResult(value);
+    if (context.method === "HEAD") {
+        return result.withBody(null);
+    }
+    return result;
+}
+//# sourceMappingURL=httpRoute.result.normalize.js.map

package/dist/httpRouter/result/httpRoute.result.output.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Zudojs HTTP route result output methods.
+ *
+ * Extends HttpRouteResult with serialization methods via prototype.
+ */
+export {};
+//# sourceMappingURL=httpRoute.result.output.d.ts.map

package/dist/httpRouter/result/httpRoute.result.output.js

@@ -0,0 +1,34 @@
+/**
+ * Zudojs HTTP route result output methods.
+ *
+ * Extends HttpRouteResult with serialization methods via prototype.
+ */
+import { HttpRouteResult } from "./httpRoute.result.class.js";
+import { serializeBody } from "./httpRoute.result.serialize.js";
+import { isJsonSerializable } from "./httpRoute.result.serialize.js";
+/* -------------------------------------------------------------------------- */
+/* Serialization Methods                                                      */
+/* -------------------------------------------------------------------------- */
+HttpRouteResult.prototype.toResponse = function (options = {}) {
+    const headers = new Headers(this.headers);
+    if (this.contentType && !headers.has("content-type")) {
+        headers.set("content-type", this.contentType);
+    }
+    const body = serializeBody(this.body, this.contentType);
+    return new Response(body, {
+        status: this.status,
+        statusText: this.statusText,
+        headers,
+    });
+};
+HttpRouteResult.prototype.toJSON = function () {
+    return {
+        status: this.status,
+        statusText: this.statusText,
+        headers: this.headers,
+        body: isJsonSerializable(this.body) ? this.body : undefined,
+        contentType: this.contentType,
+        metadata: this.metadata,
+    };
+};
+//# sourceMappingURL=httpRoute.result.output.js.map

package/dist/httpRouter/result/httpRoute.result.serialize.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Zudojs HTTP route result body serialization helpers.
+ */
+import type { RouteResultBody } from "./httpRoute.result.type.js";
+export declare function serializeBody(body: RouteResultBody, contentType?: string): BodyInit | null;
+export declare function valueToJsonObject(value: number | boolean | bigint): Record<string, unknown>;
+export declare function isJsonSerializable(value: unknown): boolean;
+//# sourceMappingURL=httpRoute.result.serialize.d.ts.map

package/dist/httpRouter/result/httpRoute.result.serialize.js

@@ -0,0 +1,61 @@
+/**
+ * Zudojs HTTP route result body serialization helpers.
+ */
+import { isReadableStream } from "./httpRoute.result.util.js";
+/* -------------------------------------------------------------------------- */
+/* Body Serialization                                                         */
+/* -------------------------------------------------------------------------- */
+export function serializeBody(body, contentType) {
+    if (body === null || body === undefined) {
+        return null;
+    }
+    if (typeof body === "string") {
+        return body;
+    }
+    if (body instanceof Uint8Array) {
+        return body;
+    }
+    if (body instanceof ArrayBuffer) {
+        return body;
+    }
+    if (isReadableStream(body)) {
+        return body;
+    }
+    if (isJsonContentType(contentType)) {
+        return JSON.stringify(body);
+    }
+    return JSON.stringify(body);
+}
+function isJsonContentType(contentType) {
+    if (!contentType) {
+        return false;
+    }
+    return (contentType.toLowerCase().includes("application/json") ||
+        contentType.toLowerCase().includes("+json"));
+}
+/* -------------------------------------------------------------------------- */
+/* Value Helpers                                                              */
+/* -------------------------------------------------------------------------- */
+export function valueToJsonObject(value) {
+    return {
+        value: typeof value === "bigint" ? value.toString() : value,
+    };
+}
+export function isJsonSerializable(value) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return true;
+    }
+    if (typeof value === "bigint") {
+        return false;
+    }
+    if (value instanceof Uint8Array ||
+        value instanceof ArrayBuffer ||
+        isReadableStream(value)) {
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=httpRoute.result.serialize.js.map

package/dist/httpRouter/result/httpRoute.result.type.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Zudojs HTTP route result types and constants.
+ */
+import type { HttpMethod, MatchedRoute } from "../core/types/httpRouter.type.js";
+import type { HttpRequestContext as RequestContext } from "../../httpRequest/httpRequest.context.js";
+import type { HttpResponseContext as ResponseContext } from "../../httpResponse/httpResponse.context.js";
+export type RouteResultBody = string | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | Record<string, unknown> | readonly unknown[] | null;
+export type RouteResultValue = void | null | string | number | boolean | bigint | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | Record<string, unknown> | readonly unknown[] | RouteResult;
+export interface RouteResultInit {
+    readonly status?: number;
+    readonly statusText?: string;
+    readonly headers?: HeadersInit;
+    readonly body?: RouteResultBody;
+    readonly contentType?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface RouteResult {
+    readonly status: number;
+    readonly statusText: string | undefined;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: RouteResultBody;
+    readonly contentType: string | undefined;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+export interface RouteResultContext {
+    readonly request: RequestContext;
+    readonly response: ResponseContext;
+    readonly route: MatchedRoute;
+    readonly method: HttpMethod | "*";
+    readonly path: string;
+    readonly params: Readonly<Record<string, string>>;
+}
+export interface RouteResultOptions {
+    readonly defaultStatus?: number;
+    readonly defaultContentType?: string;
+    readonly serializeJson?: boolean;
+    readonly headOnly?: boolean;
+}
+export declare const DEFAULT_ROUTE_STATUS = 200;
+export declare const DEFAULT_CONTENT_TYPE = "application/json; charset=utf-8";
+//# sourceMappingURL=httpRoute.result.type.d.ts.map

package/dist/httpRouter/result/httpRoute.result.type.js

@@ -0,0 +1,9 @@
+/**
+ * Zudojs HTTP route result types and constants.
+ */
+/* -------------------------------------------------------------------------- */
+/* Constants                                                                  */
+/* -------------------------------------------------------------------------- */
+export const DEFAULT_ROUTE_STATUS = 200;
+export const DEFAULT_CONTENT_TYPE = "application/json; charset=utf-8";
+//# sourceMappingURL=httpRoute.result.type.js.map

package/dist/httpRouter/result/httpRoute.result.util.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Zudojs HTTP route result utility helpers.
+ */
+export declare function normalizeHeaders(headers?: HeadersInit): Record<string, string>;
+export declare function getHeader(headers: Record<string, string>, name: string): string | undefined;
+export declare function validateStatus(status: number): void;
+export declare function isReadableStream(value: unknown): value is ReadableStream<Uint8Array>;
+//# sourceMappingURL=httpRoute.result.util.d.ts.map

package/dist/httpRouter/result/httpRoute.result.util.js

@@ -0,0 +1,52 @@
+/**
+ * Zudojs HTTP route result utility helpers.
+ */
+/* -------------------------------------------------------------------------- */
+/* Headers                                                                    */
+/* -------------------------------------------------------------------------- */
+export function normalizeHeaders(headers) {
+    if (!headers) {
+        return {};
+    }
+    const output = {};
+    if (headers instanceof Headers) {
+        headers.forEach((value, key) => {
+            output[key] = value;
+        });
+        return output;
+    }
+    if (Array.isArray(headers)) {
+        for (const [key, value] of headers) {
+            output[key] = value;
+        }
+        return output;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        output[key] = String(value);
+    }
+    return output;
+}
+export function getHeader(headers, name) {
+    const target = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === target) {
+            return value;
+        }
+    }
+    return undefined;
+}
+/* -------------------------------------------------------------------------- */
+/* Validation                                                                 */
+/* -------------------------------------------------------------------------- */
+export function validateStatus(status) {
+    if (!Number.isInteger(status) || status < 100 || status > 599) {
+        throw new RangeError(`Invalid HTTP status code: ${status}.`);
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Type Guards                                                                */
+/* -------------------------------------------------------------------------- */
+export function isReadableStream(value) {
+    return (typeof ReadableStream !== "undefined" && value instanceof ReadableStream);
+}
+//# sourceMappingURL=httpRoute.result.util.js.map

package/dist/httpRouter/result/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * HTTP route results.
+ */
+export { HttpRouteResult, ok, created, noContent, redirect, badRequest, unauthorized, forbidden, notFound, conflict, tooManyRequests, internalServerError, accepted, methodNotAllowed, unprocessableEntity, notImplemented, serviceUnavailable, routeResult, response, normalizeRouteResult, resultFromContext, isRouteResult, isRouteResultInit, isRouteResultBody, DEFAULT_ROUTE_STATUS, DEFAULT_CONTENT_TYPE, } from "./httpRoute.result.js";
+export type { RouteResultBody, RouteResultValue, RouteResultInit, RouteResult, RouteResultContext, RouteResultOptions, } from "./httpRoute.result.type.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpRouter/result/index.js

@@ -0,0 +1,5 @@
+/**
+ * HTTP route results.
+ */
+export { HttpRouteResult, ok, created, noContent, redirect, badRequest, unauthorized, forbidden, notFound, conflict, tooManyRequests, internalServerError, accepted, methodNotAllowed, unprocessableEntity, notImplemented, serviceUnavailable, routeResult, response, normalizeRouteResult, resultFromContext, isRouteResult, isRouteResultInit, isRouteResultBody, DEFAULT_ROUTE_STATUS, DEFAULT_CONTENT_TYPE, } from "./httpRoute.result.js";
+//# sourceMappingURL=index.js.map

package/dist/httpRouter/tree/core/httpTree.helper.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Route tree helper functions.
+ *
+ * @module httpRoute/tree/helpers
+ */
+import type { MutableRouteTreeNode } from "./httpTree.type.js";
+/**
+ * Gets pattern segments from a path.
+ */
+export declare function getPatternSegments(path: string): readonly string[];
+/**
+ * Inserts a segment into the tree.
+ */
+export declare function insertSegment(node: MutableRouteTreeNode, segments: readonly string[], handler: unknown, methods: readonly string[], metadata: Record<string, unknown>): void;
+/**
+ * Removes a route from the tree.
+ */
+export declare function removeRouteFromTree(node: MutableRouteTreeNode, segments: readonly string[]): boolean;
+/**
+ * Checks if a node is empty.
+ */
+export declare function isEmptyNode(node: MutableRouteTreeNode): boolean;
+/**
+ * Checks if a method matches.
+ */
+export declare function matchesMethod(node: MutableRouteTreeNode, method: string): boolean;
+/**
+ * Splits a path into segments.
+ */
+export declare function splitPath(path: string): readonly string[];
+//# sourceMappingURL=httpTree.helper.d.ts.map

package/dist/httpRouter/tree/core/httpTree.helper.js

@@ -0,0 +1,80 @@
+/**
+ * Route tree helper functions.
+ *
+ * @module httpRoute/tree/helpers
+ */
+import { createChildNode } from "./httpTree.nodeCreation.js";
+/**
+ * Gets pattern segments from a path.
+ */
+export function getPatternSegments(path) {
+    return path.split("/").filter(Boolean);
+}
+/**
+ * Inserts a segment into the tree.
+ */
+export function insertSegment(node, segments, handler, methods, metadata) {
+    if (segments.length === 0) {
+        node.handler = handler;
+        for (const method of methods) {
+            node.methods.add(method);
+        }
+        Object.assign(node.metadata, metadata);
+        return;
+    }
+    const [segment, ...rest] = segments;
+    if (segment === undefined) {
+        return;
+    }
+    let child = node.children.get(segment);
+    if (!child) {
+        child = createChildNode(segment);
+        node.children.set(segment, child);
+    }
+    insertSegment(child, rest, handler, methods, metadata);
+}
+/**
+ * Removes a route from the tree.
+ */
+export function removeRouteFromTree(node, segments) {
+    if (segments.length === 0) {
+        if (node.handler) {
+            node.handler = undefined;
+            node.methods.clear();
+            return true;
+        }
+        return false;
+    }
+    const [segment, ...rest] = segments;
+    if (segment === undefined) {
+        return false;
+    }
+    const child = node.children.get(segment);
+    if (!child) {
+        return false;
+    }
+    const removed = removeRouteFromTree(child, rest);
+    if (removed && isEmptyNode(child)) {
+        node.children.delete(segment);
+    }
+    return removed;
+}
+/**
+ * Checks if a node is empty.
+ */
+export function isEmptyNode(node) {
+    return node.children.size === 0 && !node.handler && node.methods.size === 0;
+}
+/**
+ * Checks if a method matches.
+ */
+export function matchesMethod(node, method) {
+    return node.methods.has(method) || node.methods.has("*");
+}
+/**
+ * Splits a path into segments.
+ */
+export function splitPath(path) {
+    return path.split("/").filter(Boolean);
+}
+//# sourceMappingURL=httpTree.helper.js.map

package/dist/httpRouter/tree/core/httpTree.nodeCreation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Route tree node creation utilities.
+ *
+ * @module httpRoute/tree/nodeCreation
+ */
+import type { MutableRouteTreeNode } from "./httpTree.type.js";
+/**
+ * Creates a child node based on the segment.
+ */
+export declare function createChildNode(segment: string): MutableRouteTreeNode;
+//# sourceMappingURL=httpTree.nodeCreation.d.ts.map

package/dist/httpRouter/tree/core/httpTree.nodeCreation.js

@@ -0,0 +1,54 @@
+/**
+ * Route tree node creation utilities.
+ *
+ * @module httpRoute/tree/nodeCreation
+ */
+/**
+ * Creates a child node based on the segment.
+ */
+export function createChildNode(segment) {
+    if (segment.startsWith(":")) {
+        return {
+            name: segment.slice(1),
+            type: "parameter",
+            children: new Map(),
+            methods: new Set(),
+            metadata: {},
+            optional: false,
+            wildcard: false,
+            param: segment.slice(1),
+        };
+    }
+    if (segment === "*") {
+        return {
+            name: "*",
+            type: "wildcard",
+            children: new Map(),
+            methods: new Set(),
+            metadata: {},
+            optional: false,
+            wildcard: true,
+        };
+    }
+    if (segment.endsWith("?")) {
+        return {
+            name: segment.slice(0, -1),
+            type: "optional",
+            children: new Map(),
+            methods: new Set(),
+            metadata: {},
+            optional: true,
+            wildcard: false,
+        };
+    }
+    return {
+        name: segment,
+        type: "static",
+        children: new Map(),
+        methods: new Set(),
+        metadata: {},
+        optional: false,
+        wildcard: false,
+    };
+}
+//# sourceMappingURL=httpTree.nodeCreation.js.map

package/dist/httpRouter/tree/core/httpTree.traversal.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Route tree traversal functions.
+ *
+ * @module httpRoute/tree/traversal
+ */
+import type { MutableRouteTreeNode } from "./httpTree.type.js";
+/**
+ * Collects candidates from the tree.
+ */
+export declare function collectCandidates(node: MutableRouteTreeNode, segments: readonly string[]): MutableRouteTreeNode[];
+/**
+ * Collects optional routes from the tree.
+ */
+export declare function collectOptionalRoutes(node: MutableRouteTreeNode): MutableRouteTreeNode[];
+/**
+ * Collects all routes from the tree.
+ */
+export declare function collectRoutes(node: MutableRouteTreeNode, path: string): Array<{
+    readonly path: string;
+    readonly node: MutableRouteTreeNode;
+}>;
+/**
+ * Finds a static child node.
+ */
+export declare function findStaticChild(node: MutableRouteTreeNode, name: string): MutableRouteTreeNode | undefined;
+//# sourceMappingURL=httpTree.traversal.d.ts.map