@pureq/pureq 1.0.1 → 1.1.3

package/README.md

@@ -6,7 +6,7 @@ Functional, immutable, type-safe HTTP transport layer for TypeScript.
 
 ---
 
-**pureq** is not another fetch wrapper. It's a **policy-first transport layer** that makes HTTP behavior explicit, composable, and observable — across frontend, BFF, backend, and edge runtimes.
+**pureq** is not another fetch wrapper. It's a **policy-first transport layer** that makes HTTP behavior explicit, composable, and observable across frontend, BFF, backend, and edge runtimes.
 
 ```ts
 import { createClient, retry, circuitBreaker, dedupe } from "pureq";
@@ -19,7 +19,7 @@ const api = createClient({ baseURL: "https://api.example.com" })
 const user = await api.getJson<User>("/users/:id", { params: { id: "42" } });
 ```
 
-Zero runtime dependencies. Works everywhere `fetch` works.
+Zero runtime dependencies in the core package. Works everywhere `fetch` works.
 
 ## Install
 
@@ -27,57 +27,113 @@ Zero runtime dependencies. Works everywhere `fetch` works.
 npm install @pureq/pureq
 ```
 
-## Quick Start
+### Node.js (with FileSystem support)
 
-### The simplest case
+If using Node.js specific adapters (like `FileSystemQueueStorageAdapter`), use the node subpath:
 
 ```ts
-import { createClient } from "pureq";
+import { FileSystemQueueStorageAdapter } from "pureq/node";
+```
 
-const client = createClient();
+> [!NOTE]
+> Core package (`pureq`) is zero-dependency and runtime-agnostic.
+> Node-only adapters (for example `FileSystemQueueStorageAdapter`) live behind `pureq/node` so browser bundles stay clean and small.
 
-const response = await client.get("https://api.example.com/health");
-console.log(response.status); // 200
-```
+## Quick Start
 
-### Typed path parameters
+### A quicker start than raw fetch
 
 ```ts
-// TypeScript ensures you provide { id: string } for :id
-const response = await client.get("/users/:id", {
-  params: { id: "42" },
+import { createClient } from "pureq";
+
+type User = { id: string; name: string };
+
+const client = createClient({ baseURL: "https://api.example.com" });
+
+// GET + status check + JSON parse + typed path params
+const user = await client.getJson<User>("/users/:userId", {
+  params: { userId: "42" },
 });
 
-const user = await response.json<{ id: string; name: string }>();
+console.log(user.name);
 ```
 
-### JSON helpers (one-liner)
+### Type-safe path parameters (Template Literal Types)
 
 ```ts
-// GET + status check + JSON parse in one step
-const user = await client.getJson<User>("/users/:id", {
-  params: { id: "42" },
+// Param keys are derived from the URL template at compile time.
+
+// ✅ Compiles
+await client.get("/users/:userId/posts/:postId", {
+  params: { userId: "1", postId: "42" },
+});
+
+// ❌ TypeScript error: missing postId
+await client.get("/users/:userId/posts/:postId", {
+  params: { userId: "1" },
 });
 ```
 
-### Non-throwing Result API
+### Result API to prevent missed error handling
 
 ```ts
-const result = await client.getResult("/users/:id", {
-  params: { id: "42" },
+const result = await client.getJsonResult<User>("/users/:userId", {
+  params: { userId: "42" },
 });
 
 if (!result.ok) {
-  // result.error.kind: "network" | "timeout" | "aborted" | "http" | "circuit-open" | "unknown"
-  console.error(result.error.kind, result.error.message);
+  // Switching on kind gives explicit, exhaustive transport handling.
+  switch (result.error.kind) {
+    case "network":
+      showOfflineBanner();
+      break;
+    case "timeout":
+      showRetryToast();
+      break;
+    case "http":
+      if (result.error.status === 401) redirectToLogin();
+      break;
+    case "circuit-open":
+      switchToFallbackMode();
+      break;
+    case "aborted":
+    case "storage-error":
+    case "auth-error":
+    case "validation-error":
+    case "unknown":
+      reportTransportError(result.error);
+      break;
+    default: {
+      const exhaustive: never = result.error.kind;
+      throw new Error(`Unhandled error kind: ${exhaustive}`);
+    }
+  }
   return;
 }
 
-const response = result.data; // HttpResponse
+// result.data is strongly typed JSON
+renderUser(result.data);
 ```
 
 Every request method has a `*Result` variant that never throws — transport failures become values you can pattern-match on.
 
