fetchvault 1.0.0

package/dist/retry.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Determines whether a failed request should be retried.
+ *
+ * @param statusCode HTTP status code when available; `null` indicates network failure.
+ * @param attempt Current retry attempt number starting at 1.
+ * @param maxRetries Maximum retry attempts allowed.
+ * @returns `true` when retry conditions are met.
+ * @example
+ * const retry = shouldRetry(503, 1, 3)
+ */
+export declare function shouldRetry(statusCode: number | null, attempt: number, maxRetries: number): boolean;
+/**
+ * Calculates an exponential backoff delay with jitter.
+ *
+ * @param attempt Current retry attempt number starting at 1.
+ * @param randomFn Random number generator for deterministic testing.
+ * @returns Delay in milliseconds.
+ * @example
+ * const delayMs = calculateRetryDelay(2)
+ */
+export declare function calculateRetryDelay(attempt: number, randomFn?: () => number): number;
+/**
+ * Waits for a retry delay interval.
+ *
+ * @param delayMs Delay duration in milliseconds.
+ * @returns Promise that resolves after the delay.
+ * @example
+ * await waitForRetryDelay(1_000)
+ */
+export declare function waitForRetryDelay(delayMs: number): Promise<void>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAUT;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,MAAoB,GACnC,MAAM,CAIR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhE"}

package/dist/retry.js

@@ -0,0 +1,51 @@
+const BASE_RETRY_DELAY_MS = 1000;
+const MAX_JITTER_MS = 500;
+const SERVER_ERROR_MIN = 500;
+const SERVER_ERROR_MAX = 599;
+/**
+ * Determines whether a failed request should be retried.
+ *
+ * @param statusCode HTTP status code when available; `null` indicates network failure.
+ * @param attempt Current retry attempt number starting at 1.
+ * @param maxRetries Maximum retry attempts allowed.
+ * @returns `true` when retry conditions are met.
+ * @example
+ * const retry = shouldRetry(503, 1, 3)
+ */
+export function shouldRetry(statusCode, attempt, maxRetries) {
+    if (attempt > maxRetries) {
+        return false;
+    }
+    if (statusCode === null) {
+        return true;
+    }
+    return statusCode >= SERVER_ERROR_MIN && statusCode <= SERVER_ERROR_MAX;
+}
+/**
+ * Calculates an exponential backoff delay with jitter.
+ *
+ * @param attempt Current retry attempt number starting at 1.
+ * @param randomFn Random number generator for deterministic testing.
+ * @returns Delay in milliseconds.
+ * @example
+ * const delayMs = calculateRetryDelay(2)
+ */
+export function calculateRetryDelay(attempt, randomFn = Math.random) {
+    const exponentDelay = 2 ** attempt * BASE_RETRY_DELAY_MS;
+    const jitter = Math.floor(randomFn() * (MAX_JITTER_MS + 1));
+    return exponentDelay + jitter;
+}
+/**
+ * Waits for a retry delay interval.
+ *
+ * @param delayMs Delay duration in milliseconds.
+ * @returns Promise that resolves after the delay.
+ * @example
+ * await waitForRetryDelay(1_000)
+ */
+export function waitForRetryDelay(delayMs) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, delayMs);
+    });
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA,MAAM,mBAAmB,GAAG,IAAK,CAAA;AACjC,MAAM,aAAa,GAAG,GAAG,CAAA;AACzB,MAAM,gBAAgB,GAAG,GAAG,CAAA;AAC5B,MAAM,gBAAgB,GAAG,GAAG,CAAA;AAE5B;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CACzB,UAAyB,EACzB,OAAe,EACf,UAAkB;IAElB,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;QACzB,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,UAAU,IAAI,gBAAgB,IAAI,UAAU,IAAI,gBAAgB,CAAA;AACzE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,WAAyB,IAAI,CAAC,MAAM;IAEpC,MAAM,aAAa,GAAG,CAAC,IAAI,OAAO,GAAG,mBAAmB,CAAA;IACxD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC,CAAA;IAC3D,OAAO,aAAa,GAAG,MAAM,CAAA;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IAC9B,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/timeout.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Parses a timeout value into milliseconds.
+ *
+ * @param input Human-readable timeout (e.g. `"500ms"`, `"1.5s"`) or numeric milliseconds.
+ * @returns Timeout duration in milliseconds.
+ * @example
+ * const timeoutMs = parseTimeout('5s')
+ */
+export declare function parseTimeout(input: string | number): number;
+/**
+ * Creates a timeout-backed abort signal and merges it with an optional external signal.
+ *
+ * @param timeout Timeout value in human-readable format or milliseconds.
+ * @param externalSignal Optional user-provided abort signal.
+ * @returns Signal, cleanup callback, and timeout-state accessor.
+ * @example
+ * const controller = createTimeoutSignal('5s', options.signal)
+ */
+export declare function createTimeoutSignal(timeout: string | number | undefined, externalSignal?: AbortSignal): {
+    signal: AbortSignal | undefined;
+    cleanup: () => void;
+    didTimeout: () => boolean;
+};
+/**
+ * Merges two abort signals into a single composite signal.
+ *
+ * @param primary Primary abort signal.
+ * @param secondary Optional secondary abort signal.
+ * @returns Composite abort signal that aborts when either source aborts.
+ * @example
+ * const signal = mergeAbortSignals(internal.signal, options.signal)
+ */
+export declare function mergeAbortSignals(primary: AbortSignal, secondary?: AbortSignal): AbortSignal;
+//# sourceMappingURL=timeout.d.ts.map

