@zudojs/http 0.1.0 → 1.1.0

package/dist/httpInterceptors/httpInterceptor.helper.js

@@ -0,0 +1,53 @@
+/**
+ * HTTP interceptor helper functions.
+ *
+ * @module httpInterceptors/helpers
+ */
+/**
+ * Normalizes a priority string.
+ */
+export function normalizePriority(priority) {
+    const normalized = priority.toLowerCase();
+    switch (normalized) {
+        case "first":
+        case "high":
+        case "normal":
+        case "low":
+        case "last":
+            return normalized;
+        default:
+            return "normal";
+    }
+}
+/**
+ * Sanitizes a name for use as an identifier.
+ */
+export function sanitizeName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+/**
+ * Compares two IDs for ordering.
+ */
+export function compareIds(a, b) {
+    return a.localeCompare(b);
+}
+/**
+ * Extracts a sequence number from an ID.
+ */
+export function extractSequence(id) {
+    const digits = id.match(/-(\d+)$/)?.[1];
+    return digits === undefined ? 0 : parseInt(digits, 10);
+}
+/**
+ * Generates a default request ID.
+ */
+export function defaultRequestId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).slice(2, 8);
+    return `req-${timestamp}-${random}`;
+}
+//# sourceMappingURL=httpInterceptor.helper.js.map

package/dist/httpInterceptors/httpInterceptor.type.d.ts

@@ -0,0 +1,48 @@
+/**
+ * HTTP interceptor types.
+ *
+ * @module httpInterceptors/types
+ */
+export type InterceptorPhase = "request" | "response" | "error" | "before-request" | "after-request";
+export type InterceptorPriority = "first" | "high" | "normal" | "low" | "last";
+export interface HttpInterceptorMetadata {
+    readonly id: string;
+    readonly name: string;
+    readonly phase: InterceptorPhase;
+    readonly priority: InterceptorPriority;
+    readonly enabled: boolean;
+    readonly description?: string;
+    readonly tags: readonly string[];
+}
+export interface HttpInterceptorOptions {
+    readonly name?: string;
+    readonly phase?: InterceptorPhase;
+    readonly priority?: InterceptorPriority;
+    readonly enabled?: boolean;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+}
+export interface RegisteredHttpInterceptor<T> {
+    readonly metadata: HttpInterceptorMetadata;
+    readonly handler: T;
+    readonly options: HttpInterceptorOptions;
+}
+export interface HttpInterceptorManagerOptions {
+    readonly maxInterceptors?: number;
+    readonly strictPhase?: boolean;
+    readonly allowDuplicateNames?: boolean;
+}
+export interface HttpInterceptorSnapshot {
+    readonly interceptors: readonly HttpInterceptorMetadata[];
+    readonly timestamp: number;
+    readonly version: number;
+}
+export interface InternalInterceptor<T> {
+    readonly id: string;
+    /** Monotonic registration order, used to keep the chain stable. */
+    readonly sequence: number;
+    readonly metadata: HttpInterceptorMetadata;
+    readonly handler: T;
+    readonly options: HttpInterceptorOptions;
+}
+//# sourceMappingURL=httpInterceptor.type.d.ts.map

package/dist/httpInterceptors/httpInterceptor.type.js

@@ -0,0 +1,7 @@
+/**
+ * HTTP interceptor types.
+ *
+ * @module httpInterceptors/types
+ */
+export {};
+//# sourceMappingURL=httpInterceptor.type.js.map

package/dist/httpInterceptors/manager/httpInterceptor.lookup.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Interceptor lookup and management.
+ *
+ * @module httpInterceptors/manager/lookup
+ */
+import type { InterceptorPhase, RegisteredHttpInterceptor, InternalInterceptor } from "../httpInterceptor.type.js";
+export declare function findByPhase<T>(interceptors: Map<string, InternalInterceptor<T>>, phase: InterceptorPhase): readonly RegisteredHttpInterceptor<T>[];
+export declare function enable<T>(interceptors: Map<string, InternalInterceptor<T>>, id: string): boolean;
+export declare function disable<T>(interceptors: Map<string, InternalInterceptor<T>>, id: string): boolean;
+export declare function getAll<T>(interceptors: Map<string, InternalInterceptor<T>>): readonly RegisteredHttpInterceptor<T>[];
+//# sourceMappingURL=httpInterceptor.lookup.d.ts.map

