@vereda/http 1.0.0

package/dist/core/backoff.d.ts

@@ -0,0 +1,9 @@
+import type { BackoffFn, BackoffOptions } from "./types.ts";
+/** Default base delay in ms for exponential backoff. */
+export declare const DEFAULT_BASE_DELAY_MS = 200;
+/** Default max delay cap in ms for exponential backoff. */
+export declare const DEFAULT_MAX_DELAY_MS = 30000;
+/** Default jitter setting for exponential backoff. */
+export declare const DEFAULT_JITTER = true;
+export declare function buildBackoffFn(config?: BackoffFn | BackoffOptions): BackoffFn;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/core/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/core/backoff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5D,wDAAwD;AACxD,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,sDAAsD;AACtD,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,cAAc,GAAG,SAAS,CAgB7E"}

package/dist/core/backoff.js

@@ -0,0 +1,23 @@
+/** Default base delay in ms for exponential backoff. */
+export const DEFAULT_BASE_DELAY_MS = 200;
+/** Default max delay cap in ms for exponential backoff. */
+export const DEFAULT_MAX_DELAY_MS = 30_000;
+/** Default jitter setting for exponential backoff. */
+export const DEFAULT_JITTER = true;
+export function buildBackoffFn(config) {
+    if (typeof config === "function") {
+        return config;
+    }
+    const baseDelayMs = config?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    const maxDelayMs = config?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    const jitter = config?.jitter ?? DEFAULT_JITTER;
+    return (attempt) => {
+        const exponential = baseDelayMs * 2 ** attempt;
+        const capped = Math.min(exponential, maxDelayMs);
+        if (!jitter)
+            return capped;
+        // Full jitter: random value in [0, capped]
+        return Math.random() * capped;
+    };
+}
+//# sourceMappingURL=backoff.js.map

package/dist/core/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../src/core/backoff.ts"],"names":[],"mappings":"AAEA,wDAAwD;AACxD,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AACzC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAC3C,sDAAsD;AACtD,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;AAEnC,MAAM,UAAU,cAAc,CAAC,MAAmC;IACjE,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;QAClC,OAAO,MAAM,CAAC;IACf,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,EAAE,WAAW,IAAI,qBAAqB,CAAC;IACjE,MAAM,UAAU,GAAG,MAAM,EAAE,UAAU,IAAI,oBAAoB,CAAC;IAC9D,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,IAAI,cAAc,CAAC;IAEhD,OAAO,CAAC,OAAe,EAAU,EAAE;QAClC,MAAM,WAAW,GAAG,WAAW,GAAG,CAAC,IAAI,OAAO,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM;YAAE,OAAO,MAAM,CAAC;QAC3B,2CAA2C;QAC3C,OAAO,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC;IAC/B,CAAC,CAAC;AACH,CAAC"}

package/dist/core/client.d.ts

