recker 1.0.26 → 1.0.27-next.8396df6

package/dist/browser/cache/memory-storage.d.ts

@@ -0,0 +1,132 @@
+import { CacheEntry, CacheStorage } from '../types/index.js';
+export interface CompressionConfig {
+    enabled: boolean;
+    threshold?: number;
+}
+export interface MemoryStorageOptions {
+    maxSize?: number;
+    maxMemoryBytes?: number;
+    maxMemoryPercent?: number;
+    ttl?: number;
+    evictionPolicy?: 'lru' | 'fifo';
+    compression?: boolean | CompressionConfig;
+    enableStats?: boolean;
+    monitorInterval?: number;
+    heapUsageThreshold?: number;
+    cleanupInterval?: number;
+    onEvict?: (info: EvictionInfo) => void;
+    onPressure?: (info: PressureInfo) => void;
+}
+export interface EvictionInfo {
+    reason: 'size' | 'memory' | 'heap' | 'expired';
+    key?: string;
+    freedBytes: number;
+    currentBytes: number;
+    maxMemoryBytes: number;
+}
+export interface PressureInfo {
+    reason: 'limit' | 'heap';
+    heapLimit: number;
+    heapUsed: number;
+    heapRatio?: number;
+    currentBytes: number;
+    maxMemoryBytes: number;
+    freedBytes: number;
+}
+export interface CacheStats {
+    enabled: boolean;
+    hits: number;
+    misses: number;
+    sets: number;
+    deletes: number;
+    evictions: number;
+    hitRate: number;
+    totalItems: number;
+    memoryUsageBytes: number;
+    maxMemoryBytes: number;
+    evictedDueToMemory: number;
+}
+export interface MemoryStats {
+    currentMemoryBytes: number;
+    maxMemoryBytes: number;
+    maxMemoryPercent: number;
+    memoryUsagePercent: number;
+    cachePercentOfSystemMemory: number;
+    totalItems: number;
+    maxSize: number;
+    evictedDueToMemory: number;
+    memoryPressureEvents: number;
+    averageItemSize: number;
+    memoryUsage: {
+        current: string;
+        max: string;
+        available: string;
+    };
+    systemMemory: {
+        total: string;
+        free: string;
+        used: string;
+        cachePercent: string;
+    };
+}
+export interface CompressionStats {
+    enabled: boolean;
+    totalItems: number;
+    compressedItems: number;
+    compressionThreshold: number;
+    totalOriginalSize: number;
+    totalCompressedSize: number;
+    averageCompressionRatio: string;
+    spaceSavingsPercent: string;
+    memoryUsage: {
+        uncompressed: string;
+        compressed: string;
+        saved: string;
+    };
+}
+export declare class MemoryStorage implements CacheStorage {
+    private storage;
+    private meta;
+    private readonly maxSize;
+    private readonly maxMemoryBytes;
+    private readonly maxMemoryPercent;
+    private readonly defaultTtl;
+    private readonly evictionPolicy;
+    private readonly compressionEnabled;
+    private readonly compressionThreshold;
+    private readonly enableStats;
+    private readonly heapUsageThreshold;
+    private readonly onEvict?;
+    private readonly onPressure?;
+    private currentMemoryBytes;
+    private evictedDueToMemory;
+    private memoryPressureEvents;
+    private accessCounter;
+    private monitorHandle;
+    private cleanupHandle;
+    private stats;
+    private compressionStats;
+    constructor(options?: MemoryStorageOptions);
+    get(key: string): Promise<CacheEntry | undefined>;
+    set(key: string, entry: CacheEntry, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(prefix?: string): void;
+    size(): number;
+    keys(): string[];
+    has(key: string): boolean;
+    getStats(): CacheStats;
+    getMemoryStats(): MemoryStats;
+    getCompressionStats(): CompressionStats;
+    shutdown(): void;
+    private deleteInternal;
+    private recordStat;
+    private isCompressed;
+    private compress;
+    private decompress;
+    private selectEvictionCandidate;
+    private evictOne;
+    private enforceMemoryLimit;
+    private reduceMemoryTo;
+    private memoryHealthCheck;
+    private cleanupExpired;
+}

package/dist/browser/cache/memory-storage.js

@@ -0,0 +1,454 @@
+import { ConfigurationError } from '../core/errors.js';
+import zlib from 'node:zlib';
+import os from 'node:os';
+import { getEffectiveTotalMemoryBytes, resolveCacheMemoryLimit, formatBytes, getHeapStats, } from './memory-limits.js';
+export class MemoryStorage {
+    storage = new Map();
+    meta = new Map();
+    maxSize;
+    maxMemoryBytes;
+    maxMemoryPercent;
+    defaultTtl;
+    evictionPolicy;
+    compressionEnabled;
+    compressionThreshold;
+    enableStats;
+    heapUsageThreshold;
+    onEvict;
+    onPressure;
+    currentMemoryBytes = 0;
+    evictedDueToMemory = 0;
+    memoryPressureEvents = 0;
+    accessCounter = 0;
+    monitorHandle = null;
+    cleanupHandle = null;
+    stats = {
+        hits: 0,
+        misses: 0,
+        sets: 0,
+        deletes: 0,
+        evictions: 0,
+    };
+    compressionStats = {
+        totalCompressed: 0,
+        totalOriginalSize: 0,
+        totalCompressedSize: 0,
+    };
+    constructor(options = {}) {
+        if (options.maxMemoryBytes &&
+            options.maxMemoryBytes > 0 &&
+            options.maxMemoryPercent &&
+            options.maxMemoryPercent > 0) {
+            throw new ConfigurationError('[MemoryStorage] Cannot use both maxMemoryBytes and maxMemoryPercent', { configKey: 'maxMemoryBytes|maxMemoryPercent' });
+        }
+        if (options.maxMemoryPercent !== undefined &&
+            (options.maxMemoryPercent < 0 || options.maxMemoryPercent > 1)) {
+            throw new ConfigurationError('[MemoryStorage] maxMemoryPercent must be between 0 and 1', { configKey: 'maxMemoryPercent' });
+        }
+        this.maxSize = options.maxSize ?? 1000;
+        this.defaultTtl = options.ttl ?? 300000;
+        this.evictionPolicy = options.evictionPolicy ?? 'lru';
+        this.enableStats = options.enableStats ?? false;
+        this.heapUsageThreshold = options.heapUsageThreshold ?? 0.6;
+        if (options.maxMemoryBytes && options.maxMemoryBytes > 0) {
+            this.maxMemoryBytes = options.maxMemoryBytes;
+            this.maxMemoryPercent = 0;
+        }
+        else if (options.maxMemoryPercent && options.maxMemoryPercent > 0) {
+            const effectiveTotal = getEffectiveTotalMemoryBytes();
+            this.maxMemoryBytes = Math.floor(effectiveTotal * options.maxMemoryPercent);
+            this.maxMemoryPercent = options.maxMemoryPercent;
+        }
+        else {
+            const resolved = resolveCacheMemoryLimit({});
+            this.maxMemoryBytes = resolved.maxMemoryBytes;
+            this.maxMemoryPercent = resolved.inferredPercent ?? 0;
+        }
+        if (options.compression === true) {
+            this.compressionEnabled = true;
+            this.compressionThreshold = 1024;
+        }
+        else if (typeof options.compression === 'object' &&
+            options.compression.enabled) {
+            this.compressionEnabled = true;
+            this.compressionThreshold = options.compression.threshold ?? 1024;
+        }
+        else {
+            this.compressionEnabled = false;
+            this.compressionThreshold = 1024;
+        }
+        this.onEvict = options.onEvict;
+        this.onPressure = options.onPressure;
+        const monitorInterval = options.monitorInterval ?? 15000;
+        if (monitorInterval > 0) {
+            this.monitorHandle = setInterval(() => this.memoryHealthCheck(), monitorInterval);
+            this.monitorHandle.unref();
+        }
+        const cleanupInterval = options.cleanupInterval ?? 60000;
+        if (cleanupInterval > 0) {
+            this.cleanupHandle = setInterval(() => this.cleanupExpired(), cleanupInterval);
+            this.cleanupHandle.unref();
+        }
+    }
+    async get(key) {
+        const data = this.storage.get(key);
+        const metadata = this.meta.get(key);
+        if (!data || !metadata) {
+            this.recordStat('misses');
+            return undefined;
+        }
+        const now = Date.now();
+        if (now > metadata.expiresAt) {
+            this.deleteInternal(key);
+            this.recordStat('misses');
+            return undefined;
+        }
+        if (this.evictionPolicy === 'lru') {
+            metadata.lastAccess = now;
+            metadata.accessOrder = ++this.accessCounter;
+        }
+        this.recordStat('hits');
+        if (this.isCompressed(data)) {
+            try {
+                const decompressed = this.decompress(data);
+                return JSON.parse(decompressed);
+            }
+            catch {
+                this.deleteInternal(key);
+                return undefined;
+            }
+        }
+        return JSON.parse(data);
+    }
+    async set(key, entry, ttl) {
+        const effectiveTtl = ttl ?? this.defaultTtl;
+        const now = Date.now();
+        const serialized = JSON.stringify(entry);
+        const originalSize = Buffer.byteLength(serialized, 'utf8');
+        let finalData = serialized;
+        let compressedSize = originalSize;
+        let compressed = false;
+        if (this.compressionEnabled && originalSize >= this.compressionThreshold) {
+            try {
+                const result = this.compress(serialized);
+                finalData = result;
+                compressedSize = Buffer.byteLength(result.__data, 'utf8');
+                compressed = true;
+                this.compressionStats.totalCompressed++;
+                this.compressionStats.totalOriginalSize += originalSize;
+                this.compressionStats.totalCompressedSize += compressedSize;
+            }
+            catch {
+            }
+        }
+        const existingMeta = this.meta.get(key);
+        if (existingMeta) {
+            this.currentMemoryBytes -= existingMeta.compressedSize;
+        }
+        if (!this.enforceMemoryLimit(compressedSize)) {
+            this.evictedDueToMemory++;
+            return;
+        }
+        if (!existingMeta && this.storage.size >= this.maxSize) {
+            this.evictOne('size');
+        }
+        this.storage.set(key, finalData);
+        this.meta.set(key, {
+            createdAt: now,
+            expiresAt: now + effectiveTtl,
+            lastAccess: now,
+            insertOrder: ++this.accessCounter,
+            accessOrder: this.accessCounter,
+            compressed,
+            originalSize,
+            compressedSize,
+        });
+        this.currentMemoryBytes += compressedSize;
+        this.recordStat('sets');
+    }
+    async delete(key) {
+        this.deleteInternal(key);
+        this.recordStat('deletes');
+    }
+    clear(prefix) {
+        if (!prefix) {
+            this.storage.clear();
+            this.meta.clear();
+            this.currentMemoryBytes = 0;
+            this.evictedDueToMemory = 0;
+            if (this.enableStats) {
+                this.stats = { hits: 0, misses: 0, sets: 0, deletes: 0, evictions: 0 };
+            }
+            return;
+        }
+        for (const key of this.storage.keys()) {
+            if (key.startsWith(prefix)) {
+                this.deleteInternal(key);
+            }
+        }
+    }
+    size() {
+        return this.storage.size;
+    }
+    keys() {
+        return Array.from(this.storage.keys());
+    }
+    has(key) {
+        const meta = this.meta.get(key);
+        if (!meta)
+            return false;
+        if (Date.now() > meta.expiresAt) {
+            this.deleteInternal(key);
+            return false;
+        }
+        return true;
+    }
+    getStats() {
+        const total = this.stats.hits + this.stats.misses;
+        const hitRate = total > 0 ? this.stats.hits / total : 0;
+        return {
+            enabled: this.enableStats,
+            ...this.stats,
+            hitRate,
+            totalItems: this.storage.size,
+            memoryUsageBytes: this.currentMemoryBytes,
+            maxMemoryBytes: this.maxMemoryBytes,
+            evictedDueToMemory: this.evictedDueToMemory,
+        };
+    }
+    getMemoryStats() {
+        const totalItems = this.storage.size;
+        const memoryUsagePercent = this.maxMemoryBytes > 0
+            ? (this.currentMemoryBytes / this.maxMemoryBytes) * 100
+            : 0;
+        const systemTotal = os.totalmem();
+        const systemFree = os.freemem();
+        const systemUsed = systemTotal - systemFree;
+        const cachePercentOfSystem = systemTotal > 0 ? (this.currentMemoryBytes / systemTotal) * 100 : 0;
+        return {
+            currentMemoryBytes: this.currentMemoryBytes,
+            maxMemoryBytes: this.maxMemoryBytes,
+            maxMemoryPercent: this.maxMemoryPercent,
+            memoryUsagePercent: parseFloat(memoryUsagePercent.toFixed(2)),
+            cachePercentOfSystemMemory: parseFloat(cachePercentOfSystem.toFixed(2)),
+            totalItems,
+            maxSize: this.maxSize,
+            evictedDueToMemory: this.evictedDueToMemory,
+            memoryPressureEvents: this.memoryPressureEvents,
+            averageItemSize: totalItems > 0 ? Math.round(this.currentMemoryBytes / totalItems) : 0,
+            memoryUsage: {
+                current: formatBytes(this.currentMemoryBytes),
+                max: formatBytes(this.maxMemoryBytes),
+                available: formatBytes(Math.max(0, this.maxMemoryBytes - this.currentMemoryBytes)),
+            },
+            systemMemory: {
+                total: formatBytes(systemTotal),
+                free: formatBytes(systemFree),
+                used: formatBytes(systemUsed),
+                cachePercent: `${cachePercentOfSystem.toFixed(2)}%`,
+            },
+        };
+    }
+    getCompressionStats() {
+        if (!this.compressionEnabled) {
+            return {
+                enabled: false,
+                totalItems: this.storage.size,
+                compressedItems: 0,
+                compressionThreshold: this.compressionThreshold,
+                totalOriginalSize: 0,
+                totalCompressedSize: 0,
+                averageCompressionRatio: '0',
+                spaceSavingsPercent: '0',
+                memoryUsage: {
+                    uncompressed: '0 B',
+                    compressed: '0 B',
+                    saved: '0 B',
+                },
+            };
+        }
+        const ratio = this.compressionStats.totalOriginalSize > 0
+            ? (this.compressionStats.totalCompressedSize /
+                this.compressionStats.totalOriginalSize).toFixed(2)
+            : '0';
+        const savings = this.compressionStats.totalOriginalSize > 0
+            ? (((this.compressionStats.totalOriginalSize -
+                this.compressionStats.totalCompressedSize) /
+                this.compressionStats.totalOriginalSize) *
+                100).toFixed(2)
+            : '0';
+        const saved = this.compressionStats.totalOriginalSize -
+            this.compressionStats.totalCompressedSize;
+        return {
+            enabled: true,
+            totalItems: this.storage.size,
+            compressedItems: this.compressionStats.totalCompressed,
+            compressionThreshold: this.compressionThreshold,
+            totalOriginalSize: this.compressionStats.totalOriginalSize,
+            totalCompressedSize: this.compressionStats.totalCompressedSize,
+            averageCompressionRatio: ratio,
+            spaceSavingsPercent: savings,
+            memoryUsage: {
+                uncompressed: formatBytes(this.compressionStats.totalOriginalSize),
+                compressed: formatBytes(this.compressionStats.totalCompressedSize),
+                saved: formatBytes(saved),
+            },
+        };
+    }
+    shutdown() {
+        if (this.monitorHandle) {
+            clearInterval(this.monitorHandle);
+            this.monitorHandle = null;
+        }
+        if (this.cleanupHandle) {
+            clearInterval(this.cleanupHandle);
+            this.cleanupHandle = null;
+        }
+    }
+    deleteInternal(key) {
+        const meta = this.meta.get(key);
+        if (meta) {
+            this.currentMemoryBytes -= meta.compressedSize;
+        }
+        this.storage.delete(key);
+        this.meta.delete(key);
+    }
+    recordStat(type) {
+        if (this.enableStats) {
+            this.stats[type]++;
+        }
+    }
+    isCompressed(data) {
+        return (typeof data === 'object' && data !== null && '__compressed' in data);
+    }
+    compress(data) {
+        const buffer = Buffer.from(data, 'utf8');
+        const compressed = zlib.gzipSync(buffer);
+        return {
+            __compressed: true,
+            __data: compressed.toString('base64'),
+            __originalSize: buffer.length,
+        };
+    }
+    decompress(data) {
+        const buffer = Buffer.from(data.__data, 'base64');
+        const decompressed = zlib.gunzipSync(buffer);
+        return decompressed.toString('utf8');
+    }
+    selectEvictionCandidate() {
+        if (this.meta.size === 0)
+            return null;
+        let candidate = null;
+        let candidateValue = this.evictionPolicy === 'lru' ? Infinity : Infinity;
+        for (const [key, meta] of this.meta) {
+            const value = this.evictionPolicy === 'lru' ? meta.accessOrder : meta.insertOrder;
+            if (value < candidateValue) {
+                candidateValue = value;
+                candidate = key;
+            }
+        }
+        return candidate;
+    }
+    evictOne(reason) {
+        const candidate = this.selectEvictionCandidate();
+        if (!candidate)
+            return null;
+        const meta = this.meta.get(candidate);
+        const freedBytes = meta?.compressedSize ?? 0;
+        this.deleteInternal(candidate);
+        this.stats.evictions++;
+        if (reason === 'memory' || reason === 'heap') {
+            this.evictedDueToMemory++;
+        }
+        this.onEvict?.({
+            reason,
+            key: candidate,
+            freedBytes,
+            currentBytes: this.currentMemoryBytes,
+            maxMemoryBytes: this.maxMemoryBytes,
+        });
+        return { key: candidate, freedBytes };
+    }
+    enforceMemoryLimit(incomingSize) {
+        if (incomingSize > this.maxMemoryBytes) {
+            return false;
+        }
+        while (this.currentMemoryBytes + incomingSize > this.maxMemoryBytes &&
+            this.storage.size > 0) {
+            const result = this.evictOne('memory');
+            if (!result)
+                break;
+        }
+        return this.currentMemoryBytes + incomingSize <= this.maxMemoryBytes;
+    }
+    reduceMemoryTo(targetBytes) {
+        targetBytes = Math.max(0, targetBytes);
+        let freedBytes = 0;
+        while (this.currentMemoryBytes > targetBytes && this.storage.size > 0) {
+            const result = this.evictOne('memory');
+            if (!result)
+                break;
+            freedBytes += result.freedBytes;
+        }
+        return freedBytes;
+    }
+    memoryHealthCheck() {
+        let totalFreed = 0;
+        if (this.currentMemoryBytes > this.maxMemoryBytes) {
+            const before = this.currentMemoryBytes;
+            this.enforceMemoryLimit(0);
+            const freed = before - this.currentMemoryBytes;
+            if (freed > 0) {
+                totalFreed += freed;
+                this.memoryPressureEvents++;
+                this.onPressure?.({
+                    reason: 'limit',
+                    heapLimit: getHeapStats().heapLimit,
+                    heapUsed: getHeapStats().heapUsed,
+                    currentBytes: this.currentMemoryBytes,
+                    maxMemoryBytes: this.maxMemoryBytes,
+                    freedBytes: freed,
+                });
+            }
+        }
+        const { heapUsed, heapLimit, heapRatio } = getHeapStats();
+        if (heapLimit > 0 && heapRatio >= this.heapUsageThreshold) {
+            const before = this.currentMemoryBytes;
+            const target = Math.floor(this.currentMemoryBytes * 0.5);
+            this.reduceMemoryTo(target);
+            const freed = before - this.currentMemoryBytes;
+            if (freed > 0) {
+                totalFreed += freed;
+                this.memoryPressureEvents++;
+                this.onPressure?.({
+                    reason: 'heap',
+                    heapLimit,
+                    heapUsed,
+                    heapRatio,
+                    currentBytes: this.currentMemoryBytes,
+                    maxMemoryBytes: this.maxMemoryBytes,
+                    freedBytes: freed,
+                });
+            }
+        }
+        return totalFreed;
+    }
+    cleanupExpired() {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [key, meta] of this.meta) {
+            if (now > meta.expiresAt) {
+                this.deleteInternal(key);
+                cleaned++;
+                this.onEvict?.({
+                    reason: 'expired',
+                    key,
+                    freedBytes: meta.compressedSize,
+                    currentBytes: this.currentMemoryBytes,
+                    maxMemoryBytes: this.maxMemoryBytes,
+                });
+            }
+        }
+        return cleaned;
+    }
+}

