fetchguard 1.6.3 → 2.1.0

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import * as ts_micro_result from 'ts-micro-result';
 import { Result, ErrorDetail, ResultMeta } from 'ts-micro-result';
-import * as ts_micro_result_factories_errors_advanced from 'ts-micro-result/factories/errors-advanced';
 
 /**
  * FetchGuard Business Types
@@ -23,6 +22,18 @@ interface TokenInfo {
     refreshToken?: string | null;
     user?: unknown;
 }
+/**
+ * Options for token exchange operation
+ *
+ * Used when switching tenant, changing scope, or any operation
+ * that exchanges current token for a new one with different claims
+ */
+interface ExchangeTokenOptions {
+    /** HTTP method to use. Default: 'POST' */
+    method?: 'POST' | 'PUT';
+    /** Payload to send with the request (e.g., tenantId, scope) */
+    payload?: Record<string, unknown>;
+}
 /**
  * Auth result returned from auth operations and auth state changes
  * Used by: login(), logout(), refreshToken(), onAuthStateChanged()
@@ -66,6 +77,18 @@ interface TokenProvider {
      * @returns Result<TokenInfo> with all fields reset (token = '', refreshToken = undefined, user = undefined)
      */
     logout(payload?: unknown): Promise<Result<TokenInfo>>;
+    /**
+     * Exchange current token for a new one with different context
+     *
+     * Useful for switching tenants, changing scopes, or any operation
+     * that requires exchanging the current token for a new one.
+     *
+     * @param accessToken - Current access token (injected by worker)
+     * @param url - URL to call for token exchange
+     * @param options - Exchange options (method, payload)
+     * @returns Result<TokenInfo> with new tokens
+     */
+    exchangeToken(accessToken: string, url: string, options?: ExchangeTokenOptions): Promise<Result<TokenInfo>>;
     /**
      * Custom auth methods (optional)
      * Examples: loginWithPhone, loginWithGoogle, loginWithFacebook, etc.
@@ -76,6 +99,16 @@ interface TokenProvider {
      */
     [key: string]: (...args: any[]) => Promise<Result<TokenInfo>>;
 }
+/**
+ * Storage error context for debugging
+ */
+type StorageErrorContext = 'get' | 'set' | 'delete' | 'open';
+/**
+ * Storage error callback type
+ * Called when IndexedDB operations fail (quota exceeded, permission denied, etc.)
+ * Storage still fails closed (returns null), but this allows logging/debugging.
+ */
+type StorageErrorCallback = (error: Error, context: StorageErrorContext) => void;
 /**
  * Interface for refresh token storage - only stores refresh token
  *
@@ -144,6 +177,46 @@ interface FetchGuardOptions {
     refreshEarlyMs?: number;
     /** Default headers to include in all requests */
     defaultHeaders?: Record<string, string>;
+    /**
+     * Maximum concurrent requests to worker (default: 6)
+     * Controls how many requests can be in-flight simultaneously.
+     * Set to 1 for strictly sequential processing.
+     * Higher values increase throughput but may cause worker congestion.
+     */
+    maxConcurrent?: number;
+    /**
+     * Maximum queue size for pending requests (default: 1000)
+     * When queue is full, new requests will immediately fail with QUEUE_FULL error.
+     * Prevents memory leak if worker is unresponsive.
+     */
+    maxQueueSize?: number;
+    /**
+     * Worker setup timeout in milliseconds (default: 10000)
+     * How long to wait for worker to be ready before failing.
+     */
+    setupTimeout?: number;
+    /**
+     * Default request timeout in milliseconds (default: 30000)
+     * How long to wait for a request to complete before timing out.
+     * Can be overridden per-request via fetch options.
+     */
+    requestTimeout?: number;
+    /**
+     * Debug hooks for observing operations (logging, monitoring)
+     * All hooks are observe-only - they cannot modify requests/responses.
+     */
+    debug?: DebugHooks;
+    /**
+     * Retry configuration for network errors
+     * Only retries on transport failures, NOT on HTTP errors (4xx/5xx)
+     */
+    retry?: RetryConfig;
+    /**
+     * Request deduplication configuration
+     * When enabled, duplicate requests to the same URL within a time window
+     * will share the same response instead of making multiple requests.
+     */
+    dedupe?: DedupeConfig;
 }
 /**
  * Internal worker configuration
@@ -163,25 +236,31 @@ interface FetchGuardRequestInit extends RequestInit {
     includeHeaders?: boolean;
 }
 /**
- * API response structure
+ * Fetch envelope - raw HTTP response from worker
+ *
+ * Worker only fetches and returns raw data, does NOT judge HTTP status.
+ * Client receives envelope and decides ok/err based on business logic.
+ *
+ * - status: HTTP status code (2xx, 3xx, 4xx, 5xx)
  * - body: string (text/JSON) or base64 (binary)
  * - contentType: always present, indicates how to decode body
  * - headers: empty object if includeHeaders: false
- * - status: HTTP status code
  */