package/dist/httpInterceptors/manager/httpInterceptor.lookup.js

@@ -0,0 +1,62 @@
+/**
+ * Interceptor lookup and management.
+ *
+ * @module httpInterceptors/manager/lookup
+ */
+function comparePriority(a, b) {
+    const order = {
+        first: 0,
+        high: 1,
+        normal: 2,
+        low: 3,
+        last: 4,
+    };
+    return order[a] - order[b];
+}
+export function findByPhase(interceptors, phase) {
+    return getAll(interceptors)
+        .filter((i) => i.metadata.phase === phase && i.metadata.enabled)
+        .sort((a, b) => comparePriority(a.metadata.priority, b.metadata.priority));
+}
+export function enable(interceptors, id) {
+    const interceptor = interceptors.get(id);
+    if (!interceptor) {
+        return false;
+    }
+    interceptors.set(id, {
+        ...interceptor,
+        metadata: {
+            ...interceptor.metadata,
+            enabled: true,
+        },
+    });
+    return true;
+}
+export function disable(interceptors, id) {
+    const interceptor = interceptors.get(id);
+    if (!interceptor) {
+        return false;
+    }
+    interceptors.set(id, {
+        ...interceptor,
+        metadata: {
+            ...interceptor.metadata,
+            enabled: false,
+        },
+    });
+    return true;
+}
+export function getAll(interceptors) {
+    /*
+     * Sort on the stored registration sequence. Parsing the trailing digits out
+     * of the id collided across name prefixes ("auth-1" vs "audit-1").
+     */
+    return Array.from(interceptors.values())
+        .sort((a, b) => a.sequence - b.sequence)
+        .map((i) => ({
+        metadata: i.metadata,
+        handler: i.handler,
+        options: i.options,
+    }));
+}
+//# sourceMappingURL=httpInterceptor.lookup.js.map

package/dist/httpInterceptors/manager/httpInterceptor.manager.d.ts

@@ -0,0 +1,24 @@
+/**
+ * HTTP interceptor manager implementation.
+ *
+ * @module httpInterceptors/manager
+ */
+import type { InterceptorPhase, HttpInterceptorOptions, RegisteredHttpInterceptor, HttpInterceptorManagerOptions, HttpInterceptorSnapshot } from "../httpInterceptor.type.js";
+export declare class HttpInterceptorManager<T> {
+    private readonly registry;
+    private readonly options;
+    constructor(options?: HttpInterceptorManagerOptions);
+    register(handler: T, options?: HttpInterceptorOptions): string;
+    unregister(id: string): boolean;
+    get(id: string): RegisteredHttpInterceptor<T> | undefined;
+    has(id: string): boolean;
+    hasByName(name: string): boolean;
+    findByPhase(phase: InterceptorPhase): readonly RegisteredHttpInterceptor<T>[];
+    enable(id: string): boolean;
+    disable(id: string): boolean;
+    clear(): void;
+    snapshot(): HttpInterceptorSnapshot;
+    getAll(): readonly RegisteredHttpInterceptor<T>[];
+    get size(): number;
+}
+//# sourceMappingURL=httpInterceptor.manager.d.ts.map

package/dist/httpInterceptors/manager/httpInterceptor.manager.js