+### Systematic Error Codes
+
+For enterprise-grade observability, `PureqError` exposes both `kind` and `code` on the same error object. They represent the same category in two formats:
+
+- `kind`: human-friendly lowercase string (e.g. `"timeout"`)
+- `code`: machine-readable Screaming Snake Case (e.g. `"PUREQ_TIMEOUT"`)
+
+```ts
+if (!result.ok) {
+  if (result.error.kind === "timeout" && result.error.code === "PUREQ_TIMEOUT") {
+    // Handle specifically...
+  }
+}
+```
+
+Common codes: `PUREQ_TIMEOUT`, `PUREQ_NETWORK_ERROR`, `PUREQ_OFFLINE_QUEUE_FULL`, `PUREQ_AUTH_REFRESH_FAILED`, `PUREQ_VALIDATION_ERROR`.
+
 ---
 
 ## Why pureq
@@ -215,16 +271,56 @@ const withAuth = withRetry.useRequestInterceptor((req) => ({
 
 This makes it trivial to share a base client while customizing per-dependency behavior.
 
+### The "Why" of Immutability
+
+Unlike mutable interceptor stacks, pureq clients are branchable snapshots.
+
+```ts
+import { authRefresh, createClient, dedupe, retry } from "pureq";
+
+const base = createClient({ baseURL: "https://api.example.com" })
+  .use(retry({ maxRetries: 2, delay: 200 }));
+
+// Public API: cache-friendly and lightweight
+const publicApi = base.use(dedupe({ methods: ["GET", "HEAD"] }));
+
+// Auth API: isolated auth policy without mutating publicApi
+const authedApi = base
+  .use(authRefresh({ refresh: refreshToken }))
+  .useRequestInterceptor((req) => ({
+    ...req,
+    headers: { ...req.headers, Authorization: `Bearer ${getToken()}` },
+  }));
+```
+
+This pattern is especially useful in BFFs: you keep shared defaults, then safely branch per upstream or trust boundary.
+
 ### Middleware: the Onion Model
 
 Middleware wraps the entire request lifecycle. Each middleware can intercept the request before it happens, await the result, and post-process the response:
 
 ```text
-Request → [dedupe] → [retry] → [circuitBreaker] → fetch() → Response
-                                                       ↑
-                                              the "onion" unwinds
+Request
+  -> [dedupe]
+  -> [retry]
+  -> [circuitBreaker]
+  -> [adapter/fetch]
+  <- [circuitBreaker]
+  <- [retry]
+  <- [dedupe]
+Response
 ```
 
+Think of `retry` and `circuitBreaker` as wrappers around `next()`.
+
+- Outer wrappers see the whole execution envelope.
+- Inner wrappers only see what reaches them.
+
+That is why order changes behavior. Example:
+
+- `retry` outside `circuitBreaker`: each retry attempt passes through breaker logic.
+- `circuitBreaker` outside `retry`: breaker sees one wrapped operation that may include internal retries.
+
 Middleware can:
 
 - Transform the request before `next()`
@@ -300,9 +396,28 @@ const client = createClient({ baseURL: "https://api.example.com" })
   .use(dedupe())                                         // collapse duplicate in-flight GETs
   .use(httpCache({ ttlMs: 10_000, maxEntries: 200 }))    // in-memory cache with LRU eviction
   .use(retry({ maxRetries: 3, delay: 200, backoff: true })) // exponential backoff
-  .use(circuitBreaker({ failureThreshold: 5, cooldownMs: 30_000 }));
+  .use(circuitBreaker({ failureThreshold: 5, cooldownMs: 30_000 }))
+  .use(validation({ validate: (data) => !!data }))       // zero-dependency schema validation
+  .use(fallback({ value: { body: "default", status: 200 } as any })); // graceful degradation
 ```
 
+### Standard Order (recommended)
+
+For most production stacks, this order is a safe default:
+
+```text
+[dedupe] -> [httpCache] -> [retry] -> [circuitBreaker] -> [validation] -> [adapter]
+```
+
+Why this order:
+
+- `dedupe` outermost to collapse duplicate in-flight work early.
+- `httpCache` before retry to short-circuit cache hits.
+- `retry` before `circuitBreaker` so each attempt is still guarded by breaker state.
+- `validation` near the inner edge to validate final payloads before returning to callers.
+
+If order is reversed accidentally, behavior can drift (for example, retrying inside a layer you expected to run once).
+
 ### Retry
 
 Full-featured retry with exponential backoff, Retry-After header respect, and retry budget.
@@ -313,15 +428,19 @@ import { retry } from "pureq";
 client.use(retry({
   maxRetries: 3,
   delay: 200,
+  methods: ["GET", "PUT", "DELETE"], // Safe defaults: idempotent methods only
   backoff: true,
-  maxDelay: 5_000,
-  retryBudgetMs: 2000,            // total time cap across all retries
-  retryOnStatus: [429, 500, 502, 503, 504],
-  respectRetryAfter: true,
   onRetry: ({ attempt, error }) => console.warn(`Retry #${attempt}`, error),
 }));
 ```
 
+**Safety First**: By default, `retry` only targets idempotent methods. To retry `POST` or `PATCH`, you must explicitly add them to `methods` and ensure the backend supports idempotency keys.
+
+```text
+POST /api/orders HTTP/1.1
+Idempotency-Key: abc-123
+```
+
 ### Deadline Propagation
 
 Enforces a total request budget across all retry attempts — different from a per-request timeout.
@@ -407,20 +526,37 @@ Queues mutation requests when offline and replays them when connectivity restore
 ```ts
 import { createOfflineQueue, idempotencyKey } from "pureq";
 
