@web-widget/shared-cache/dist/shared-cache.d.ts

Standards-compliant HTTP cache implementation for server-side JavaScript with RFC 7234 compliance and cross-runtime support

/**
 * Filter options for controlling which keys to include/exclude in cache key generation.
 * Used to fine-tune cache key granularity and avoid cache pollution.
 */
interface FilterOptions {
    /** Array of keys to explicitly include in the cache key */
    include?: string[];
    /** Array of keys to explicitly exclude from the cache key */
    exclude?: string[];
    /** Array of keys to check for presence only (value set to empty string) */
    checkPresence?: string[];
}
/**
 * Configuration rules for generating cache keys.
 * Defines which parts of the request should contribute to the cache key.
 *
 * Each property can be:
 * - `true`: Include the part with default behavior
 * - `false`: Exclude the part entirely
 * - `FilterOptions`: Include with specific filtering rules
 */
interface SharedCacheKeyRules {
    /** Use request cookies as part of cache key for personalization */
    cookie?: FilterOptions | boolean;
    /** Use device type detection as part of cache key for responsive content */
    device?: FilterOptions | boolean;
    /** Use request headers as part of cache key for content negotiation */
    header?: FilterOptions | boolean;
    /** Use request host as part of cache key for multi-tenant applications */
    host?: FilterOptions | boolean;
    /** Use URL pathname as part of cache key for resource identification */
    pathname?: FilterOptions | boolean;
    /** Use URL search parameters as part of cache key for dynamic content */
    search?: FilterOptions | boolean;
    /** Use custom part of cache key for application-specific logic */
    [customPart: string]: unknown | boolean | undefined;
}
/**
 * Function signature for custom cache key part definers.
 * Allows extending cache key generation with application-specific logic.
 */
interface SharedCacheKeyPartDefiners {
    [customPart: string]: (request: Request, options?: unknown) => Promise<string> | undefined;
}
/**
 * Filters an array of key-value pairs based on include/exclude rules.
 *
 * This function implements a filtering algorithm that:
 * 1. First applies exclusion rules (blacklist)
 * 2. Then applies inclusion rules (whitelist)
 * 3. Finally applies presence check rules (keys without values)
 *
 * @param array - Array of [key, value] tuples to filter
 * @param options - Filtering options
 * @returns Filtered array of [key, value] tuples
 */
declare function filter(array: [key: string, value: string][], options?: FilterOptions): [key: string, value: string][];
/**
 * Generates a cache key component based on request cookies.
 *
 * This function creates a deterministic cache key part from HTTP cookies,
 * which is useful for personalized content caching. Cookie values are hashed
 * to protect sensitive information while maintaining cache effectiveness.
 *
 * @param request - The HTTP request containing cookies
 * @param options - Optional filtering rules for cookie selection
 * @returns Promise resolving to cookie-based cache key component (format: "name1=hash1&name2=hash2")
 */
declare function cookie(request: Request, options?: FilterOptions): Promise<string>;
/**
 * Generates a cache key component based on device type detection.
 *
 * This function identifies the device type from User-Agent headers
 * and includes it in the cache key for responsive content delivery.
 * Useful for serving different content to mobile, tablet, and desktop devices.
 *
 * @param request - The HTTP request containing User-Agent header
 * @param options - Optional filtering rules for device type
 * @returns Promise resolving to device-based cache key component
 */
declare function device(request: Request, options?: FilterOptions): Promise<string>;
/**
 * Generates a cache key component based on the request host.
 *
 * This function extracts the host from the URL for multi-tenant applications
 * where different hosts serve different content.
 *
 * @param url - The request URL containing the host
 * @param options - Optional filtering rules for host inclusion
 * @returns Host-based cache key component
 */
declare function host(url: URL, options?: FilterOptions): string;
/**
 * Generates a cache key component based on the URL pathname.
 *
 * This function extracts the pathname for resource-based cache differentiation.
 * Essential for most caching scenarios as different paths represent different resources.
 *
 * @param url - The request URL containing the pathname
 * @param options - Optional filtering rules for pathname inclusion
 * @returns Pathname-based cache key component
 */
