request-ledger 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1059 @@
+'use strict';
+
+/**
+ * Request Ledger - Type Definitions
+ *
+ * This file contains all public TypeScript interfaces and types
+ * for the request-ledger library.
+ */
+// =============================================================================
+// Error Types
+// =============================================================================
+/**
+ * Base error class for request-ledger errors.
+ */
+class LedgerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LedgerError';
+    }
+}
+/**
+ * Error thrown when persistence fails.
+ */
+class PersistenceError extends LedgerError {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'PersistenceError';
+    }
+}
+/**
+ * Error thrown when a network request fails.
+ */
+class NetworkError extends LedgerError {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'NetworkError';
+    }
+}
+/**
+ * Error thrown when an entry is not found.
+ */
+class EntryNotFoundError extends LedgerError {
+    constructor(entryId) {
+        super(`Entry not found: ${entryId}`);
+        this.entryId = entryId;
+        this.name = 'EntryNotFoundError';
+    }
+}
+/**
+ * Error thrown when a duplicate entry is detected.
+ */
+class DuplicateEntryError extends LedgerError {
+    constructor(entryId) {
+        super(`Duplicate entry: ${entryId}`);
+        this.entryId = entryId;
+        this.name = 'DuplicateEntryError';
+    }
+}
+
+/**
+ * IndexedDB Storage Adapter
+ *
+ * Implements the LedgerStorage interface using IndexedDB for
+ * persistent, reliable storage that survives page reloads.
+ */
+const DEFAULT_DB_NAME = 'request-ledger';
+const DEFAULT_STORE_NAME = 'entries';
+const DEFAULT_MAX_ENTRIES = 1000;
+const DB_VERSION = 1;
+/**
+ * IndexedDB implementation of LedgerStorage.
+ *
+ * Features:
+ * - Atomic writes using transactions
+ * - Entries ordered by createdAt
+ * - Max size enforcement with oldest-first eviction
+ * - Proper error handling
+ */
+class IndexedDBStorage {
+    constructor(config = {}) {
+        this.db = null;
+        this.dbPromise = null;
+        this.dbName = config.dbName ?? DEFAULT_DB_NAME;
+        this.storeName = config.storeName ?? DEFAULT_STORE_NAME;
+        this.maxEntries = config.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    }
+    /**
+     * Get or initialize the database connection.
+     */
+    async getDb() {
+        if (this.db) {
+            return this.db;
+        }
+        if (this.dbPromise) {
+            return this.dbPromise;
+        }
+        this.dbPromise = new Promise((resolve, reject) => {
+            const request = indexedDB.open(this.dbName, DB_VERSION);
+            request.onerror = () => {
+                reject(new PersistenceError('Failed to open IndexedDB', request.error ?? undefined));
+            };
+            request.onsuccess = () => {
+                this.db = request.result;
+                resolve(request.result);
+            };
+            request.onupgradeneeded = (event) => {
+                const db = event.target.result;
+                // Create object store if it doesn't exist
+                if (!db.objectStoreNames.contains(this.storeName)) {
+                    const store = db.createObjectStore(this.storeName, { keyPath: 'id' });
+                    // Create indexes for efficient querying
+                    store.createIndex('status', 'status', { unique: false });
+                    store.createIndex('createdAt', 'createdAt', { unique: false });
+                    store.createIndex('idempotencyKey', 'idempotencyKey', { unique: false });
+                }
+            };
+        });
+        return this.dbPromise;
+    }
+    /**
+     * Execute a transaction and return a promise.
+     */
+    async transaction(mode, operation) {
+        const db = await this.getDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(this.storeName, mode);
+            const store = tx.objectStore(this.storeName);
+            const request = operation(store);
+            request.onsuccess = () => {
+                resolve(request.result);
+            };
+            request.onerror = () => {
+                reject(new PersistenceError('Transaction failed', request.error ?? undefined));
+            };
+            tx.onerror = () => {
+                reject(new PersistenceError('Transaction failed', tx.error ?? undefined));
+            };
+        });
+    }
+    /**
+     * Store a new entry.
+     * Throws DuplicateEntryError if entry with same ID exists.
+     * Evicts oldest entries if maxEntries is exceeded.
+     */
+    async put(entry) {
+        const db = await this.getDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(this.storeName, 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            // First check if entry already exists
+            const getRequest = store.get(entry.id);
+            getRequest.onsuccess = () => {
+                if (getRequest.result) {
+                    reject(new DuplicateEntryError(entry.id));
+                    return;
+                }
+                // Serialize body and metadata for storage
+                const storedEntry = {
+                    ...entry,
+                    request: {
+                        ...entry.request,
+                        body: JSON.stringify(entry.request.body),
+                    },
+                    metadata: entry.metadata ? JSON.stringify(entry.metadata) : undefined,
+                };
+                const addRequest = store.add(storedEntry);
+                addRequest.onsuccess = () => {
+                    // Check if we need to evict old entries
+                    this.evictIfNeeded(store).then(resolve).catch(reject);
+                };
+                addRequest.onerror = () => {
+                    reject(new PersistenceError('Failed to add entry', addRequest.error ?? undefined));
+                };
+            };
+            getRequest.onerror = () => {
+                reject(new PersistenceError('Failed to check for existing entry', getRequest.error ?? undefined));
+            };
+            tx.onerror = () => {
+                reject(new PersistenceError('Transaction failed', tx.error ?? undefined));
+            };
+        });
+    }
+    /**
+     * Evict oldest entries if count exceeds maxEntries.
+     */
+    async evictIfNeeded(store) {
+        return new Promise((resolve, reject) => {
+            const countRequest = store.count();
+            countRequest.onsuccess = () => {
+                const count = countRequest.result;
+                if (count <= this.maxEntries) {
+                    resolve();
+                    return;
+                }
+                const toDelete = count - this.maxEntries;
+                const index = store.index('createdAt');
+                const cursorRequest = index.openCursor();
+                let deleted = 0;
+                cursorRequest.onsuccess = () => {
+                    const cursor = cursorRequest.result;
+                    if (cursor && deleted < toDelete) {
+                        store.delete(cursor.primaryKey);
+                        deleted++;
+                        cursor.continue();
+                    }
+                    else {
+                        resolve();
+                    }
+                };
+                cursorRequest.onerror = () => {
+                    reject(new PersistenceError('Failed to evict entries', cursorRequest.error ?? undefined));
+                };
+            };
+            countRequest.onerror = () => {
+                reject(new PersistenceError('Failed to count entries', countRequest.error ?? undefined));
+            };
+        });
+    }
+    /**
+     * Get all entries ordered by createdAt ascending.
+     */
+    async getAll() {
+        const db = await this.getDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(this.storeName, 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const index = store.index('createdAt');
+            const request = index.getAll();
+            request.onsuccess = () => {
+                const entries = request.result.map(this.deserializeEntry);
+                resolve(entries);
+            };
+            request.onerror = () => {
+                reject(new PersistenceError('Failed to get entries', request.error ?? undefined));
+            };
+        });
+    }
+    /**
+     * Get a single entry by ID.
+     */
+    async get(id) {
+        const result = await this.transaction('readonly', (store) => store.get(id));
+        return result ? this.deserializeEntry(result) : undefined;
+    }
+    /**
+     * Update an existing entry.
+     */
+    async update(id, patch) {
+        const db = await this.getDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(this.storeName, 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            const getRequest = store.get(id);
+            getRequest.onsuccess = () => {
+                const existing = getRequest.result;
+                if (!existing) {
+                    reject(new EntryNotFoundError(id));
+                    return;
+                }
+                // Merge patch with existing entry
+                const updated = { ...existing };
+                if (patch.status !== undefined)
+                    updated.status = patch.status;
+                if (patch.attemptCount !== undefined)
+                    updated.attemptCount = patch.attemptCount;
+                if (patch.lastAttemptAt !== undefined)
+                    updated.lastAttemptAt = patch.lastAttemptAt;
+                // Allow explicitly clearing error by checking if key exists in patch
+                if ('error' in patch) {
+                    if (patch.error === undefined) {
+                        delete updated.error;
+                    }
+                    else {
+                        updated.error = patch.error;
+                    }
+                }
+                const putRequest = store.put(updated);
+                putRequest.onsuccess = () => resolve();
+                putRequest.onerror = () => {
+                    reject(new PersistenceError('Failed to update entry', putRequest.error ?? undefined));
+                };
+            };
+            getRequest.onerror = () => {
+                reject(new PersistenceError('Failed to get entry for update', getRequest.error ?? undefined));
+            };
+            tx.onerror = () => {
+                reject(new PersistenceError('Transaction failed', tx.error ?? undefined));
+            };
+        });
+    }
+    /**
+     * Remove an entry by ID.
+     */
+    async remove(id) {
+        await this.transaction('readwrite', (store) => store.delete(id));
+    }
+    /**
+     * Remove all entries.
+     */
+    async clear() {
+        await this.transaction('readwrite', (store) => store.clear());
+    }
+    /**
+     * Get the count of entries.
+     */
+    async count() {
+        return this.transaction('readonly', (store) => store.count());
+    }
+    /**
+     * Deserialize an entry from storage.
+     */
+    deserializeEntry(stored) {
+        const request = stored['request'];
+        return {
+            id: stored['id'],
+            request: {
+                url: request['url'],
+                method: request['method'],
+                headers: request['headers'],
+                body: request['body'] ? JSON.parse(request['body']) : undefined,
+            },
+            status: stored['status'],
+            attemptCount: stored['attemptCount'],
+            createdAt: stored['createdAt'],
+            lastAttemptAt: stored['lastAttemptAt'],
+            error: stored['error'],
+            idempotencyKey: stored['idempotencyKey'],
+            metadata: stored['metadata']
+                ? JSON.parse(stored['metadata'])
+                : undefined,
+        };
+    }
+    /**
+     * Close the database connection.
+     */
+    close() {
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+            this.dbPromise = null;
+        }
+    }
+}
+
+/**
+ * Online Detection Module
+ *
+ * Provides reliable online detection that doesn't rely solely on navigator.onLine.
+ * Supports custom ping endpoints and user-provided check functions.
+ */
+const DEFAULT_PING_TIMEOUT = 5000;
+/**
+ * Creates an online checker function based on the provided configuration.
+ *
+ * The checker combines multiple signals:
+ * 1. navigator.onLine (fast but unreliable)
+ * 2. Optional ping endpoint (reliable but slower)
+ * 3. Custom check function (user-defined)
+ *
+ * @param config Online check configuration
+ * @returns Function that returns true if online, false if offline
+ */
+function createOnlineChecker(config = {}) {
+    const { pingUrl, pingTimeout = DEFAULT_PING_TIMEOUT, customCheck } = config;
+    // If user provided a custom check, use it
+    if (customCheck) {
+        return customCheck;
+    }
+    // If no ping URL, use navigator.onLine only
+    if (!pingUrl) {
+        return async () => {
+            return typeof navigator !== 'undefined' ? navigator.onLine : true;
+        };
+    }
+    // Combine navigator.onLine with ping check
+    return async () => {
+        // Fast path: if navigator says offline, trust it
+        if (typeof navigator !== 'undefined' && !navigator.onLine) {
+            return false;
+        }
+        // Ping the endpoint to confirm connectivity
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), pingTimeout);
+            const response = await fetch(pingUrl, {
+                method: 'HEAD',
+                mode: 'no-cors', // Allow cross-origin pings
+                cache: 'no-store',
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            // In no-cors mode, we can't read the response, but if we get here
+            // without an error, the request succeeded
+            return response.type === 'opaque' || response.ok;
+        }
+        catch (error) {
+            // Any error (network, DNS, timeout, abort) means offline
+            return false;
+        }
+    };
+}
+/**
+ * Check if an error indicates a network failure (vs application error).
+ *
+ * This is used to determine if a request should be queued vs reported as failed.
+ */
+function isNetworkError(error) {
+    if (error instanceof TypeError) {
+        // Fetch throws TypeError for network errors with specific messages
+        const message = error.message.toLowerCase();
+        // Check for specific network error patterns from browsers
+        return (message === 'failed to fetch' || // Chrome, Edge
+            message === 'network request failed' || // Safari
+            message === 'load failed' || // Safari
+            message === 'networkerror' || // Firefox
+            message.startsWith('networkerror when') // Firefox detailed
+        );
+    }
+    if (error instanceof DOMException) {
+        // AbortError from timeout or manual abort
+        return error.name === 'AbortError';
+    }
+    return false;
+}
+/**
+ * Check if an HTTP status code indicates a retryable server error.
+ *
+ * Returns true for 5xx errors (server errors).
+ * Returns false for 4xx errors (client errors - these should not be retried).
+ */
+function isRetryableStatusCode(status) {
+    return status >= 500 && status < 600;
+}
+/**
+ * Check if an HTTP status code indicates a client error (non-retryable).
+ */
+function isClientError(status) {
+    return status >= 400 && status < 500;
+}
+
+/**
+ * Backoff Utilities
+ *
+ * Provides delay calculation for retry strategies.
+ */
+/**
+ * Calculate the delay before the next retry attempt.
+ *
+ * @param strategy The retry strategy configuration
+ * @param attemptCount The number of attempts made so far (1-indexed)
+ * @returns Delay in milliseconds, or null if max attempts reached
+ */
+function calculateBackoffDelay(strategy, attemptCount) {
+    switch (strategy.type) {
+        case 'fixed': {
+            if (attemptCount >= strategy.maxAttempts) {
+                return null;
+            }
+            return strategy.delayMs;
+        }
+        case 'exponential': {
+            if (attemptCount >= strategy.maxAttempts) {
+                return null;
+            }
+            // Exponential backoff: baseMs * 2^(attempt-1)
+            const delay = strategy.baseMs * Math.pow(2, attemptCount - 1);
+            return Math.min(delay, strategy.maxMs);
+        }
+        case 'manual': {
+            // Manual strategy never auto-retries
+            return null;
+        }
+    }
+}
+/**
+ * Check if more retry attempts are allowed.
+ *
+ * @param strategy The retry strategy configuration
+ * @param attemptCount The number of attempts made so far
+ * @returns true if more attempts are allowed
+ */
+function canRetry(strategy, attemptCount) {
+    if (strategy.type === 'manual') {
+        // Manual strategy allows retries but user must trigger them
+        return true;
+    }
+    return attemptCount < strategy.maxAttempts;
+}
+/**
+ * Create a promise that resolves after the specified delay.
+ */
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Default retry strategy.
+ */
+const DEFAULT_RETRY_STRATEGY = {
+    type: 'exponential',
+    baseMs: 1000,
+    maxMs: 30000,
+    maxAttempts: 3,
+};
+
+/**
+ * Replay Engine
+ *
+ * Handles the ordered processing of queued requests.
+ * Ensures crash-safety and deterministic processing.
+ */
+/**
+ * The replay engine processes queued requests in order.
+ *
+ * Key behaviors:
+ * - Processes entries in insertion order (by createdAt)
+ * - Single processing loop at a time (no parallel process() calls)
+ * - Crash-safe: marks stale 'processing' entries as 'pending' on start
+ * - Respects concurrency limit
+ * - Stops on first error if stopOnError is true
+ */
+class ReplayEngine {
+    constructor(config) {
+        this.isProcessing = false;
+        this.isPaused = false;
+        this.lastError = null;
+        this.abortController = null;
+        this.storage = config.storage;
+        this.onlineCheck = config.onlineCheck;
+        this.retry = config.retry;
+        this.hooks = config.hooks;
+        this.idempotencyHeader = config.idempotencyHeader;
+    }
+    /**
+     * Get the current state of the replay engine.
+     */
+    async getState() {
+        if (this.isPaused) {
+            return 'paused';
+        }
+        if (this.isProcessing) {
+            return 'processing';
+        }
+        if (this.lastError) {
+            return 'error';
+        }
+        const entries = await this.storage.getAll();
+        const hasPending = entries.some(e => e.status === 'pending' || e.status === 'processing');
+        return hasPending ? 'pending' : 'idle';
+    }
+    /**
+     * Process pending entries in the queue.
+     *
+     * @param options Processing options
+     */
+    async process(options = {}) {
+        const { concurrency = 1, stopOnError = true, onSuccess, onFailure, } = options;
+        // Prevent multiple concurrent process() calls
+        if (this.isProcessing) {
+            return;
+        }
+        this.isProcessing = true;
+        this.lastError = null;
+        this.abortController = new AbortController();
+        try {
+            // Crash recovery: mark any 'processing' entries as 'pending'
+            await this.recoverStaleEntries();
+            // Process loop
+            while (!this.isPaused && !this.abortController.signal.aborted) {
+                // Check if we're online
+                const online = await this.onlineCheck();
+                if (!online) {
+                    // Wait a bit and check again
+                    await delay(1000);
+                    continue;
+                }
+                // Get pending entries
+                const entries = await this.storage.getAll();
+                const pending = entries.filter(e => e.status === 'pending');
+                if (pending.length === 0) {
+                    break;
+                }
+                // Process up to 'concurrency' entries in parallel
+                const batch = pending.slice(0, concurrency);
+                const results = await Promise.allSettled(batch.map(entry => this.processEntry(entry)));
+                // Handle results
+                let hasError = false;
+                for (let i = 0; i < results.length; i++) {
+                    const result = results[i];
+                    const entry = batch[i];
+                    if (!entry || !result)
+                        continue;
+                    if (result.status === 'fulfilled') {
+                        // Entry processed successfully
+                        await this.storage.remove(entry.id);
+                        onSuccess?.(entry);
+                    }
+                    else {
+                        // Entry failed
+                        hasError = true;
+                        const error = result.reason instanceof Error
+                            ? result.reason
+                            : new Error(String(result.reason));
+                        // Get updated entry from storage (it may have been updated)
+                        const updatedEntry = await this.storage.get(entry.id);
+                        if (updatedEntry) {
+                            onFailure?.(updatedEntry, error);
+                        }
+                        if (stopOnError) {
+                            this.lastError = error;
+                            break;
+                        }
+                    }
+                }
+                // Stop if we encountered an error and stopOnError is true
+                if (hasError && stopOnError) {
+                    break;
+                }
+            }
+        }
+        finally {
+            this.isProcessing = false;
+            this.abortController = null;
+        }
+    }
+    /**
+     * Process a single entry.
+     *
+     * @param entry The entry to process
+     * @throws Error if processing fails
+     */
+    async processEntry(entry) {
+        // Mark as processing
+        await this.storage.update(entry.id, {
+            status: 'processing',
+            lastAttemptAt: Date.now(),
+            attemptCount: entry.attemptCount + 1,
+        });
+        // Fire replay start hook
+        this.hooks.onReplayStart?.(entry);
+        try {
+            // Build the request
+            const headers = new Headers(entry.request.headers);
+            // Add idempotency key if present
+            if (entry.idempotencyKey) {
+                headers.set(this.idempotencyHeader, entry.idempotencyKey);
+            }
+            // Determine body
+            let body;
+            if (entry.request.body !== undefined && entry.request.body !== null) {
+                body = JSON.stringify(entry.request.body);
+                if (!headers.has('Content-Type')) {
+                    headers.set('Content-Type', 'application/json');
+                }
+            }
+            // Make the request
+            const response = await fetch(entry.request.url, {
+                method: entry.request.method,
+                headers,
+                body,
+                signal: this.abortController?.signal,
+            });
+            // Check for client errors (4xx) - not retryable
+            if (isClientError(response.status)) {
+                const error = new Error(`HTTP ${response.status}: Client error`);
+                await this.markAsFailed(entry, error, response.status.toString());
+                this.hooks.onReplayFailure?.(entry, error);
+                throw error;
+            }
+            // Check for server errors (5xx) - retryable
+            if (isRetryableStatusCode(response.status)) {
+                const canRetryMore = this.canRetryEntry(entry);
+                if (canRetryMore) {
+                    // Mark back as pending for retry
+                    await this.storage.update(entry.id, { status: 'pending' });
+                    // Wait for backoff delay
+                    const backoffDelay = calculateBackoffDelay(this.retry, entry.attemptCount + 1);
+                    if (backoffDelay !== null) {
+                        await delay(backoffDelay);
+                    }
+                    throw new Error(`HTTP ${response.status}: Server error, will retry`);
+                }
+                else {
+                    // No more retries, mark as failed
+                    const error = new Error(`HTTP ${response.status}: Server error, max retries exceeded`);
+                    await this.markAsFailed(entry, error, response.status.toString());
+                    this.hooks.onReplayFailure?.(entry, error);
+                    throw error;
+                }
+            }
+            // Success! Fire success hook
+            this.hooks.onReplaySuccess?.(entry, response);
+        }
+        catch (error) {
+            // Check if it's a network error
+            if (isNetworkError(error)) {
+                const canRetryMore = this.canRetryEntry(entry);
+                if (canRetryMore) {
+                    // Mark back as pending for retry
+                    await this.storage.update(entry.id, { status: 'pending' });
+                    // Wait for backoff delay
+                    const backoffDelay = calculateBackoffDelay(this.retry, entry.attemptCount + 1);
+                    if (backoffDelay !== null) {
+                        await delay(backoffDelay);
+                    }
+                }
+                else {
+                    // No more retries, mark as failed
+                    const networkError = new NetworkError('Network error, max retries exceeded', error instanceof Error ? error : undefined);
+                    await this.markAsFailed(entry, networkError, 'NETWORK_ERROR');
+                    this.hooks.onReplayFailure?.(entry, networkError);
+                }
+                throw error;
+            }
+            // Re-throw other errors (they were already handled above)
+            throw error;
+        }
+    }
+    /**
+     * Check if entry can be retried based on retry strategy.
+     */
+    canRetryEntry(entry) {
+        if (this.retry.type === 'manual') {
+            return false; // Manual retries don't auto-retry
+        }
+        return entry.attemptCount + 1 < this.retry.maxAttempts;
+    }
+    /**
+     * Mark an entry as failed.
+     */
+    async markAsFailed(entry, error, code) {
+        await this.storage.update(entry.id, {
+            status: 'failed',
+            error: {
+                message: error.message,
+                code,
+            },
+        });
+    }
+    /**
+     * Recover stale 'processing' entries.
+     *
+     * This handles crash recovery: if the page was closed while
+     * processing, entries would be stuck in 'processing' state.
+     */
+    async recoverStaleEntries() {
+        const entries = await this.storage.getAll();
+        for (const entry of entries) {
+            if (entry.status === 'processing') {
+                await this.storage.update(entry.id, { status: 'pending' });
+            }
+        }
+    }
+    /**
+     * Pause processing.
+     */
+    pause() {
+        this.isPaused = true;
+        this.abortController?.abort();
+    }
+    /**
+     * Resume processing.
+     */
+    resume() {
+        this.isPaused = false;
+    }
+    /**
+     * Check if processing is paused.
+     */
+    get paused() {
+        return this.isPaused;
+    }
+    /**
+     * Check if currently processing.
+     */
+    get processing() {
+        return this.isProcessing;
+    }
+}
+
+/**
+ * Request Ledger
+ *
+ * A durable, client-side HTTP request ledger for web applications
+ * operating on unreliable networks.
+ *
+ * Core behaviors:
+ * - Records API request intent when offline or network is unstable
+ * - Persists requests across page reloads, crashes, and browser restarts
+ * - Replays requests deterministically when connectivity is restored
+ * - Never silently drops requests
+ * - Never assumes business-level conflict resolution
+ */
+const DEFAULT_IDEMPOTENCY_HEADER = 'X-Idempotency-Key';
+/**
+ * The main RequestLedger class.
+ *
+ * Provides a durable request queue that persists across page reloads
+ * and replays requests when connectivity is restored.
+ */
+class RequestLedger {
+    constructor(config = {}) {
+        this.isDestroyed = false;
+        // Initialize storage
+        this.storage = config.storage ?? new IndexedDBStorage(config.storageConfig);
+        // Initialize online checker
+        this.onlineCheck = createOnlineChecker(config.onlineCheck);
+        // Set retry strategy
+        this.retryStrategy = config.retry ?? DEFAULT_RETRY_STRATEGY;
+        // Set hooks
+        this.hooks = config.hooks ?? {};
+        // Set idempotency header
+        this.idempotencyHeader = config.idempotencyHeader ?? DEFAULT_IDEMPOTENCY_HEADER;
+        // Initialize replay engine
+        this.replayEngine = new ReplayEngine({
+            storage: this.storage,
+            onlineCheck: this.onlineCheck,
+            retry: this.retryStrategy,
+            hooks: this.hooks,
+            idempotencyHeader: this.idempotencyHeader,
+        });
+    }
+    /**
+     * Make a request through the ledger.
+     *
+     * Behavior:
+     * - If online → attempt immediately
+     * - If offline or request fails due to network → persist to ledger
+     * - If persistence fails → throw explicitly
+     *
+     * @param options The request options
+     * @returns Response if request succeeded immediately, void if queued
+     */
+    async request(options) {
+        this.ensureNotDestroyed();
+        // Check if online
+        const online = await this.onlineCheck();
+        if (online) {
+            // Try to make the request immediately
+            try {
+                const response = await this.executeRequest(options);
+                return response;
+            }
+            catch (error) {
+                // If it's a network error, queue the request
+                if (isNetworkError(error)) {
+                    await this.persistRequest(options);
+                    return;
+                }
+                // Re-throw non-network errors
+                throw error;
+            }
+        }
+        else {
+            // Offline: queue the request
+            await this.persistRequest(options);
+        }
+    }
+    /**
+     * Execute an HTTP request.
+     */
+    async executeRequest(options) {
+        const { url, method, headers = {}, body, idempotencyKey } = options;
+        const requestHeaders = new Headers(headers);
+        // Add idempotency key if present
+        if (idempotencyKey) {
+            requestHeaders.set(this.idempotencyHeader, idempotencyKey);
+        }
+        // Determine body
+        let requestBody;
+        if (body !== undefined && body !== null) {
+            requestBody = JSON.stringify(body);
+            if (!requestHeaders.has('Content-Type')) {
+                requestHeaders.set('Content-Type', 'application/json');
+            }
+        }
+        return fetch(url, {
+            method,
+            headers: requestHeaders,
+            body: requestBody ?? null,
+        });
+    }
+    /**
+     * Persist a request to the ledger.
+     */
+    async persistRequest(options) {
+        const entry = {
+            id: options.id,
+            request: {
+                url: options.url,
+                method: options.method,
+                headers: options.headers ?? {},
+                body: options.body,
+            },
+            status: 'pending',
+            attemptCount: 0,
+            createdAt: Date.now(),
+            ...(options.idempotencyKey && { idempotencyKey: options.idempotencyKey }),
+            ...(options.metadata && { metadata: options.metadata }),
+        };
+        try {
+            await this.storage.put(entry);
+            // Fire onPersist hook
+            this.hooks.onPersist?.(entry);
+        }
+        catch (error) {
+            if (error instanceof PersistenceError) {
+                throw error;
+            }
+            throw new PersistenceError('Failed to persist request to ledger', error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Process pending entries in the ledger.
+     *
+     * @param options Processing options
+     */
+    async process(options = {}) {
+        this.ensureNotDestroyed();
+        await this.replayEngine.process(options);
+    }
+    /**
+     * Pause processing.
+     */
+    pause() {
+        this.ensureNotDestroyed();
+        this.replayEngine.pause();
+    }
+    /**
+     * Resume processing.
+     */
+    resume() {
+        this.ensureNotDestroyed();
+        this.replayEngine.resume();
+    }
+    /**
+     * Clear all completed entries.
+     *
+     * Note: In this implementation, completed entries are automatically
+     * removed, so this is a no-op. Provided for API completeness.
+     */
+    async clearCompleted() {
+        this.ensureNotDestroyed();
+        const entries = await this.storage.getAll();
+        for (const entry of entries) {
+            if (entry.status === 'completed') {
+                await this.storage.remove(entry.id);
+            }
+        }
+    }
+    /**
+     * Get the current state of the ledger.
+     */
+    async getState() {
+        this.ensureNotDestroyed();
+        return this.replayEngine.getState();
+    }
+    /**
+     * List all entries in the ledger.
+     */
+    async list() {
+        this.ensureNotDestroyed();
+        return this.storage.getAll();
+    }
+    /**
+     * Get a single entry by ID.
+     */
+    async get(id) {
+        this.ensureNotDestroyed();
+        return this.storage.get(id);
+    }
+    /**
+     * Manually retry a failed entry.
+     *
+     * This is useful when using the 'manual' retry strategy.
+     *
+     * @param id The entry ID to retry
+     */
+    async retry(id) {
+        this.ensureNotDestroyed();
+        const entry = await this.storage.get(id);
+        if (!entry) {
+            throw new Error(`Entry not found: ${id}`);
+        }
+        if (entry.status !== 'failed') {
+            throw new Error(`Entry is not in failed state: ${id}`);
+        }
+        // Reset status to pending and clear error
+        await this.storage.update(id, {
+            status: 'pending',
+            error: undefined,
+        });
+    }
+    /**
+     * Remove a specific entry from the ledger.
+     *
+     * @param id The entry ID to remove
+     */
+    async remove(id) {
+        this.ensureNotDestroyed();
+        await this.storage.remove(id);
+    }
+    /**
+     * Clear all entries from the ledger.
+     */
+    async clear() {
+        this.ensureNotDestroyed();
+        await this.storage.clear();
+    }
+    /**
+     * Destroy the ledger instance.
+     *
+     * This closes the storage connection and prevents further operations.
+     */
+    async destroy() {
+        if (this.isDestroyed)
+            return;
+        this.isDestroyed = true;
+        this.replayEngine.pause();
+        // Close storage if it has a close method
+        if ('close' in this.storage && typeof this.storage.close === 'function') {
+            this.storage.close();
+        }
+    }
+    /**
+     * Ensure the ledger is not destroyed.
+     */
+    ensureNotDestroyed() {
+        if (this.isDestroyed) {
+            throw new Error('Ledger has been destroyed');
+        }
+    }
+}
+/**
+ * Create a new RequestLedger instance.
+ *
+ * @param config Configuration options
+ * @returns A new RequestLedger instance
+ */
+function createLedger(config = {}) {
+    return new RequestLedger(config);
+}
+
+exports.DuplicateEntryError = DuplicateEntryError;
+exports.EntryNotFoundError = EntryNotFoundError;
+exports.IndexedDBStorage = IndexedDBStorage;
+exports.LedgerError = LedgerError;
+exports.NetworkError = NetworkError;
+exports.PersistenceError = PersistenceError;
+exports.RequestLedger = RequestLedger;
+exports.calculateBackoffDelay = calculateBackoffDelay;
+exports.canRetry = canRetry;
+exports.createLedger = createLedger;
+exports.createOnlineChecker = createOnlineChecker;
+exports.delay = delay;
+exports.isNetworkError = isNetworkError;
+exports.isRetryableStatusCode = isRetryableStatusCode;
+//# sourceMappingURL=index.cjs.map