@zudojs/http 0.1.0 → 1.1.0

package/dist/httpCsp/validation/index.js

@@ -0,0 +1,6 @@
+/**
+ * CSP validation utilities.
+ */
+export { isValidDirectiveName, normalizeDirectiveName, } from "./httpCsp.validation.js";
+export { validateCSP } from "./httpCsp.validate.js";
+//# sourceMappingURL=index.js.map

package/dist/httpErrors/factories/httpError.clientError.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Client HTTP error factory functions (4xx).
+ *
+ * @module httpErrors/factories/client
+ */
+import type { HttpErrorOptions } from "../httpError.type.js";
+import { HttpError } from "../httpError.base.js";
+/**
+ * Creates a 400 Bad Request error.
+ */
+export declare function badRequest(message?: string, options?: HttpErrorOptions): HttpError;
+/**
+ * Creates a 401 Unauthorized error.
+ */
+export declare function unauthorized(message?: string, options?: HttpErrorOptions): HttpError;
+/**
+ * Creates a 403 Forbidden error.
+ */
+export declare function forbidden(message?: string, options?: HttpErrorOptions): HttpError;
+/**
+ * Creates a 404 Not Found error.
+ */
+export declare function notFound(message?: string, options?: HttpErrorOptions): HttpError;
+/**
+ * Creates a 405 Method Not Allowed error.
+ */
+export declare function methodNotAllowed(message?: string, options?: HttpErrorOptions): HttpError;
+/**
+ * Creates a 409 Conflict error.
+ */
+export declare function conflict(message?: string, options?: HttpErrorOptions): HttpError;
+/**
+ * Creates a 422 Unprocessable Entity error.
+ */
+export declare function unprocessableEntity(message?: string, options?: HttpErrorOptions): HttpError;
+/**
+ * Creates a 429 Too Many Requests error.
+ */
+export declare function tooManyRequests(message?: string, options?: HttpErrorOptions): HttpError;
+//# sourceMappingURL=httpError.clientError.d.ts.map

package/dist/httpErrors/factories/httpError.clientError.js

@@ -0,0 +1,79 @@
+/**
+ * Client HTTP error factory functions (4xx).
+ *
+ * @module httpErrors/factories/client
+ */
+import { HttpError } from "../httpError.base.js";
+/**
+ * Creates a 400 Bad Request error.
+ */
+export function badRequest(message, options) {
+    return new HttpError(400, message ?? "Bad Request", {
+        ...options,
+        code: options?.code ?? "BAD_REQUEST",
+    });
+}
+/**
+ * Creates a 401 Unauthorized error.
+ */
+export function unauthorized(message, options) {
+    return new HttpError(401, message ?? "Unauthorized", {
+        ...options,
+        code: options?.code ?? "UNAUTHORIZED",
+    });
+}
+/**
+ * Creates a 403 Forbidden error.
+ */
+export function forbidden(message, options) {
+    return new HttpError(403, message ?? "Forbidden", {
+        ...options,
+        code: options?.code ?? "FORBIDDEN",
+    });
+}
+/**
+ * Creates a 404 Not Found error.
+ */
+export function notFound(message, options) {
+    return new HttpError(404, message ?? "Not Found", {
+        ...options,
+        code: options?.code ?? "NOT_FOUND",
+    });
+}
+/**
+ * Creates a 405 Method Not Allowed error.
+ */
+export function methodNotAllowed(message, options) {
+    return new HttpError(405, message ?? "Method Not Allowed", {
+        ...options,
+        code: options?.code ?? "METHOD_NOT_ALLOWED",
+    });
+}
+/**
+ * Creates a 409 Conflict error.
+ */
+export function conflict(message, options) {
+    return new HttpError(409, message ?? "Conflict", {
+        ...options,
+        code: options?.code ?? "CONFLICT",
+    });
+}
+/**
+ * Creates a 422 Unprocessable Entity error.
+ */
+export function unprocessableEntity(message, options) {
+    return new HttpError(422, message ?? "Unprocessable Entity", {
+        ...options,
+        code: options?.code ?? "UNPROCESSABLE_ENTITY",
+    });
+}
+/**
+ * Creates a 429 Too Many Requests error.
+ */
+export function tooManyRequests(message, options) {
+    return new HttpError(429, message ?? "Too Many Requests", {
+        ...options,
+        code: options?.code ?? "TOO_MANY_REQUESTS",
+    });
+}
+//# sourceMappingURL=httpError.clientError.js.map