declare function pathname(url: URL, options?: FilterOptions): string;
/**
 * Generates a cache key component based on URL search parameters.
 *
 * This function extracts and sorts query parameters to create consistent
 * cache keys for dynamic content. Parameters are sorted alphabetically
 * to ensure consistent key generation regardless of parameter order.
 *
 * @param url - The request URL containing search parameters
 * @param options - Optional filtering rules for parameter selection
 * @returns Search parameter-based cache key component (format: "?param1=value1&param2=value2")
 */
declare function search(url: URL, options?: FilterOptions): string;
/**
 * Generates a cache key component based on HTTP Vary header processing.
 *
 * This function implements the HTTP Vary header semantics as defined in RFC 7231.
 * It creates cache key components from request headers that are listed in the
 * response's Vary header, enabling proper content negotiation caching.
 *
 * Header names are converted to lowercase for case-insensitive comparison
 * as per HTTP specification (RFC 7230 Section 3.2).
 *
 * @param request - The HTTP request containing headers to process
 * @param options - Optional filtering rules for header selection
 * @returns Promise resolving to vary-based cache key component (format: "header1=hash1&header2=hash2")
 */
declare function vary(request: Request, options?: FilterOptions): Promise<string>;
/**
 * List of HTTP headers that should not be included in cache keys.
 *
 * These headers are excluded for the following reasons:
 * - High cardinality: Risk of cache fragmentation (Accept-*, User-Agent, Referer)
 * - Cache/proxy features: Would interfere with caching logic (Cache-Control, If-*)
 * - Covered by other features: Handled by dedicated cache key components (Cookie, Host)
 * - Implementation details: Not relevant for cache key generation (Content-Length, Connection)
 *
 * Based on best practices from CDN implementations and HTTP caching specifications.
 */
declare const CANNOT_INCLUDE_HEADERS: readonly ["accept", "accept-charset", "accept-encoding", "accept-datetime", "accept-language", "referer", "user-agent", "connection", "content-length", "cache-control", "if-match", "if-modified-since", "if-none-match", "if-unmodified-since", "range", "upgrade", "cookie", "host", "vary", "x-cache-status"];
/**
 * Generates a cache key component based on request headers.
 *
 * This function creates cache key components from HTTP request headers,
 * useful for content negotiation and custom header-based caching.
 * Header values are hashed to keep cache keys compact while preventing
 * cache pollution from high-cardinality headers.
 *
 * Certain headers are automatically excluded to prevent cache fragmentation
 * and conflicts with other cache features.
 *
 * @param request - The HTTP request containing headers to process
 * @param options - Optional filtering rules for header selection
 * @returns Promise resolving to header-based cache key component
 * @throws {TypeError} When attempting to include a forbidden header
 */
declare function header(request: Request, options?: FilterOptions): Promise<string>;
/**
 * Default cache key generation rules.
 *
 * Includes the most common cache key components that work for most HTTP caching scenarios:
 * - host: Enables multi-tenant caching
 * - pathname: Differentiates resources
 * - search: Handles query parameters
 *
 * These defaults provide a good balance between cache effectiveness and key uniqueness.
 */
declare const DEFAULT_CACHE_KEY_RULES: SharedCacheKeyRules;
/**
 * Creates a cache key generator function with customizable rules and part definers.
 *
 * This factory function creates a highly configurable cache key generator that can
 * be tailored for specific application needs. The generated function follows a
 * consistent key format: `[cacheName/]host+pathname+search[#fragment1:fragment2:...]`
 *
 * Cache key structure:
 * - Base URL parts (host, pathname, search) are concatenated directly
 * - Fragment parts (cookie, device, header, custom) are hashed and joined with ":"
 * - Fragments are appended after "#" if any exist
 * - Cache name prefix is added if specified (except for "default")
 *
 * @param cacheName - Optional cache namespace (omitted if "default")
 * @param cacheKeyPartDefiners - Optional custom part definers for extending functionality
 * @returns A cache key generator function that accepts requests and rules
 *
 * @example
 * ```typescript
 * const generator = createCacheKeyGenerator('api-cache');
 * const key = await generator(request, { host: true, pathname: true, cookie: true });
 * // Result: "api-cache/example.com/api/users?limit=10#cookie=abc123"
 * ```
 */
