fetchvault 1.0.0

package/README.md

@@ -0,0 +1,273 @@
+# FetchVault
+
+> A tiny, zero-dependency fetch wrapper with retries, timeouts, deduplication, circuit breaking, mocking, and typed results.
+
+![npm version](https://img.shields.io/npm/v/fetchvault)
+![bundle size <3kb](https://img.shields.io/badge/bundle-%3C3kb-brightgreen)
+![zero dependencies](https://img.shields.io/badge/dependencies-0-success)
+![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178c6)
+![MIT](https://img.shields.io/badge/license-MIT-blue)
+
+---
+
+## Why FetchVault?
+
+FetchVault gives you a safer default for HTTP calls without pulling in a heavy client.
+
+- Shielded results: every request resolves to a predictable `{ data, error, statusCode }` shape
+- Lightning fast: tiny footprint with zero runtime dependencies
+- Retry built in: automatic retries for network failures and `5xx` responses
+- Human-friendly timeouts: use values like `"500ms"` or `"5s"`
+- Smart deduplication: concurrent `GET` requests reuse the same in-flight call
+- Circuit breaker protection: repeated upstream failures stop hammering unhealthy services
+- Middleware hooks: intercept and transform requests or responses
+- Built-in mocking: return local mock data without touching the network
+- Schema validation: plug in Zod or any `parse(data)` schema
+- TypeScript-ready: typed results and typed client helpers out of the box
+
+---
+
+## Quick Start
+
+```bash
+npm install fetchvault
+```
+
+```ts
+import { fetchvault } from 'fetchvault'
+
+const { data, error, statusCode } = await fetchvault<{ id: string }>(
+  'https://api.example.com/users/1'
+)
+
+if (error) {
+  console.error(error.code, error.message)
+} else {
+  console.log(statusCode, data.id)
+}
+```
+
+### Why teams like it
+
+- Cleaner async code with fewer hidden failure paths
+- Easier UI and API handling because success and failure share one shape
+- Useful resilience features without adding Axios-sized overhead
+- Good fit for browser apps, Node services, CLIs, and SDKs
+
+---
+
+## The Result Pattern
+
+FetchVault always resolves with the same object shape:
+
+```ts
+type VaultResult<T> = {
+  data: T | null
+  error: VaultError | null
+  statusCode: number | null
+}
+```
+
+That means you can handle API calls with a simple `if (error)` branch instead of mixing `try/catch` into normal control flow.
+
+Before (Axios):
+
+```ts
+try {
+  const response = await axios.get('/users/1')
+  console.log(response.data)
+} catch (error) {
+  console.error(error)
+}
+```
+
+After (FetchVault):
+
+```ts
+const { data, error } = await fetchvault<{ id: string }>('/users/1')
+
+if (error) {
+  console.error(error.code, error.message)
+} else {
+  console.log(data.id)
+}
+```
+
+`fetchvault()` always returns the same shape, so TypeScript nudges you toward explicit and predictable error handling.
+
+---
+
+## API Reference
+
+### fetchvault(url, options)
+
+```ts
+fetchvault<T, S extends VaultSchema<T> = never>(
+  url: string,
+  options?: VaultOptions<T, S>
+): Promise<VaultResult<S extends never ? T : InferSchema<S>>>
+```
+
+`VaultOptions` fields:
+
+- `method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'` HTTP method (`GET` default)
+- `headers?: Record<string, string>` request headers
+- `body?: unknown` request body (objects are JSON-serialized)
+- `timeout?: string | number` timeout like `"5s"`, `"500ms"`, or `300`
+- `retries?: number` retries for network and `5xx` failures (default `3`)
+- `schema?: S` structural validator with `parse(data)`
+- `signal?: AbortSignal` external abort signal merged with timeout signal
+- `deduplicate?: boolean` deduplicate concurrent `GET` calls (default `true`)
+- `mock?: VaultMockConfig` bypass network and return mock data
+- `beforeRequest?: VaultRequestHook[]` ordered request middleware
+- `afterResponse?: VaultResponseHook[]` ordered response middleware
+
+### createClient(config)
+
+```ts
+import { createClient } from 'fetchvault'
+
+const api = createClient({
+  baseURL: 'https://api.example.com',
+  headers: { Authorization: 'Bearer token' },
+  timeout: '10s',
+  retries: 2,
+  beforeRequest: [
+    async (req) => ({
+      ...req,
+      headers: { ...req.headers, 'x-client': 'web' }
+    })
+  ]
+})
+
+const result = await api.get<{ id: string }>('/users/1')
+```
+
+### Features with code examples
+
+- Retries with jitter
+
+```ts
+const result = await fetchvault('https://api.example.com/unstable', { retries: 3 })
+```
+
+- Circuit breaker
+
+```ts
+const api = createClient({ baseURL: 'https://upstream.example.com' })
+const result = await api.get('/health')
+```
+
+- Request deduplication
+
+```ts
+const a = fetchvault('https://api.example.com/users')
+const b = fetchvault('https://api.example.com/users')
+const [first, second] = await Promise.all([a, b])
+```
+
+Both calls reuse the same in-flight `GET` request by default.
+
+- Human-readable timeouts
+
+```ts
+await fetchvault('https://api.example.com/slow', { timeout: '1.5s' })
+```
+
+- Middleware / interceptors
+
+```ts
+await fetchvault('https://api.example.com/users', {
+  beforeRequest: [
+    (req) => ({
+      ...req,
+      headers: { ...req.headers, Authorization: 'Bearer token' }
+    })
+  ],
+  afterResponse: [
+    (res) => ({ ...res, data: { payload: res.data } })
+  ]
+})
+```
+
+- Built-in mocking
+
+```ts
+await fetchvault('https://api.example.com/users', {
+  mock: { data: [{ id: '1' }], status: 200, delay: '200ms' }
+})
+```
+
+- Schema validation with Zod
+
+```ts
+import { z } from 'zod'
+
+const User = z.object({ id: z.string() })
+const result = await fetchvault('https://api.example.com/users/1', { schema: User })
+```
+
+Any schema object with a `parse(data)` method works, so you are not locked into one validation library.
+
+---
+
+## Error Codes
+
+FetchVault keeps errors machine-readable so your app logic can branch safely.
+
+```ts
+if (error?.code === 'TIMEOUT') {
+  showRetryToast()
+}
+
+if (error?.code === 'HTTP_ERROR' && statusCode === 401) {
+  redirectToLogin()
+}
+```
+
+Common error codes include:
+
+- `HTTP_ERROR`
+- `NETWORK_ERROR`
+- `TIMEOUT`
+- `VALIDATION_ERROR`
+- `MIDDLEWARE_ERROR`
+- `CIRCUIT_OPEN`
+
+---
+
+## How It Works
+
+### Circuit Breaker State Machine
+
+```text
+  CLOSED --(5 failures)--> OPEN
+     ^                       |
+     |                    (30 sec)
+     |                       v
+  (success)            HALF_OPEN
+     +------(probe)----------+
+```
+
+### Retry + Jitter
+
+FetchVault retries only network failures and HTTP `5xx` responses.
+
+`delay = (2^attempt * 1000ms) + jitter(0..500ms)`
+
+Jitter prevents synchronized retries and reduces thundering herd spikes.
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome. Before opening a PR, run:
+
+```bash
+npm test
+npm run build
+```
+
+## License
+
+MIT

package/dist/circuit.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Available circuit breaker states.
+ *
+ * @example
+ * const state: VaultCircuitState = 'CLOSED'
+ */
+export type VaultCircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+/**
+ * Circuit breaker that protects unstable upstream services.
+ *
+ * @example
+ * const breaker = new VaultCircuitBreaker()
+ * if (breaker.canRequest()) { ... }
+ */
+export declare class VaultCircuitBreaker {
+    private state;
+    private consecutiveFailures;
+    private probeInFlight;
+    private resetTimer;
+    /**
+     * Returns the current circuit state.
+     *
+     * @returns Current state of the breaker.
+     * @example
+     * const state = breaker.getState()
+     */
+    getState(): VaultCircuitState;
+    /**
+     * Determines whether a request is allowed to execute.
+     *
+     * @returns `true` if request may proceed.
+     * @example
+     * if (breaker.canRequest()) {
+     *   // execute request
+     * }
+     */
+    canRequest(): boolean;
+    /**
+     * Records a successful request and restores healthy state.
+     *
+     * @returns Nothing.
+     * @example
+     * breaker.recordSuccess()
+     */
+    recordSuccess(): void;
+    /**
+     * Records a failed request and updates state machine transitions.
+     *
+     * @returns Nothing.
+     * @example
+     * breaker.recordFailure()
+     */
+    recordFailure(): void;
+    private openCircuit;
+    private scheduleHalfOpen;
+    private transitionTo;
+}
+/**
+ * Gets or creates a circuit breaker for a base URL key.
+ *
+ * @param registry Circuit map to read/write.
+ * @param baseUrl Base URL key.
+ * @returns Existing or new `VaultCircuitBreaker`.
+ * @example
+ * const breaker = getCircuitBreaker(circuitMap, 'https://api.example.com')
+ */
+export declare function getCircuitBreaker(registry: Map<string, VaultCircuitBreaker>, baseUrl: string): VaultCircuitBreaker;
+//# sourceMappingURL=circuit.d.ts.map

package/dist/circuit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit.d.ts","sourceRoot":"","sources":["../src/circuit.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAA;AAE/D;;;;;;GAMG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,mBAAmB,CAAI;IAC/B,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,UAAU,CAA6C;IAE/D;;;;;;OAMG;IACH,QAAQ,IAAI,iBAAiB;IAI7B;;;;;;;;OAQG;IACH,UAAU,IAAI,OAAO;IAiBrB;;;;;;OAMG;IACH,aAAa,IAAI,IAAI;IAMrB;;;;;;OAMG;IACH,aAAa,IAAI,IAAI;IAarB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,YAAY;CAOrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC1C,OAAO,EAAE,MAAM,GACd,mBAAmB,CASrB"}

package/dist/circuit.js

@@ -0,0 +1,119 @@
+const MAX_FAILURES = 5;
+const RESET_TIMEOUT_MS = 30000;
+/**
+ * Circuit breaker that protects unstable upstream services.
+ *
+ * @example
+ * const breaker = new VaultCircuitBreaker()
+ * if (breaker.canRequest()) { ... }
+ */
+export class VaultCircuitBreaker {
+    constructor() {
+        this.state = 'CLOSED';
+        this.consecutiveFailures = 0;
+        this.probeInFlight = false;
+        this.resetTimer = null;
+    }
+    /**
+     * Returns the current circuit state.
+     *
+     * @returns Current state of the breaker.
+     * @example
+     * const state = breaker.getState()
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Determines whether a request is allowed to execute.
+     *
+     * @returns `true` if request may proceed.
+     * @example
+     * if (breaker.canRequest()) {
+     *   // execute request
+     * }
+     */
+    canRequest() {
+        if (this.state === 'CLOSED') {
+            return true;
+        }
+        if (this.state === 'OPEN') {
+            return false;
+        }
+        if (this.probeInFlight) {
+            return false;
+        }
+        this.probeInFlight = true;
+        return true;
+    }
+    /**
+     * Records a successful request and restores healthy state.
+     *
+     * @returns Nothing.
+     * @example
+     * breaker.recordSuccess()
+     */
+    recordSuccess() {
+        this.consecutiveFailures = 0;
+        this.probeInFlight = false;
+        this.transitionTo('CLOSED');
+    }
+    /**
+     * Records a failed request and updates state machine transitions.
+     *
+     * @returns Nothing.
+     * @example
+     * breaker.recordFailure()
+     */
+    recordFailure() {
+        if (this.state === 'HALF_OPEN') {
+            this.probeInFlight = false;
+            this.openCircuit();
+            return;
+        }
+        this.consecutiveFailures += 1;
+        if (this.consecutiveFailures >= MAX_FAILURES) {
+            this.openCircuit();
+        }
+    }
+    openCircuit() {
+        this.transitionTo('OPEN');
+        this.probeInFlight = false;
+        this.scheduleHalfOpen();
+    }
+    scheduleHalfOpen() {
+        if (this.resetTimer) {
+            clearTimeout(this.resetTimer);
+        }
+        this.resetTimer = setTimeout(() => {
+            this.transitionTo('HALF_OPEN');
+            this.probeInFlight = false;
+        }, RESET_TIMEOUT_MS);
+    }
+    transitionTo(nextState) {
+        this.state = nextState;
+        if (nextState === 'CLOSED' && this.resetTimer) {
+            clearTimeout(this.resetTimer);
+            this.resetTimer = null;
+        }
+    }
+}
+/**
+ * Gets or creates a circuit breaker for a base URL key.
+ *
+ * @param registry Circuit map to read/write.
+ * @param baseUrl Base URL key.
+ * @returns Existing or new `VaultCircuitBreaker`.
+ * @example
+ * const breaker = getCircuitBreaker(circuitMap, 'https://api.example.com')
+ */
+export function getCircuitBreaker(registry, baseUrl) {
+    const existing = registry.get(baseUrl);
+    if (existing) {
+        return existing;
+    }
+    const created = new VaultCircuitBreaker();
+    registry.set(baseUrl, created);
+    return created;
+}
+//# sourceMappingURL=circuit.js.map

package/dist/circuit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit.js","sourceRoot":"","sources":["../src/circuit.ts"],"names":[],"mappings":"AAAA,MAAM,YAAY,GAAG,CAAC,CAAA;AACtB,MAAM,gBAAgB,GAAG,KAAM,CAAA;AAU/B;;;;;;GAMG;AACH,MAAM,OAAO,mBAAmB;IAAhC;QACU,UAAK,GAAsB,QAAQ,CAAA;QACnC,wBAAmB,GAAG,CAAC,CAAA;QACvB,kBAAa,GAAG,KAAK,CAAA;QACrB,eAAU,GAAyC,IAAI,CAAA;IAgGjE,CAAC;IA9FC;;;;;;OAMG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAA;IACnB,CAAC;IAED;;;;;;;;OAQG;IACH,UAAU;QACR,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAA;QACb,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC1B,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,CAAC,aAAa,GAAG,IAAI,CAAA;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;;OAMG;IACH,aAAa;QACX,IAAI,CAAC,mBAAmB,GAAG,CAAC,CAAA;QAC5B,IAAI,CAAC,aAAa,GAAG,KAAK,CAAA;QAC1B,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAA;IAC7B,CAAC;IAED;;;;;;OAMG;IACH,aAAa;QACX,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAC/B,IAAI,CAAC,aAAa,GAAG,KAAK,CAAA;YAC1B,IAAI,CAAC,WAAW,EAAE,CAAA;YAClB,OAAM;QACR,CAAC;QAED,IAAI,CAAC,mBAAmB,IAAI,CAAC,CAAA;QAC7B,IAAI,IAAI,CAAC,mBAAmB,IAAI,YAAY,EAAE,CAAC;YAC7C,IAAI,CAAC,WAAW,EAAE,CAAA;QACpB,CAAC;IACH,CAAC;IAEO,WAAW;QACjB,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAA;QACzB,IAAI,CAAC,aAAa,GAAG,KAAK,CAAA;QAC1B,IAAI,CAAC,gBAAgB,EAAE,CAAA;IACzB,CAAC;IAEO,gBAAgB;QACtB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QAC/B,CAAC;QAED,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,GAAG,EAAE;YAChC,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,CAAA;YAC9B,IAAI,CAAC,aAAa,GAAG,KAAK,CAAA;QAC5B,CAAC,EAAE,gBAAgB,CAAC,CAAA;IACtB,CAAC;IAEO,YAAY,CAAC,SAA4B;QAC/C,IAAI,CAAC,KAAK,GAAG,SAAS,CAAA;QACtB,IAAI,SAAS,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC9C,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;YAC7B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAA;QACxB,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAA0C,EAC1C,OAAe;IAEf,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IACtC,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,mBAAmB,EAAE,CAAA;IACzC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IAC9B,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,12 @@
+import type { VaultClient, VaultClientConfig } from './types.js';
+/**
+ * Creates a pre-configured FetchVault client instance.
+ *
+ * @param config Client defaults including base URL, headers, timeout, retries, and hooks.
+ * @returns Client with HTTP verb helpers bound to the provided base URL.
+ * @example
+ * const api = createClient({ baseURL: 'https://api.example.com', headers: { Authorization: 'Bearer token' } })
+ */
+export declare function createClient(config: VaultClientConfig): VaultClient;
+export default createClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EAOlB,MAAM,YAAY,CAAA;AAEnB;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAuBnE;AAiDD,eAAe,YAAY,CAAA"}

package/dist/client.js

@@ -0,0 +1,63 @@
+import { createFetchVaultEngine } from './core.js';
+/**
+ * Creates a pre-configured FetchVault client instance.
+ *
+ * @param config Client defaults including base URL, headers, timeout, retries, and hooks.
+ * @returns Client with HTTP verb helpers bound to the provided base URL.
+ * @example
+ * const api = createClient({ baseURL: 'https://api.example.com', headers: { Authorization: 'Bearer token' } })
+ */
+export function createClient(config) {
+    const circuitMap = new Map();
+    const dedupMap = new Map();
+    const engine = createFetchVaultEngine({ circuitMap, dedupMap });
+    const methodFactory = (method) => {
+        return async function clientMethod(path, options) {
+            const mergedOptions = mergeOptions(config, options, method);
+            const target = joinUrl(config.baseURL, path);
+            return engine(target, mergedOptions);
+        };
+    };
+    return {
+        get: methodFactory('GET'),
+        post: methodFactory('POST'),
+        put: methodFactory('PUT'),
+        patch: methodFactory('PATCH'),
+        delete: methodFactory('DELETE')
+    };
+}
+function mergeOptions(config, options, method) {
+    const callOptions = options ?? {};
+    return {
+        ...callOptions,
+        method: callOptions.method ?? method,
+        headers: mergeHeaders(config.headers, callOptions.headers),
+        timeout: callOptions.timeout ?? config.timeout,
+        retries: callOptions.retries ?? config.retries,
+        beforeRequest: mergeHooks(config.beforeRequest, callOptions.beforeRequest),
+        afterResponse: mergeHooks(config.afterResponse, callOptions.afterResponse)
+    };
+}
+function mergeHeaders(instanceHeaders, callHeaders) {
+    return {
+        ...(instanceHeaders ?? {}),
+        ...(callHeaders ?? {})
+    };
+}
+function mergeHooks(instanceHooks, callHooks) {
+    return [...(instanceHooks ?? []), ...(callHooks ?? [])];
+}
+function joinUrl(baseURL, path) {
+    if (!path) {
+        return baseURL;
+    }
+    if (baseURL.endsWith('/') && path.startsWith('/')) {
+        return `${baseURL.slice(0, -1)}${path}`;
+    }
+    if (!baseURL.endsWith('/') && !path.startsWith('/')) {
+        return `${baseURL}/${path}`;
+    }
+    return `${baseURL}${path}`;
+}
+export default createClient;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AAYlD;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,MAAyB;IACpD,MAAM,UAAU,GAAG,IAAI,GAAG,EAA+B,CAAA;IACzD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAyC,CAAA;IACjE,MAAM,MAAM,GAAG,sBAAsB,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAA;IAE/D,MAAM,aAAa,GAAG,CAAC,MAAmD,EAAqB,EAAE;QAC/F,OAAO,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,OAA4B;YAE5B,MAAM,aAAa,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;YAC3D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;YAC5C,OAAO,MAAM,CAAO,MAAM,EAAE,aAAa,CAAC,CAAA;QAC5C,CAAC,CAAA;IACH,CAAC,CAAA;IAED,OAAO;QACL,GAAG,EAAE,aAAa,CAAC,KAAK,CAAC;QACzB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC;QAC3B,GAAG,EAAE,aAAa,CAAC,KAAK,CAAC;QACzB,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC;QAC7B,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC;KAChC,CAAA;AACH,CAAC;AAED,SAAS,YAAY,CACnB,MAAyB,EACzB,OAAuC,EACvC,MAAmD;IAEnD,MAAM,WAAW,GAAG,OAAO,IAAK,EAAyB,CAAA;IACzD,OAAO;QACL,GAAG,WAAW;QACd,MAAM,EAAE,WAAW,CAAC,MAAM,IAAI,MAAM;QACpC,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC;QAC1D,OAAO,EAAE,WAAW,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO;QAC9C,OAAO,EAAE,WAAW,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO;QAC9C,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC;QAC1E,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC;KAC3E,CAAA;AACH,CAAC;AAED,SAAS,YAAY,CACnB,eAAwC,EACxC,WAAoC;IAEpC,OAAO;QACL,GAAG,CAAC,eAAe,IAAI,EAAE,CAAC;QAC1B,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC;KACvB,CAAA;AACH,CAAC;AAED,SAAS,UAAU,CAAI,aAAwB,EAAE,SAAoB;IACnE,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAA;AACzD,CAAC;AAED,SAAS,OAAO,CAAC,OAAe,EAAE,IAAY;IAC5C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,CAAA;IACzC,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACpD,OAAO,GAAG,OAAO,IAAI,IAAI,EAAE,CAAA;IAC7B,CAAC;IAED,OAAO,GAAG,OAAO,GAAG,IAAI,EAAE,CAAA;AAC5B,CAAC;AAED,eAAe,YAAY,CAAA"}

package/dist/core.d.ts

@@ -0,0 +1,29 @@
+import { VaultCircuitBreaker } from './circuit.js';
+import type { InferSchema, VaultOptions, VaultResult, VaultSchema } from './types.js';
+interface EngineContext {
+    circuitMap: Map<string, VaultCircuitBreaker>;
+    dedupMap: Map<string, Promise<VaultResult<unknown>>>;
+}
+type EngineResult<T, S extends VaultSchema<T> = never> = VaultResult<S extends never ? T : InferSchema<S>>;
+type EngineFunction = <T, S extends VaultSchema<T> = never>(url: string, options?: VaultOptions<T, S>) => Promise<EngineResult<T, S>>;
+/**
+ * Creates an isolated FetchVault engine.
+ *
+ * @param context Optional per-engine circuit and dedup stores.
+ * @returns Request function that follows the FetchVault result pattern.
+ * @example
+ * const engine = createFetchVaultEngine({ circuitMap: new Map(), dedupMap: new Map() })
+ */
+export declare function createFetchVaultEngine(context?: Partial<EngineContext>): EngineFunction;
+/**
+ * Executes a resilient fetch call using FetchVault defaults.
+ *
+ * @param url Target URL.
+ * @param options Optional request configuration.
+ * @returns Discriminated result union with data or structured error.
+ * @example
+ * const result = await fetchvault<{ id: string }>('/users/1')
+ */
+export declare function fetchvault<T, S extends VaultSchema<T> = never>(url: string, options?: VaultOptions<T, S>): Promise<VaultResult<S extends never ? T : InferSchema<S>>>;
+export default fetchvault;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAMrE,OAAO,KAAK,EACV,WAAW,EAEX,YAAY,EAEZ,WAAW,EAEX,WAAW,EACZ,MAAM,YAAY,CAAA;AAKnB,UAAU,aAAa;IACrB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAA;IAC5C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;CACrD;AAED,KAAK,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,WAAW,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,WAAW,CAAC,CAAC,SAAS,KAAK,GAAG,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;AAE1G,KAAK,cAAc,GAAG,CAAC,CAAC,EAAE,CAAC,SAAS,WAAW,CAAC,CAAC,CAAC,GAAG,KAAK,EACxD,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,KACzB,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AAchC;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,cAAc,CAsB3F;AAID;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,CAAC,SAAS,WAAW,CAAC,CAAC,CAAC,GAAG,KAAK,EAClE,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,GAC3B,OAAO,CAAC,WAAW,CAAC,CAAC,SAAS,KAAK,GAAG,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAE5D;AAuUD,eAAe,UAAU,CAAA"}