-interface ApiResponse {
-    body: string;
+interface FetchEnvelope {
     status: number;
+    body: string;
     contentType: string;
     headers: Record<string, string>;
 }
 /**
  * Serialized file data for transfer over postMessage
+ * Uses ArrayBuffer for zero-copy transfer via Transferable
  */
 interface SerializedFile {
     name: string;
     type: string;
-    data: number[];
+    /** ArrayBuffer - transferred via postMessage Transferable for zero-copy */
+    buffer: ArrayBuffer;
 }
 /**
  * Serialized FormData entry - can be string or file
@@ -194,6 +273,187 @@ interface SerializedFormData {
     _type: 'FormData';
     entries: Array<[string, SerializedFormDataEntry]>;
 }
+/**
+ * Result of FormData serialization with transferables
+ * Used for zero-copy transfer via postMessage
+ */
+interface SerializedFormDataResult {
+    data: SerializedFormData;
+    /** ArrayBuffers to transfer - pass to postMessage as second argument */
+    transferables: ArrayBuffer[];
+}
+/**
+ * Network error detail for transport failures
+ * Used when no HTTP response is received (connection failed, timeout, cancelled)
+ */
+interface NetworkErrorDetail {
+    code: 'NETWORK_ERROR' | 'REQUEST_CANCELLED' | 'RESPONSE_PARSE_FAILED';
+    message: string;
+}
+/**
+ * Reason for token refresh
+ */
+type RefreshReason = 'expired' | 'proactive' | 'manual';
+/**
+ * Request timing metrics for performance monitoring
+ *
+ * All times are in milliseconds.
+ */
+interface RequestMetrics {
+    /** When request was initiated (Date.now()) */
+    startTime: number;
+    /** When response was received (Date.now()) */
+    endTime: number;
+    /** Total duration (endTime - startTime) */
+    duration: number;
+    /** Time spent waiting in queue before processing */
+    queueTime: number;
+    /** Time spent in IPC (postMessage round-trip overhead) */
+    ipcTime: number;
+}
+/**
+ * Debug hooks for observing FetchGuard operations
+ *
+ * All hooks are observe-only - they cannot modify requests/responses.
+ * Useful for logging, debugging, and monitoring.
+ *
+ * Note: Hooks run synchronously and should not perform heavy operations.
+ */
+interface DebugHooks {
+    /**
+     * Called before each request is sent to worker
+     * @param url - Request URL
+     * @param options - Request options (method, headers, etc.)
+     */
+    onRequest?: (url: string, options: FetchGuardRequestInit) => void;
+    /**
+     * Called when response is received from worker
+     * @param url - Request URL
+     * @param envelope - Response envelope (status, body, headers)
+     * @param metrics - Request timing metrics (optional, for performance monitoring)
+     */
+    onResponse?: (url: string, envelope: FetchEnvelope, metrics?: RequestMetrics) => void;
+    /**
+     * Called when token refresh occurs
+     * @param reason - Why refresh happened: 'expired', 'proactive', or 'manual'
+     */
+    onRefresh?: (reason: RefreshReason) => void;
+    /**
+     * Called when transport error occurs (network failure, timeout, cancelled)
+     * @param url - Request URL
+     * @param error - Error detail with code and message
+     * @param metrics - Request timing metrics (optional)
+     */
+    onError?: (url: string, error: NetworkErrorDetail, metrics?: RequestMetrics) => void;
+    /**
+     * Called when worker is ready after initialization
+     */
+    onWorkerReady?: () => void;
+    /**
+     * Called when worker encounters a fatal error
+     * @param error - Error event from worker
+     */
+    onWorkerError?: (error: ErrorEvent) => void;
+}
+/**
+ * Retry configuration for network errors
+ *
+ * Only retries on transport failures (network error, timeout).
+ * Does NOT retry on HTTP errors (4xx/5xx) - those are valid responses.
+ * Does NOT retry cancelled requests.
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts (default: 0 = no retry)
+     */
+    maxAttempts?: number;
+    /**
+     * Delay between retries in milliseconds (default: 1000)
+     */
+    delay?: number;
+    /**
+     * Exponential backoff multiplier (default: 1 = no backoff)
+     * Example: delay=1000, backoff=2 => 1s, 2s, 4s, 8s...
+     */
+    backoff?: number;
+    /**
+     * Maximum delay in milliseconds (default: 30000)
+     * Caps the delay when using exponential backoff
+     */
+    maxDelay?: number;
+    /**
+     * Jitter factor to add randomness to retry delays (default: 0 = no jitter)
+     * Range: 0 to 1 (e.g., 0.5 = ±50% randomness)
+     * Helps prevent thundering herd when many clients retry simultaneously.
+     *
+     * Note: Jitter is only applied when shouldRetry returns true.
+     * If request fails permanently, no jitter delay occurs.
+     *
+     * Example: delay=1000, jitter=0.5 => delay between 500ms and 1500ms
+     */
+    jitter?: number;
+    /**
+     * Custom condition to determine if error should be retried
+     * Default: retry on NETWORK_ERROR only
+     * @param error - The error that occurred
+     * @returns true to retry, false to fail immediately
+     */
+    shouldRetry?: (error: NetworkErrorDetail) => boolean;
+}
+/**
+ * Request deduplication configuration
+ *
+ * When enabled, identical GET requests (same URL) within a time window
+ * will share the same in-flight request instead of making duplicates.
+ *
+ * IMPORTANT:
+ * - Only applies to GET requests (POST/PUT/DELETE are never deduplicated)
+ * - Only deduplicates in-flight requests (not caching)
+ * - Safe for most read operations
+ */
+interface DedupeConfig {
+    /**
+     * Enable deduplication (default: false)
+     */
+    enabled?: boolean;
+    /**
+     * Time window in milliseconds to consider requests as duplicates (default: 0)
+     * 0 = only dedupe concurrent/in-flight requests
+     * >0 = also dedupe requests within this time window after completion
+     */
+    window?: number;
+    /**
+     * Custom key generator for deduplication
+     * Default: uses URL only for GET requests
+     * @param url - Request URL
+     * @param options - Request options
+     * @returns Key string, or null to skip deduplication for this request
+     */
+    keyGenerator?: (url: string, options: FetchGuardRequestInit) => string | null;
+}
+/**
+ * Transport result - represents the outcome of a network request
+ *
+ * IMPORTANT: This is a TRANSPORT result, not a business result.
+ * - ok = HTTP response received (check envelope.status for 2xx/4xx/5xx)
+ * - err = Network failure (no response received)
+ *
+ * Example:
+ * ```typescript
+ * const result = await api.get('/users')
+ * if (result.ok) {
+ *   // Transport succeeded - got HTTP response
+ *   if (result.data.status >= 200 && result.data.status < 400) {
+ *     // Business success
+ *   } else {
+ *     // Business error (4xx/5xx) - still has response body
+ *   }
+ * } else {
+ *   // Transport failed - no response (network error, timeout, cancelled)
+ * }
+ * ```
+ */
+type TransportResult = Result<FetchEnvelope>;
 
 /**
  * FetchGuard Client - main interface cho việc gọi API thông qua Web Worker
@@ -202,14 +462,28 @@ declare class FetchGuardClient {
     private worker;
     private messageId;
     private pendingRequests;
+    /** Track request URLs for debug hooks */
+    private requestUrls;
+    /** Track request timing for metrics */
+    private requestTimings;
     private authListeners;
     private readyListeners;
     private isReady;
     private requestQueue;