declare function createCacheKeyGenerator(cacheName?: string, cacheKeyPartDefiners?: SharedCacheKeyPartDefiners): (request: Request, cacheKeyRules?: SharedCacheKeyRules) => Promise<string>;

/**
 * Generic logger interface for any logging implementation.
 * Provides standardized logging methods compatible with console, winston, pino, etc.
 */
interface Logger {
    /**
     * Log informational messages about normal operations.
     */
    info(message?: unknown, ...optionalParams: unknown[]): void;
    /**
     * Log warning messages about potentially problematic situations.
     */
    warn(message?: unknown, ...optionalParams: unknown[]): void;
    /**
     * Log detailed debugging information.
     */
    debug(message?: unknown, ...optionalParams: unknown[]): void;
    /**
     * Log error messages about failed operations.
     */
    error(message?: unknown, ...optionalParams: unknown[]): void;
}
/**
 * Log levels in order of priority (lowest to highest)
 */
declare enum LogLevel {
    DEBUG = 0,
    INFO = 1,
    WARN = 2,
    ERROR = 3
}
/**
 * Structured logger utility class that provides consistent logging format and optional level filtering
 * @template TContext - The log context type structure, defaults to a flexible object type
 */
declare class StructuredLogger<TContext = Record<string, unknown>> {
    private logger?;
    private minLevel;
    private prefix?;
    constructor(logger?: Logger, minLevel?: LogLevel, prefix?: string);
    /**
     * Log debug information about operations
     */
    debug(operation: string, context?: TContext, details?: string): void;
    /**
     * Log informational messages about successful operations
     */
    info(operation: string, context?: TContext, details?: string): void;
    /**
     * Log warning messages about potentially problematic situations
     */
    warn(operation: string, context?: TContext, details?: string): void;
    /**
     * Log error messages about failed operations
     */
    error(operation: string, context?: TContext, details?: string): void;
    /**
     * Handle promise rejections with proper error logging
     */
    handleAsyncError: (operation: string, context?: TContext) => (error: unknown) => void;
    /**
     * Check if a log level should be output based on minimum level setting
     */
    private shouldLog;
    /**
     * Create a new logger instance with a different minimum level
     */
    withLevel(minLevel: LogLevel): StructuredLogger<TContext>;
    /**
     * Create a new logger instance with a different prefix
     */
    withPrefix(prefix: string): StructuredLogger<TContext>;
    /**
     * Check if logger is available and can log at the specified level
     */
    canLog(level: LogLevel): boolean;
}
/**
 * Helper function to create a structured logger instance
 * @template TContext - The log context type structure
 */
declare function createLogger<TContext = Record<string, unknown>>(logger?: Logger, minLevel?: LogLevel, prefix?: string): StructuredLogger<TContext>;
/**
 * Helper function to create a SharedCache-specific logger instance
 * @deprecated Use createLogger with prefix parameter instead
 */
declare function createSharedCacheLogger<TContext = Record<string, unknown>>(logger?: Logger, minLevel?: LogLevel): StructuredLogger<TContext>;
declare const SharedCacheLogger: typeof StructuredLogger;

/**
 * Log context structure for SharedCache operations
 */
interface SharedCacheLogContext {
    /** The URL being processed */
    url?: string;
    /** Cache key involved in the operation */
    cacheKey?: string;
    /** HTTP status code */
    status?: number;
    /** Operation duration in milliseconds */
    duration?: number;
    /** Error object if applicable */
    error?: unknown;
    /** Cache hit/miss/stale status */
    cacheStatus?: string;
    /** TTL value in seconds */
    ttl?: number;
    /** Request method */
    method?: string;
    /** Additional context data */
    [key: string]: unknown;
}
type WebCache = globalThis.Cache;
type WebCacheQueryOptions = globalThis.CacheQueryOptions;
type WebCacheStorage = globalThis.CacheStorage;
type WebRequest = globalThis.Request;
type WebRequestInit = globalThis.RequestInit;
/**
 * Configuration options for SharedCache instances.
 * These options control caching behavior and key generation.
 */