@@ -0,0 +1,58 @@
+/**
+ * HTTP interceptor manager implementation.
+ *
+ * @module httpInterceptors/manager
+ */
+import { InterceptorRegistry } from "./httpInterceptor.registration.js";
+import { createSnapshot } from "./httpInterceptor.snapshot.js";
+import { findByPhase, enable, disable, getAll, } from "./httpInterceptor.lookup.js";
+export class HttpInterceptorManager {
+    registry;
+    options;
+    constructor(options = {}) {
+        this.options = {
+            maxInterceptors: 100,
+            strictPhase: false,
+            allowDuplicateNames: false,
+            ...options,
+        };
+        this.registry = new InterceptorRegistry(this.options);
+    }
+    register(handler, options = {}) {
+        return this.registry.register(handler, options);
+    }
+    unregister(id) {
+        return this.registry.unregister(id);
+    }
+    get(id) {
+        return this.registry.get(id);
+    }
+    has(id) {
+        return this.registry.has(id);
+    }
+    hasByName(name) {
+        return this.registry.hasByName(name);
+    }
+    findByPhase(phase) {
+        return findByPhase(this.registry.underlying, phase);
+    }
+    enable(id) {
+        return enable(this.registry.underlying, id);
+    }
+    disable(id) {
+        return disable(this.registry.underlying, id);
+    }
+    clear() {
+        this.registry.clear();
+    }
+    snapshot() {
+        return createSnapshot(this.registry);
+    }
+    getAll() {
+        return getAll(this.registry.underlying);
+    }
+    get size() {
+        return this.registry.size;
+    }
+}
+//# sourceMappingURL=httpInterceptor.manager.js.map

package/dist/httpInterceptors/manager/httpInterceptor.registration.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Interceptor registration.
+ *
+ * @module httpInterceptors/manager/registration
+ */
+import type { HttpInterceptorOptions, RegisteredHttpInterceptor, InternalInterceptor } from "../httpInterceptor.type.js";
+export interface InterceptorRegistryOptions {
+    readonly maxInterceptors?: number;
+    readonly strictPhase?: boolean;
+    readonly allowDuplicateNames?: boolean;
+}
+export declare class InterceptorRegistry<T> {
+    private readonly interceptors;
+    private version;
+    private sequence;
+    private readonly options;
+    constructor(options?: InterceptorRegistryOptions);
+    register(handler: T, options?: HttpInterceptorOptions): string;
+    unregister(id: string): boolean;
+    get(id: string): RegisteredHttpInterceptor<T> | undefined;
+    has(id: string): boolean;
+    hasByName(name: string): boolean;
+    clear(): void;
+    get size(): number;
+    get version_number(): number;
+    get underlying(): Map<string, InternalInterceptor<T>>;
+}
+//# sourceMappingURL=httpInterceptor.registration.d.ts.map

package/dist/httpInterceptors/manager/httpInterceptor.registration.js