+// 1. Create durable storage (IndexedDB for browser, FS for Node)
+const storage = new IndexedDBQueueStorageAdapter();
+
+// 2. (Optional) Wrap with encryption for enterprise security
+// myCryptoKey can come from crypto.subtle.generateKey(...) or importKey/deriveKey from a password.
+const encryptedStorage = new EncryptedQueueStorageAdapter(storage, myCryptoKey);
+
 const queue = createOfflineQueue({
+  storage: encryptedStorage,
   methods: ["POST", "PUT", "PATCH"],
-  maxQueueSize: 100,
+  ttlMs: 24 * 60 * 60 * 1000, // 24h expiration
+  lockName: "my-app-offline-lock", // Multi-tab coordination
 });
 
 const client = createClient()
-  .use(idempotencyKey())   // strongly recommended with offlineQueue
+  .use(idempotencyKey())
   .use(queue.middleware);
 
 // Later, when back online:
-await queue.flush(
-  (req) => client.post(req.url, req.body),
-  { concurrency: 3 }  // parallel replay
-);
+await queue.flush((req) => client.post(req.url, req.body));
+```
+
+**Durable Adapters**:
+
+- `IndexedDBQueueStorageAdapter`: Standard browser persistence.
+- `FileSystemQueueStorageAdapter`: Node.js persistence (import from `pureq/node`).
+- `EncryptedQueueStorageAdapter`: Wrapper that encrypts data at rest using AES-GCM.
+
+```ts
+// Example: Creating an encrypted storage
+const encrypted = new EncryptedQueueStorageAdapter(new IndexedDBQueueStorageAdapter(), key);
 ```
 
 ### Idempotency Keys
@@ -436,6 +572,64 @@ client.use(idempotencyKey({
 }));
 ```
 
