@tekir/cache 0.1.8 → 0.1.10

package/dist/stores/database.js

@@ -1,129 +0,0 @@
-/**
- * Database-backed cache store using a SQLite/SQL table with optional TTL.
- * The table is created automatically on first use.
- *
- * @example
- * ```ts
- * const store = new DatabaseCacheStore(db, 'cache')
- * await store.set('key', { foo: 'bar' }, 300)
- * ```
- */
-export class DatabaseCacheStore {
-    db;
-    table;
-    _ready = false;
-    /**
-     * Create a new DatabaseCacheStore.
-     *
-     * @param db - A database client with `exec`, `run`, and `queryOne` methods.
-     * @param table - The SQL table name for storing cache entries. Defaults to `'cache'`.
-     * @throws Error if the table name contains invalid characters.
-     */
-    constructor(db, table = 'cache') {
-        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table))
-            throw new Error(`Invalid table name: "${table}"`);
-        this.db = db;
-        this.table = table;
-    }
-    async _ensureTable() {
-        if (this._ready)
-            return;
-        try {
-            await this.db.exec(`CREATE TABLE IF NOT EXISTS "${this.table}" (key TEXT PRIMARY KEY, value TEXT, expires_at INTEGER)`);
-            this._ready = true;
-        }
-        catch (e) {
-            // Don't silently swallow: an unset _ready means every later get/set blows
-            // up with a confusing SQL error. Surface the real cause and rethrow so the
-            // misconfiguration is visible at the point of failure.
-            console.error(`[@tekir/cache] Failed to create cache table "${this.table}": ${e.message}`);
-            throw e;
-        }
-    }
-    /**
-     * Retrieve a cached value by key. Expired entries are deleted and `null` is returned.
-     *
-     * @param key - The cache key.
-     * @returns The stored value parsed from JSON, or `null`.
-     */
-    async get(key) {
-        await this._ensureTable();
-        const row = await this.db.queryOne(`SELECT value, expires_at FROM "${this.table}" WHERE key = ?`, [key]);
-        if (!row)
-            return null;
-        if (row.expires_at && Date.now() > row.expires_at) {
-            await this.db.run(`DELETE FROM "${this.table}" WHERE key = ?`, [key]);
-            return null;
-        }
-        try {
-            return JSON.parse(row.value);
-        }
-        catch {
-            return row.value;
-        }
-    }
-    /**
-     * Store a value under the given key, reptekirg any existing entry.
-     *
-     * @param key - The cache key.
-     * @param value - The value to cache (serialized to JSON).
-     * @param ttlSeconds - Time-to-live in seconds. Omit for no expiration.
-     */
-    async set(key, value, ttlSeconds) {
-        await this._ensureTable();
-        const val = JSON.stringify(value);
-        const expiresAt = ttlSeconds ? Date.now() + ttlSeconds * 1000 : null;
-        await this.db.run(`INSERT OR REPLACE INTO "${this.table}" (key, value, expires_at) VALUES (?, ?, ?)`, [key, val, expiresAt]);
-    }
-    /**
-     * Check whether a key exists and is not expired.
-     *
-     * @param key - The cache key.
-     * @returns `true` if the key exists and has not expired.
-     */
-    async has(key) {
-        await this._ensureTable();
-        const row = await this.db.queryOne(`SELECT expires_at FROM "${this.table}" WHERE key = ?`, [key]);
-        if (!row)
-            return false;
-        if (row.expires_at && Date.now() > row.expires_at) {
-            await this.db.run(`DELETE FROM "${this.table}" WHERE key = ?`, [key]);
-            return false;
-        }
-        // Present even if the stored value is `null` (negative caching).
-        return true;
-    }
-    /**
-     * Delete a key from the database.
-     *
-     * @param key - The cache key to remove.
-     * @returns Always returns `true`.
-     */
-    async delete(key) {
-        await this._ensureTable();
-        await this.db.run(`DELETE FROM "${this.table}" WHERE key = ?`, [key]);
-        return true;
-    }
-    /**
-     * Delete all expired entries. Entries are otherwise only removed when read,
-     * so call this periodically to stop never-read expired rows from accumulating.
-     *
-     * @returns A promise that resolves once expired rows have been removed.
-     */
-    async prune() {
-        await this._ensureTable();
-        await this.db.run(`DELETE FROM "${this.table}" WHERE expires_at IS NOT NULL AND expires_at < ?`, [Date.now()]);
-    }
-    /**
-     * Remove all entries from the cache table.
-     *
-     * @example
-     * ```ts
-     * await store.flush()
-     * ```
-     */
-    async flush() {
-        await this._ensureTable();
-        await this.db.run(`DELETE FROM "${this.table}"`);
-    }
-}