interface SharedCacheOptions {
    /**
     * Cache namespace for organizing cached responses.
     * Used internally to distinguish between different cache instances.
     * @internal
     */
    _cacheName?: string;
    /**
     * Rules for generating cache keys from requests.
     * Controls which parts of the request are used in the cache key.
     */
    cacheKeyRules?: SharedCacheKeyRules;
    /**
     * Custom functions for generating cache key parts.
     * Allows extending cache key generation with custom logic.
     */
    cacheKeyPartDefiners?: SharedCacheKeyPartDefiners;
    /**
     * Custom logger for debugging and monitoring cache operations.
     */
    logger?: Logger;
}
/**
 * Key-Value storage interface for cache persistence.
 * This abstraction allows different storage backends (memory, Redis, etc.).
 */
interface KVStorage {
    /**
     * Retrieve a value from storage.
     * @param cacheKey - The key to retrieve
     * @returns The stored value or undefined if not found
     */
    get: (cacheKey: string) => Promise<unknown | undefined>;
    /**
     * Store a value in storage with optional TTL.
     * @param cacheKey - The key to store
     * @param value - The value to store
     * @param ttl - Time to live in seconds (optional)
     */
    set: (cacheKey: string, value: unknown, ttl?: number) => Promise<void>;
    /**
     * Delete a value from storage.
     * @param cacheKey - The key to delete
     * @returns True if the key was deleted, false if it didn't exist
     */
    delete: (cacheKey: string) => Promise<boolean>;
}
/**
 * Cache status values as defined in HTTP caching standards.
 * These represent the result of cache operations.
 */
type SharedCacheStatus = 
/** Cache hit - response served from cache */
'HIT'
/** Cache miss - response fetched from origin */
 | 'MISS'
/** Cached response expired, fetched fresh response */
 | 'EXPIRED'
/** Stale response served (stale-while-revalidate) */
 | 'STALE'
/** Cache bypassed due to cache-control directives */
 | 'BYPASS'
/** Cached response revalidated and still fresh */
 | 'REVALIDATED'
/** Dynamic response that cannot be cached */
 | 'DYNAMIC';
/**
 * Extended cache query options for shared cache operations.
 * Extends standard SharedCacheQueryOptions with shared cache specific options.
 */
type SharedCacheQueryOptions = WebCacheQueryOptions & {
    /**
     * Internal option to ignore request cache control headers.
     * @internal
     */
    _ignoreRequestCacheControl?: boolean;
    /**
     * Internal fetch function override.
     * @internal
     */
    _fetch?: typeof globalThis.fetch;
    /**
     * Internal waitUntil function for background operations.
     * @internal
     */
    _waitUntil?: (promise: Promise<unknown>) => void;
};
/**
 * Type alias for fetch function compatible with shared cache.
 */
type SharedCacheFetch = (input: SharedCacheRequestInfo | URL, init?: SharedCacheRequestInit) => Promise<Response>;
type SharedCacheRequestInfo = Request | string;
type SharedCacheRequestInit = WebRequestInit & {
    sharedCache?: SharedCacheRequestInitProperties;
};
type SharedCacheRequest = WebRequest & {
    sharedCache?: SharedCacheRequestInitProperties;
};
/**
 * Shared cache specific request properties.
 * These properties control cache behavior on a per-request basis.
 */
interface SharedCacheRequestInitProperties {
    /**
     * Override the cache-control header for caching decisions.
     * This allows forcing specific cache behavior regardless of origin headers.
     */
    cacheControlOverride?: string;
    /**
     * Custom cache key rules for this specific request.
     * Overrides default cache key generation rules.
     */
    cacheKeyRules?: SharedCacheKeyRules;
    /**
     * Whether to ignore request cache-control headers.
     * When true, request cache-control directives are ignored.
     */
    ignoreRequestCacheControl?: boolean;
    /**
     * Whether to ignore Vary header processing.
     * When true, Vary header is not considered for cache key generation.
     */
    ignoreVary?: boolean;
    /**
     * Override the vary header for this request.
     * Allows custom vary behavior regardless of response headers.
     */
    varyOverride?: string;
    /**
     * Function to handle background operations (like stale-while-revalidate).
     * Called with promises that should be awaited in the background.
     */
    waitUntil?: (promise: Promise<unknown>) => void;
}

