@revealui/cache 0.0.0-canary-20260409021642

package/dist/index.d.ts

@@ -0,0 +1,448 @@
+import { C as CacheStore } from './types-CmU1eRbl.js';
+export { a as CacheEntry } from './types-CmU1eRbl.js';
+import { NextRequest, NextResponse } from 'next/server';
+
+/**
+ * CDN Configuration and Cache Management
+ *
+ * Utilities for CDN caching, edge caching, and cache invalidation
+ */
+/**
+ * CDN Cache Configuration
+ */
+interface CDNCacheConfig {
+    provider?: 'cloudflare' | 'vercel' | 'fastly' | 'custom';
+    zones?: string[];
+    ttl?: number;
+    staleWhileRevalidate?: number;
+    staleIfError?: number;
+    bypassCache?: boolean;
+    cacheKey?: string[];
+    varyHeaders?: string[];
+}
+declare const DEFAULT_CDN_CONFIG: CDNCacheConfig;
+/**
+ * Generate Cache-Control header
+ */
+declare function generateCacheControl(config: {
+    maxAge?: number;
+    sMaxAge?: number;
+    staleWhileRevalidate?: number;
+    staleIfError?: number;
+    public?: boolean;
+    private?: boolean;
+    immutable?: boolean;
+    noCache?: boolean;
+    noStore?: boolean;
+}): string;
+/**
+ * Cache presets for different asset types
+ */
+declare const CDN_CACHE_PRESETS: {
+    readonly immutable: {
+        readonly maxAge: 31536000;
+        readonly sMaxAge: 31536000;
+        readonly public: true;
+        readonly immutable: true;
+    };
+    readonly static: {
+        readonly maxAge: 2592000;
+        readonly sMaxAge: 31536000;
+        readonly staleWhileRevalidate: 86400;
+        readonly public: true;
+    };
+    readonly api: {
+        readonly maxAge: 0;
+        readonly sMaxAge: 60;
+        readonly staleWhileRevalidate: 30;
+        readonly public: true;
+    };
+    readonly page: {
+        readonly maxAge: 0;
+        readonly sMaxAge: 300;
+        readonly staleWhileRevalidate: 60;
+        readonly public: true;
+    };
+    readonly private: {
+        readonly maxAge: 300;
+        readonly private: true;
+        readonly staleWhileRevalidate: 60;
+    };
+    readonly noCache: {
+        readonly noStore: true;
+    };
+    readonly revalidate: {
+        readonly maxAge: 0;
+        readonly sMaxAge: 0;
+        readonly noCache: true;
+    };
+};
+/**
+ * CDN Purge Configuration
+ */
+interface CDNPurgeConfig {
+    provider: 'cloudflare' | 'vercel' | 'fastly';
+    apiKey?: string;
+    apiSecret?: string;
+    zoneId?: string;
+    distributionId?: string;
+}
+/**
+ * Purge CDN cache
+ */
+declare function purgeCDNCache(urls: string[], config: CDNPurgeConfig): Promise<{
+    success: boolean;
+    purged: number;
+    errors?: string[];
+}>;
+/**
+ * Purge by cache tag
+ */
+declare function purgeCacheByTag(tags: string[], config: CDNPurgeConfig): Promise<{
+    success: boolean;
+    purged: number;
+    errors?: string[];
+}>;
+/**
+ * Purge everything
+ */
+declare function purgeAllCache(config: CDNPurgeConfig): Promise<{
+    success: boolean;
+    errors?: string[];
+}>;
+/**
+ * CDN cache warming
+ */
+declare function warmCDNCache(urls: string[], options?: {
+    concurrency?: number;
+    headers?: Record<string, string>;
+}): Promise<{
+    warmed: number;
+    failed: number;
+    errors: string[];
+}>;
+/**
+ * Generate cache tags
+ */
+declare function generateCacheTags(resource: {
+    type: string;
+    id?: string | number;
+    related?: string[];
+}): string[];
+/**
+ * Edge cache configuration for Vercel
+ */
+declare function generateVercelCacheConfig(preset: keyof typeof CDN_CACHE_PRESETS): {
+    headers: {
+        'Cache-Control': string;
+        'CDN-Cache-Control': string;
+        'Vercel-CDN-Cache-Control': string;
+    };
+};
+/**
+ * Edge cache configuration for Cloudflare
+ */
+declare function generateCloudflareConfig(preset: keyof typeof CDN_CACHE_PRESETS, options?: {
+    cacheTags?: string[];
+    bypassOnCookie?: string;
+}): {
+    headers: Record<string, string>;
+};
+/**
+ * Check if response should be cached
+ */
+declare function shouldCacheResponse(status: number, headers: Headers): boolean;
+/**
+ * Calculate cache TTL from headers
+ */
+declare function getCacheTTL(headers: Headers): number;
+
+/**
+ * Edge Caching and ISR (Incremental Static Regeneration)
+ *
+ * Utilities for Next.js edge caching, ISR, and on-demand revalidation
+ */
+
+/**
+ * Next.js extends the standard RequestInit with a `next` property
+ * for ISR revalidation and cache tags.
+ */
+interface NextFetchRequestInit extends RequestInit {
+    next?: {
+        revalidate?: number | false;
+        tags?: string[];
+    };
+}
+/**
+ * ISR Configuration
+ */
+interface ISRConfig {
+    revalidate?: number | false;
+    tags?: string[];
+    dynamicParams?: boolean;
+}
+declare const ISR_PRESETS: {
+    readonly always: {
+        readonly revalidate: 0;
+    };
+    readonly minute: {
+        readonly revalidate: 60;
+    };
+    readonly fiveMinutes: {
+        readonly revalidate: 300;
+    };
+    readonly hourly: {
+        readonly revalidate: 3600;
+    };
+    readonly daily: {
+        readonly revalidate: 86400;
+    };
+    readonly never: {
+        readonly revalidate: false;
+    };
+};
+/**
+ * Generate static params for ISR
+ */
+declare function generateStaticParams<T>(fetchFn: () => Promise<T[]>, mapFn: (item: T) => Record<string, string>): Promise<Array<Record<string, string>>>;
+/**
+ * Revalidate tag
+ */
+declare function revalidateTag(tag: string, secret?: string): Promise<{
+    revalidated: boolean;
+    error?: string;
+}>;
+/**
+ * Revalidate path
+ */
+declare function revalidatePath(path: string, secret?: string): Promise<{
+    revalidated: boolean;
+    error?: string;
+}>;
+/**
+ * Revalidate multiple paths
+ */
+declare function revalidatePaths(paths: string[], secret?: string): Promise<{
+    revalidated: number;
+    failed: number;
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}>;
+/**
+ * Revalidate multiple tags
+ */
+declare function revalidateTags(tags: string[], secret?: string): Promise<{
+    revalidated: number;
+    failed: number;
+    errors: Array<{
+        tag: string;
+        error: string;
+    }>;
+}>;
+/**
+ * Edge middleware cache configuration
+ */
+interface EdgeCacheConfig {
+    cache?: 'force-cache' | 'no-cache' | 'no-store' | 'only-if-cached';
+    next?: {
+        revalidate?: number | false;
+        tags?: string[];
+    };
+}
+/**
+ * Create edge cached fetch
+ */
+declare function createEdgeCachedFetch(config?: EdgeCacheConfig): <T>(url: string, options?: NextFetchRequestInit) => Promise<T>;
+/**
+ * Unstable cache wrapper (Next.js 14+)
+ */
+declare function createCachedFunction<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, options?: {
+    tags?: string[];
+    revalidate?: number | false;
+}): (...args: TArgs) => Promise<TReturn>;
+/**
+ * Edge rate limiting with cache
+ */
+interface EdgeRateLimitConfig {
+    limit: number;
+    window: number;
+    key?: (request: NextRequest) => string;
+}
+declare class EdgeRateLimiter {
+    private config;
+    private cache;
+    constructor(config: EdgeRateLimitConfig);
+    /**
+     * Check rate limit
+     */
+    check(request: NextRequest): {
+        allowed: boolean;
+        limit: number;
+        remaining: number;
+        reset: number;
+    };
+    /**
+     * Clean up expired entries
+     */
+    cleanup(): void;
+}
+/**
+ * Edge geolocation caching
+ */
+interface GeoLocation {
+    country?: string;
+    region?: string;
+    city?: string;
+    latitude?: number;
+    longitude?: number;
+}
+declare function getGeoLocation(request: NextRequest): GeoLocation | null;
+/**
+ * Edge A/B testing with cache
+ */
+declare function getABTestVariant(request: NextRequest, testName: string, variants: string[]): string;
+/**
+ * Edge personalization cache
+ */
+interface PersonalizationConfig {
+    userId?: string;
+    preferences?: Record<string, unknown>;
+    location?: GeoLocation;
+    device?: 'mobile' | 'tablet' | 'desktop';
+    variant?: string;
+}
+declare function getPersonalizationConfig(request: NextRequest): PersonalizationConfig;
+/**
+ * Edge cache headers helper
+ */
+declare function setEdgeCacheHeaders(response: NextResponse, config: {
+    maxAge?: number;
+    sMaxAge?: number;
+    staleWhileRevalidate?: number;
+    tags?: string[];
+}): NextResponse;
+/**
+ * Preload links for critical resources
+ */
+declare function addPreloadLinks(response: NextResponse, resources: Array<{
+    href: string;
+    as: string;
+    type?: string;
+    crossorigin?: boolean;
+}>): NextResponse;
+/**
+ * Cache warming for ISR pages
+ */
+declare function warmISRCache(paths: string[], baseURL?: string): Promise<{
+    warmed: number;
+    failed: number;
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}>;
+
+/**
+ * Cache Invalidation Channel
+ *
+ * Coordinates cache invalidation across instances using a shared database table.
+ * Events are written to `_cache_invalidation_events` and consumed by polling.
+ *
+ * Architecture:
+ *   - Publisher: writes invalidation event to shared PGlite/PostgreSQL table
+ *   - Subscriber: polls the table for new events and forwards to local CacheStore
+ *   - Events auto-expire after TTL to prevent unbounded table growth
+ *
+ * Future: Replace polling with ElectricSQL shape subscriptions or LISTEN/NOTIFY
+ * for real-time push-based invalidation (Phase 5.10C/E).
+ */
+
+type InvalidationEventType = 'delete' | 'delete-prefix' | 'delete-tags' | 'clear';
+interface InvalidationEvent {
+    id: string;
+    type: InvalidationEventType;
+    /** Cache keys to delete (for 'delete' type). */
+    keys?: string[];
+    /** Prefix to match (for 'delete-prefix' type). */
+    prefix?: string;
+    /** Tags to match (for 'delete-tags' type). */
+    tags?: string[];
+    /** Instance ID that published the event (for deduplication). */
+    sourceInstance: string;
+    /** Timestamp when the event was created. */
+    createdAt: number;
+}
+interface InvalidationChannelOptions {
+    /** Unique instance identifier (used to skip self-published events). */
+    instanceId: string;
+    /** Poll interval in milliseconds (default: 5000). */
+    pollIntervalMs?: number;
+    /** Event TTL in seconds — events older than this are pruned (default: 60). */
+    eventTtlSeconds?: number;
+}
+interface PGliteInstance {
+    exec(query: string): Promise<unknown>;
+    query<T = Record<string, unknown>>(query: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+    close(): Promise<void>;
+}
+declare class CacheInvalidationChannel {
+    private db;
+    private store;
+    private instanceId;
+    private pollIntervalMs;
+    private eventTtlSeconds;
+    private lastSeenTimestamp;
+    /** IDs processed at exactly lastSeenTimestamp (prevents re-processing on >= query). */
+    private processedAtBoundary;
+    private pollTimer;
+    private ready;
+    constructor(db: PGliteInstance, store: CacheStore, options: InvalidationChannelOptions);
+    private init;
+    /** Start polling for invalidation events. */
+    start(): Promise<void>;
+    /** Stop polling. */
+    stop(): void;
+    /** Publish a key deletion event. */
+    publishDelete(...keys: string[]): Promise<void>;
+    /** Publish a prefix deletion event. */
+    publishDeletePrefix(prefix: string): Promise<void>;
+    /** Publish a tag-based deletion event. */
+    publishDeleteTags(tags: string[]): Promise<void>;
+    /** Publish a clear-all event. */
+    publishClear(): Promise<void>;
+    private publish;
+    /** Poll for new events and apply them to the local cache store. */
+    poll(): Promise<number>;
+    private applyEvent;
+    /** Remove events older than the TTL. */
+    private prune;
+    /** Release resources. */
+    close(): Promise<void>;
+}
+
+/**
+ * Internal logger for @revealui/cache.
+ *
+ * Defaults to `console`. Consumers should call `configureCacheLogger()`
+ * to supply a structured logger (e.g. from `@revealui/utils/logger`).
+ */
+interface CacheLogger {
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+/**
+ * Replace the default console logger with a structured logger.
+ */
+declare function configureCacheLogger(logger: CacheLogger): void;
+/**
+ * Get the current cache logger instance.
+ */
+declare function getCacheLogger(): CacheLogger;
+
+export { type CDNCacheConfig, type CDNPurgeConfig, CDN_CACHE_PRESETS, CacheInvalidationChannel, type CacheLogger, CacheStore, DEFAULT_CDN_CONFIG, type EdgeCacheConfig, type EdgeRateLimitConfig, EdgeRateLimiter, type GeoLocation, type ISRConfig, ISR_PRESETS, type InvalidationChannelOptions, type InvalidationEvent, type InvalidationEventType, type PersonalizationConfig, addPreloadLinks, configureCacheLogger, createCachedFunction, createEdgeCachedFetch, generateCacheControl, generateCacheTags, generateCloudflareConfig, generateStaticParams, generateVercelCacheConfig, getABTestVariant, getCacheLogger, getCacheTTL, getGeoLocation, getPersonalizationConfig, purgeAllCache, purgeCDNCache, purgeCacheByTag, revalidatePath, revalidatePaths, revalidateTag, revalidateTags, setEdgeCacheHeaders, shouldCacheResponse, warmCDNCache, warmISRCache };