package/dist/stores/memory.js

@@ -1,108 +0,0 @@
-/**
- * In-memory cache store with optional TTL expiration. Data is stored in a Map
- * and lost when the process exits. Ideal for development and testing.
- *
- * @example
- * ```ts
- * const store = new MemoryCacheStore()
- * await store.set('key', 'value', 60)
- * const val = await store.get<string>('key') // 'value'
- * ```
- */
-export class MemoryCacheStore {
-    data = new Map();
-    maxEntries;
-    writes = 0;
-    /**
-     * @param options.maxEntries - Hard cap on stored entries. When exceeded, the
-     *   oldest insertion-order entry is evicted (after pruning expired ones).
-     *   Defaults to 10000 to bound memory growth from never-read keys. Set to 0
-     *   to disable the cap.
-     */
-    constructor(options = {}) {
-        this.maxEntries = options.maxEntries ?? 10000;
-    }
-    /** Remove every entry whose TTL has elapsed. */
-    prune() {
-        const now = Date.now();
-        for (const [k, entry] of this.data) {
-            if (entry.expiresAt && now > entry.expiresAt)
-                this.data.delete(k);
-        }
-    }
-    /**
-     * Retrieve a cached value by key. Returns `null` if the key does not exist
-     * or has expired.
-     *
-     * @param key - The cache key.
-     * @returns The stored value cast to `T`, or `null`.
-     */
-    async get(key) {
-        const entry = this.data.get(key);
-        if (!entry)
-            return null;
-        if (entry.expiresAt && Date.now() > entry.expiresAt) {
-            this.data.delete(key);
-            return null;
-        }
-        return entry.value;
-    }
-    /**
-     * Store a value under the given key with an optional TTL.
-     *
-     * @param key - The cache key.
-     * @param value - The value to cache.
-     * @param ttlSeconds - Time-to-live in seconds. Omit for no expiration.
-     */
-    async set(key, value, ttlSeconds) {
-        this.data.set(key, {
-            value,
-            expiresAt: ttlSeconds ? Date.now() + ttlSeconds * 1000 : null,
-        });
-        // Periodically sweep expired entries so keys that are never read again don't
-        // accumulate unbounded, then enforce the size cap.
-        if (this.maxEntries > 0) {
-            if (++this.writes % 256 === 0)
-                this.prune();
-            while (this.data.size > this.maxEntries) {
-                const oldest = this.data.keys().next().value;
-                if (oldest === undefined)
-                    break;
-                this.data.delete(oldest);
-            }
-        }
-    }
-    /**
-     * Check whether a key exists and is not expired.
-     *
-     * @param key - The cache key.
-     * @returns `true` if the key exists and has not expired.
-     */
-    async has(key) {
-        // Check the map directly so an explicitly stored `null` value still counts
-        // as present (get() alone can't distinguish stored-null from absent).
-        const entry = this.data.get(key);
-        if (!entry)
-            return false;
-        if (entry.expiresAt && Date.now() > entry.expiresAt) {
-            this.data.delete(key);
-            return false;
-        }
-        return true;
-    }
-    /**
-     * Delete a key from the store.
-     *
-     * @param key - The cache key to remove.
-     * @returns `true` if the key was present and deleted.
-     */
-    async delete(key) {
-        return this.data.delete(key);
-    }
-    /**
-     * Remove all entries from the store.
-     */
-    async flush() {
-        this.data.clear();
-    }
-}

package/dist/stores/redis.js