/**
 * SharedCache implements the Cache interface with additional features for shared caching.
 * It provides HTTP-compliant caching with support for revalidation, stale-while-revalidate,
 * and custom cache key generation.
 *
 * This implementation follows HTTP caching semantics as defined in RFC 7234 and related specifications.
 */
declare class SharedCache implements WebCache {
    #private;
    /**
     * Creates a new SharedCache instance.
     *
     * @param storage - The key-value storage backend for persistence
     * @param options - Configuration options for cache behavior
     * @throws {TypeError} When storage is not provided
     */
    constructor(storage: KVStorage, options?: SharedCacheOptions);
    /**
     * The add() method is not implemented in this cache implementation.
     * This method is part of the Cache interface but not commonly used in practice.
     *
     * @param _request - The request to add (unused)
     * @throws {Error} Always throws as this method is not implemented
     */
    add(_request: SharedCacheRequestInfo): Promise<void>;
    /**
     * The addAll() method is not implemented in this cache implementation.
     * This method is part of the Cache interface but not commonly used in practice.
     *
     * @param _requests - The requests to add (unused)
     * @throws {Error} Always throws as this method is not implemented
     */
    addAll(_requests: SharedCacheRequestInfo[]): Promise<void>;
    /**
     * The delete() method of the Cache interface finds the Cache entry whose key
     * matches the request, and if found, deletes the Cache entry and returns a Promise
     * that resolves to true. If no Cache entry is found, it resolves to false.
     *
     * This implementation follows the algorithm specified in the Cache API specification:
     * https://w3c.github.io/ServiceWorker/#cache-delete
     *
     * @param request - The Request for which you are looking to delete. This can be a Request object or a URL.
     * @param options - An object whose properties control how matching is done in the delete operation.
     * @returns A Promise that resolves to true if the cache entry is deleted, or false otherwise.
     */
    delete(request: SharedCacheRequestInfo, options?: SharedCacheQueryOptions): Promise<boolean>;
    /**
     * The keys() method is not implemented in this cache implementation.
     * This method would return all Request objects that serve as keys for cached responses.
     *
     * @param _request - Optional request to match against (unused)
     * @param _options - Optional query options (unused)
     * @throws {Error} Always throws as this method is not implemented
     */
    keys(_request?: SharedCacheRequestInfo, _options?: SharedCacheQueryOptions): Promise<readonly SharedCacheRequest[]>;
    /**
     * The match() method of the Cache interface returns a Promise that resolves
     * to the Response associated with the first matching request in the Cache
     * object. If no match is found, the Promise resolves to undefined.
     *
     * This implementation includes advanced features:
     * - HTTP cache validation (ETag, Last-Modified)
     * - Stale-while-revalidate support
     * - Custom cache key generation
     * - Proper Vary header handling
     *
     * @param request - The Request for which you are attempting to find responses in the Cache.
     *                  This can be a Request object or a URL.
     * @param options - An object that sets options for the match operation.
     * @returns A Promise that resolves to the first Response that matches the request
     *          or to undefined if no match is found.
     */
    match(request: SharedCacheRequestInfo, options?: SharedCacheQueryOptions): Promise<Response | undefined>;
    /**
     * The matchAll() method is not implemented in this cache implementation.
     * This method would return all matching responses for a given request.
     *
     * @param _request - Optional request to match against (unused)
     * @param _options - Optional query options (unused)
     * @throws {Error} Always throws as this method is not implemented
     */
    matchAll(_request?: SharedCacheRequestInfo, _options?: SharedCacheQueryOptions): Promise<readonly Response[]>;
    /**
     * The put() method of the Cache interface allows key/value pairs to be added
     * to the current Cache object.
     *
     * This implementation includes several HTTP-compliant validations:
     * - Only HTTP/HTTPS schemes are supported for GET requests
     * - 206 (Partial Content) responses are rejected
     * - Vary: * responses are rejected
     * - Body usage validation to prevent corruption
     *
     * @param request - The Request object or URL that you want to add to the cache.
     * @param response - The Response you want to match up to the request.
     * @throws {TypeError} For various validation failures as per Cache API specification
     */
    put(request: SharedCacheRequestInfo, response: Response): Promise<void>;
}