package/dist/timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../src/timeout.ts"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAuB3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EACpC,cAAc,CAAC,EAAE,WAAW,GAC3B;IACD,MAAM,EAAE,WAAW,GAAG,SAAS,CAAA;IAC/B,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,UAAU,EAAE,MAAM,OAAO,CAAA;CAC1B,CAmBA;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,SAAS,CAAC,EAAE,WAAW,GACtB,WAAW,CAoBb"}

package/dist/timeout.js

@@ -0,0 +1,87 @@
+const MILLISECONDS_SUFFIX = 'ms';
+const SECONDS_SUFFIX = 's';
+const MS_MULTIPLIER = 1;
+const SECONDS_TO_MS = 1000;
+const DURATION_PATTERN = /^(\d*\.?\d+)(ms|s)$/i;
+/**
+ * Parses a timeout value into milliseconds.
+ *
+ * @param input Human-readable timeout (e.g. `"500ms"`, `"1.5s"`) or numeric milliseconds.
+ * @returns Timeout duration in milliseconds.
+ * @example
+ * const timeoutMs = parseTimeout('5s')
+ */
+export function parseTimeout(input) {
+    if (typeof input === 'number' && Number.isFinite(input) && input >= 0) {
+        return input;
+    }
+    if (typeof input !== 'string') {
+        throw new TypeError('Timeout must be a non-negative number or a duration string like "500ms" or "5s".');
+    }
+    const normalized = input.trim().toLowerCase();
+    const match = normalized.match(DURATION_PATTERN);
+    if (!match) {
+        throw new TypeError(`Invalid timeout format "${input}". Use values like "500ms", "5s", or 300.`);
+    }
+    const amount = Number(match[1]);
+    const unit = match[2];
+    if (!Number.isFinite(amount) || amount < 0) {
+        throw new TypeError(`Invalid timeout value "${input}". Timeout must be non-negative.`);
+    }
+    const multiplier = unit === MILLISECONDS_SUFFIX ? MS_MULTIPLIER : SECONDS_TO_MS;
+    return Math.round(amount * multiplier);
+}
+/**
+ * Creates a timeout-backed abort signal and merges it with an optional external signal.
+ *
+ * @param timeout Timeout value in human-readable format or milliseconds.
+ * @param externalSignal Optional user-provided abort signal.
+ * @returns Signal, cleanup callback, and timeout-state accessor.
+ * @example
+ * const controller = createTimeoutSignal('5s', options.signal)
+ */
+export function createTimeoutSignal(timeout, externalSignal) {
+    if (timeout === undefined) {
+        return { signal: externalSignal, cleanup: () => undefined, didTimeout: () => false };
+    }
+    const timeoutMs = parseTimeout(timeout);
+    const timeoutController = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        timeoutController.abort(new Error('FetchVault timeout exceeded'));
+    }, timeoutMs);
+    const signal = mergeAbortSignals(timeoutController.signal, externalSignal);
+    return {
+        signal,
+        cleanup: () => clearTimeout(timer),
+        didTimeout: () => timedOut
+    };
+}
+/**
+ * Merges two abort signals into a single composite signal.
+ *
+ * @param primary Primary abort signal.
+ * @param secondary Optional secondary abort signal.
+ * @returns Composite abort signal that aborts when either source aborts.
+ * @example
+ * const signal = mergeAbortSignals(internal.signal, options.signal)
+ */
+export function mergeAbortSignals(primary, secondary) {
+    if (!secondary) {
+        return primary;
+    }
+    if (typeof AbortSignal.any === 'function') {
+        return AbortSignal.any([primary, secondary]);
+    }
+    const compositeController = new AbortController();
+    const abortComposite = () => compositeController.abort();
+    if (primary.aborted || secondary.aborted) {
+        abortComposite();
+        return compositeController.signal;
+    }
+    primary.addEventListener('abort', abortComposite, { once: true });
+    secondary.addEventListener('abort', abortComposite, { once: true });
+    return compositeController.signal;
+}
+//# sourceMappingURL=timeout.js.map