-    private isProcessingQueue;
-    private queueTimeout;
+    private activeRequests;
+    private readonly maxConcurrent;
+    private readonly maxQueueSize;
+    private readonly setupTimeout;
+    private readonly requestTimeout;
     private setupResolve?;
     private setupReject?;
+    private readonly debug?;
+    private readonly retry?;
+    private readonly dedupe?;
+    /** In-flight requests for deduplication */
+    private readonly inFlightRequests;
+    /** Recent completed requests for time-window deduplication */
+    private readonly recentResults;
     constructor(options: FetchGuardOptions);
     /**
      * Initialize worker with config and provider
@@ -228,9 +502,57 @@ declare class FetchGuardClient {
      */
     private generateMessageId;
     /**
-     * Make API request
+     * Make API request with optional deduplication, retry, and AbortSignal support
+     *
+     * @param url - Full URL to fetch
+     * @param options - Request options including optional AbortSignal
+     * @returns Result with FetchEnvelope on success, error on failure
+     *
+     * @example
+     * // With AbortSignal
+     * const controller = new AbortController()
+     * setTimeout(() => controller.abort(), 5000)
+     * const result = await api.fetch('/slow', { signal: controller.signal })
+     */
+    fetch(url: string, options?: FetchGuardRequestInit): Promise<Result<FetchEnvelope>>;
+    /**
+     * Wrap a promise with AbortSignal support
      */
