@strav/cache 1.0.0-alpha.25

package/README.md

@@ -0,0 +1,29 @@
+# @strav/cache
+
+Key/value cache with TTLs for Strav 1.0. Apps inject the abstract `Cache` token; the provider in the container picks the concrete driver — `MemoryCache` for single-node dev, `PostgresCache` for multi-node deployments. Same dependency shape as `@strav/broadcast` (kernel-free core in the root, optional Postgres driver under a subpath).
+
+```ts
+import { Cache } from '@strav/cache'
+
+@inject()
+class LeadsService {
+  constructor(private readonly cache: Cache) {}
+
+  async trending(): Promise<Lead[]> {
+    return this.cache.remember('leads.trending', '5m', async () => {
+      return this.leads.query().orderBy('score', 'desc').limit(10).get()
+    })
+  }
+}
+```
+
+Canonical docs live in [`docs/cache/README.md`](../../docs/cache/README.md).
+
+## What ships
+
+| Driver | Subpath | Notes |
+|---|---|---|
+| Memory | `@strav/cache` (root) + `@strav/cache/memory` | In-process. Bounded buffer; locks + tags first-class. Single-node only. |
+| Postgres | `@strav/cache/postgres` | Cross-process backplane via three tables (`strav_cache`, `strav_cache_locks`, `strav_cache_tags`). Atomic increments via row locks, FK cascade keeps tag rows tight. |
+
+The full Cache surface (`get`/`put`/`forget`/`has`/`flush`/`add`/`increment`/`decrement`/`remember`/`rememberForever`/`lock`/`tags`) ships on both drivers; the abstract base provides `remember` + `rememberForever` so every driver behaves identically there. No Redis driver yet — apps that need one write against the `Cache` contract (two abstract methods + the wrapper classes for locks/tags).

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@strav/cache",
+  "version": "1.0.0-alpha.25",
+  "description": "Strav cache layer — Cache abstraction + MemoryCache (in-process) + PostgresCache (cross-process ledger) + RedisCache (Bun.RedisClient, all data structures incl. tagged sets) + MemcachedCache (text-protocol client over Bun.connect). Atomic increments, distributed locks, tagged invalidation. Mirrors @strav/broadcast: kernel-free core in the root, every driver under its own subpath.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./memory": "./src/drivers/memory/index.ts",
+    "./postgres": "./src/drivers/postgres/index.ts",
+    "./redis": "./src/drivers/redis/index.ts",
+    "./memcached": "./src/drivers/memcached/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@strav/kernel": "1.0.0-alpha.25"
+  },
+  "peerDependencies": {
+    "@strav/database": "1.0.0-alpha.25",
+    "@types/bun": ">=1.3.14"
+  },
+  "peerDependenciesMeta": {
+    "@strav/database": {
+      "optional": true
+    }
+  },
+  "devDependencies": null
+}

package/src/cache.ts