@@ -0,0 +1,98 @@
+import { type BulkheadSnapshot } from "../queue/bulkhead.ts";
+import { type MiddlewareFn } from "../queue/executor.ts";
+import { type Ticket } from "../ticket/ticket.ts";
+import type { ClientConfig, CloseOptions, LifecycleEventMap, ParsedRequestOptions, ParseFn, RequestOptions, UnparsedRequestOptions } from "./types.ts";
+export declare class HttpClient {
+    private readonly config;
+    private readonly emitter;
+    private readonly middlewares;
+    private readonly bulkheads;
+    private readonly circuitBreakers;
+    private readonly partitionConfigs;
+    private readonly logger;
+    private readonly metrics;
+    private readonly redactQuery;
+    private readonly customFetch;
+    private _closed;
+    private _closing;
+    private readonly _inflightTickets;
+    private constructor();
+    static create(config: ClientConfig): HttpClient;
+    use(middleware: MiddlewareFn): this;
+    on<K extends keyof LifecycleEventMap>(event: K, listener: (data: LifecycleEventMap[K]) => void): this;
+    off<K extends keyof LifecycleEventMap>(event: K, listener: (data: LifecycleEventMap[K]) => void): this;
+    /** Send a request. With `parse`, `data` is whatever `parse` returns; without
+     *  it, the body is left unread on `raw` and `data` is `undefined`. When
+     *  `parse` may or may not be set, `data` is `T | undefined`. */
+    request<T>(url: string, options: ParsedRequestOptions<T>): Ticket<T>;
+    request(url: string, options?: UnparsedRequestOptions): Ticket<undefined>;
+    request<T>(url: string, options?: RequestOptions<T>): Ticket<T | undefined>;
+    private send;
+    private _fireFirstAttempt;
+    /** Apply the unified retry gate after the first attempt failed (attempt 0).
+     *  Returns true if the request must NOT be retried — the ticket is resolved
+     *  with the raw error and must not be queued. */
+    private vetoed;
+    private _scheduleInBulkhead;
+    /** GET request. */
+    get<T>(url: string, options: Omit<ParsedRequestOptions<T>, "method">): Ticket<T>;
+    get(url: string, options?: Omit<UnparsedRequestOptions, "method">): Ticket<undefined>;
+    /** HEAD request. */
+    head<T>(url: string, options: Omit<ParsedRequestOptions<T>, "method">): Ticket<T>;
+    head(url: string, options?: Omit<UnparsedRequestOptions, "method">): Ticket<undefined>;
+    /** OPTIONS request. */
+    options<T>(url: string, options: Omit<ParsedRequestOptions<T>, "method">): Ticket<T>;
+    options(url: string, options?: Omit<UnparsedRequestOptions, "method">): Ticket<undefined>;
+    /** POST request. */
+    post<T>(url: string, body: BodyInit | (() => BodyInit) | undefined, options: Omit<ParsedRequestOptions<T>, "method" | "body">): Ticket<T>;
+    post(url: string, body?: BodyInit | (() => BodyInit), options?: Omit<UnparsedRequestOptions, "method" | "body">): Ticket<undefined>;
+    /** PUT request. */
+    put<T>(url: string, body: BodyInit | (() => BodyInit) | undefined, options: Omit<ParsedRequestOptions<T>, "method" | "body">): Ticket<T>;
+    put(url: string, body?: BodyInit | (() => BodyInit), options?: Omit<UnparsedRequestOptions, "method" | "body">): Ticket<undefined>;
+    /** PATCH request. */
+    patch<T>(url: string, body: BodyInit | (() => BodyInit) | undefined, options: Omit<ParsedRequestOptions<T>, "method" | "body">): Ticket<T>;
+    patch(url: string, body?: BodyInit | (() => BodyInit), options?: Omit<UnparsedRequestOptions, "method" | "body">): Ticket<undefined>;
+    /** DELETE request. */
+    delete<T>(url: string, options: Omit<ParsedRequestOptions<T>, "method">): Ticket<T>;
+    delete(url: string, options?: Omit<UnparsedRequestOptions, "method">): Ticket<undefined>;
+    /** Return a snapshot of all active bulkhead partitions.
+     *  Each entry includes the partition name, running/queued counts,
+     *  and configured concurrency/maxQueueSize limits. */
+    partitions(): BulkheadSnapshot[];
+    /** Close the client. New requests throw `ConfigurationError("client closed")`.
+     *  When `drain` is true, in-flight tickets are awaited up to `timeoutMs`
+     *  before the promise resolves, then remaining tickets are cancelled.
+     *  When `drain` is false (default), all in-flight tickets are cancelled
+     *  immediately.
+     *
+     *  `timeoutMs` is required when `drain` is true to prevent indefinite
+     *  hangs — use a value that fits your shutdown budget. */
+    close(opts?: CloseOptions): Promise<void>;
+    private _close;
+    /** The partition `_fireFirstAttempt` will use, or undefined when the URL
+     *  can't be resolved (that path surfaces the error on the ticket). */
+    private tryResolvePartition;
+    private resolveUrl;
+    private mergeTimeout;
+    private mergeRetry;
+    /** Returns the URL for logging, redacted if redactQuery is enabled. */
+    private logUrl;
+    /** Never throws: listener and metrics-sink errors are isolated (B3), since
+     *  callers emit mid-transition — e.g. `success` right before `markDone`. */
+    private emit;
+    private emitMetrics;
+    /** Push current queue-depth gauges: per-partition bulkhead backlog and the
+     *  global semaphore backlog (the D1 cap devs most need visibility into).
+     *  Polled from emit()'s request-start/terminal-event hooks rather than
+     *  pushed on the semaphore's own enqueue/dequeue, so a single request that
+     *  is briefly queued and released between those two hooks can land on
+     *  neither poll and never register — reliable for a sustained backlog,
+     *  not for a lone momentary wait (see docs/operations.md). `queuedMs` on
+     *  the lifecycle events has no such gap; it's measured, not polled. */
+    private emitQueueDepthGauges;
+}
+/** Parse JSON response body without validation.
+ *  Useful when you just need the raw parsed JSON object/array.
+ *  Unlike `parse` with Zod, this does not validate the shape. */
+export declare function json<T>(): ParseFn<T>;
+//# sourceMappingURL=client.d.ts.map

package/dist/core/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"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"}