@@ -1,143 +0,0 @@
-/**
- * Redis-backed cache store with key prefixing and optional TTL.
- * Delegates all operations to a Redis client and prefixes keys to avoid collisions.
- *
- * @example
- * ```ts
- * const store = new RedisCacheStore(redisClient, 'app:cache:')
- * await store.set('user:1', { name: 'Alice' }, 300)
- * const user = await store.get<{ name: string }>('user:1')
- * ```
- */
-export class RedisCacheStore {
-    redis;
-    prefix;
-    /**
-     * Create a new RedisCacheStore.
-     *
-     * @param redis - A Redis client implementing the {@link RedisClient} interface.
-     * @param prefix - A string prepended to every cache key. Defaults to `'cache:'`.
-     */
-    constructor(redis, prefix = 'cache:') {
-        this.redis = redis;
-        this.prefix = prefix;
-    }
-    /**
-     * Retrieve a cached value by key. Returns `null` if the key does not exist.
-     * The stored JSON string is parsed back into the original type.
-     *
-     * @param key - The cache key (without prefix).
-     * @returns The stored value cast to `T`, or `null` if not found.
-     *
-     * @example
-     * ```ts
-     * const value = await store.get<string>('greeting') // 'hello' or null
-     * ```
-     */
-    async get(key) {
-        const val = await this.redis.get(this.prefix + key);
-        if (val === null)
-            return null;
-        try {
-            return JSON.parse(val);
-        }
-        catch {
-            return val;
-        }
-    }
-    /**
-     * Store a value under the given key with an optional TTL.
-     * The value is serialized to JSON before being sent to Redis.
-     *
-     * @param key - The cache key (without prefix).
-     * @param value - The value to cache (serialized to JSON).
-     * @param ttlSeconds - Time-to-live in seconds. Omit for no expiration.
-     *
-     * @example
-     * ```ts
-     * await store.set('token', 'abc123', 3600) // expires in 1 hour
-     * ```
-     */
-    async set(key, value, ttlSeconds) {
-        const val = JSON.stringify(value);
-        const fullKey = this.prefix + key;
-        if (ttlSeconds) {
-            const sendable = this.redis;
-            if (typeof sendable.send === "function") {
-                // Atomic SET ... EX so a crash between SET and EXPIRE can never leave a
-                // permanent (TTL-less) key behind.
-                await sendable.send("SET", [fullKey, val, "EX", String(Math.floor(ttlSeconds))]);
-            }
-            else {
-                // Fallback for clients without a raw `send`: best-effort two-step.
-                await this.redis.set(fullKey, val);
-                await this.redis.expire(fullKey, ttlSeconds);
-            }
-        }
-        else {
-            await this.redis.set(fullKey, val);
-        }
-    }
-    /**
-     * Check whether a key exists in Redis.
-     *
-     * @param key - The cache key (without prefix).
-     * @returns `true` if the key exists.
-     *
-     * @example
-     * ```ts
-     * if (await store.has('session:abc')) { ... }
-     * ```
-     */
-    async has(key) {
-        // Coerces both shapes: @tekir/redis returns boolean, node-redis/ioredis
-        // return number. `!!0` → false, `!!1` → true, `!!true` → true.
-        return !!(await this.redis.exists(this.prefix + key));
-    }
-    /**
-     * Delete a key from Redis.
-     *
-     * @param key - The cache key (without prefix) to remove.
-     * @returns Always returns `true`.
-     *
-     * @example
-     * ```ts
-     * await store.delete('expired-token')
-     * ```
-     */
-    async delete(key) {
-        await this.redis.del(this.prefix + key);
-        return true;
-    }
-    /**
-     * Remove only this store's keys (those under its prefix) using a non-blocking
-     * SCAN + DEL. This no longer flushes the entire Redis database, so data owned
-     * by other stores sharing the same database (sessions, queues, ...) is left
-     * intact.
-     *
-     * If the prefix is empty (which would match every key) this throws rather than
-     * risk wiping unrelated data; configure a non-empty prefix to use flush.
-     *
-     * @example
-     * ```ts
-     * await store.flush()
-     * ```
-     */
-    async flush() {
-        if (!this.prefix) {
-            throw new Error('[@tekir/cache] RedisCacheStore.flush() refused: an empty prefix would delete every key in the database. Configure a non-empty prefix.');
-        }
-        // Structural cast: callers may pass clients with varying `send` arg
-        // types. We only need it to accept a string command and an array.
-        const client = this.redis;
-        const pattern = `${this.prefix}*`;
-        let cursor = '0';
-        do {
-            const reply = (await client.send('SCAN', [cursor, 'MATCH', pattern, 'COUNT', '100']));
-            const [next, batch] = reply;
-            cursor = next;
-            if (batch && batch.length)
-                await client.send('DEL', batch);
-        } while (cursor !== '0');
-    }
-}

package/dist/types.js

@@ -1 +0,0 @@
-export {};