-    fetch(url: string, options?: FetchGuardRequestInit): Promise<Result<ApiResponse>>;
+    private wrapWithAbortSignal;
+    /**
+     * Fetch with retry logic and AbortSignal support (internal)
+     */
+    private fetchWithRetryAndSignal;
+    /**
+     * Generate deduplication key for request
+     * Returns null if request should not be deduplicated
+     */
+    private getDedupeKey;
+    /**
+     * Apply jitter to a delay value
+     * Jitter adds ±(jitter * delay) randomness to prevent thundering herd
+     * @param delay - Base delay in milliseconds
+     * @param jitter - Jitter factor (0-1)
+     * @returns Jittered delay
+     */
+    private applyJitter;
+    /**
+     * Default retry condition - only retry on NETWORK_ERROR
+     */
+    private defaultShouldRetry;
+    /**
+     * Calculate request metrics from timing data
+     */
+    private calculateMetrics;
+    /**
+     * Sleep helper for retry delay
+     */
+    private sleep;
+    /**
+     * Sleep with abort signal support
+     * Returns true if aborted, false if completed normally
+     */
+    private sleepWithAbort;
     /**
      * Fetch with id for external cancellation
      * Returns { id, result, cancel }
@@ -238,7 +560,7 @@ declare class FetchGuardClient {
      */
     fetchWithId(url: string, options?: FetchGuardRequestInit): {
         id: string;
-        result: Promise<Result<ApiResponse>>;
+        result: Promise<Result<FetchEnvelope>>;
         cancel: () => void;
     };
     /**
@@ -248,11 +570,11 @@ declare class FetchGuardClient {
     /**
      * Convenience methods
      */