@@ -0,0 +1,104 @@
+/**
+ * `Cache` — the abstract base every driver extends and apps inject
+ * via the container.
+ *
+ * Driver primitives (subclass overrides):
+ *
+ *   - `get(key)` — returns the stored value or `null`. Expired entries
+ *     return `null` AND are removed in passing.
+ *   - `put(key, value, ttl?)` — overwrite. `ttl` parsed via `parseTtl`.
+ *   - `has(key)` — boolean check.
+ *   - `forget(key)` — delete. Returns true if a key was actually
+ *     removed.
+ *   - `flush()` — clear everything. DEV-mode tool; production code
+ *     should prefer scoped invalidation.
+ *   - `add(key, value, ttl)` — atomic put-if-absent. Returns true if
+ *     stored, false if a value was already there (and unexpired).
+ *   - `increment(key, by)` / `decrement(key, by)` — atomic numeric
+ *     update. Drivers must guarantee atomicity across concurrent
+ *     callers; the Memory driver is fine for single-process dev,
+ *     Postgres uses an UPDATE … RETURNING.
+ *   - `lock(name, ttl)` — return a `CacheLock` handle. The same `name`
+ *     across processes / requests competes for one slot.
+ *   - `tags(...tags)` — return a `TaggedCache` namespace.
+ *
+ * The base provides:
+ *
+ *   - `remember(key, ttl, fn)` / `rememberForever(key, fn)` — the
+ *     "get or compute and cache" pattern. Implemented once on top of
+ *     `get` + `put` so every driver behaves identically.
+ *   - `close()` — default no-op; drivers override to release pools.
+ *
+ * Non-abstract on purpose so the class can serve as the container
+ * token (`app.singleton(Cache, factory)`). Subclasses MUST override
+ * the primitives; the default implementations throw to surface
+ * forgotten overrides during development. Same trade-off as
+ * `kernel`'s `Logger` and `@strav/broadcast`'s `Broadcaster`.
+ */
+
+import type { CacheLock, CacheTtl, TaggedCache } from './types.ts'
+
+export class Cache {
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  get<T = unknown>(key: string, fallback?: T | null): Promise<T | null> {
+    throw new Error('Cache.get must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  put(key: string, value: unknown, ttl?: CacheTtl): Promise<void> {
+    throw new Error('Cache.put must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  has(key: string): Promise<boolean> {
+    throw new Error('Cache.has must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  forget(key: string): Promise<boolean> {
+    throw new Error('Cache.forget must be overridden by the driver subclass.')
+  }
+  flush(): Promise<void> {
+    throw new Error('Cache.flush must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  add(key: string, value: unknown, ttl: CacheTtl): Promise<boolean> {
+    throw new Error('Cache.add must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  increment(key: string, by = 1): Promise<number> {
+    throw new Error('Cache.increment must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  decrement(key: string, by = 1): Promise<number> {
+    throw new Error('Cache.decrement must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  lock(name: string, ttl: CacheTtl): CacheLock {
+    throw new Error('Cache.lock must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  tags(...tags: string[]): TaggedCache {
+    throw new Error('Cache.tags must be overridden by the driver subclass.')
+  }
+
+  // ─── Higher-level patterns (driver-agnostic) ───────────────────────────────
+
+  /**
+   * "Get this value, or compute and cache it." The most common
+   * cache-aside shape — and the one driver-portable code reaches for
+   * by default.
+   */
+  async remember<T>(key: string, ttl: CacheTtl, fn: () => Promise<T> | T): Promise<T> {
+    const cached = await this.get<T>(key)
+    if (cached !== null) return cached
+    const fresh = await fn()
+    await this.put(key, fresh, ttl)
+    return fresh
+  }
+
+  /** `remember` with no TTL. The entry persists until `forget` / `flush`. */
+  rememberForever<T>(key: string, fn: () => Promise<T> | T): Promise<T> {
+    return this.remember(key, null, fn)
+  }
+
+  /** Optional driver-resource cleanup. Default no-op. */
+  async close(): Promise<void> {}
+}

package/src/cache_error.ts

@@ -0,0 +1,75 @@
+/**
+ * Typed error hierarchy. Same shape as `@strav/broadcast` /
+ * `@strav/notification` — base `CacheError` extending `StravError`,
+ * narrower subclasses with stable `code`s apps can branch on.
+ */
+
+import { StravError } from '@strav/kernel'
+
+interface CacheErrorOptions {
+  code?: string
+  status?: number
+  context?: Record<string, unknown>
+  cause?: unknown
+}
+
+export class CacheError extends StravError {
+  constructor(message: string, options: CacheErrorOptions = {}) {
+    super(
+      message,
+      { code: options.code ?? 'cache.error', status: options.status ?? 500 },
+      {
+        ...(options.context ? { context: options.context } : {}),
+        ...(options.cause !== undefined ? { cause: options.cause } : {}),
+      },
+    )
+  }
+}
+
+/** Driver constructed with bad config (empty connection url, etc.). */
+export class CacheConfigError extends CacheError {
+  constructor(message: string, options: { context?: Record<string, unknown> } = {}) {
+    super(message, {
+      code: 'cache.config',
+      status: 500,
+      ...(options.context ? { context: options.context } : {}),
+    })
+  }
+}
+
+/** A driver primitive rejected at I/O time (network, query failed, etc.). */
+export class CacheDriverError extends CacheError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(message, {
+      code: 'cache.driver',
+      status: 502,
+      ...(options.context ? { context: options.context } : {}),
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}
+
+/** `CacheLock.block(timeoutMs, fn)` exhausted its window. */
+export class CacheLockTimeoutError extends CacheError {
+  constructor(message: string, options: { context?: Record<string, unknown> } = {}) {
+    super(message, {
+      code: 'cache.lock_timeout',
+      status: 503,
+      ...(options.context ? { context: options.context } : {}),
+    })
+  }
+}
+
+/** `cache.put(key, value, ttl)` got a TTL string it couldn't parse. */
+export class CacheTtlParseError extends CacheError {
+  constructor(message: string, options: { context?: Record<string, unknown> } = {}) {
+    super(message, {
+      code: 'cache.ttl_parse',
+      status: 400,
+      ...(options.context ? { context: options.context } : {}),
+    })
+  }
+}

package/src/cache_provider.ts

@@ -0,0 +1,45 @@
+/**
+ * `CacheProvider` — registers `MemoryCache` under the `Cache` token by
+ * default.
+ *
+ * Apps that want the Postgres backplane swap providers:
+ *
+ *   import { CacheProvider } from '@strav/cache'
+ *   import { PostgresCacheProvider } from '@strav/cache/postgres'
+ *
+ *   providers: [
+ *     ...,
+ *     new PostgresCacheProvider(),    // INSTEAD OF CacheProvider
+ *   ]
+ *
+ * Both providers register under the same `Cache` token, so app code
+ * injecting `Cache` doesn't change between dev and prod.
+ */
+
+import { type Application, ConfigRepository, ServiceProvider } from '@strav/kernel'
+import { Cache } from './cache.ts'
+import { MemoryCache, type MemoryCacheOptions } from './drivers/memory/memory_cache.ts'
+
+export interface MemoryCacheConfig extends MemoryCacheOptions {
+  driver: 'memory'
+}
+
+export class CacheProvider extends ServiceProvider {
+  override readonly name = 'cache'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(Cache, (c) => {
+      const cfg = c.resolve(ConfigRepository).get('cache') as MemoryCacheConfig | undefined
+      return new MemoryCache(cfg !== undefined && cfg.now !== undefined ? { now: cfg.now } : {})
+    })
+  }
+
+  override async boot(app: Application): Promise<void> {
+    app.resolve(Cache)
+  }
+
+  override async shutdown(app: Application): Promise<void> {
+    await app.resolve(Cache).close()
+  }
+}

package/src/drivers/memcached/index.ts

@@ -0,0 +1,6 @@
+export { MemcachedCache, type MemcachedCacheOptions } from './memcached_cache.ts'
+export {
+  type MemcachedCacheConfig,
+  MemcachedCacheProvider,
+} from './memcached_cache_provider.ts'
+export { MemcachedClient, type MemcachedClientOptions } from './memcached_client.ts'

package/src/drivers/memcached/memcached_cache.ts

@@ -0,0 +1,288 @@
+/**
+ * `MemcachedCache` — Memcached-backed cross-process cache.
+ *
+ * Operation mapping (text protocol):
+ *
+ *   - `get` → `get key\r\n` → `VALUE key 0 N\r\n<value>\r\nEND\r\n`.
+ *     JSON.parse, fall back to the raw string for non-JSON payloads
+ *     (counters return bare decimal text).
+ *   - `put` → `set key 0 N bytes\r\n<value>\r\n`.
+ *   - `has` → `get` + non-null check.
+ *   - `forget` → `delete key\r\n`.
+ *   - `flush` → `flush_all\r\n` — wipes the WHOLE server. There's no
+ *     prefix-scoped equivalent in Memcached. Apps that share their
+ *     Memcached instance with other code shouldn't use `flush`.
+ *   - `add` → `add key 0 N bytes\r\n<value>\r\n` (atomic put-if-absent).
+ *   - `increment` / `decrement` → `incr key by\r\n` (or `decr`).
+ *     Memcached returns `NOT_FOUND` for missing keys; the driver
+ *     falls back to an `add` of the delta, then re-`incr`s on race.
+ *   - `lock(name, ttl)` → `add` (atomic). **No CAS-scoped release** —
+ *     a slow caller's expired lock can be released by a different
+ *     holder. Apps that need strict ownership use Redis or Postgres.
+ *   - `tags(...)` → throws `CacheDriverError`. Memcached has no
+ *     native sets and no SCAN; emulating tags would require a
+ *     full-server scan per flush. Out of scope.
+ *
+ * Keys are namespaced with `prefix` (default `'strav:'`). Memcached
+ * keys are ASCII-only, no whitespace, ≤250 bytes — the driver does
+ * NOT validate this; callers are expected to keep keys clean.
+ */
+
+import { Cache } from '../../cache.ts'
+import { CacheConfigError, CacheDriverError, CacheLockTimeoutError } from '../../cache_error.ts'
+import { parseTtl } from '../../ttl.ts'
+import type { CacheLock, CacheTtl, TaggedCache } from '../../types.ts'
+import { MemcachedClient, type MemcachedClientOptions } from './memcached_client.ts'
+
+const ENCODER = new TextEncoder()
+const DECODER = new TextDecoder()
+
+export interface MemcachedCacheOptions extends Omit<MemcachedClientOptions, 'host' | 'port'> {
+  host: string
+  port: number
+  /** Key namespace prefix. Default `'strav:'`. */
+  prefix?: string
+  /** Pre-constructed client for tests. */
+  client?: MemcachedClient
+}
+
+export class MemcachedCache extends Cache {
+  private readonly client: MemcachedClient
+  private readonly ownsClient: boolean
+  private readonly prefix: string
+
+  constructor(options: MemcachedCacheOptions) {
+    super()
+    this.prefix = options.prefix ?? 'strav:'
+    if (options.client !== undefined) {
+      this.client = options.client
+      this.ownsClient = false
+    } else {
+      if (!options.host || !options.port) {
+        throw new CacheConfigError(
+          'MemcachedCache requires `host` + `port` (or an injected `client`).',
+        )
+      }
+      this.client = new MemcachedClient({
+        host: options.host,
+        port: options.port,
+        ...(options.connectTimeoutMs !== undefined
+          ? { connectTimeoutMs: options.connectTimeoutMs }
+          : {}),
+        ...(options.requestTimeoutMs !== undefined
+          ? { requestTimeoutMs: options.requestTimeoutMs }
+          : {}),
+      })
+      this.ownsClient = true
+    }
+  }
+
+  // ─── Core primitives ───────────────────────────────────────────────────────
+
+  override async get<T = unknown>(key: string, fallback: T | null = null): Promise<T | null> {
+    const reply = DECODER.decode(await this.client.send(`get ${this.k(key)}\r\n`))
+    if (reply === 'END\r\n') return fallback
+    if (!reply.startsWith('VALUE ')) {
+      throw new CacheDriverError(`MemcachedCache.get: unexpected reply: ${trimError(reply)}`, {
+        context: { key },
+      })
+    }
+    const headerEnd = reply.indexOf('\r\n')
+    const header = reply.slice(0, headerEnd) // `VALUE key 0 N`
+    const bytes = Number(header.split(' ')[3] ?? '0')
+    const valueStart = headerEnd + 2
+    const value = reply.slice(valueStart, valueStart + bytes)
+    return this.decode<T>(value, fallback)
+  }
+
+  override async put(key: string, value: unknown, ttl?: CacheTtl): Promise<void> {
+    const seconds = parseTtl(ttl) ?? 0
+    await this.storeCommand('set', key, value, seconds)
+  }
+
+  override async has(key: string): Promise<boolean> {
+    const reply = DECODER.decode(await this.client.send(`get ${this.k(key)}\r\n`))
+    return !reply.startsWith('END\r\n')
+  }
+
+  override async forget(key: string): Promise<boolean> {
+    const reply = DECODER.decode(await this.client.send(`delete ${this.k(key)}\r\n`))
+    return reply.startsWith('DELETED')
+  }
+
+  override async flush(): Promise<void> {
+    // flush_all is server-wide — apps sharing the instance shouldn't
+    // call this. There is no scoped equivalent in Memcached.
+    await this.client.send('flush_all\r\n')
+  }
+
+  override async add(key: string, value: unknown, ttl: CacheTtl): Promise<boolean> {
+    const seconds = parseTtl(ttl) ?? 0
+    return this.storeCommand('add', key, value, seconds)
+  }
+
+  override async increment(key: string, by = 1): Promise<number> {
+    return this.adjust(key, by, 'incr')
+  }
+
+  override async decrement(key: string, by = 1): Promise<number> {
+    return this.adjust(key, by, 'decr')
+  }
+
+  override lock(name: string, ttl: CacheTtl): CacheLock {
+    return new MemcachedCacheLock(this, name, ttl)
+  }
+
+  override tags(..._tags: string[]): TaggedCache {
+    throw new CacheDriverError(
+      'MemcachedCache does not support tagged invalidation — Memcached has no native sets and no SCAN. Use RedisCache or PostgresCache for tag support.',
+    )
+  }
+
+  override async close(): Promise<void> {
+    if (!this.ownsClient) return
+    await this.client.close()
+  }
+
+  // ─── Lock internals ────────────────────────────────────────────────────────
+
+  /** @internal */
+  async _tryAcquireLock(name: string, ttl: CacheTtl): Promise<string | undefined> {
+    const seconds = parseTtl(ttl)
+    if (seconds === null) {
+      throw new CacheConfigError('MemcachedCache.lock: TTL must be set — no "forever" locks.')
+    }
+    const owner = randomToken()
+    const stored = await this.storeCommand('add', `lock:${name}`, owner, seconds)
+    return stored ? owner : undefined
+  }
+
+  /** @internal */
+  async _releaseLock(name: string, owner: string): Promise<boolean> {
+    // No CAS-scoped delete in Memcached's text protocol — read the
+    // value, compare, then delete. A slim race window exists where
+    // another holder acquired between our `get` and `delete`; document
+    // the limitation and let apps that need strict ownership pick a
+    // different driver.
+    const current = await this.get<string>(`lock:${name}`)
+    if (current !== owner) return false
+    return this.forget(`lock:${name}`)
+  }
+
+  // ─── Internals ─────────────────────────────────────────────────────────────
+
+  private async storeCommand(
+    cmd: 'set' | 'add',
+    key: string,
+    value: unknown,
+    seconds: number,
+  ): Promise<boolean> {
+    const encoded = ENCODER.encode(JSON.stringify(value))
+    const header = `${cmd} ${this.k(key)} 0 ${seconds} ${encoded.length}\r\n`
+    const headerBytes = ENCODER.encode(header)
+    const trailer = ENCODER.encode('\r\n')
+    const payload = new Uint8Array(headerBytes.length + encoded.length + trailer.length)
+    payload.set(headerBytes, 0)
+    payload.set(encoded, headerBytes.length)
+    payload.set(trailer, headerBytes.length + encoded.length)
+    const reply = DECODER.decode(await this.client.send(payload))
+    if (reply.startsWith('STORED')) return true
+    if (reply.startsWith('NOT_STORED')) return false
+    throw new CacheDriverError(`MemcachedCache.${cmd}: unexpected reply: ${trimError(reply)}`, {
+      context: { key },
+    })
+  }
+
+  private async adjust(key: string, by: number, op: 'incr' | 'decr'): Promise<number> {
+    const reply = DECODER.decode(await this.client.send(`${op} ${this.k(key)} ${by}\r\n`))
+    if (/^\d+/.test(reply)) return Number(reply.split('\r\n')[0])
+    if (!reply.startsWith('NOT_FOUND')) {
+      throw new CacheDriverError(`MemcachedCache.${op}: unexpected reply: ${trimError(reply)}`, {
+        context: { key },
+      })
+    }
+    // NOT_FOUND — try to seed via add(delta). Use no expiry (0) so the
+    // counter behaves like Redis (forever until forget).
+    const seedValue = op === 'incr' ? by : -by
+    const stored = await this.storeCommand('add', key, seedValue, 0)
+    if (stored) return seedValue
+    // Race — another caller created the key first. Re-run incr/decr.
+    const replyAfter = DECODER.decode(await this.client.send(`${op} ${this.k(key)} ${by}\r\n`))
+    if (/^\d+/.test(replyAfter)) return Number(replyAfter.split('\r\n')[0])
+    throw new CacheDriverError(
+      `MemcachedCache.${op}: still NOT_FOUND after seed retry — odd race or non-numeric value at "${key}".`,
+      { context: { key } },
+    )
+  }
+
+  private k(key: string): string {
+    return `${this.prefix}${key}`
+  }
+
+  private decode<T>(raw: string, fallback: T | null): T | null {
+    try {
+      return JSON.parse(raw) as T
+    } catch {
+      return raw as unknown as T
+    }
+  }
+}
+
+class MemcachedCacheLock implements CacheLock {
+  private owner: string | undefined
+
+  constructor(
+    private readonly cache: MemcachedCache,
+    readonly name: string,
+    private readonly ttl: CacheTtl,
+  ) {}
+
+  async acquire(): Promise<boolean> {
+    if (this.owner !== undefined) return false
+    const token = await this.cache._tryAcquireLock(this.name, this.ttl)
+    if (token === undefined) return false
+    this.owner = token
+    return true
+  }
+
+  async release(): Promise<boolean> {
+    if (this.owner === undefined) return false
+    const released = await this.cache._releaseLock(this.name, this.owner)
+    this.owner = undefined
+    return released
+  }
+
+  async block<T>(timeoutMs: number, fn: () => Promise<T> | T): Promise<T> {
+    if (timeoutMs < 0 || !Number.isFinite(timeoutMs)) {
+      throw new Error(
+        `CacheLock.block: timeoutMs must be a non-negative finite number; got: ${timeoutMs}`,
+      )
+    }
+    const deadline = Date.now() + timeoutMs
+    const pollIntervalMs = 75
+    while (true) {
+      if (await this.acquire()) {
+        try {
+          return await fn()
+        } finally {
+          await this.release()
+        }
+      }
+      if (Date.now() >= deadline) {
+        throw new CacheLockTimeoutError(
+          `CacheLock "${this.name}" not acquired within ${timeoutMs}ms.`,
+          { context: { lock: this.name, timeoutMs } },
+        )
+      }
+      await new Promise<void>((r) => setTimeout(r, pollIntervalMs))
+    }
+  }
+}
+
+function randomToken(): string {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+}
+
+function trimError(reply: string): string {
+  return reply.replace(/\r\n$/, '').slice(0, 200)
+}

package/src/drivers/memcached/memcached_cache_provider.ts

@@ -0,0 +1,39 @@
+import { type Application, ConfigRepository, ServiceProvider } from '@strav/kernel'
+import { Cache } from '../../cache.ts'
+import { CacheConfigError } from '../../cache_error.ts'
+import { MemcachedCache, type MemcachedCacheOptions } from './memcached_cache.ts'
+
+export interface MemcachedCacheConfig extends Omit<MemcachedCacheOptions, 'client'> {
+  driver: 'memcached'
+}
+
+export class MemcachedCacheProvider extends ServiceProvider {
+  override readonly name = 'cache'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(Cache, (c) => {
+      const cfg = c.resolve(ConfigRepository).get('cache') as MemcachedCacheConfig | undefined
+      if (cfg === undefined || !cfg.host || !cfg.port) {
+        throw new CacheConfigError(
+          'MemcachedCacheProvider: `config.cache.host` and `config.cache.port` are required.',
+        )
+      }
+      return new MemcachedCache({
+        host: cfg.host,
+        port: cfg.port,
+        ...(cfg.prefix !== undefined ? { prefix: cfg.prefix } : {}),
+        ...(cfg.connectTimeoutMs !== undefined ? { connectTimeoutMs: cfg.connectTimeoutMs } : {}),
+        ...(cfg.requestTimeoutMs !== undefined ? { requestTimeoutMs: cfg.requestTimeoutMs } : {}),
+      })
+    })
+  }
+
+  override async boot(app: Application): Promise<void> {
+    app.resolve(Cache)
+  }
+
+  override async shutdown(app: Application): Promise<void> {
+    await app.resolve(Cache).close()
+  }
+}