@@ -0,0 +1,119 @@
+/**
+ * Interceptor registration.
+ *
+ * @module httpInterceptors/manager/registration
+ */
+import { normalizePriority, sanitizeName } from "../httpInterceptor.helper.js";
+function generateId(name, sequence) {
+    const base = name ? sanitizeName(name) : "interceptor";
+    return `${base}-${sequence}`;
+}
+const INTERCEPTOR_PHASES = [
+    "request",
+    "response",
+    "error",
+    "before-request",
+    "after-request",
+];
+export class InterceptorRegistry {
+    interceptors = new Map();
+    version = 0;
+    /*
+     * Ids used to be derived from `Map.size`, which *decreases* on unregister.
+     * Registering after an unregister therefore reproduced a live id and
+     * `Map.set` silently replaced the interceptor holding it. A counter that
+     * only ever increases cannot collide.
+     */
+    sequence = 0;
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    register(handler, options = {}) {
+        const maxInterceptors = this.options.maxInterceptors;
+        if (maxInterceptors !== undefined &&
+            this.interceptors.size >= maxInterceptors) {
+            throw new RangeError(`Cannot register interceptor: the configured maximum of ${maxInterceptors} is already registered.`);
+        }
+        if (this.options.allowDuplicateNames === false &&
+            options.name !== undefined &&
+            this.hasByName(options.name)) {
+            throw new Error(`An interceptor named "${options.name}" is already registered.`);
+        }
+        if (this.options.strictPhase === true &&
+            options.phase !== undefined &&
+            !INTERCEPTOR_PHASES.includes(options.phase)) {
+            throw new TypeError(`Unknown interceptor phase "${options.phase}".`);
+        }
+        const sequence = this.sequence++;
+        const id = generateId(options.name, sequence);
+        if (this.interceptors.has(id)) {
+            throw new Error(`An interceptor with id "${id}" is already registered.`);
+        }
+        const name = options.name ?? id;
+        const phase = options.phase ?? "request";
+        const priority = normalizePriority(options.priority ?? "normal");
+        const metadata = {
+            id,
+            name,
+            phase,
+            priority,
+            enabled: options.enabled ?? true,
+            description: options.description,
+            tags: options.tags ?? [],
+        };
+        const interceptor = {
+            id,
+            sequence,
+            metadata,
+            handler,
+            options,
+        };
+        this.interceptors.set(id, interceptor);
+        this.version++;
+        return id;
+    }
+    unregister(id) {
+        const existed = this.interceptors.delete(id);
+        if (existed) {
+            this.version++;
+        }
+        return existed;
+    }
+    get(id) {
+        const interceptor = this.interceptors.get(id);
+        if (!interceptor) {
+            return undefined;
+        }
+        return {
+            metadata: interceptor.metadata,
+            handler: interceptor.handler,
+            options: interceptor.options,
+        };
+    }
+    has(id) {
+        return this.interceptors.has(id);
+    }
+    hasByName(name) {
+        for (const interceptor of this.interceptors.values()) {
+            if (interceptor.metadata.name === name) {
+                return true;
+            }
+        }
+        return false;
+    }
+    clear() {
+        this.interceptors.clear();
+        this.version++;
+    }
+    get size() {
+        return this.interceptors.size;
+    }
+    get version_number() {
+        return this.version;
+    }
+    get underlying() {
+        return this.interceptors;
+    }
+}
+//# sourceMappingURL=httpInterceptor.registration.js.map

package/dist/httpInterceptors/manager/httpInterceptor.snapshot.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Interceptor snapshot functionality.
+ *
+ * @module httpInterceptors/manager/snapshot
+ */
+import type { HttpInterceptorSnapshot } from "../httpInterceptor.type.js";
+import type { InterceptorRegistry } from "./httpInterceptor.registration.js";
+/**
+ * Creates a snapshot of the interceptor registry.
+ */
+export declare function createSnapshot<T>(registry: InterceptorRegistry<T>): HttpInterceptorSnapshot;
+//# sourceMappingURL=httpInterceptor.snapshot.d.ts.map

package/dist/httpInterceptors/manager/httpInterceptor.snapshot.js

@@ -0,0 +1,17 @@
+/**
+ * Interceptor snapshot functionality.
+ *
+ * @module httpInterceptors/manager/snapshot
+ */
+import { getAll } from "./httpInterceptor.lookup.js";
+/**
+ * Creates a snapshot of the interceptor registry.
+ */
+export function createSnapshot(registry) {
+    return {
+        interceptors: getAll(registry.underlying).map((i) => i.metadata),
+        timestamp: Date.now(),
+        version: registry.version_number,
+    };
+}
+//# sourceMappingURL=httpInterceptor.snapshot.js.map

package/dist/httpInterceptors/manager/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * HTTP interceptor manager.
+ *
+ * @module httpInterceptors/manager
+ */
+export * from "./httpInterceptor.registration.js";
+export * from "./httpInterceptor.lookup.js";
+export * from "./httpInterceptor.snapshot.js";
+export * from "./httpInterceptor.manager.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpInterceptors/manager/index.js

@@ -0,0 +1,10 @@
+/**
+ * HTTP interceptor manager.
+ *
+ * @module httpInterceptors/manager
+ */
+export * from "./httpInterceptor.registration.js";
+export * from "./httpInterceptor.lookup.js";
+export * from "./httpInterceptor.snapshot.js";
+export * from "./httpInterceptor.manager.js";
+//# sourceMappingURL=index.js.map