package/dist/timeout.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Machine-readable error codes emitted by FetchVault.
+ *
+ * @example
+ * const code: VaultErrorCode = 'TIMEOUT'
+ */
+export type VaultErrorCode = 'NETWORK_ERROR' | 'TIMEOUT' | 'PARSE_ERROR' | 'VALIDATION_ERROR' | 'CIRCUIT_OPEN' | 'MIDDLEWARE_ERROR' | 'HTTP_ERROR' | 'UNKNOWN';
+/**
+ * Structured error object returned on failed requests.
+ *
+ * @example
+ * const error: VaultError = { code: 'HTTP_ERROR', message: 'Request failed' }
+ */
+export interface VaultError {
+    /** Machine-readable error code */
+    code: VaultErrorCode;
+    /** Human-readable message */
+    message: string;
+    /** The original thrown value, if any */
+    cause?: unknown;
+}
+/**
+ * Successful FetchVault response shape.
+ *
+ * @example
+ * const success: VaultSuccess<{ ok: true }> = { data: { ok: true }, error: null, statusCode: 200 }
+ */
+export interface VaultSuccess<T> {
+    /** The parsed and validated response data */
+    data: T;
+    /** Always null on success */
+    error: null;
+    /** HTTP status code of the response */
+    statusCode: number;
+}
+/**
+ * Failed FetchVault response shape.
+ *
+ * @example
+ * const failure: VaultFailure = { data: null, error: { code: 'NETWORK_ERROR', message: 'Offline' }, statusCode: null }
+ */
+export interface VaultFailure {
+    /** Always null on failure */
+    data: null;
+    /** Structured error object describing what went wrong */
+    error: VaultError;
+    /** HTTP status code if available, null for network-level failures */
+    statusCode: number | null;
+}
+/**
+ * The standard result object returned by every FetchVault call.
+ * Uses a discriminated union to enforce explicit error handling.
+ * A vault always gives you back exactly what you put in � or tells
+ * you clearly why it couldn't.
+ *
+ * @example
+ * const result: VaultResult<{ id: string }> = await fetchvault('/users/1')
+ */
+export type VaultResult<T> = VaultSuccess<T> | VaultFailure;
+/**
+ * Structural schema contract compatible with Zod, Valibot, Yup, and others.
+ *
+ * @example
+ * const schema: VaultSchema<{ id: string }> = { parse: (input) => input as { id: string } }
+ */
+export interface VaultSchema<T> {
+    /** Parses and validates unknown input into typed output */
+    parse: (data: unknown) => T;
+}
+/**
+ * Infers the output type from a structural schema.
+ *
+ * @example
+ * type User = InferSchema<{ parse: (input: unknown) => { id: string } }>
+ */
+export type InferSchema<S> = S extends VaultSchema<infer Output> ? Output : never;
+/**
+ * Internal request model used by middleware pipelines.
+ *
+ * @example
+ * const req: VaultRequest = { url: '/users', method: 'GET', headers: {} }
+ */
+export interface VaultRequest {
+    /** Final request URL */
+    url: string;
+    /** HTTP method in uppercase */
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Request headers as plain object */
+    headers: Record<string, string>;
+    /** Request body before fetch boundary serialization */
+    body?: unknown;
+    /** Optional merged abort signal */
+    signal?: AbortSignal;
+}
+/**
+ * Internal response model used by middleware pipelines.
+ *
+ * @example
+ * const res: VaultResponse = { statusCode: 200, headers: { 'content-type': 'application/json' }, raw: { ok: true }, data: { ok: true } }
+ */
+export interface VaultResponse {
+    /** HTTP status code */
+    statusCode: number;
+    /** Response headers as plain object */
+    headers: Record<string, string>;
+    /** Raw payload before schema validation */
+    raw: unknown;
+    /** Current transformed payload */
+    data: unknown;
+}
+/**
+ * Hook executed before a request is sent.
+ *
+ * @example
+ * const hook: VaultRequestHook = async (req) => ({ ...req, headers: { ...req.headers, Authorization: 'Bearer token' } })
+ */
+export type VaultRequestHook = (req: VaultRequest) => VaultRequest | Promise<VaultRequest>;
+/**
+ * Hook executed after a response is received.
+ *
+ * @example
+ * const hook: VaultResponseHook = (res) => ({ ...res, data: res.raw })
+ */
+export type VaultResponseHook = (res: VaultResponse) => VaultResponse | Promise<VaultResponse>;
+/**
+ * Mock response configuration.
+ *
+ * @example
+ * const mock: VaultMockConfig = { data: { ok: true }, status: 200, delay: '200ms' }
+ */
+export interface VaultMockConfig {
+    /** Data to return as the mock response */
+    data: unknown;
+    /** Mock HTTP status code � default: 200 */
+    status?: number;
+    /** Simulated network delay e.g. "200ms" */
+    delay?: string | number;
+}
+/**
+ * Request options for a FetchVault call.
+ *
+ * @example
+ * const options: VaultOptions<{ id: string }, never> = { method: 'GET', timeout: '5s' }
+ */
+export interface VaultOptions<T, S> {
+    /** HTTP method � defaults to GET */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Request headers merged with instance-level headers */
+    headers?: Record<string, string>;
+    /** Request body � will be JSON.stringify'd automatically */
+    body?: unknown;
+    /** Human-readable timeout e.g. "5s" or "500ms" */
+    timeout?: string | number;
+    /** Number of retries on 5xx or network failure � default: 3 */
+    retries?: number;
+    /** Optional validation schema (Zod, Valibot, Yup compatible) */
+    schema?: S;
+    /** User-provided AbortSignal � merged with internal timeout signal */
+    signal?: AbortSignal;
+    /** Deduplicate concurrent GET requests � default: true */
+    deduplicate?: boolean;
+    /** If provided, bypasses network and returns mock data */
+    mock?: VaultMockConfig;
+    /** Hooks that run before the request is sent */
+    beforeRequest?: Array<VaultRequestHook>;
+    /** Hooks that run after a response is received */
+    afterResponse?: Array<VaultResponseHook>;
+}
+/**
+ * Client-level defaults used by `createClient`.
+ *
+ * @example
+ * const config: VaultClientConfig = { baseURL: 'https://api.example.com', timeout: '10s' }
+ */
+export interface VaultClientConfig {
+    /** Base URL prefixed to every method path */
+    baseURL: string;
+    /** Default headers merged into each request */
+    headers?: Record<string, string>;
+    /** Default timeout inherited by each request */
+    timeout?: string | number;
+    /** Default retry count inherited by each request */
+    retries?: number;
+    /** Default before-request hooks */
+    beforeRequest?: Array<VaultRequestHook>;
+    /** Default after-response hooks */
+    afterResponse?: Array<VaultResponseHook>;
+}
+/**
+ * Callable method contract used by each HTTP verb helper.
+ *
+ * @example
+ * const get: VaultClientMethod = (path) => fetchvault(path)
+ */
+export type VaultClientMethod = <T, S extends VaultSchema<T> = never>(path: string, options?: VaultOptions<T, S>) => Promise<VaultResult<S extends never ? T : InferSchema<S>>>;
+/**
+ * Pre-configured FetchVault client interface.
+ *
+ * @example
+ * const client: VaultClient = createClient({ baseURL: 'https://api.example.com' })
+ */
+export interface VaultClient {
+    /** Executes a GET request */
+    get: VaultClientMethod;
+    /** Executes a POST request */
+    post: VaultClientMethod;
+    /** Executes a PUT request */
+    put: VaultClientMethod;
+    /** Executes a PATCH request */
+    patch: VaultClientMethod;
+    /** Executes a DELETE request */
+    delete: VaultClientMethod;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "fetchvault",
+  "version": "1.0.0",
+  "description": "A resilient, typed, zero-dependency fetch wrapper with circuit-breaker, retry, and deduplication.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && node scripts/build-cjs.mjs",
+    "test": "vitest run",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "keywords": [
+    "fetch",
+    "resilience",
+    "circuit-breaker",
+    "retry",
+    "deduplication",
+    "typescript"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}