+### Auth Refresh
+
+Automatically handles 401 Unauthorized errors by refreshing the token and retrying the request. Includes built-in "thundering herd" prevention to ensure only one refresh request is in-flight at a time.
+
+```ts
+import { authRefresh } from "pureq";
+
+client.use(authRefresh({
+  refresh: async () => {
+    // Multiple 401s will only trigger ONE refresh call.
+    const res = await fetch("/api/refresh", { method: "POST" });
+    return (await res.json()).token;
+  },
+  // Optional: customize how the request is updated
+  updateRequest: (req, token) => ({
+    ...req,
+    headers: { ...req.headers, Authorization: `Bearer ${token}` }
+  })
+}));
+```
+
+### Validation
+
+A zero-dependency bridge to any schema validation library (Zod, Valibot, etc.) or custom type guards.
+
+```ts
+import { validation } from "pureq";
+import { z } from "zod";
+
+const UserSchema = z.object({ id: z.string(), name: z.string() });
+
+client.use(validation({
+  validate: (data) => UserSchema.parse(data), // Throws PUREQ_VALIDATION_ERROR on failure
+  message: "Invalid API response schema"
+}));
+```
+
+### Fallback
+
+Enables "Graceful Degradation" by returning a default value or cached data when a request fails.
+
+```ts
+import { fallback, HttpResponse, type PureqError } from "pureq";
+
+const isPureqError = (value: unknown): value is PureqError => {
+  return typeof value === "object" && value !== null && "code" in value && "kind" in value;
+};
+
+client.use(fallback({
+  value: new HttpResponse(new Response(JSON.stringify({ items: [] }), { status: 200 })),
+  when: (trigger) =>
+    trigger.type === "error" &&
+    isPureqError(trigger.error) &&
+    trigger.error.code === "PUREQ_TIMEOUT" &&
+    trigger.error.kind === "timeout"
+}));
+```
+
 ### Policy Guardrails
 
 pureq validates your middleware stack at client creation time and rejects invalid combinations:
@@ -479,7 +673,7 @@ for (const mw of backendPreset()) backend = backend.use(mw);
 | `frontendPreset()` | 5s | 1 | GET/HEAD | 4 failures / 10s cooldown | ✅ |
 | `bffPreset()` | 3s | 2 | GET/HEAD | 5 failures / 20s cooldown | ✅ body-only |
 | `backendPreset()` | 2.5s | 3 | off | 6 failures / 30s cooldown | ✅ body-only |
-| `resilientPreset()` | — | 2 | All | 5 failures / 30s cooldown | ✅ |
+| `resilientPreset()` | none (pair with `defaultTimeout()` if needed) | 2 | GET/HEAD | 5 failures / 30s cooldown | ✅ |
 
 All presets are built from the same public middleware. You can inspect and override any parameter.
 
