raffel 0.1.2

package/dist/cache/drivers/redis.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Redis Cache Driver
+ *
+ * Duck-typed Redis driver that works with any Redis-like client.
+ * Supports ioredis, node-redis, and other compatible clients.
+ *
+ * Features:
+ * - Works with any Redis-compatible client
+ * - Key prefixing for namespacing
+ * - Optional compression
+ * - Automatic TTL handling
+ */
+import type { CacheDriver, CacheGetResult, CacheStats, RedisDriverOptions } from '../types.js';
+/**
+ * Redis Cache Driver
+ *
+ * @example With ioredis
+ * ```typescript
+ * import Redis from 'ioredis'
+ *
+ * const redis = new Redis()
+ * const cache = new RedisDriver({ client: redis })
+ *
+ * await cache.set('key', { data: 'value' }, 60000)
+ * const result = await cache.get('key')
+ * ```
+ *
+ * @example With node-redis
+ * ```typescript
+ * import { createClient } from 'redis'
+ *
+ * const redis = createClient()
+ * await redis.connect()
+ *
+ * const cache = new RedisDriver({ client: redis })
+ * ```
+ */
+export declare class RedisDriver implements CacheDriver {
+    readonly name = "redis";
+    private readonly client;
+    private readonly prefix;
+    private readonly compressionEnabled;
+    private readonly compressionThreshold;
+    private _stats;
+    constructor(options: RedisDriverOptions);
+    /**
+     * Get a cached entry
+     */
+    get(key: string): Promise<CacheGetResult | undefined>;
+    /**
+     * Set a cached entry
+     */
+    set(key: string, value: unknown, ttlMs: number, tags?: string[]): Promise<void>;
+    /**
+     * Delete a cached entry
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all cached entries, or those matching a prefix
+     */
+    clear(prefix?: string): Promise<void>;
+    /**
+     * Check if a key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Get all keys matching a pattern
+     */
+    keys(pattern?: string): Promise<string[]>;
+    /**
+     * Get cache statistics
+     */
+    stats(): CacheStats;
+    /**
+     * Shutdown the driver
+     */
+    shutdown(): Promise<void>;
+    private getFullKey;
+}
+/**
+ * Create a Redis cache driver
+ */
+export declare function createRedisDriver(options: RedisDriverOptions): CacheDriver;
+//# sourceMappingURL=redis.d.ts.map

package/dist/cache/drivers/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../../src/cache/drivers/redis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EACV,WAAW,EAEX,cAAc,EACd,UAAU,EACV,kBAAkB,EAEnB,MAAM,aAAa,CAAA;AAapB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,WAAY,YAAW,WAAW;IAC7C,QAAQ,CAAC,IAAI,WAAU;IAEvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAQ;IAG7C,OAAO,CAAC,MAAM,CAMb;gBAEW,OAAO,EAAE,kBAAkB;IAWvC;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IA2C3D;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAuCrF;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC;;OAEG;IACG,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B3C;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBxC;;OAEG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgB/C;;OAEG;IACH,KAAK,IAAI,UAAU;IAWnB;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAU/B,OAAO,CAAC,UAAU;CAGnB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAE1E"}

package/dist/cache/drivers/redis.js