/**
 * SharedCacheStorage implements the CacheStorage interface for managing multiple named caches.
 *
 * This implementation provides a shared cache storage system that maintains multiple
 * named cache instances backed by a single key-value storage system. It follows the
 * Web API CacheStorage specification while adding shared caching capabilities.
 *
 * Features:
 * - Named cache management with automatic instance creation
 * - Shared storage backend across all cache instances
 * - Lazy cache initialization for better performance
 * - Memory-efficient cache instance reuse
 *
 * @example
 * ```typescript
 * import { CacheStorage } from '@web-widget/shared-cache';
 * const storage = new MyKVStorage();
 * const cacheStorage = new CacheStorage(storage);
 * const apiCache = await cacheStorage.open('api');
 * const staticCache = await cacheStorage.open('static');
 * ```
 */
declare class SharedCacheStorage implements WebCacheStorage {
    #private;
    /**
     * Creates a new SharedCacheStorage instance.
     *
     * @param storage - The key-value storage backend to use for all caches
     * @param options - Optional default configuration for created cache instances
     * @throws {TypeError} When storage is not provided
     */
    constructor(storage: KVStorage, options?: SharedCacheOptions);
    /**
     * Deletes a named cache and all its contents.
     *
     * This method removes a cache by name and cleans up all associated data.
     * The operation is atomic - either the entire cache is deleted or none of it.
     *
     * Note: This implementation is currently not available and will throw an error.
     * Future versions may implement cache deletion with proper cleanup of storage keys.
     *
     * @param _cacheName - The name of the cache to delete
     * @returns Promise resolving to true if cache was deleted, false if it didn't exist
     * @throws {Error} Always throws as this method is not yet implemented
     */
    delete(_cacheName: string): Promise<boolean>;
    /**
     * Checks if a named cache exists.
     *
     * This method determines whether a cache with the given name exists in storage.
     *
     * Note: This implementation is currently not available and will throw an error.
     * Future versions may implement cache existence checking.
     *
     * @param _cacheName - The name of the cache to check
     * @returns Promise resolving to true if cache exists, false otherwise
     * @throws {Error} Always throws as this method is not yet implemented
     */
    has(_cacheName: string): Promise<boolean>;
    /**
     * Returns all cache names.
     *
     * This method lists all cache names that exist in storage.
     *
     * Note: This implementation is currently not available and will throw an error.
     * Future versions may implement cache enumeration.
     *
     * @returns Promise resolving to array of cache names
     * @throws {Error} Always throws as this method is not yet implemented
     */
    keys(): Promise<string[]>;
    /**
     * Searches across all caches for a matching request.
     *
     * This method performs a cross-cache search to find a cached response
     * that matches the given request. It's useful for scenarios where
     * content might be cached in multiple named caches.
     *
     * Note: This implementation is currently not available and will throw an error.
     * Future versions may implement cross-cache matching.
     *
     * @param _request - The request to match against
     * @param _options - Optional query options for the search
     * @returns Promise resolving to matching response or undefined
     * @throws {Error} Always throws as this method is not yet implemented
     */
    match(_request: RequestInfo, _options?: MultiCacheQueryOptions): Promise<Response | undefined>;
    /**
     * Opens or creates a named cache instance.
     *
     * This method implements the CacheStorage.open() specification, returning
     * a Promise that resolves to a Cache object matching the given name.
     *
     * The implementation includes:
     * - Automatic cache instance creation for new names
     * - Instance reuse for existing cache names (singleton pattern)
     * - Proper cache configuration inheritance from storage options
     * - Memory-efficient lazy initialization
     *
     * Cache instances share the same storage backend but use prefixed keys
     * to maintain isolation between different named caches.
     *
     * @param cacheName - The name of the cache to open or create
     * @returns Promise resolving to the requested SharedCache instance
     *
     * @example
     * ```typescript
     * const apiCache = await cacheStorage.open('api-v1');
     * const staticCache = await cacheStorage.open('static-assets');
     * // Same cache name returns the same instance
     * const sameCache = await cacheStorage.open('api-v1');
     * console.log(apiCache === sameCache); // true
     * ```
     */
    open(cacheName: string): Promise<SharedCache>;
}

