@tekir/cache 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tekir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+<p align="center">
+  <img src="https://tekir.io/logo.svg" width="80" alt="tekir" />
+</p>
+
+<h1 align="center">@tekir/cache</h1>
+
+<p align="center">In-memory, Redis, and database caching abstraction</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@tekir/cache"><img src="https://img.shields.io/npm/v/@tekir/cache.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@tekir/cache"><img src="https://img.shields.io/npm/dm/@tekir/cache.svg" alt="npm downloads" /></a>
+  <a href="https://github.com/tekir-io/tekir/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@tekir/cache.svg" alt="license" /></a>
+</p>
+
+<p align="center">
+  <a href="https://tekir.io">Website</a> · <a href="https://docs.tekir.io">Documentation</a> · <a href="https://github.com/tekir-io/tekir">GitHub</a>
+</p>
+
+---
+
+## Installation
+
+```bash
+bun add @tekir/cache
+```
+
+For full usage and configuration, see the [documentation](https://docs.tekir.io/advanced/cache).
+
+## License
+
+MIT

package/dist/cache.d.ts

@@ -0,0 +1,109 @@
+import type { CacheConfig, CacheStore } from './types';
+/**
+ * Multi-store cache manager that delegates to configured {@link CacheStore}
+ * implementations. Supports named stores, a default TTL, and convenience
+ * methods like {@link getOrSet} and {@link pull}.
+ *
+ * @example
+ * ```ts
+ * const cache = new Cache({ stores: { memory: new MemoryCacheStore() }, ttl: 60 })
+ * await cache.set('key', 'value')
+ * const val = await cache.get<string>('key')
+ * ```
+ */
+export declare class Cache {
+    private stores;
+    private defaultStore;
+    private defaultTtl;
+    /**
+     * Create a new Cache instance.
+     *
+     * @param config - Cache configuration including stores, default store name, and TTL.
+     */
+    constructor(config?: CacheConfig);
+    /**
+     * Retrieve a specific named store, or the default store if no name is given.
+     *
+     * @param name - The store name. Omit to use the default store.
+     * @returns The resolved {@link CacheStore} instance.
+     * @throws Error if the requested store is not configured.
+     *
+     * @example
+     * ```ts
+     * const redis = cache.store('redis')
+     * await redis.get('key')
+     * ```
+     */
+    store(name?: string): CacheStore;
+    /**
+     * Get a value from the default store.
+     *
+     * @param key - The cache key.
+     * @returns The cached value, or `null` if not found or expired.
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Set a value in the default store.
+     *
+     * @param key - The cache key.
+     * @param value - The value to store.
+     * @param ttl - Time-to-live in seconds. Falls back to the default TTL.
+     */
+    set(key: string, value: unknown, ttl?: number): Promise<void>;
+    /**
+     * Check whether a key exists (and is not expired) in the default store.
+     *
+     * @param key - The cache key.
+     * @returns `true` if the key exists.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Delete a key from the default store.
+     *
+     * @param key - The cache key.
+     * @returns `true` if the key was deleted.
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Flush all entries from the default store.
+     */
+    flush(): Promise<void>;
+    /**
+     * Get a cached value or compute and store it if missing. Inspired by AdonisJS.
+     *
+     * @param key - The cache key.
+     * @param ttl - Time-to-live in seconds for the computed value.
+     * @param factory - An async function that produces the value when not cached.
+     * @returns The cached or freshly-computed value.
+     *
+     * @example
+     * ```ts
+     * const users = await cache.getOrSet('users', 300, () => db.query('SELECT * FROM users'))
+     * ```
+     */
+    getOrSet<T>(key: string, ttl: number, factory: () => Promise<T>): Promise<T>;
+    /**
+     * Get a value and immediately delete it from the cache (atomic get-and-remove).
+     *
+     * @param key - The cache key.
+     * @returns The cached value, or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * const token = await cache.pull<string>('one-time-token')
+     * ```
+     */
+    pull<T = unknown>(key: string): Promise<T | null>;
+}
+/**
+ * Create a new {@link Cache} instance with the given configuration.
+ *
+ * @param config - Optional cache configuration.
+ * @returns A new Cache instance.
+ *
+ * @example
+ * ```ts
+ * const cache = createCache({ ttl: 120 })
+ * ```
+ */
+export declare function createCache(config?: CacheConfig): Cache;

package/dist/cache.js

@@ -0,0 +1,133 @@
+import { MemoryCacheStore } from './stores/memory';
+/**
+ * Multi-store cache manager that delegates to configured {@link CacheStore}
+ * implementations. Supports named stores, a default TTL, and convenience
+ * methods like {@link getOrSet} and {@link pull}.
+ *
+ * @example
+ * ```ts
+ * const cache = new Cache({ stores: { memory: new MemoryCacheStore() }, ttl: 60 })
+ * await cache.set('key', 'value')
+ * const val = await cache.get<string>('key')
+ * ```
+ */
+export class Cache {
+    stores;
+    defaultStore;
+    defaultTtl;
+    /**
+     * Create a new Cache instance.
+     *
+     * @param config - Cache configuration including stores, default store name, and TTL.
+     */
+    constructor(config = {}) {
+        this.stores = config.stores || { memory: new MemoryCacheStore() };
+        this.defaultStore = config.default || Object.keys(this.stores)[0];
+        this.defaultTtl = config.ttl || 3600;
+    }
+    /**
+     * Retrieve a specific named store, or the default store if no name is given.
+     *
+     * @param name - The store name. Omit to use the default store.
+     * @returns The resolved {@link CacheStore} instance.
+     * @throws Error if the requested store is not configured.
+     *
+     * @example
+     * ```ts
+     * const redis = cache.store('redis')
+     * await redis.get('key')
+     * ```
+     */
+    store(name) {
+        const storeName = name || this.defaultStore;
+        const s = this.stores[storeName];
+        if (!s)
+            throw new Error(`Cache store "${storeName}" not configured`);
+        return s;
+    }
+    /**
+     * Get a value from the default store.
+     *
+     * @param key - The cache key.
+     * @returns The cached value, or `null` if not found or expired.
+     */
+    async get(key) { return this.store().get(key); }
+    /**
+     * Set a value in the default store.
+     *
+     * @param key - The cache key.
+     * @param value - The value to store.
+     * @param ttl - Time-to-live in seconds. Falls back to the default TTL.
+     */
+    async set(key, value, ttl) { return this.store().set(key, value, ttl ?? this.defaultTtl); }
+    /**
+     * Check whether a key exists (and is not expired) in the default store.
+     *
+     * @param key - The cache key.
+     * @returns `true` if the key exists.
+     */
+    async has(key) { return this.store().has(key); }
+    /**
+     * Delete a key from the default store.
+     *
+     * @param key - The cache key.
+     * @returns `true` if the key was deleted.
+     */
+    async delete(key) { return this.store().delete(key); }
+    /**
+     * Flush all entries from the default store.
+     */
+    async flush() { return this.store().flush(); }
+    /**
+     * Get a cached value or compute and store it if missing. Inspired by AdonisJS.
+     *
+     * @param key - The cache key.
+     * @param ttl - Time-to-live in seconds for the computed value.
+     * @param factory - An async function that produces the value when not cached.
+     * @returns The cached or freshly-computed value.
+     *
+     * @example
+     * ```ts
+     * const users = await cache.getOrSet('users', 300, () => db.query('SELECT * FROM users'))
+     * ```
+     */
+    async getOrSet(key, ttl, factory) {
+        const cached = await this.get(key);
+        if (cached !== null)
+            return cached;
+        const value = await factory();
+        await this.set(key, value, ttl);
+        return value;
+    }
+    /**
+     * Get a value and immediately delete it from the cache (atomic get-and-remove).
+     *
+     * @param key - The cache key.
+     * @returns The cached value, or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * const token = await cache.pull<string>('one-time-token')
+     * ```
+     */
+    async pull(key) {
+        const value = await this.get(key);
+        if (value !== null)
+            await this.delete(key);
+        return value;
+    }
+}
+/**
+ * Create a new {@link Cache} instance with the given configuration.
+ *
+ * @param config - Optional cache configuration.
+ * @returns A new Cache instance.
+ *
+ * @example
+ * ```ts
+ * const cache = createCache({ ttl: 120 })
+ * ```
+ */
+export function createCache(config) {
+    return new Cache(config);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { CacheStore, CacheConfig } from './types';
+export { MemoryCacheStore } from './stores/memory';
+export { RedisCacheStore } from './stores/redis';
+export { DatabaseCacheStore } from './stores/database';
+export { Cache, createCache } from './cache';
+export { CacheProvider } from './provider';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { MemoryCacheStore } from './stores/memory';
+export { RedisCacheStore } from './stores/redis';
+export { DatabaseCacheStore } from './stores/database';
+export { Cache, createCache } from './cache';
+export { CacheProvider } from './provider';

package/dist/provider.d.ts

@@ -0,0 +1,21 @@
+import type { App } from '@tekir/core';
+/**
+ * Service provider that registers a {@link Cache} instance into the application
+ * container. Reads the `cache` configuration to create stores for each configured
+ * driver (`memory`, `redis`, or `database`).
+ *
+ * @example
+ * ```ts
+ * // In your kernel:
+ * app.register(new CacheProvider())
+ * ```
+ */
+export declare class CacheProvider {
+    /**
+     * Register the cache service with the application. Reads `cache.stores`,
+     * `cache.ttl`, and `cache.default` from the application config.
+     *
+     * @param app - The application instance.
+     */
+    register(app: App): Promise<void>;
+}

package/dist/provider.js

@@ -0,0 +1,86 @@
+import { Cache } from './cache';
+import { MemoryCacheStore } from './stores/memory';
+/**
+ * Service provider that registers a {@link Cache} instance into the application
+ * container. Reads the `cache` configuration to create stores for each configured
+ * driver (`memory`, `redis`, or `database`).
+ *
+ * @example
+ * ```ts
+ * // In your kernel:
+ * app.register(new CacheProvider())
+ * ```
+ */
+export class CacheProvider {
+    /**
+     * Register the cache service with the application. Reads `cache.stores`,
+     * `cache.ttl`, and `cache.default` from the application config.
+     *
+     * @param app - The application instance.
+     */
+    async register(app) {
+        const config = app.use('config');
+        if (!config('cache'))
+            return;
+        const storesConfig = config('cache.stores', {});
+        const stores = {};
+        for (const [name, storeConfig] of Object.entries(storesConfig)) {
+            // Already a CacheStore instance (backwards compat)
+            if (storeConfig && typeof storeConfig.get === 'function') {
+                stores[name] = storeConfig;
+                continue;
+            }
+            const driver = storeConfig?.driver || name;
+            if (driver === 'memory') {
+                stores[name] = new MemoryCacheStore();
+            }
+            else if (driver === 'redis') {
+                let redis;
+                try {
+                    redis = app.use('redis');
+                }
+                catch { }
+                if (!redis) {
+                    // Fallback: create instance from config
+                    let Redis;
+                    try {
+                        Redis = (await import('@tekir/redis')).Redis;
+                    }
+                    catch {
+                        throw new Error(`[@tekir/cache] Store "${name}" uses the redis driver but @tekir/redis is not installed. ` +
+                            'Run: bun add @tekir/redis and register RedisProvider before CacheProvider.');
+                    }
+                    redis = new Redis({ ...config('redis', {}), ...storeConfig });
+                }
+                const { RedisCacheStore } = await import('./stores/redis');
+                stores[name] = new RedisCacheStore(redis, storeConfig?.prefix);
+            }
+            else if (driver === 'database') {
+                let db;
+                try {
+                    db = app.use('db');
+                }
+                catch { }
+                if (!db) {
+                    throw new Error(`[@tekir/cache] Store "${name}" uses the database driver but no database service is registered. ` +
+                        'Add DatabaseProvider to your kernel before CacheProvider.');
+                }
+                const { DatabaseCacheStore } = await import('./stores/database');
+                stores[name] = new DatabaseCacheStore(db, storeConfig?.table);
+            }
+            else {
+                throw new Error(`[@tekir/cache] Unknown cache driver "${driver}" for store "${name}". ` +
+                    'Supported drivers: memory, redis, database');
+            }
+        }
+        // Fallback to memory if no stores configured
+        if (Object.keys(stores).length === 0) {
+            stores.memory = new MemoryCacheStore();
+        }
+        app.instance('cache', new Cache({
+            stores,
+            ttl: config('cache.ttl', 60),
+            default: config('cache.default', Object.keys(stores)[0]),
+        }));
+    }
+}

package/dist/stores/database.d.ts

@@ -0,0 +1,63 @@
+import type { CacheStore } from '../types';
+/**
+ * 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 declare class DatabaseCacheStore implements CacheStore {
+    private db;
+    private table;
+    private _ready;
+    /**
+     * 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: any, table?: string);
+    private _ensureTable;
+    /**
+     * 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`.
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * 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.
+     */
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    /**
+     * Check whether a key exists and is not expired.
+     *
+     * @param key - The cache key.
+     * @returns `true` if the key exists and has not expired.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Delete a key from the database.
+     *
+     * @param key - The cache key to remove.
+     * @returns Always returns `true`.
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Remove all entries from the cache table.
+     *
+     * @example
+     * ```ts
+     * await store.flush()
+     * ```
+     */
+    flush(): Promise<void>;
+}

package/dist/stores/database.js

@@ -0,0 +1,104 @@
+/**
+ * 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 { }
+    }
+    /**
+     * 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) {
+        return (await this.get(key)) !== null;
+    }
+    /**
+     * 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;
+    }
+    /**
+     * 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.d.ts

@@ -0,0 +1,49 @@
+import type { CacheStore } from '../types';
+/**
+ * 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 declare class MemoryCacheStore implements CacheStore {
+    private data;
+    /**
+     * 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`.
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * 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.
+     */
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    /**
+     * Check whether a key exists and is not expired.
+     *
+     * @param key - The cache key.
+     * @returns `true` if the key exists and has not expired.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Delete a key from the store.
+     *
+     * @param key - The cache key to remove.
+     * @returns `true` if the key was present and deleted.
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Remove all entries from the store.
+     */
+    flush(): Promise<void>;
+}