package/dist/httpErrors/factories/httpError.serverError.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Server HTTP error factory functions (5xx).
+ *
+ * @module httpErrors/factories/server
+ */
+import type { HttpErrorOptions } from "../httpError.type.js";
+import { HttpError } from "../httpError.base.js";
+/**
+ * Creates a 500 Internal Server Error.
+ */
+export declare function internalServerError(message?: string, options?: HttpErrorOptions): HttpError;
+/**
+ * Creates a 501 Not Implemented error.
+ */
+export declare function notImplemented(message?: string, options?: HttpErrorOptions): HttpError;
+/**
+ * Creates a 502 Bad Gateway error.
+ */
+export declare function badGateway(message?: string, options?: HttpErrorOptions): HttpError;
+/**
+ * Creates a 503 Service Unavailable error.
+ */
+export declare function serviceUnavailable(message?: string, options?: HttpErrorOptions): HttpError;
+/**
+ * Creates a 504 Gateway Timeout error.
+ */
+export declare function gatewayTimeout(message?: string, options?: HttpErrorOptions): HttpError;
+//# sourceMappingURL=httpError.serverError.d.ts.map

package/dist/httpErrors/factories/httpError.serverError.js

@@ -0,0 +1,52 @@
+/**
+ * Server HTTP error factory functions (5xx).
+ *
+ * @module httpErrors/factories/server
+ */
+import { HttpError } from "../httpError.base.js";
+/**
+ * Creates a 500 Internal Server Error.
+ */
+export function internalServerError(message, options) {
+    return new HttpError(500, message ?? "Internal Server Error", {
+        ...options,
+        code: options?.code ?? "INTERNAL_SERVER_ERROR",
+    });
+}
+/**
+ * Creates a 501 Not Implemented error.
+ */
+export function notImplemented(message, options) {
+    return new HttpError(501, message ?? "Not Implemented", {
+        ...options,
+        code: options?.code ?? "NOT_IMPLEMENTED",
+    });
+}
+/**
+ * Creates a 502 Bad Gateway error.
+ */
+export function badGateway(message, options) {
+    return new HttpError(502, message ?? "Bad Gateway", {
+        ...options,
+        code: options?.code ?? "BAD_GATEWAY",
+    });
+}
+/**
+ * Creates a 503 Service Unavailable error.
+ */
+export function serviceUnavailable(message, options) {
+    return new HttpError(503, message ?? "Service Unavailable", {
+        ...options,
+        code: options?.code ?? "SERVICE_UNAVAILABLE",
+    });
+}
+/**
+ * Creates a 504 Gateway Timeout error.
+ */
+export function gatewayTimeout(message, options) {
+    return new HttpError(504, message ?? "Gateway Timeout", {
+        ...options,
+        code: options?.code ?? "GATEWAY_TIMEOUT",
+    });
+}
+//# sourceMappingURL=httpError.serverError.js.map

package/dist/httpErrors/httpError.base.d.ts

@@ -8,7 +8,6 @@
  */
 import { HttpError as BaseHttpError } from "@zudojs/errors";
 import type { HttpErrorOptions } from "./httpError.type.js";
-import { getStatusText } from "./httpError.helper.js";
 /**
  * HTTP error with response-specific properties.
  *
@@ -38,5 +37,4 @@ export declare class HttpError extends BaseHttpError {
      */
     withDetails(details: unknown): HttpError;
 }
-export { getStatusText };
 //# sourceMappingURL=httpError.base.d.ts.map

package/dist/httpErrors/httpError.base.js

@@ -7,7 +7,7 @@
  * @module httpErrors/base
  */
 import { HttpError as BaseHttpError } from "@zudojs/errors";
-import { normalizeHeaders, getStatusText } from "./httpError.helper.js";
+import { normalizeHeaders, getStatusText } from "./httpError.util.js";
 /**
  * HTTP error with response-specific properties.
  *
@@ -54,6 +54,8 @@ export class HttpError extends BaseHttpError {
             details: this.details,
             expose: this.expose,
             metadata: this.metadata,
+            /* An additive transform must not sever the original error chain. */
+            cause: this.cause,
         });
     }
     /**
@@ -66,8 +68,8 @@ export class HttpError extends BaseHttpError {
             details,
             expose: this.expose,
             metadata: this.metadata,
+            cause: this.cause,
         });
     }
 }
-export { getStatusText };
 //# sourceMappingURL=httpError.base.js.map

package/dist/httpErrors/httpError.helper.d.ts

@@ -0,0 +1,19 @@
+/**
+ * HTTP error helpers barrel.
+ *
+ * Factory functions, type guards, and utilities.
+ *
+ * @module httpErrors/helpers
+ */
+import type { HttpErrorOptions } from "./httpError.type.js";
+import { HttpError } from "./httpError.base.js";
+export * from "./factories/httpError.clientError.js";
+export * from "./factories/httpError.serverError.js";
+export * from "./httpError.typeGuard.js";
+export * from "./httpError.invalidJson.js";
+export * from "./httpError.util.js";
+/**
+ * Creates an HTTP error with the specified status code.
+ */
+export declare function httpError(status: number, message?: string, options?: HttpErrorOptions): HttpError;
+//# sourceMappingURL=httpError.helper.d.ts.map