package/dist/httpKeepAlive/httpKeepAlive.core.d.ts

@@ -0,0 +1,63 @@
+/**
+ * HTTP keep-alive utilities.
+ *
+ * Provides framework-agnostic helpers for connection persistence,
+ * Keep-Alive header parsing, timeout handling, and connection policy.
+ *
+ * Transport-specific socket management belongs to the server/client adapter
+ * layer. This module only handles HTTP-level semantics.
+ */
+export interface KeepAliveOptions {
+    readonly enabled?: boolean;
+    readonly timeout?: number;
+    readonly maxRequests?: number;
+    readonly maxIdleTime?: number;
+}
+export interface KeepAliveConfig {
+    readonly enabled: boolean;
+    readonly timeout: number | undefined;
+    readonly maxRequests: number | undefined;
+    readonly maxIdleTime: number | undefined;
+}
+export interface KeepAliveParameters {
+    readonly timeout?: number;
+    readonly max?: number;
+    readonly extensions: Readonly<Record<string, string | undefined>>;
+}
+export interface KeepAliveState {
+    readonly requests: number;
+    readonly createdAt: number;
+    readonly lastUsedAt: number;
+    readonly closed: boolean;
+}
+export declare const DEFAULT_KEEP_ALIVE_ENABLED = true;
+export declare const DEFAULT_KEEP_ALIVE_TIMEOUT = 5000;
+export declare const DEFAULT_KEEP_ALIVE_MAX_REQUESTS = 100;
+export declare const MIN_KEEP_ALIVE_TIMEOUT = 0;
+export declare const MAX_KEEP_ALIVE_TIMEOUT = 86400000;
+export declare function createKeepAliveConfig(options?: KeepAliveOptions | undefined): KeepAliveConfig;
+export declare function normalizeTimeout(timeout: number | undefined): number | undefined;
+export declare function normalizeMaxRequests(maxRequests: number | undefined): number | undefined;
+export declare function parseKeepAliveHeader(value: string | undefined | null): KeepAliveParameters;
+export declare function formatKeepAliveHeader(parameters?: Partial<KeepAliveParameters> | undefined): string;
+export declare function parseConnectionHeader(value: string | undefined | null): string[];
+export declare function hasConnectionToken(value: string | undefined | null, token: string): boolean;
+export declare function isConnectionCloseRequested(value: string | undefined | null): boolean;
+export declare function isConnectionKeepAliveRequested(value: string | undefined | null): boolean;
+export declare function supportsPersistentConnections(httpVersion: string): boolean;
+export declare function defaultConnectionPersistence(httpVersion: string): boolean;
+export declare function shouldKeepAlive(httpVersion: string, connectionHeader: string | undefined | null, options?: KeepAliveOptions | undefined): boolean;
+export declare function createConnectionHeader(keepAlive: boolean): string;
+export declare function shouldSendKeepAliveHeader(httpVersion: string): boolean;
+export declare function createKeepAliveState(now?: number): KeepAliveState;
+export declare function recordKeepAliveRequest(state: KeepAliveState, now?: number): KeepAliveState;
+export declare function closeKeepAlive(state: KeepAliveState, now?: number): KeepAliveState;
+export declare function hasExceededMaxRequests(state: KeepAliveState, maxRequests: number | undefined): boolean;
+export declare function hasExceededIdleTimeout(state: KeepAliveState, maxIdleTime: number | undefined, now?: number): boolean;
+export declare function shouldCloseKeepAlive(state: KeepAliveState, options?: KeepAliveOptions | undefined, now?: number): boolean;
+export declare function millisecondsToSeconds(milliseconds: number): number;
+export declare function secondsToMilliseconds(seconds: number): number;
+export declare function createKeepAliveHeader(options?: KeepAliveOptions | undefined): string | undefined;
+export declare function addConnectionToken(value: string | undefined | null, token: string): string;
+export declare function removeConnectionToken(value: string | undefined | null, token: string): string;
+//# sourceMappingURL=httpKeepAlive.core.d.ts.map