-    get(url: string, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<ApiResponse>>;
-    post(url: string, body?: unknown, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<ApiResponse>>;
-    put(url: string, body?: unknown, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<ApiResponse>>;
-    delete(url: string, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<ApiResponse>>;
-    patch(url: string, body?: unknown, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<ApiResponse>>;
+    get(url: string, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<FetchEnvelope>>;
+    post(url: string, body?: unknown, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<FetchEnvelope>>;
+    put(url: string, body?: unknown, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<FetchEnvelope>>;
+    delete(url: string, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<FetchEnvelope>>;
+    patch(url: string, body?: unknown, options?: Omit<FetchGuardRequestInit, 'method' | 'body'>): Promise<Result<FetchEnvelope>>;
     /**
      * Generic method to call any auth method on provider
      * @param method - Method name (login, logout, loginWithPhone, etc.)
@@ -279,6 +601,34 @@ declare class FetchGuardClient {
      * @param emitEvent - Whether to emit AUTH_STATE_CHANGED event (default: true)
      */
     refreshToken(emitEvent?: boolean): Promise<Result<AuthResult>>;
+    /**
+     * Exchange current token for a new one with different context
+     *
+     * Useful for:
+     * - Switching tenants in multi-tenant apps
+     * - Changing authorization scope
+     * - Impersonating users (admin feature)
+     *
+     * @param url - URL to call for token exchange
+     * @param options - Exchange options (method, payload)
+     * @param emitEvent - Whether to emit AUTH_STATE_CHANGED event (default: true)
+     *
+     * @example
+     * // Switch tenant
+     * await api.exchangeToken('https://auth.example.com/auth/select-tenant', {
+     *   payload: { tenantId: 'tenant_123' }
+     * })
+     *
+     * // Change scope with PUT method
+     * await api.exchangeToken('https://auth.example.com/auth/switch-context', {
+     *   method: 'PUT',
+     *   payload: { scope: 'admin' }
+     * })
+     */
+    exchangeToken(url: string, options?: {
+        method?: 'POST' | 'PUT';
+        payload?: Record<string, unknown>;
+    }, emitEvent?: boolean): Promise<Result<AuthResult>>;
     /**
      * Check if worker is ready
      */
@@ -304,16 +654,24 @@ declare class FetchGuardClient {
     /**
      * Send message through queue system
      * All messages go through queue for sequential processing
+     * @param transferables - Optional Transferable objects for zero-copy postMessage
      */
     private sendMessageQueued;
     /**
-     * Process message queue sequentially
+     * Process message queue with concurrency limit
+     *
+     * Uses semaphore pattern to allow N concurrent requests.
      * Benefits:
-     * - Sequential processing prevents worker overload
+     * - Higher throughput than sequential processing
+     * - Backpressure via maxConcurrent limit
      * - Better error isolation (one failure doesn't affect others)
-     * - 50ms delay between requests for backpressure
      */
     private processQueue;
+    /**
+     * Called when a request completes (success or error)
+     * Decrements active count and processes next items in queue
+     */
+    private onRequestComplete;
     /**
      * Cleanup - terminate worker
      */
@@ -387,11 +745,14 @@ interface WorkerPayloads {
     };
     AUTH_STATE_CHANGED: AuthResult;
     AUTH_CALL_RESULT: AuthResult;
-    FETCH_RESULT: ApiResponse;
+    FETCH_RESULT: FetchEnvelope;
     FETCH_ERROR: {
         error: string;
         status?: number;
     };
+    TOKEN_REFRESHED: {
+        reason: RefreshReason;
+    };
 }
 /**
  * Generate message type from payload definition
@@ -447,6 +808,7 @@ declare const InitErrors: {
  */
 declare const AuthErrors: {
     readonly TokenRefreshFailed: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+    readonly TokenExchangeFailed: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
     readonly LoginFailed: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
     readonly LogoutFailed: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
     readonly NotAuthenticated: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
@@ -456,8 +818,8 @@ declare const AuthErrors: {
  */
 declare const DomainErrors: {
     readonly NotAllowed: (params?: ({
-        url: any;
-    } & Partial<ts_micro_result_factories_errors_advanced.BaseErrorParams>) | undefined) => ts_micro_result.ErrorDetail;
+        url: string | number;
+    } & Partial<ts_micro_result.BaseErrorParams>) | undefined) => ts_micro_result.ErrorDetail;
 };
 /**
  * Request/Response errors (network, HTTP, parsing)
@@ -466,11 +828,57 @@ declare const RequestErrors: {
     readonly NetworkError: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
     readonly Cancelled: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
     readonly HttpError: (params?: ({
-        status: any;
-    } & Partial<ts_micro_result_factories_errors_advanced.BaseErrorParams>) | undefined) => ts_micro_result.ErrorDetail;
+        status: string | number;
+    } & Partial<ts_micro_result.BaseErrorParams>) | undefined) => ts_micro_result.ErrorDetail;
     readonly ResponseParseFailed: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
+    readonly QueueFull: (params?: ({
+        size: string | number;
+        maxSize: string | number;
+    } & Partial<ts_micro_result.BaseErrorParams>) | undefined) => ts_micro_result.ErrorDetail;
+    readonly Timeout: (params?: ts_micro_result.BaseErrorParams) => ts_micro_result.ErrorDetail;
 };
 
+/**
+ * Error codes as constants for type-safe error matching
+ *
+ * Usage:
+ * ```typescript
+ * import { ERROR_CODES } from 'fetchguard'
+ *
+ * if (result.errors[0]?.code === ERROR_CODES.NETWORK_ERROR) {
+ *   // Handle network error
+ * }
+ * ```
+ */
+declare const ERROR_CODES: {
+    readonly UNEXPECTED: "UNEXPECTED";
+    readonly UNKNOWN_MESSAGE: "UNKNOWN_MESSAGE";
+    readonly RESULT_PARSE_ERROR: "RESULT_PARSE_ERROR";
+    readonly INIT_ERROR: "INIT_ERROR";
+    readonly PROVIDER_INIT_FAILED: "PROVIDER_INIT_FAILED";
+    readonly INIT_FAILED: "INIT_FAILED";
+    readonly TOKEN_REFRESH_FAILED: "TOKEN_REFRESH_FAILED";
+    readonly TOKEN_EXCHANGE_FAILED: "TOKEN_EXCHANGE_FAILED";
+    readonly LOGIN_FAILED: "LOGIN_FAILED";
+    readonly LOGOUT_FAILED: "LOGOUT_FAILED";
+    readonly NOT_AUTHENTICATED: "NOT_AUTHENTICATED";
+    readonly DOMAIN_NOT_ALLOWED: "DOMAIN_NOT_ALLOWED";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly REQUEST_CANCELLED: "REQUEST_CANCELLED";
+    readonly HTTP_ERROR: "HTTP_ERROR";
+    readonly RESPONSE_PARSE_FAILED: "RESPONSE_PARSE_FAILED";
+    readonly QUEUE_FULL: "QUEUE_FULL";
+    readonly REQUEST_TIMEOUT: "REQUEST_TIMEOUT";
+};
+/**
+ * Union type of all error code values
+ */
+type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
+/**
+ * Union type of all error code keys (useful for telemetry mapping)
+ */
+type ErrorCodeKey = keyof typeof ERROR_CODES;
+
 /**
  * Register a token provider with name
  */
@@ -531,12 +939,30 @@ interface ProviderConfig {
  */
 declare function createProvider(config: ProviderConfig): TokenProvider;
 
+/**
+ * IndexedDB storage options
+ */
+interface IndexedDBStorageOptions {
+    /** Database name (default: 'FetchGuardDB') */
+    dbName?: string;
+    /** Key for refresh token (default: 'refreshToken') */
+    refreshTokenKey?: string;
+    /**
+     * Error callback for debugging storage failures
+     * Called when IndexedDB operations fail (quota exceeded, permission denied, etc.)
+     * Storage still fails closed (returns null), but this allows logging/debugging.
+     */
+    onError?: StorageErrorCallback;
+}
 /**
  * IndexedDB storage - only stores refresh token in IndexedDB
  * Suitable for body-based refresh strategy
  * Persists refresh token for reuse after reload
+ *
+ * @param options - Storage options or legacy dbName string
+ * @param legacyRefreshTokenKey - Legacy refreshTokenKey (for backward compatibility)
  */
-declare function createIndexedDBStorage(dbName?: string, refreshTokenKey?: string): RefreshTokenStorage;
+declare function createIndexedDBStorage(options?: IndexedDBStorageOptions | string, legacyRefreshTokenKey?: string): RefreshTokenStorage;
 
 /**
  * Body parser - parse token from response body (JSON)
@@ -638,15 +1064,18 @@ declare function createBodyProvider(config: {
 
 /**
  * Serialize FormData for transfer over postMessage
- * Inspired by api-worker.js:484-518
  *
- * FormData cannot be cloned via postMessage, so we need to serialize it first
- * Files are converted to ArrayBuffer -> number[] for transfer
+ * FormData cannot be cloned via postMessage, so we need to serialize it first.
+ * Files are converted to ArrayBuffer and returned as transferables for zero-copy transfer.
+ *
+ * IMPORTANT: Preserves original field order by using single-pass iteration.
+ *
+ * @returns SerializedFormDataResult with data and transferables array
  */
-declare function serializeFormData(formData: FormData): Promise<SerializedFormData>;
+declare function serializeFormData(formData: FormData): Promise<SerializedFormDataResult>;
 /**
  * Deserialize SerializedFormData back to FormData in worker
- * Reconstructs File objects from serialized data
+ * Reconstructs File objects from transferred ArrayBuffers
  */
 declare function deserializeFormData(serialized: SerializedFormData): FormData;
 /**
@@ -669,4 +1098,138 @@ declare function base64ToArrayBuffer(base64: string): ArrayBuffer;
  */
 declare function isBinaryContentType(contentType: string): boolean;
 
-export { type ApiResponse, AuthErrors, type AuthResult, type AuthStrategy, DomainErrors, FetchGuardClient, type FetchGuardOptions, type FetchGuardRequestInit, GeneralErrors, InitErrors, MSG, type MainToWorkerMessage, type MessageType, type ProviderConfig, type ProviderPresetConfig, type RefreshTokenStorage, RequestErrors, type SerializedFile, type SerializedFormData, type SerializedFormDataEntry, type TokenInfo, type TokenParser, type TokenProvider, type WorkerConfig, type WorkerToMainMessage, base64ToArrayBuffer, bodyParser, bodyStrategy, clearProviders, cookieParser, cookieStrategy, createBodyProvider, createBodyStrategy, createClient, createCookieProvider, createCookieStrategy, createIndexedDBStorage, createProvider, deserializeFormData, getProvider, hasProvider, isBinaryContentType, isFormData, isSerializedFormData, listProviders, registerProvider, serializeFormData, unregisterProvider };
+/**
+ * Helper functions for common Result patterns
+ *
+ * These utilities simplify working with FetchGuard's Result-based API
+ * by providing type-safe helpers for common operations.
+ */
+
+/**
+ * Check if result is a network/transport error (not an HTTP response)
+ *
+ * @example
+ * const result = await api.fetch('/users')
+ * if (isNetworkError(result)) {
+ *   console.error('Network failed:', result.errors[0]?.message)
+ * }
+ */
+declare function isNetworkError(result: Result<FetchEnvelope>): result is Result<FetchEnvelope> & {
+    ok: false;
+};
+/**
+ * Check if response is successful (2xx status)
+ *
+ * @example
+ * if (isSuccess(result)) {
+ *   const data = parseJson(result)
+ * }
+ */
+declare function isSuccess(result: Result<FetchEnvelope>): boolean;
+/**
+ * Check if response is a client error (4xx status)
+ *
+ * @example
+ * if (isClientError(result)) {
+ *   console.error('Bad request:', getErrorMessage(result))
+ * }
+ */
+declare function isClientError(result: Result<FetchEnvelope>): boolean;
+/**
+ * Check if response is a server error (5xx status)
+ *
+ * @example
+ * if (isServerError(result)) {
+ *   // Maybe retry?
+ * }
+ */
+declare function isServerError(result: Result<FetchEnvelope>): boolean;
+/**
+ * Parse JSON body safely with optional type inference
+ *
+ * Returns null if:
+ * - Result is a network error (no response)
+ * - Body is not valid JSON
+ *
+ * @example
+ * const users = parseJson<User[]>(result)
+ * if (users) {
+ *   // Use users array
+ * }
+ */
+declare function parseJson<T = unknown>(result: Result<FetchEnvelope>): T | null;
+/**
+ * Get human-readable error message from result
+ *
+ * For network errors: returns the error message
+ * For HTTP errors: tries to parse message from body, falls back to status code
+ *
+ * @example
+ * if (!isSuccess(result)) {
+ *   toast.error(getErrorMessage(result))
+ * }
+ */
+declare function getErrorMessage(result: Result<FetchEnvelope>): string;
+/**
+ * Get error body with type safety (best-effort parsing)
+ *
+ * NOTE: This is best-effort parsing. The error body comes from the server
+ * and may not match the expected shape. Always handle null return and
+ * validate before using typed properties.
+ *
+ * @example
+ * interface ApiError {
+ *   code: string
+ *   message: string
+ *   errors?: { field: string; message: string }[]
+ * }
+ *
+ * const errorBody = getErrorBody<ApiError>(result)
+ * if (errorBody?.errors) {
+ *   errorBody.errors.forEach(e => console.error(`${e.field}: ${e.message}`))
+ * }
+ */
+declare function getErrorBody<T = unknown>(result: Result<FetchEnvelope>): T | null;
+/**
+ * Get the HTTP status code from result
+ *
+ * Returns null if result is a network error (no HTTP response)
+ *
+ * @example
+ * const status = getStatus(result)
+ * if (status === 401) {
+ *   // Redirect to login
+ * }
+ */
+declare function getStatus(result: Result<FetchEnvelope>): number | null;
+/**
+ * Check if result has a specific HTTP status
+ *
+ * @example
+ * if (hasStatus(result, 404)) {
+ *   console.log('Not found')
+ * }
+ */
+declare function hasStatus(result: Result<FetchEnvelope>, status: number): boolean;
+/**
+ * Match result against multiple handlers
+ *
+ * @example
+ * matchResult(result, {
+ *   success: (data) => console.log('Success:', data),
+ *   clientError: (data) => console.error('Client error:', data.status),
+ *   serverError: (data) => console.error('Server error:', data.status),
+ *   networkError: (errors) => console.error('Network:', errors[0]?.message)
+ * })
+ */
+declare function matchResult<T>(result: Result<FetchEnvelope>, handlers: {
+    success?: (data: FetchEnvelope) => T;
+    clientError?: (data: FetchEnvelope) => T;
+    serverError?: (data: FetchEnvelope) => T;
+    networkError?: (errors: readonly {
+        code: string;
+        message: string;
+    }[]) => T;
+}): T | undefined;
+
+export { AuthErrors, type AuthResult, type AuthStrategy, type DebugHooks, type DedupeConfig, DomainErrors, ERROR_CODES, type ErrorCode, type ErrorCodeKey, type ExchangeTokenOptions, type FetchEnvelope, FetchGuardClient, type FetchGuardOptions, type FetchGuardRequestInit, GeneralErrors, type IndexedDBStorageOptions, InitErrors, MSG, type MainToWorkerMessage, type MessageType, type NetworkErrorDetail, type ProviderConfig, type ProviderPresetConfig, type RefreshReason, type RefreshTokenStorage, RequestErrors, type RequestMetrics, type RetryConfig, type SerializedFile, type SerializedFormData, type SerializedFormDataEntry, type StorageErrorCallback, type StorageErrorContext, type TokenInfo, type TokenParser, type TokenProvider, type TransportResult, type WorkerConfig, type WorkerToMainMessage, base64ToArrayBuffer, bodyParser, bodyStrategy, clearProviders, cookieParser, cookieStrategy, createBodyProvider, createBodyStrategy, createClient, createCookieProvider, createCookieStrategy, createIndexedDBStorage, createProvider, deserializeFormData, getErrorBody, getErrorMessage, getProvider, getStatus, hasProvider, hasStatus, isBinaryContentType, isClientError, isFormData, isNetworkError, isSerializedFormData, isServerError, isSuccess, listProviders, matchResult, parseJson, registerProvider, serializeFormData, unregisterProvider };