package/dist/httpErrors/httpError.helper.js

@@ -0,0 +1,20 @@
+/**
+ * HTTP error helpers barrel.
+ *
+ * Factory functions, type guards, and utilities.
+ *
+ * @module httpErrors/helpers
+ */
+import { HttpError } from "./httpError.base.js";
+export * from "./factories/httpError.clientError.js";
+export * from "./factories/httpError.serverError.js";
+export * from "./httpError.typeGuard.js";
+export * from "./httpError.invalidJson.js";
+export * from "./httpError.util.js";
+/**
+ * Creates an HTTP error with the specified status code.
+ */
+export function httpError(status, message, options) {
+    return new HttpError(status, message, options);
+}
+//# sourceMappingURL=httpError.helper.js.map

package/dist/httpErrors/httpError.invalidJson.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Invalid JSON error class.
+ *
+ * @module httpErrors/invalidJson
+ */
+import { HttpError } from "./httpError.base.js";
+/**
+ * Error thrown when JSON parsing fails.
+ */
+export declare class InvalidJSONError extends HttpError {
+    /**
+     * The original parse error.
+     */
+    readonly parseError: unknown;
+    constructor(message?: string, options?: {
+        readonly cause?: unknown;
+        readonly details?: unknown;
+    });
+}
+//# sourceMappingURL=httpError.invalidJson.d.ts.map

package/dist/httpErrors/httpError.invalidJson.js

@@ -0,0 +1,26 @@
+/**
+ * Invalid JSON error class.
+ *
+ * @module httpErrors/invalidJson
+ */
+import { HttpError } from "./httpError.base.js";
+/**
+ * Error thrown when JSON parsing fails.
+ */
+export class InvalidJSONError extends HttpError {
+    /**
+     * The original parse error.
+     */
+    parseError;
+    constructor(message = "Invalid JSON", options = {}) {
+        super(400, message, {
+            cause: options.cause,
+            code: "INVALID_JSON",
+            expose: true,
+            details: options.details,
+        });
+        this.name = "InvalidJSONError";
+        this.parseError = options.cause;
+    }
+}
+//# sourceMappingURL=httpError.invalidJson.js.map

package/dist/httpErrors/httpError.typeGuard.d.ts

@@ -0,0 +1,23 @@
+/**
+ * HTTP error type guards.
+ *
+ * @module httpErrors/typeGuards
+ */
+import { HttpError } from "./httpError.base.js";
+/**
+ * Determines whether an unknown value is an HttpError.
+ */
+export declare function isHttpError(value: unknown): value is HttpError;
+/**
+ * Determines whether an unknown value is a client error (4xx).
+ */
+export declare function isClientError(value: unknown): value is HttpError;
+/**
+ * Determines whether an unknown value is a server error (5xx).
+ */
+export declare function isServerError(value: unknown): value is HttpError;
+/**
+ * Determines whether a status code represents an error.
+ */
+export declare function isErrorStatus(status: number): boolean;
+//# sourceMappingURL=httpError.typeGuard.d.ts.map

package/dist/httpErrors/httpError.typeGuard.js

@@ -0,0 +1,35 @@
+/**
+ * HTTP error type guards.
+ *
+ * @module httpErrors/typeGuards
+ */
+import { HttpError } from "./httpError.base.js";
+/**
+ * Determines whether an unknown value is an HttpError.
+ */
+export function isHttpError(value) {
+    return value instanceof HttpError;
+}
+/**
+ * Determines whether an unknown value is a client error (4xx).
+ */
+export function isClientError(value) {
+    return (value instanceof HttpError &&
+        value.statusCode >= 400 &&
+        value.statusCode < 500);
+}
+/**
+ * Determines whether an unknown value is a server error (5xx).
+ */
+export function isServerError(value) {
+    return (value instanceof HttpError &&
+        value.statusCode >= 500 &&
+        value.statusCode < 600);
+}
+/**
+ * Determines whether a status code represents an error.
+ */
+export function isErrorStatus(status) {
+    return status >= 400 && status < 600;
+}
+//# sourceMappingURL=httpError.typeGuard.js.map