@@ -523,6 +717,24 @@ const snap = diagnostics.snapshot();
 console.log(snap.p50, snap.p95, snap.total, snap.success, snap.failed);
 ```
 
+### Policy Tracing (Debuggability)
+
+Ever wonder *why* a request was retried or why the circuit opened? `pureq` records a detailed decision trace for every request.
+
+```ts
+import { explainPolicyTrace } from "pureq";
+
+try {
+  await client.get("/flakey-endpoint");
+} catch (err) {
+  // Prints exactly what happened:
+  // [2026-04-10T10:00:00Z] RETRY: RETRY (status=503)
+  // [2026-04-10T10:00:01Z] RETRY: RETRY (status=503)
+  // [2026-04-10T10:00:02Z] CIRCUIT-BREAKER: TRIP (reason="failure threshold exceeded")
+  console.log(explainPolicyTrace(err.request));
+}
+```
+
 ### OpenTelemetry integration
 
 Map transport events to OTel-compatible attributes:
@@ -789,6 +1001,20 @@ More details: [Runtime compatibility matrix](./docs/runtime_compatibility_matrix
 
 ---
 
+## Production Readiness Checklist
+
+If you are adopting pureq in a production service, start with these defaults:
+
+- Set a request time budget (`defaultTimeout()` or `deadline()`) first.
+- Add `retry()` with explicit status/method policy.
+- Add `validation()` for critical response payloads.
+- Add `circuitBreaker()` for unstable upstreams.
+- Enable diagnostics hooks (`onRequestStart/onRequestSuccess/onRequestError`).
+- Prefer `*Result` APIs on boundary layers to avoid unhandled transport errors.
+- Use `idempotencyKey()` before retrying write operations.
+
+---
+
 ## API Reference
 
 ### Client
@@ -828,12 +1054,15 @@ More details: [Runtime compatibility matrix](./docs/runtime_compatibility_matrix
 | Middleware | Purpose |
 | --------- | ------- |
 | `retry(options)` | Exponential backoff, Retry-After, budget |
+| `authRefresh(options)` | Automatic token refresh (thundering herd prevention) |
 | `deadline(options)` | Total request budget across retries |
 | `defaultTimeout(ms)` | Default per-request timeout |
 | `circuitBreaker(options)` | Fail-fast on repeated failures |
 | `concurrencyLimit(options)` | Cap in-flight requests |
 | `dedupe(options?)` | Collapse duplicate concurrent requests |
 | `hedge(options)` | Duplicate request for tail latency |
+| `validation(options)` | Schema validation bridge (Zod/Valibot ready) |
+| `fallback(options)` | Graceful degradation with fallback values |
 | `httpCache(options)` | In-memory cache with ETag/stale-if-error |
 | `createOfflineQueue(options?)` | Offline mutation queue with replay |
 | `idempotencyKey(options?)` | Auto-inject idempotency headers |

package/dist/src/adapters/storage/encryptedStorage.d.ts

@@ -0,0 +1,16 @@
+import type { OfflineQueueStorageAdapter, QueuedRequest } from "../../middleware/offlineQueue";
+/**
+ * A wrapper for OfflineQueueStorageAdapter that encrypts request data at rest.
+ * Crucial for enterprise compliance when storing PII or auth tokens in local storage.
+ */
+export declare class EncryptedQueueStorageAdapter implements OfflineQueueStorageAdapter {
+    private readonly inner;
+    private readonly key;
+    constructor(inner: OfflineQueueStorageAdapter, key: CryptoKey);
+    push(item: QueuedRequest): Promise<void>;
+    getAll(): Promise<readonly QueuedRequest[]>;
+    remove(id: number): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+}
+//# sourceMappingURL=encryptedStorage.d.ts.map

package/dist/src/adapters/storage/encryptedStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryptedStorage.d.ts","sourceRoot":"","sources":["../../../../src/adapters/storage/encryptedStorage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAiB/F;;;GAGG;AACH,qBAAa,4BAA6B,YAAW,0BAA0B;IAE3E,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,KAAK,EAAE,0BAA0B,EACjC,GAAG,EAAE,SAAS;IAG3B,IAAI,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IASxC,MAAM,IAAI,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC;IA0D3C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAG9B"}

package/dist/src/adapters/storage/encryptedStorage.js

@@ -0,0 +1,77 @@
+import { encrypt, decrypt } from "../../utils/crypto";
+let decryptionErrorCounter = 0;
+function createDecryptionErrorId() {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+        return crypto.randomUUID();
+    }
+    decryptionErrorCounter += 1;
+    return `decrypt-${Date.now()}-${decryptionErrorCounter}`;
+}
+/**
+ * A wrapper for OfflineQueueStorageAdapter that encrypts request data at rest.
+ * Crucial for enterprise compliance when storing PII or auth tokens in local storage.
+ */
+export class EncryptedQueueStorageAdapter {
+    constructor(inner, key) {
+        this.inner = inner;
+        this.key = key;
+    }
+    async push(item) {
+        const encryptedReq = await encrypt(JSON.stringify(item.req), this.key);
+        await this.inner.push({
+            ...item,
+            req: encryptedReq,
+        });
+    }
+    async getAll() {
+        const rawItems = await this.inner.getAll();
+        const results = [];
+        const failures = [];
+        for (let index = 0; index < rawItems.length; index++) {
+            const item = rawItems[index];
+            try {
+                if (typeof item.req !== "string") {
+                    throw new Error("encrypted req payload is not a string");
+                }
+                const decryptedReqJson = await decrypt(item.req, this.key);
+                const decryptedReq = JSON.parse(decryptedReqJson);
+                const encryptedItem = item;
+                results.push({
+                    id: encryptedItem.id,
+                    queuedAt: encryptedItem.queuedAt,
+                    ...(encryptedItem.expiresAt !== undefined ? { expiresAt: encryptedItem.expiresAt } : {}),
+                    req: decryptedReq,
+                });
+            }
+            catch (error) {
+                const errorId = createDecryptionErrorId();
+                const safeName = error instanceof Error ? error.name : "UnknownError";
+                console.warn(`pureq: failed to decrypt queued request - errorId=${errorId} code=DECRYPTION_FAILURE name=${safeName}`);
+                failures.push({
+                    index,
+                    id: item.id,
+                    errorId,
+                    code: "DECRYPTION_FAILURE",
+                    name: safeName,
+                });
+            }
+        }
+        if (failures.length > 0) {
+            const aggregate = new AggregateError(failures, `pureq: failed to decrypt ${failures.length} queued request(s)`);
+            aggregate.details = failures;
+            aggregate.code = "PUREQ_DECRYPTION_FAILURE";
+            throw aggregate;
+        }
+        return results;
+    }
+    async remove(id) {
+        await this.inner.remove(id);
+    }
+    async clear() {
+        await this.inner.clear();
+    }
+    async size() {
+        return this.inner.size();
+    }
+}
+//# sourceMappingURL=encryptedStorage.js.map

package/dist/src/adapters/storage/encryptedStorage.js.map

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

package/dist/src/adapters/storage/indexedDBAdapter.d.ts

@@ -0,0 +1,16 @@
+import type { OfflineQueueStorageAdapter, QueuedRequest } from "../../middleware/offlineQueue";
+/**
+ * Standard IndexedDB-based storage for the offline queue.
+ * Survives page refreshes and browser restarts.
+ */
+export declare class IndexedDBQueueStorageAdapter implements OfflineQueueStorageAdapter {
+    private dbPromise;
+    private readonly storeName;
+    constructor(dbName?: string);
+    push(item: QueuedRequest): Promise<void>;
+    getAll(): Promise<readonly QueuedRequest[]>;
+    remove(id: number): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+}
+//# sourceMappingURL=indexedDBAdapter.d.ts.map

package/dist/src/adapters/storage/indexedDBAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexedDBAdapter.d.ts","sourceRoot":"","sources":["../../../../src/adapters/storage/indexedDBAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE/F;;;GAGG;AACH,qBAAa,4BAA6B,YAAW,0BAA0B;IAC7E,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;gBAE5B,MAAM,SAAwB;IAmBpC,IAAI,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxC,MAAM,IAAI,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC;IAW3C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAWtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAU9B"}

package/dist/src/adapters/storage/indexedDBAdapter.js

@@ -0,0 +1,75 @@
+/**
+ * Standard IndexedDB-based storage for the offline queue.
+ * Survives page refreshes and browser restarts.
+ */
+export class IndexedDBQueueStorageAdapter {
+    constructor(dbName = "pureq-offline-queue") {
+        this.storeName = "requests";
+        this.dbPromise = new Promise((resolve, reject) => {
+            if (typeof indexedDB === "undefined") {
+                reject(new Error("pureq: IndexedDB is not available in this environment"));
+                return;
+            }
+            const request = indexedDB.open(dbName, 1);
+            request.onupgradeneeded = () => {
+                const db = request.result;
+                if (!db.objectStoreNames.contains(this.storeName)) {
+                    db.createObjectStore(this.storeName, { keyPath: "id" });
+                }
+            };
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async push(item) {
+        const db = await this.dbPromise;
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction(this.storeName, "readwrite");
+            const store = transaction.objectStore(this.storeName);
+            const request = store.put(item);
+            request.onsuccess = () => resolve();
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async getAll() {
+        const db = await this.dbPromise;
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction(this.storeName, "readonly");
+            const store = transaction.objectStore(this.storeName);
+            const request = store.getAll();
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async remove(id) {
+        const db = await this.dbPromise;
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction(this.storeName, "readwrite");
+            const store = transaction.objectStore(this.storeName);
+            const request = store.delete(id);
+            request.onsuccess = () => resolve();
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async clear() {
+        const db = await this.dbPromise;
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction(this.storeName, "readwrite");
+            const store = transaction.objectStore(this.storeName);
+            const request = store.clear();
+            request.onsuccess = () => resolve();
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async size() {
+        const db = await this.dbPromise;
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction(this.storeName, "readonly");
+            const store = transaction.objectStore(this.storeName);
+            const request = store.count();
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+    }
+}
+//# sourceMappingURL=indexedDBAdapter.js.map

package/dist/src/adapters/storage/indexedDBAdapter.js.map

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