/**
 * Creates a fetch function with shared caching capabilities.
 *
 * This is the internal implementation that powers the `createFetch` export.
 * Users should import and use `createFetch` instead of this function directly.
 *
 * This function implements HTTP caching semantics on top of the standard fetch API,
 * providing automatic cache management with support for:
 * - HTTP cache semantics (RFC 7234)
 * - Conditional requests and revalidation
 * - Stale-while-revalidate patterns
 * - Custom cache control and vary header overrides
 *
 * The returned fetch function is compatible with the standard fetch API while
 * adding transparent caching capabilities.
 *
 * @param cache - Optional SharedCache instance (defaults to global cache if available)
 * @param options - Configuration options
 * @param options.fetch - Custom fetch implementation (defaults to global fetch)
 * @param options.defaults - Default shared cache options to apply to all requests
 * @returns A fetch function with caching capabilities
 *
 * @example
 * ```typescript
 * import { createFetch, CacheStorage } from '@web-widget/shared-cache';
 * import { LRUCache } from 'lru-cache';
 *
 * // Set up cache storage
 * const caches = new CacheStorage(createLRUStorage());
 * const cache = await caches.open('api-cache');
 *
 * // Create cached fetch with default options
 * const fetch = createFetch(cache, {
 *   defaults: {
 *     cacheControlOverride: 's-maxage=300',
 *     ignoreRequestCacheControl: true,
 *   }
 * });
 *
 * // Use the cached fetch
 * const response = await fetch('/api/data');
 * console.log(response.headers.get('x-cache-status')); // "MISS" or "HIT"
 * ```
 */
declare function createSharedCacheFetch(cache?: SharedCache, options?: {
    /** Custom fetch implementation to use as the underlying fetcher */
    fetch?: typeof globalThis.fetch;
    /** Default shared cache options to apply to all requests */
    defaults?: Partial<SharedCacheRequestInitProperties>;
}): SharedCacheFetch;
/**
 * Default shared cache fetch instance using global cache.
 *
 * This is a convenience export that creates a shared cache fetch function
 * using the default configuration. It will automatically use the global
 * cache storage if available.
 *
 * @deprecated
 */
declare const sharedCacheFetch: SharedCacheFetch;

/**
 * HTTP header name for cache status information.
 * This non-standard header is used to communicate cache hit/miss status.
 */
declare const CACHE_STATUS_HEADERS_NAME = "x-cache-status";
/**
 * Cache status constants as defined in HTTP caching specifications.
 * These represent the various states of cache operations.
 */
/** Response served from cache without validation */
declare const HIT: SharedCacheStatus;
/** Response not found in cache, fetched from origin */
declare const MISS: SharedCacheStatus;
/** Cached response was expired, fresh response fetched */
declare const EXPIRED: SharedCacheStatus;
/** Stale response served (e.g., during stale-while-revalidate) */
declare const STALE: SharedCacheStatus;
/** Cache was bypassed due to cache-control directives */
declare const BYPASS: SharedCacheStatus;
/** Cached response was revalidated and determined still fresh */
declare const REVALIDATED: SharedCacheStatus;
/** Response is dynamic and cannot be cached */
declare const DYNAMIC: SharedCacheStatus;

export { BYPASS, CACHE_STATUS_HEADERS_NAME, CANNOT_INCLUDE_HEADERS, SharedCache as Cache, SharedCacheStorage as CacheStorage, DEFAULT_CACHE_KEY_RULES, DYNAMIC, EXPIRED, type FilterOptions, HIT, type KVStorage, LogLevel, type Logger, MISS, REVALIDATED, STALE, type SharedCacheFetch, type SharedCacheKeyPartDefiners, type SharedCacheKeyRules, type SharedCacheLogContext, SharedCacheLogger, type SharedCacheOptions, type SharedCacheQueryOptions, type SharedCacheRequestInitProperties, type SharedCacheStatus, StructuredLogger, cookie, createCacheKeyGenerator, createSharedCacheFetch as createFetch, createLogger, createSharedCacheLogger, device, sharedCacheFetch as fetch, filter, header, host, pathname, search, vary };