package/dist/httpErrors/httpError.util.d.ts

@@ -0,0 +1,22 @@
+/**
+ * HTTP error utilities.
+ *
+ * Dependency-free helpers used by the base error class. Kept separate from
+ * `httpError.helper.ts` so the base class does not import a module that
+ * re-exports its own subclasses (which would form an initialization cycle).
+ *
+ * @module httpErrors/util
+ */
+/**
+ * Normalizes header keys to lowercase.
+ */
+export declare function normalizeHeaders(headers: Record<string, string> | undefined): Record<string, string>;
+/**
+ * Returns the standard HTTP status text for a given status code.
+ *
+ * Delegates to the package's status-text table rather than keeping a partial
+ * copy: the local map started at 400, so `new HttpError(301)` reported both
+ * `statusText` and `message` as "Unknown Status".
+ */
+export declare function getStatusText(status: number): string;
+//# sourceMappingURL=httpError.util.d.ts.map

package/dist/httpErrors/httpError.util.js

@@ -0,0 +1,36 @@
+/**
+ * HTTP error utilities.
+ *
+ * Dependency-free helpers used by the base error class. Kept separate from
+ * `httpError.helper.ts` so the base class does not import a module that
+ * re-exports its own subclasses (which would form an initialization cycle).
+ *
+ * @module httpErrors/util
+ */
+import { getStatusText as lookupStatusText } from "../httpStatus/httpStatus.lookup.js";
+/**
+ * Normalizes header keys to lowercase.
+ */
+export function normalizeHeaders(headers) {
+    if (!headers) {
+        return {};
+    }
+    const normalized = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (typeof value === "string") {
+            normalized[key.toLowerCase()] = value;
+        }
+    }
+    return normalized;
+}
+/**
+ * Returns the standard HTTP status text for a given status code.
+ *
+ * Delegates to the package's status-text table rather than keeping a partial
+ * copy: the local map started at 400, so `new HttpError(301)` reported both
+ * `statusText` and `message` as "Unknown Status".
+ */
+export function getStatusText(status) {
+    return lookupStatusText(status);
+}
+//# sourceMappingURL=httpError.util.js.map

package/dist/httpHeaders/authorization/httpHeaders.authorization.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Authorization header utilities.
+ *
+ * @module httpHeaders/authorization
+ */
+/**
+ * A parsed Authorization header with scheme and credentials.
+ */
+export interface ParsedAuthorization {
+    readonly scheme: string;
+    readonly credentials: string;
+}
+/**
+ * Parses an Authorization header value into scheme and credentials.
+ *
+ * @param value - The raw Authorization header value.
+ * @returns The parsed authorization, or `undefined` if invalid.
+ */
+export declare function parseAuthorization(value: string | undefined): ParsedAuthorization | undefined;
+/**
+ * Checks if an Authorization header value uses the Bearer scheme.
+ *
+ * @param value - The raw Authorization header value.
+ * @returns `true` if the scheme is `"Bearer"` (case-insensitive).
+ */
+export declare function isBearerAuthorization(value: string | undefined): boolean;
+/**
+ * Extracts the Bearer token from an Authorization header value.
+ *
+ * @param value - The raw Authorization header value.
+ * @returns The Bearer token, or `undefined` if not a Bearer authorization.
+ */
+export declare function getBearerToken(value: string | undefined): string | undefined;
+//# sourceMappingURL=httpHeaders.authorization.d.ts.map

package/dist/httpHeaders/authorization/httpHeaders.authorization.js