package/dist/browser/cache.d.ts

@@ -0,0 +1,40 @@
+export interface CacheEntry<T = unknown> {
+    key: string;
+    value: T;
+    createdAt: number;
+    expiresAt?: number;
+    etag?: string;
+    lastModified?: string;
+}
+export interface BrowserCacheOptions {
+    dbName?: string;
+    storeName?: string;
+    defaultTTL?: number;
+    maxEntries?: number;
+}
+export declare class IndexedDBStorage {
+    private dbName;
+    private storeName;
+    private defaultTTL;
+    private maxEntries;
+    private db;
+    private initPromise;
+    constructor(options?: BrowserCacheOptions);
+    init(): Promise<void>;
+    get<T = unknown>(key: string): Promise<CacheEntry<T> | null>;
+    set<T = unknown>(key: string, value: T, ttl?: number, metadata?: {
+        etag?: string;
+        lastModified?: string;
+    }): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    keys(): Promise<string[]>;
+    size(): Promise<number>;
+    cleanup(): Promise<number>;
+    private enforceMaxEntries;
+    close(): void;
+    destroy(): Promise<void>;
+}
+export declare function isIndexedDBAvailable(): boolean;
+export declare function getBrowserCacheStorage(options?: BrowserCacheOptions): IndexedDBStorage | null;