@tekir/cache 0.1.0

package/dist/stores/memory.js

@@ -0,0 +1,68 @@
+/**
+ * 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();
+    /**
+     * 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,
+        });
+    }
+    /**
+     * 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 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.d.ts

@@ -0,0 +1,94 @@
+import type { CacheStore } from '../types';
+interface RedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<unknown>;
+    expire(key: string, seconds: number): Promise<unknown>;
+    exists(key: string): Promise<number>;
+    del(key: string): Promise<unknown>;
+    send(command: string, args: unknown[]): Promise<unknown>;
+    connected?: boolean;
+}
+/**
+ * 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 declare class RedisCacheStore implements CacheStore {
+    private redis;
+    private 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: RedisClient, prefix?: string);
+    /**
+     * 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
+     * ```
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * 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
+     * ```
+     */
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    /**
+     * 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')) { ... }
+     * ```
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * 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')
+     * ```
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Flush the entire Redis database. Use with caution as this removes all keys,
+     * not just those managed by this store.
+     *
+     * @example
+     * ```ts
+     * await store.flush()
+     * ```
+     */
+    flush(): Promise<void>;
+}
+export {};

package/dist/stores/redis.js

@@ -0,0 +1,112 @@
+/**
+ * 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);
+        if (ttlSeconds) {
+            await this.redis.set(this.prefix + key, val);
+            await this.redis.expire(this.prefix + key, ttlSeconds);
+        }
+        else {
+            await this.redis.set(this.prefix + key, 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) {
+        return (await this.redis.exists(this.prefix + key)) > 0;
+    }
+    /**
+     * 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;
+    }
+    /**
+     * Flush the entire Redis database. Use with caution as this removes all keys,
+     * not just those managed by this store.
+     *
+     * @example
+     * ```ts
+     * await store.flush()
+     * ```
+     */
+    async flush() {
+        await this.redis.send('FLUSHDB', []);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+export interface CacheStore {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    flush(): Promise<void>;
+}
+export interface CacheConfig {
+    default?: string;
+    stores?: Record<string, CacheStore>;
+    ttl?: number;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tekir/cache",
+  "version": "0.1.0",
+  "description": "In-memory, Redis, and database caching abstraction",
+  "author": "dev@tekir.io",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tekir-io/tekir.git",
+    "directory": "packages/tekir-cache"
+  },
+  "homepage": "https://github.com/tekir-io/tekir/tree/main/packages/tekir-cache",
+  "keywords": [
+    "tekir",
+    "bun",
+    "typescript",
+    "framework",
+    "nodejs",
+    "fullstack"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "types": "dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@tekir/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@tekir/redis": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@tekir/redis": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc --noEmit false",
+    "prepublishOnly": "bun run build"
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  }
+}

package/src/cache.ts

@@ -0,0 +1,143 @@
+import type { CacheConfig, CacheStore } from './types'
+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 {
+  private stores: Record<string, CacheStore>
+  private defaultStore: string
+  private defaultTtl: number
+
+  /**
+   * Create a new Cache instance.
+   *
+   * @param config - Cache configuration including stores, default store name, and TTL.
+   */
+  constructor(config: CacheConfig = {}) {
+    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?: string): CacheStore {
+    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<T = unknown>(key: string): Promise<T | null> { return this.store().get<T>(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: string, value: unknown, ttl?: number): Promise<void> { 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: string): Promise<boolean> { 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: string): Promise<boolean> { return this.store().delete(key) }
+
+  /**
+   * Flush all entries from the default store.
+   */
+  async flush(): Promise<void> { 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<T>(key: string, ttl: number, factory: () => Promise<T>): Promise<T> {
+    const cached = await this.get<T>(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<T = unknown>(key: string): Promise<T | null> {
+    const value = await this.get<T>(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?: CacheConfig): Cache {
+  return new Cache(config)
+}

package/src/index.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/src/provider.ts

@@ -0,0 +1,93 @@
+import type { App } from '@tekir/core'
+import type { CacheStore } from './types'
+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: App) {
+    const config = app.use('config')
+    if (!config('cache')) return
+
+    const storesConfig = config('cache.stores', {}) as Record<string, any>
+    const stores: Record<string, CacheStore> = {}
+
+    for (const [name, storeConfig] of Object.entries(storesConfig)) {
+      // Already a CacheStore instance (backwards compat)
+      if (storeConfig && typeof storeConfig.get === 'function') {
+        stores[name] = storeConfig as CacheStore
+        continue
+      }
+
+      const driver = storeConfig?.driver || name
+
+      if (driver === 'memory') {
+        stores[name] = new MemoryCacheStore()
+
+      } else if (driver === 'redis') {
+        let redis: any
+        try { redis = app.use('redis') } catch {}
+        if (!redis) {
+          // Fallback: create instance from config
+          let Redis: any
+          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: any
+        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) as number,
+      default: config('cache.default', Object.keys(stores)[0]) as string,
+    }))
+  }
+}