@@ -0,0 +1,53 @@
+/**
+ * Authorization header utilities.
+ *
+ * @module httpHeaders/authorization
+ */
+/**
+ * Parses an Authorization header value into scheme and credentials.
+ *
+ * @param value - The raw Authorization header value.
+ * @returns The parsed authorization, or `undefined` if invalid.
+ */
+export function parseAuthorization(value) {
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    const separator = trimmed.indexOf(" ");
+    if (separator === -1) {
+        return undefined;
+    }
+    const scheme = trimmed.slice(0, separator).trim();
+    const credentials = trimmed.slice(separator + 1).trim();
+    if (!scheme || !credentials) {
+        return undefined;
+    }
+    return {
+        scheme,
+        credentials,
+    };
+}
+/**
+ * Checks if an Authorization header value uses the Bearer scheme.
+ *
+ * @param value - The raw Authorization header value.
+ * @returns `true` if the scheme is `"Bearer"` (case-insensitive).
+ */
+export function isBearerAuthorization(value) {
+    return parseAuthorization(value)?.scheme.toLowerCase() === "bearer";
+}
+/**
+ * Extracts the Bearer token from an Authorization header value.
+ *
+ * @param value - The raw Authorization header value.
+ * @returns The Bearer token, or `undefined` if not a Bearer authorization.
+ */
+export function getBearerToken(value) {
+    const parsed = parseAuthorization(value);
+    if (!parsed || parsed.scheme.toLowerCase() !== "bearer") {
+        return undefined;
+    }
+    return parsed.credentials;
+}
+//# sourceMappingURL=httpHeaders.authorization.js.map

package/dist/httpHeaders/authorization/index.d.ts

@@ -4,5 +4,4 @@
  * HTTP headers authorization utilities.
  */
 export * from "./httpHeaders.authorization.js";
-export * from "./index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/httpHeaders/authorization/index.js

@@ -4,5 +4,4 @@
  * HTTP headers authorization utilities.
  */
 export * from "./httpHeaders.authorization.js";
-export * from "./index.js";
 //# sourceMappingURL=index.js.map

package/dist/httpHeaders/basic/httpHeaders.basic.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Basic header existence check utilities.
+ *
+ * @module httpHeaders/basic
+ */
+import type { HTTPHeadersLike } from "../types/httpHeaders.type.js";
+/**
+ * Checks if at least one of the given header names is present.
+ *
+ * @param headers - The headers to inspect.
+ * @param names - The header names to check.
+ * @returns `true` if any of the names are present.
+ */
+export declare function hasAnyHeader(headers: HTTPHeadersLike, names: readonly string[]): boolean;
+/**
+ * Checks if all of the given header names are present.
+ *
+ * @param headers - The headers to inspect.
+ * @param names - The header names to check.
+ * @returns `true` if all names are present.
+ */
+export declare function hasAllHeaders(headers: HTTPHeadersLike, names: readonly string[]): boolean;
+//# sourceMappingURL=httpHeaders.basic.d.ts.map

package/dist/httpHeaders/basic/httpHeaders.basic.js

@@ -0,0 +1,29 @@
+/**
+ * Basic header existence check utilities.
+ *
+ * @module httpHeaders/basic
+ */
+import { asHTTPHeaders } from "../conversion/httpHeaders.conversion.js";
+/**
+ * Checks if at least one of the given header names is present.
+ *
+ * @param headers - The headers to inspect.
+ * @param names - The header names to check.
+ * @returns `true` if any of the names are present.
+ */
+export function hasAnyHeader(headers, names) {
+    const normalized = asHTTPHeaders(headers);
+    return names.some((name) => normalized.has(name));
+}
+/**
+ * Checks if all of the given header names are present.
+ *
+ * @param headers - The headers to inspect.
+ * @param names - The header names to check.
+ * @returns `true` if all names are present.
+ */
+export function hasAllHeaders(headers, names) {
+    const normalized = asHTTPHeaders(headers);
+    return names.every((name) => normalized.has(name));
+}
+//# sourceMappingURL=httpHeaders.basic.js.map

package/dist/httpHeaders/basic/httpHeaders.basicMatch.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Header value comparison utilities.
+ *
+ * @module httpHeaders/basicMatch
+ */
+import type { HTTPHeadersLike, HeaderMatchOptions } from "../types/httpHeaders.type.js";
+/**
+ * Checks if a header equals an expected value.
+ *
+ * @param headers - The headers to inspect.
+ * @param name - The header name.
+ * @param expected - The expected value.
+ * @param options - Matching options (case sensitivity, trimming).
+ * @returns `true` if the header value matches.
+ */
+export declare function headerEquals(headers: HTTPHeadersLike, name: string, expected: string, options?: HeaderMatchOptions): boolean;
+/**
+ * Checks if a header's comma-separated values contain a specific value.
+ *
+ * @param headers - The headers to inspect.
+ * @param name - The header name.
+ * @param value - The value to search for.
+ * @returns `true` if the value is found among the header's values.
+ */
+export declare function headerContains(headers: HTTPHeadersLike, name: string, value: string): boolean;
+//# sourceMappingURL=httpHeaders.basicMatch.d.ts.map