@tekir/cache 0.1.0

package/src/stores/database.ts

@@ -0,0 +1,109 @@
+import type { CacheStore } from '../types'
+
+interface CacheDbRow { value: string; expires_at: number | null }
+
+/**
+ * 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 implements CacheStore {
+  private db: any
+  private table: string
+  private _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: any, 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
+  }
+
+  private 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<T = unknown>(key: string): Promise<T | null> {
+    await this._ensureTable()
+    const row = await this.db.queryOne(`SELECT value, expires_at FROM "${this.table}" WHERE key = ?`, [key]) as CacheDbRow | null
+    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 as T }
+  }
+
+  /**
+   * 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: string, value: unknown, ttlSeconds?: number): Promise<void> {
+    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: string): Promise<boolean> {
+    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: string): Promise<boolean> {
+    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(): Promise<void> {
+    await this._ensureTable()
+    await this.db.run(`DELETE FROM "${this.table}"`)
+  }
+}

package/src/stores/memory.ts

@@ -0,0 +1,74 @@
+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 class MemoryCacheStore implements CacheStore {
+  private data = new Map<string, { value: unknown; expiresAt: number | null }>()
+
+  /**
+   * 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<T = unknown>(key: string): Promise<T | null> {
+    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 as T
+  }
+
+  /**
+   * 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: string, value: unknown, ttlSeconds?: number): Promise<void> {
+    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: string): Promise<boolean> {
+    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: string): Promise<boolean> {
+    return this.data.delete(key)
+  }
+
+  /**
+   * Remove all entries from the store.
+   */
+  async flush(): Promise<void> {
+    this.data.clear()
+  }
+}

package/src/stores/redis.ts

@@ -0,0 +1,123 @@
+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 class RedisCacheStore implements CacheStore {
+  private redis: RedisClient
+  private prefix: string
+
+  /**
+   * 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 = '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<T = unknown>(key: string): Promise<T | null> {
+    const val = await this.redis.get(this.prefix + key)
+    if (val === null) return null
+    try { return JSON.parse(val) as T } catch { return val as unknown as T }
+  }
+
+  /**
+   * 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: string, value: unknown, ttlSeconds?: number): Promise<void> {
+    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: string): Promise<boolean> {
+    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: string): Promise<boolean> {
+    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(): Promise<void> {
+    await this.redis.send('FLUSHDB', [])
+  }
+}

package/src/types.ts

@@ -0,0 +1,13 @@
+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 // default TTL in seconds
+}