@@ -0,0 +1,243 @@
+/**
+ * Redis Cache Driver
+ *
+ * Duck-typed Redis driver that works with any Redis-like client.
+ * Supports ioredis, node-redis, and other compatible clients.
+ *
+ * Features:
+ * - Works with any Redis-compatible client
+ * - Key prefixing for namespacing
+ * - Optional compression
+ * - Automatic TTL handling
+ */
+import zlib from 'node:zlib';
+/**
+ * Redis Cache Driver
+ *
+ * @example With ioredis
+ * ```typescript
+ * import Redis from 'ioredis'
+ *
+ * const redis = new Redis()
+ * const cache = new RedisDriver({ client: redis })
+ *
+ * await cache.set('key', { data: 'value' }, 60000)
+ * const result = await cache.get('key')
+ * ```
+ *
+ * @example With node-redis
+ * ```typescript
+ * import { createClient } from 'redis'
+ *
+ * const redis = createClient()
+ * await redis.connect()
+ *
+ * const cache = new RedisDriver({ client: redis })
+ * ```
+ */
+export class RedisDriver {
+    name = 'redis';
+    client;
+    prefix;
+    compressionEnabled;
+    compressionThreshold;
+    // Stats
+    _stats = {
+        hits: 0,
+        misses: 0,
+        sets: 0,
+        deletes: 0,
+        evictions: 0,
+    };
+    constructor(options) {
+        if (!options.client) {
+            throw new Error('[RedisDriver] Redis client is required');
+        }
+        this.client = options.client;
+        this.prefix = options.prefix ?? 'raffel:cache:';
+        this.compressionEnabled = options.compression ?? false;
+        this.compressionThreshold = 1024;
+    }
+    /**
+     * Get a cached entry
+     */
+    async get(key) {
+        try {
+            const fullKey = this.getFullKey(key);
+            const data = await this.client.get(fullKey);
+            if (!data) {
+                this._stats.misses++;
+                return undefined;
+            }
+            const redisEntry = JSON.parse(data);
+            // Check expiration (Redis handles TTL, but double-check)
+            if (Date.now() > redisEntry.expiresAt) {
+                await this.client.del(fullKey);
+                this._stats.misses++;
+                return undefined;
+            }
+            // Decompress if needed
+            let value = redisEntry.value;
+            if (redisEntry.compressed && typeof value === 'string') {
+                const buffer = Buffer.from(value, 'base64');
+                const decompressed = zlib.gunzipSync(buffer);
+                value = JSON.parse(decompressed.toString('utf8'));
+            }
+            this._stats.hits++;
+            const entry = {
+                value,
+                expiresAt: redisEntry.expiresAt,
+                createdAt: redisEntry.createdAt,
+                tags: redisEntry.tags,
+            };
+            return { entry, stale: false };
+        }
+        catch {
+            this._stats.misses++;
+            return undefined;
+        }
+    }
+    /**
+     * Set a cached entry
+     */
+    async set(key, value, ttlMs, tags) {
+        const now = Date.now();
+        const fullKey = this.getFullKey(key);
+        let finalValue = value;
+        let compressed = false;
+        // Compress if enabled
+        if (this.compressionEnabled) {
+            const serialized = JSON.stringify(value);
+            if (serialized.length >= this.compressionThreshold) {
+                const buffer = Buffer.from(serialized, 'utf8');
+                const compressedBuffer = zlib.gzipSync(buffer);
+                finalValue = compressedBuffer.toString('base64');
+                compressed = true;
+            }
+        }
+        const redisEntry = {
+            value: finalValue,
+            expiresAt: now + ttlMs,
+            createdAt: now,
+            tags,
+            compressed,
+        };
+        const serialized = JSON.stringify(redisEntry);
+        const ttlSeconds = Math.ceil(ttlMs / 1000);
+        // Use SETEX if available, otherwise SET with EX
+        if (this.client.setex) {
+            await this.client.setex(fullKey, ttlSeconds, serialized);
+        }
+        else {
+            await this.client.set(fullKey, serialized, 'EX', ttlSeconds);
+        }
+        this._stats.sets++;
+    }
+    /**
+     * Delete a cached entry
+     */
+    async delete(key) {
+        const fullKey = this.getFullKey(key);
+        await this.client.del(fullKey);
+        this._stats.deletes++;
+    }
+    /**
+     * Clear all cached entries, or those matching a prefix
+     */
+    async clear(prefix) {
+        const pattern = prefix ? `${this.prefix}${prefix}*` : `${this.prefix}*`;
+        try {
+            // Try using SCAN for large datasets
+            if (this.client.scan) {
+                let cursor = '0';
+                do {
+                    const [nextCursor, keys] = await this.client.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+                    cursor = nextCursor;
+                    if (keys.length > 0) {
+                        await this.client.del(keys);
+                    }
+                } while (cursor !== '0');
+            }
+            else if (this.client.keys) {
+                // Fallback to KEYS (not recommended for large datasets)
+                const keys = await this.client.keys(pattern);
+                if (keys.length > 0) {
+                    await this.client.del(keys);
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    /**
+     * Check if a key exists
+     */
+    async has(key) {
+        const fullKey = this.getFullKey(key);
+        try {
+            const data = await this.client.get(fullKey);
+            if (!data)
+                return false;
+            const redisEntry = JSON.parse(data);
+            if (Date.now() > redisEntry.expiresAt) {
+                await this.client.del(fullKey);
+                return false;
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get all keys matching a pattern
+     */
+    async keys(pattern) {
+        const fullPattern = pattern ? `${this.prefix}${pattern}` : `${this.prefix}*`;
+        const prefixLength = this.prefix.length;
+        try {
+            if (this.client.keys) {
+                const keys = await this.client.keys(fullPattern);
+                return keys.map((k) => k.slice(prefixLength));
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+        return [];
+    }
+    /**
+     * Get cache statistics
+     */
+    stats() {
+        const total = this._stats.hits + this._stats.misses;
+        const hitRate = total > 0 ? this._stats.hits / total : 0;
+        return {
+            ...this._stats,
+            hitRate,
+            totalItems: 0, // Would require SCAN to count
+        };
+    }
+    /**
+     * Shutdown the driver
+     */
+    async shutdown() {
+        if (this.client.quit) {
+            await this.client.quit();
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Private methods
+    // ─────────────────────────────────────────────────────────────────
+    getFullKey(key) {
+        return `${this.prefix}${key}`;
+    }
+}
+/**
+ * Create a Redis cache driver
+ */
+export function createRedisDriver(options) {
+    return new RedisDriver(options);
+}
+//# sourceMappingURL=redis.js.map

package/dist/cache/drivers/redis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.js","sourceRoot":"","sources":["../../../src/cache/drivers/redis.ts"],"names":[],"mappings":"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"}

package/dist/cache/drivers/s3db.d.ts

@@ -0,0 +1,78 @@
+/**
+ * S3DB Cache Driver
+ *
+ * Uses S3DB (S3-based document database) as a cache backend.
+ * Ideal for serverless environments or when you need persistent,
+ * distributed caching with S3's durability.
+ *
+ * Features:
+ * - S3's durability and availability
+ * - Works with S3-compatible storage (AWS, MinIO, R2, etc.)
+ * - Optional compression
+ * - Distributed cache out of the box
+ */
+import type { CacheDriver, CacheGetResult, CacheStats, S3DBDriverOptions } from '../types.js';
+/**
+ * S3DB Cache Driver
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { S3DB } from 's3db.js'
+ *
+ * const s3db = new S3DB({
+ *   bucket: 'my-cache-bucket',
+ *   region: 'us-east-1',
+ * })
+ *
+ * const cache = new S3DBDriver({ s3db })
+ *
+ * await cache.set('key', { data: 'value' }, 60000)
+ * const result = await cache.get('key')
+ * ```
+ */
+export declare class S3DBDriver implements CacheDriver {
+    readonly name = "s3db";
+    private readonly s3db;
+    private readonly resource;
+    private readonly compressionEnabled;
+    private readonly compressionThreshold;
+    private _stats;
+    constructor(options: S3DBDriverOptions);
+    /**
+     * Get a cached entry
+     */
+    get(key: string): Promise<CacheGetResult | undefined>;
+    /**
+     * Set a cached entry
+     */
+    set(key: string, value: unknown, ttlMs: number, tags?: string[]): Promise<void>;
+    /**
+     * Delete a cached entry
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all cached entries, or those matching a prefix
+     */
+    clear(prefix?: string): Promise<void>;
+    /**
+     * Check if a key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Get all keys matching a pattern
+     */
+    keys(pattern?: string): Promise<string[]>;
+    /**
+     * Get cache statistics
+     */
+    stats(): CacheStats;
+    /**
+     * Shutdown the driver
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Create an S3DB cache driver
+ */
+export declare function createS3DBDriver(options: S3DBDriverOptions): CacheDriver;
+//# sourceMappingURL=s3db.d.ts.map

package/dist/cache/drivers/s3db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3db.d.ts","sourceRoot":"","sources":["../../../src/cache/drivers/s3db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EACV,WAAW,EAEX,cAAc,EACd,UAAU,EACV,iBAAiB,EAElB,MAAM,aAAa,CAAA;AAapB;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,UAAW,YAAW,WAAW;IAC5C,QAAQ,CAAC,IAAI,UAAS;IAEtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAQ;IAG7C,OAAO,CAAC,MAAM,CAMb;gBAEW,OAAO,EAAE,iBAAiB;IAWtC;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IA2C3D;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCrF;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxC;;OAEG;IACG,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB3C;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBxC;;OAEG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgB/C;;OAEG;IACH,KAAK,IAAI,UAAU;IAWnB;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,WAAW,CAExE"}

package/dist/cache/drivers/s3db.js

@@ -0,0 +1,216 @@
+/**
+ * S3DB Cache Driver
+ *
+ * Uses S3DB (S3-based document database) as a cache backend.
+ * Ideal for serverless environments or when you need persistent,
+ * distributed caching with S3's durability.
+ *
+ * Features:
+ * - S3's durability and availability
+ * - Works with S3-compatible storage (AWS, MinIO, R2, etc.)
+ * - Optional compression
+ * - Distributed cache out of the box
+ */
+import zlib from 'node:zlib';
+/**
+ * S3DB Cache Driver
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { S3DB } from 's3db.js'
+ *
+ * const s3db = new S3DB({
+ *   bucket: 'my-cache-bucket',
+ *   region: 'us-east-1',
+ * })
+ *
+ * const cache = new S3DBDriver({ s3db })
+ *
+ * await cache.set('key', { data: 'value' }, 60000)
+ * const result = await cache.get('key')
+ * ```
+ */
+export class S3DBDriver {
+    name = 's3db';
+    s3db;
+    resource;
+    compressionEnabled;
+    compressionThreshold;
+    // Stats
+    _stats = {
+        hits: 0,
+        misses: 0,
+        sets: 0,
+        deletes: 0,
+        evictions: 0,
+    };
+    constructor(options) {
+        if (!options.s3db) {
+            throw new Error('[S3DBDriver] S3DB instance is required');
+        }
+        this.s3db = options.s3db;
+        this.resource = options.resource ?? 'cache';
+        this.compressionEnabled = options.compression ?? false;
+        this.compressionThreshold = 1024;
+    }
+    /**
+     * Get a cached entry
+     */
+    async get(key) {
+        try {
+            const data = await this.s3db.get(this.resource, key);
+            if (!data) {
+                this._stats.misses++;
+                return undefined;
+            }
+            const s3dbEntry = data;
+            // Check expiration
+            if (Date.now() > s3dbEntry.expiresAt) {
+                // Expired - delete and return undefined
+                await this.s3db.delete(this.resource, key).catch(() => { });
+                this._stats.misses++;
+                return undefined;
+            }
+            // Decompress if needed
+            let value = s3dbEntry.value;
+            if (s3dbEntry.compressed && typeof value === 'string') {
+                const buffer = Buffer.from(value, 'base64');
+                const decompressed = zlib.gunzipSync(buffer);
+                value = JSON.parse(decompressed.toString('utf8'));
+            }
+            this._stats.hits++;
+            const entry = {
+                value,
+                expiresAt: s3dbEntry.expiresAt,
+                createdAt: s3dbEntry.createdAt,
+                tags: s3dbEntry.tags,
+            };
+            return { entry, stale: false };
+        }
+        catch {
+            this._stats.misses++;
+            return undefined;
+        }
+    }
+    /**
+     * Set a cached entry
+     */
+    async set(key, value, ttlMs, tags) {
+        const now = Date.now();
+        let finalValue = value;
+        let compressed = false;
+        // Compress if enabled
+        if (this.compressionEnabled) {
+            const serialized = JSON.stringify(value);
+            if (serialized.length >= this.compressionThreshold) {
+                const buffer = Buffer.from(serialized, 'utf8');
+                const compressedBuffer = zlib.gzipSync(buffer);
+                finalValue = compressedBuffer.toString('base64');
+                compressed = true;
+            }
+        }
+        const s3dbEntry = {
+            value: finalValue,
+            expiresAt: now + ttlMs,
+            createdAt: now,
+            tags,
+            compressed,
+        };
+        await this.s3db.set(this.resource, key, s3dbEntry, {
+            // S3DB might support TTL natively
+            ttl: ttlMs,
+        });
+        this._stats.sets++;
+    }
+    /**
+     * Delete a cached entry
+     */
+    async delete(key) {
+        await this.s3db.delete(this.resource, key);
+        this._stats.deletes++;
+    }
+    /**
+     * Clear all cached entries, or those matching a prefix
+     */
+    async clear(prefix) {
+        try {
+            if (!prefix && this.s3db.clear) {
+                // Clear all
+                await this.s3db.clear(this.resource);
+            }
+            else if (this.s3db.list) {
+                // List and delete matching entries
+                const items = (await this.s3db.list(this.resource, {
+                    prefix,
+                }));
+                for (const item of items) {
+                    await this.s3db.delete(this.resource, item.id);
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    /**
+     * Check if a key exists
+     */
+    async has(key) {
+        try {
+            const data = await this.s3db.get(this.resource, key);
+            if (!data)
+                return false;
+            const s3dbEntry = data;
+            if (Date.now() > s3dbEntry.expiresAt) {
+                await this.s3db.delete(this.resource, key).catch(() => { });
+                return false;
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get all keys matching a pattern
+     */
+    async keys(pattern) {
+        try {
+            if (this.s3db.list) {
+                const items = (await this.s3db.list(this.resource, {
+                    prefix: pattern,
+                }));
+                return items.map((item) => item.id);
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+        return [];
+    }
+    /**
+     * Get cache statistics
+     */
+    stats() {
+        const total = this._stats.hits + this._stats.misses;
+        const hitRate = total > 0 ? this._stats.hits / total : 0;
+        return {
+            ...this._stats,
+            hitRate,
+            totalItems: 0, // Would require listing to count
+        };
+    }
+    /**
+     * Shutdown the driver
+     */
+    async shutdown() {
+        // S3DB doesn't need explicit shutdown
+    }
+}
+/**
+ * Create an S3DB cache driver
+ */
+export function createS3DBDriver(options) {
+    return new S3DBDriver(options);
+}
+//# sourceMappingURL=s3db.js.map

package/dist/cache/drivers/s3db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3db.js","sourceRoot":"","sources":["../../../src/cache/drivers/s3db.ts"],"names":[],"mappings":"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"}