@zerotal/cache 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog — @zerotal/cache
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `stable`**
+
+## [Unreleased]
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Changed
+
+- Added a typed error vocabulary (`CacheError`/`CacheSerializationError`/`CacheDeserializationError`, `E_CACHE_*` codes).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+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,82 @@
+# @zerotal/cache
+
+> A unified caching layer with in-memory, SQLite, and Redis drivers.
+
+Cache database queries, computed values, and external API responses behind a single `Cache` facade. Tag related entries to invalidate them together, coalesce concurrent misses with `remember()`, and protect mutating endpoints with idempotency middleware.
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
+
+## Installation
+
+```bash
+bun add @zerotal/cache
+```
+
+## Setup
+
+Register the provider in `bootstrap/providers.ts`:
+
+```ts
+import { CacheProvider } from "@zerotal/cache";
+```
+
+## Usage
+
+`remember()` is the primary workhorse — on a miss it calls the factory, stores the result, and returns it. Concurrent callers for the same key coalesce, so the factory runs exactly once:
+
+```ts
+import { Cache } from "@zerotal/cache";
+
+const posts = await Cache.remember("posts:page:1", 300, async () => {
+  return Post.query().where("status", "published").orderBy("published_at", "desc").paginate(10, 1);
+});
+```
+
+Basic reads, writes, and atomic counters:
+
+```ts
+await Cache.set("user:1", { id: 1, name: "Alice" }, 300); // TTL in seconds
+const user = await Cache.get<{ id: number; name: string }>("user:1"); // null on miss
+await Cache.forget("user:1");
+
+await Cache.increment("page-views:posts:42");
+const token = await Cache.pull<string>(`otp:${userId}`); // get + delete atomically
+```
+
+Group keys under tags so you can invalidate them together:
+
+```ts
+await Cache.tags(["posts", "public"]).set("posts:page:1", data, 300);
+await Cache.tags(["posts"]).flush(); // busts every "posts"-tagged key
+```
+
+Protect mutating routes against double-execution via the `Idempotency-Key` header:
+
+```ts
+import { IdempotencyMiddleware, Cache } from "@zerotal/cache";
+
+Router.post("/api/orders", [OrderController, "store"], {
+  middleware: [IdempotencyMiddleware.with({ cache: Cache.instance() })],
+});
+```
+
+## Exports
+
+| Export                                                       | Description                                                   |
+| ------------------------------------------------------------ | ------------------------------------------------------------- |
+| `Cache`                                                      | Facade over the configured cache driver.                      |
+| `CacheManager`, `TaggedCache`                                | The underlying manager and tag-scoped view.                   |
+| `CacheProvider`                                              | Service provider — register in `bootstrap/providers.ts`.      |
+| `CacheConfig`, `CacheConfigShape`                            | Config factory and its type.                                  |
+| `IdempotencyMiddleware`, `IdempotencyOptions`                | Replay-safe middleware for mutating requests.                 |
+| `CacheDriver`, `MemoryDriver`, `SqliteDriver`, `RedisDriver` | Driver contract and built-in drivers for custom registration. |
+| `errors`                                                     | Typed error vocabulary (re-exported).                         |
+
+Subpath exports:
+
+- `@zerotal/cache` — the public API above.
+- `@zerotal/cache/commands` — `CacheClearCommand` for the CLI.
+
+## Documentation
+
+- [Cache](../../docs/cache.md)

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@zerotal/cache",
+  "version": "1.0.0",
+  "license": "MIT",
+  "maturity": "stable",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./commands": "./src/commands/index.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/core": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "description": "Cache layer for Zerotal with SQLite, Redis, and in-memory drivers, tags, and stampede protection.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework",
+    "cache",
+    "redis"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/cache"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/cache#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/CacheManager.ts

@@ -0,0 +1,190 @@
+import type { CacheDriver } from "./drivers/CacheDriver.ts";
+import { CacheSerializationError, CacheDeserializationError } from "./errors.ts";
+import { FrameworkEvents, sha256Hex } from "@zerotal/core";
+import { CacheQueried } from "./events.ts";
+import type { LockManager } from "@zerotal/core/lock";
+import { LockNotAcquiredError } from "@zerotal/core/lock";
+
+// Cross-process recompute lock for remember(): how long the lock is held while the
+// factory runs, and how long a waiter blocks for the holder before recomputing anyway.
+const STAMPEDE_LOCK_TTL = 30; // seconds
+const STAMPEDE_LOCK_WAIT = 30; // seconds
+
+// ── CacheManager ──────────────────────────────────────────────────────────────
+
+export class CacheManager {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private _inFlight = new Map<string, Promise<any>>();
+
+  constructor(
+    private _driver: CacheDriver,
+    private _prefix: string = "",
+    private _defaultTtl?: number,
+    private _lock: LockManager | null = null,
+    private _stampedeProtection: boolean = true,
+  ) {}
+
+  private _key(key: string): string {
+    return this._prefix + key;
+  }
+
+  /** JSON-encode a value for storage, surfacing a typed CacheSerializationError. */
+  private _encode(key: string, value: unknown): string {
+    try {
+      return JSON.stringify(value);
+    } catch (err) {
+      throw new CacheSerializationError(key, err);
+    }
+  }
+
+  /** JSON-decode a cached value, surfacing a typed CacheDeserializationError. */
+  private _decode<T>(key: string, raw: string): T {
+    try {
+      return JSON.parse(raw) as T;
+    } catch (err) {
+      throw new CacheDeserializationError(key, err);
+    }
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    const t0 = Date.now();
+    const raw = await this._driver.get(this._key(key));
+    FrameworkEvents.emit(
+      new CacheQueried(raw === null ? "miss" : "hit", key, undefined, Date.now() - t0),
+    );
+    if (raw === null) return null;
+    return this._decode<T>(key, raw);
+  }
+
+  async set(key: string, value: unknown, ttl?: number): Promise<void> {
+    const t0 = Date.now();
+    const effectiveTtl = ttl ?? this._defaultTtl;
+    await this._driver.set(this._key(key), this._encode(key, value), effectiveTtl);
+    FrameworkEvents.emit(new CacheQueried("write", key, effectiveTtl, Date.now() - t0));
+  }
+
+  async forget(key: string): Promise<void> {
+    const t0 = Date.now();
+    await this._driver.forget(this._key(key));
+    FrameworkEvents.emit(new CacheQueried("forget", key, undefined, Date.now() - t0));
+  }
+
+  async has(key: string): Promise<boolean> {
+    const t0 = Date.now();
+    const result = await this._driver.has(this._key(key));
+    FrameworkEvents.emit(new CacheQueried("has", key, undefined, Date.now() - t0));
+    return result;
+  }
+
+  async flush(): Promise<void> {
+    const t0 = Date.now();
+    await this._driver.flush(this._prefix);
+    FrameworkEvents.emit(new CacheQueried("flush", "*", undefined, Date.now() - t0));
+  }
+
+  async remember<T>(key: string, ttl: number, fn: () => Promise<T> | T): Promise<T> {
+    const cached = await this.get<T>(key);
+    if (cached !== null) return cached;
+
+    const prefixedKey = this._key(key);
+
+    // Coalesce concurrent misses: await existing in-flight factory
+    const existing = this._inFlight.get(prefixedKey);
+    if (existing !== undefined) return existing as Promise<T>;
+
+    const promise = (async () => {
+      try {
+        return await this._computeAndStore(key, prefixedKey, ttl, fn);
+      } finally {
+        this._inFlight.delete(prefixedKey);
+      }
+    })();
+
+    this._inFlight.set(prefixedKey, promise);
+    return promise;
+  }
+
+  /**
+   * Run the factory and store its value. When stampede protection is on and a lock
+   * driver is configured, a cross-process lock ensures only one node recomputes a
+   * cold key; waiters re-check the cache after the holder finishes. A waiter that
+   * can't get the lock in time recomputes rather than failing — caching stays
+   * best-effort. Without a lock driver, only the in-process coalescing above applies.
+   */
+  private async _computeAndStore<T>(
+    key: string,
+    prefixedKey: string,
+    ttl: number,
+    fn: () => Promise<T> | T,
+  ): Promise<T> {
+    const compute = async (): Promise<T> => {
+      const value = await fn();
+      await this.set(key, value, ttl);
+      return value;
+    };
+
+    if (!this._stampedeProtection || !this._lock) return compute();
+
+    const lockKey = `cache:stampede:${prefixedKey}`;
+    const recheckThenCompute = async (): Promise<T> => {
+      // Another holder may have populated the key while we waited for the lock.
+      const fresh = await this.get<T>(key);
+      if (fresh !== null) return fresh;
+      return compute();
+    };
+
+    try {
+      return await this._lock.block(lockKey, STAMPEDE_LOCK_TTL, recheckThenCompute, {
+        timeout: STAMPEDE_LOCK_WAIT,
+        retryDelay: 50,
+      });
+    } catch (err) {
+      if (err instanceof LockNotAcquiredError) return recheckThenCompute();
+      throw err;
+    }
+  }
+
+  async forever(key: string, value: unknown): Promise<void> {
+    const t0 = Date.now();
+    await this._driver.set(this._key(key), this._encode(key, value), undefined);
+    FrameworkEvents.emit(new CacheQueried("write", key, undefined, Date.now() - t0));
+  }
+
+  /**
+   * Scope reads/writes to a **tag namespace**. Tags are a deterministic, ordered
+   * namespace: `tags([...])` sorts and joins the names into a key prefix, so
+   * `tags(['a','b'])` and `tags(['b','a'])` address the same entries (the order
+   * no longer matters), and `tags([...]).flush()` clears exactly that namespace.
+   *
+   * Note: this is namespacing, not a per-tag index — flushing `tags(['b'])` does
+   * NOT invalidate entries written under `tags(['a','b'])`. Flush with the same
+   * tag set you wrote with. (A true multi-tag index — where any one tag can
+   * invalidate every entry carrying it — is intentionally out of scope for v1.)
+   *
+   * The namespace is a fixed-length digest of the sorted tag list rather than the names
+   * joined together, because `flush()` is a prefix delete and a joined prefix contains its
+   * own sub-namespaces: `tags(['a'])` produced `a:`, which matches `a:b:key`, so flushing
+   * `['a']` wiped the `['a','b']` namespace this docblock promises it will not. A digest
+   * also stops a tag that happens to contain the separator from colliding —
+   * `tags(['a:b'])` and `tags(['a','b'])` are different namespaces.
+   */
+  tags(tagNames: string[]): TaggedCache {
+    // Sorted so the namespace is order-independent: tags(['b','a']) === tags(['a','b']).
+    // NUL-joined so the digest input is unambiguous for any tag content.
+    const canonical = [...tagNames].sort().join(String.fromCharCode(0));
+    const tagPrefix = `t${sha256Hex(canonical).slice(0, 16)}:`;
+    return new TaggedCache(
+      this._driver,
+      this._prefix + tagPrefix,
+      undefined,
+      this._lock,
+      this._stampedeProtection,
+    );
+  }
+
+  dispose(): void {
+    this._driver.dispose?.();
+  }
+}
+
+export class TaggedCache extends CacheManager {}

package/src/IdempotencyMiddleware.ts

@@ -0,0 +1,261 @@
+import type { NextFn, HttpContext } from "@zerotal/core";
+import { currentApp, BaseMiddleware } from "@zerotal/core";
+import type { LockManager } from "@zerotal/core/lock";
+import { LockNotAcquiredError } from "@zerotal/core/lock";
+import type { CacheManager } from "./CacheManager.ts";
+
+// Cross-process idempotency lock: hold time while the handler runs, and how long a
+// concurrent request waits for the holder before executing anyway.
+const IDEMPOTENCY_LOCK_TTL = 60; // seconds
+const IDEMPOTENCY_LOCK_WAIT = 30; // seconds
+
+// ── Stored payload ────────────────────────────────────────────────────────────
+
+interface StoredResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+  bodyHash: string | null; // SHA-256 of original request body, null when validateBody disabled
+}
+
+// ── Options ───────────────────────────────────────────────────────────────────
+
+export interface IdempotencyOptions {
+  /**
+   * CacheManager that stores idempotent responses.
+   * Required — pass via `IdempotencyMiddleware.with({ cache: manager })`.
+   */
+  cache: CacheManager | undefined;
+
+  /**
+   * Seconds to retain a stored response. After this, the same key can be
+   * reused without replaying the previous response. Default: `86400` (24 h).
+   */
+  ttl: number;
+
+  /**
+   * HTTP methods subject to idempotency checks.
+   * Default: `['POST', 'PUT', 'PATCH', 'DELETE']`.
+   */
+  methods: string[];
+
+  /**
+   * Request header that carries the client-supplied idempotency key.
+   * Default: `'Idempotency-Key'`.
+   */
+  header: string;
+
+  /**
+   * When `true`, a 422 is returned if the same idempotency key arrives with
+   * a different request body. Useful for detecting accidental key reuse.
+   * Default: `false`.
+   */
+  validateBody: boolean;
+
+  /**
+   * Take a cross-process lock (via the lock primitive) so only one node executes the
+   * handler for a given key at a time, even across machines. Default: `true`.
+   * Degrades to in-process coalescing + cache replay when no lock driver is configured.
+   */
+  useLock: boolean;
+
+  /**
+   * Explicit lock manager. When omitted (and `useLock` is true), the manager is
+   * resolved from the container's `lock` binding at request time.
+   */
+  lock?: LockManager;
+}
+
+// ── Middleware ────────────────────────────────────────────────────────────────
+
+/**
+ * Idempotency middleware — prevents double-execution of mutating requests.
+ *
+ * Clients attach an `Idempotency-Key: <uuid>` header to any mutating request.
+ * On the first request the handler executes normally and the response is
+ * stored in the cache. All subsequent requests with the same key receive the
+ * stored response without re-running the handler.
+ *
+ * Concurrent requests for the same key are coalesced: within a process via an
+ * in-flight map, and across processes via a cross-process lock (the lock
+ * primitive) so only one node executes the handler at a time. Cross-process
+ * locking is on by default and degrades to cache-backed replay when no lock
+ * driver is configured; disable it with `useLock: false`.
+ *
+ * Replayed responses carry an `Idempotency-Replay: true` header so clients
+ * can distinguish fresh from cached responses.
+ *
+ * 5xx responses are never cached so transient errors don't permanently
+ * suppress retries.
+ *
+ * @example
+ * import { IdempotencyMiddleware } from '@zerotal/cache';
+ * import { Cache } from '@zerotal/cache';
+ *
+ * // Per-route
+ * Router.post('/api/orders', [OrderController, 'store'], {
+ *   middleware: [IdempotencyMiddleware.with({ cache: Cache.instance() })],
+ * });
+ *
+ * // Global
+ * app.use([IdempotencyMiddleware.with({ cache: cacheManager, ttl: 48 * 3600 })]);
+ */
+export class IdempotencyMiddleware extends BaseMiddleware<IdempotencyOptions> {
+  protected options: IdempotencyOptions = {
+    cache: undefined,
+    ttl: 86_400, // 24 h
+    methods: ["POST", "PUT", "PATCH", "DELETE"],
+    header: "Idempotency-Key",
+    validateBody: false,
+    useLock: true,
+  };
+
+  // Per-process in-flight map — coalesces concurrent requests with the same key
+  // so only one handler execution runs at a time within this process.
+  private static readonly _inFlight = new Map<string, Promise<Response>>();
+
+  async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
+    const method = http.request.method.toUpperCase();
+    if (!this.options.methods.includes(method)) return next();
+
+    const idempotencyKey = http.header(this.options.header);
+    if (!idempotencyKey) return next();
+
+    const { cache, ttl, validateBody } = this.options;
+    if (!cache) return next();
+
+    const cacheKey = `idempotency:${idempotencyKey.trim().slice(0, 512)}`;
+
+    // Compute body hash now — before next() can consume the stream.
+    const bodyHash = validateBody ? await _hashBody(http.request) : null;
+
+    // ── Replay from cache ─────────────────────────────────────────────────────
+    const stored = await cache.get<StoredResponse>(cacheKey);
+    if (stored) {
+      if (validateBody && stored.bodyHash !== null && stored.bodyHash !== bodyHash) {
+        return Response.json(
+          {
+            message: "This Idempotency-Key was used with a different request body.",
+          },
+          { status: 422 },
+        );
+      }
+      return _rehydrate(stored, true);
+    }
+
+    // ── Coalesce within process ───────────────────────────────────────────────
+    const inFlight = IdempotencyMiddleware._inFlight.get(cacheKey);
+    if (inFlight) {
+      const replayed = (await inFlight).clone();
+      replayed.headers.set("Idempotency-Replay", "true");
+      return replayed;
+    }
+
+    // Run the handler exactly once and cache its response. Re-checks the cache first
+    // so a request that just waited on the cross-process lock replays the stored
+    // response instead of executing the handler again.
+    const executeOnce = async (): Promise<Response> => {
+      const fresh = await cache.get<StoredResponse>(cacheKey);
+      if (fresh) {
+        if (validateBody && fresh.bodyHash !== null && fresh.bodyHash !== bodyHash) {
+          const conflict = Response.json(
+            { message: "This Idempotency-Key was used with a different request body." },
+            { status: 422 },
+          );
+          http.response = conflict;
+          return conflict;
+        }
+        const replay = _rehydrate(fresh, true);
+        http.response = replay;
+        return replay;
+      }
+
+      await next();
+
+      if (http.response && http.response.status < 500) {
+        const serialized = await _serialize(http.response, bodyHash);
+        // Replace http.response with a fresh response so the body is reusable
+        // by anything downstream that still needs to read it.
+        http.response = _rehydrate(serialized, false);
+        await cache.set(cacheKey, serialized, ttl);
+        return http.response;
+      }
+
+      const fallback = http.response ?? new Response("", { status: 500 });
+      http.response = fallback;
+      return fallback;
+    };
+
+    // ── Execute under a cross-process lock, then resolve in-process waiters ────
+    const lock = this._resolveLock();
+    const runGuarded = async (): Promise<Response> => {
+      if (!lock) return executeOnce();
+      try {
+        return await lock.block(`idempotency:lock:${cacheKey}`, IDEMPOTENCY_LOCK_TTL, executeOnce, {
+          timeout: IDEMPOTENCY_LOCK_WAIT,
+          retryDelay: 50,
+        });
+      } catch (err) {
+        // Couldn't get the lock in time — run anyway rather than fail the request.
+        if (err instanceof LockNotAcquiredError) return executeOnce();
+        throw err;
+      }
+    };
+
+    let resolveInFlight!: (r: Response) => void;
+    const inFlightPromise = new Promise<Response>((resolve) => {
+      resolveInFlight = resolve;
+    });
+    IdempotencyMiddleware._inFlight.set(cacheKey, inFlightPromise);
+
+    try {
+      const result = await runGuarded();
+      resolveInFlight(result.clone());
+      return result;
+    } catch (err) {
+      resolveInFlight(new Response("", { status: 500 }));
+      throw err;
+    } finally {
+      IdempotencyMiddleware._inFlight.delete(cacheKey);
+    }
+  }
+
+  /** Resolve the lock manager: explicit option, else the container's `lock` binding. */
+  private _resolveLock(): LockManager | null {
+    if (this.options.lock) return this.options.lock;
+    if (!this.options.useLock) return null;
+    try {
+      return (currentApp().container.tryMake("lock") as LockManager | null) ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** @internal — expose for testing only */
+  static _clearInFlight(): void {
+    IdempotencyMiddleware._inFlight.clear();
+  }
+}
+
+// ── Serialization helpers ─────────────────────────────────────────────────────
+
+async function _serialize(res: Response, bodyHash: string | null): Promise<StoredResponse> {
+  const headers: Record<string, string> = {};
+  res.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+  const body = await res.clone().text();
+  return { status: res.status, headers, body, bodyHash };
+}
+
+function _rehydrate(stored: StoredResponse, replay: boolean): Response {
+  const headers = { ...stored.headers };
+  if (replay) headers["Idempotency-Replay"] = "true";
+  return new Response(stored.body, { status: stored.status, headers });
+}
+
+async function _hashBody(req: Request): Promise<string> {
+  const buf = await req.clone().arrayBuffer();
+  const hash = await crypto.subtle.digest("SHA-256", buf);
+  return Buffer.from(hash).toString("hex");
+}

package/src/commands/CacheClearCommand.ts

@@ -0,0 +1,29 @@
+import type { Application } from "@zerotal/core";
+import { Command } from "@zerotal/core";
+import type { CacheManager } from "../CacheManager.ts";
+
+export class CacheClearCommand extends Command {
+  static commandName = "cache:clear";
+  static description = "Clear all cached values";
+  static needsApp = true;
+
+  static flags = [
+    {
+      name: "driver",
+      type: "string" as const,
+      description: "Clear a specific driver (sqlite | redis | memory)",
+    },
+  ];
+
+  async run(): Promise<void> {
+    const app = this.app as Application | undefined;
+    if (!app) {
+      this.error("Application not available.");
+      return;
+    }
+
+    const cache = app.container.makeSync("cache") as CacheManager;
+    await cache.flush();
+    this.info("Cache cleared.");
+  }
+}

package/src/commands/index.ts

@@ -0,0 +1 @@
+export { CacheClearCommand } from "./CacheClearCommand.ts";

package/src/config.ts

@@ -0,0 +1,52 @@
+import { deepMerge } from "@zerotal/core";
+
+export interface CacheConfigShape {
+  /** Which cache driver to use. Default: 'sqlite' */
+  driver: "sqlite" | "redis" | "memory";
+  /**
+   * Key prefix prepended to all cache keys. Default: `'zerotal:cache:'`.
+   * This MUST stay distinct from the queue driver's `zerotal:jobs:` namespace —
+   * a shared `zerotal:` prefix meant `Cache.flush()` (KEYS zerotal:* + DEL) also
+   * deleted every pending/failed job on the same Redis DB.
+   */
+  prefix: string;
+  /** Default TTL in seconds. Default: 3600 (1 hour) */
+  ttl: number;
+  /**
+   * Guard `remember()` recomputes with a cross-process lock so only one node runs the
+   * factory on a cold key (cache stampede protection). Requires a lock driver to be
+   * configured; degrades to in-process coalescing otherwise. Default: `true`.
+   */
+  stampedeProtection: boolean;
+  /** SQLite-specific options */
+  sqlite: {
+    /** Path to the SQLite file. Use ':memory:' for in-process cache. */
+    path: string;
+  };
+}
+
+const defaults: CacheConfigShape = {
+  driver: "sqlite",
+  prefix: "zerotal:cache:",
+  ttl: 3600,
+  stampedeProtection: true,
+  sqlite: { path: ":memory:" },
+};
+
+/**
+ * Create a typed cache configuration object with defaults.
+ *
+ * @example
+ * import { CacheConfig } from '@zerotal/cache';
+ * export default CacheConfig({ driver: 'sqlite', ttl: 600 });
+ */
+export function CacheConfig(options: Partial<CacheConfigShape> = {}): CacheConfigShape {
+  return deepMerge(defaults, options);
+}
+
+// Register this package's config namespace for typed config() dot-paths.
+declare module "@zerotal/core" {
+  interface ConfigRegistry {
+    cache: CacheConfigShape;
+  }
+}

package/src/drivers/CacheDriver.ts

@@ -0,0 +1,34 @@
+export interface CacheDriver {
+  /**
+   * Retrieve a cached value. Returns null if the key does not exist
+   * or has expired.
+   */
+  get(key: string): Promise<string | null>;
+
+  /**
+   * Store a value. ttl is in seconds; omit for no expiry.
+   */
+  set(key: string, value: string, ttl?: number): Promise<void>;
+
+  /**
+   * Remove a single key.
+   */
+  forget(key: string): Promise<void>;
+
+  /**
+   * Check whether a key exists and has not expired.
+   */
+  has(key: string): Promise<boolean>;
+
+  /**
+   * Remove all keys matching the given prefix.
+   * Used by TaggedCache to flush a tag group.
+   */
+  flush(prefix?: string): Promise<void>;
+
+  /**
+   * Release any background resources (timers, connections).
+   * Called on graceful shutdown by CacheManager.dispose().
+   */
+  dispose?(): void;
+}

package/src/drivers/MemoryDriver.ts

@@ -0,0 +1,89 @@
+import type { CacheDriver } from "./CacheDriver.ts";
+import { FrameworkEvents } from "@zerotal/core";
+import { CacheEvicted } from "../events.ts";
+
+interface Entry {
+  value: string;
+  expiresAt: number | null;
+}
+
+export class MemoryDriver implements CacheDriver {
+  private _store = new Map<string, Entry>();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private _sweepInterval: any;
+
+  /**
+   * @param sweepMs - How often to run the background sweep (ms).
+   *                  Defaults to 5 minutes. Pass 0 to disable auto-sweeping.
+   */
+  constructor(sweepMs = 5 * 60 * 1_000) {
+    if (sweepMs > 0) {
+      this._sweepInterval = setInterval(() => this.sweep(), sweepMs);
+    }
+  }
+
+  async get(key: string): Promise<string | null> {
+    const entry = this._store.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+      this._store.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+
+  async set(key: string, value: string, ttl?: number): Promise<void> {
+    const expiresAt = ttl === undefined ? null : Date.now() + ttl * 1000;
+    this._store.set(key, { value, expiresAt });
+  }
+
+  async forget(key: string): Promise<void> {
+    this._store.delete(key);
+  }
+
+  async has(key: string): Promise<boolean> {
+    const entry = this._store.get(key);
+    if (!entry) return false;
+    if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+      this._store.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  async flush(prefix?: string): Promise<void> {
+    if (prefix === undefined) {
+      this._store.clear();
+      return;
+    }
+    for (const key of this._store.keys()) {
+      if (key.startsWith(prefix)) this._store.delete(key);
+    }
+  }
+
+  /**
+   * Proactively remove all expired entries from the internal store.
+   *
+   * Called automatically on the sweep interval. Also callable manually
+   * (e.g. before taking a memory snapshot or in tests).
+   */
+  sweep(): void {
+    const now = Date.now();
+    for (const [key, entry] of this._store.entries()) {
+      if (entry.expiresAt !== null && entry.expiresAt <= now) {
+        this._store.delete(key);
+        FrameworkEvents.emit(new CacheEvicted(key, "ttl"));
+      }
+    }
+  }
+
+  /** Number of entries currently in the store (including expired-but-unswept). */
+  get size(): number {
+    return this._store.size;
+  }
+
+  /** Stop the background sweep interval. Call during graceful shutdown. */
+  dispose(): void {
+    clearInterval(this._sweepInterval);
+  }
+}

package/src/drivers/RedisDriver.ts

@@ -0,0 +1,55 @@
+import { redis } from "bun";
+import type { CacheDriver } from "./CacheDriver.ts";
+
+export class RedisDriver implements CacheDriver {
+  private _prefix: string;
+
+  constructor(prefix = "") {
+    this._prefix = prefix;
+  }
+
+  private _key(key: string): string {
+    return this._prefix + key;
+  }
+
+  async get(key: string): Promise<string | null> {
+    return redis.get(this._key(key));
+  }
+
+  async set(key: string, value: string, ttl?: number): Promise<void> {
+    const namespaced = this._key(key);
+    if (ttl === undefined) {
+      await redis.set(namespaced, value);
+      return;
+    }
+    await redis.set(namespaced, value, "EX", ttl);
+  }
+
+  async forget(key: string): Promise<void> {
+    await redis.del(this._key(key));
+  }
+
+  async has(key: string): Promise<boolean> {
+    return (await this.get(key)) !== null;
+  }
+
+  async flush(prefix?: string): Promise<void> {
+    const pattern = this._key(prefix ?? "") + "*";
+    // Iterate with SCAN rather than the blocking KEYS: KEYS walks the whole
+    // keyspace in one shot and stalls the server on large DBs. SCAN is cursored
+    // and non-blocking. The cache prefix (`zerotal:cache:`) is disjoint from the
+    // queue's `zerotal:jobs:`, so this never touches queued jobs.
+    let cursor = "0";
+    do {
+      const reply = (await redis.send("SCAN", [cursor, "MATCH", pattern, "COUNT", "100"])) as
+        [string, string[]] | null;
+      if (!reply) break;
+      cursor = reply[0];
+      const batch = reply[1] ?? [];
+      for (let i = 0; i < batch.length; i += 100) {
+        const slice = batch.slice(i, i + 100);
+        if (slice.length > 0) await redis.del(...slice);
+      }
+    } while (cursor !== "0");
+  }
+}

package/src/drivers/SqliteDriver.ts

@@ -0,0 +1,99 @@
+import type { CacheDriver } from "./CacheDriver.ts";
+
+/**
+ * Minimal SQL connection shape this driver needs — a callable tagged-template that
+ * runs a query. Declared locally so `@zerotal/cache` stays decoupled from the ORM;
+ * any Bun `SQL` instance (or the ORM's `SQLInstance`) satisfies it structurally.
+ */
+interface SqlConnection {
+  <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+}
+
+export class SqliteDriver implements CacheDriver {
+  private _sql: SqlConnection;
+  private _ready: Promise<void>;
+
+  constructor(sqlInstance: SqlConnection) {
+    this._sql = sqlInstance;
+    this._ready = this._ensureTable();
+  }
+
+  private async _ensureTable(): Promise<void> {
+    await this._sql`
+      CREATE TABLE IF NOT EXISTS zerotal_cache (
+        key        TEXT    PRIMARY KEY,
+        value      TEXT    NOT NULL,
+        expires_at INTEGER
+      )
+    `;
+  }
+
+  async get(key: string): Promise<string | null> {
+    await this._ready;
+    const now = Math.floor(Date.now() / 1000);
+    const rows = await this._sql<{ value: string }>`
+      SELECT value
+      FROM zerotal_cache
+      WHERE key = ${key}
+        AND (expires_at IS NULL OR expires_at > ${now})
+    `;
+
+    if (rows.length === 0) {
+      await this._sql`
+        DELETE FROM zerotal_cache
+        WHERE key = ${key}
+          AND expires_at IS NOT NULL
+          AND expires_at <= ${now}
+      `;
+      return null;
+    }
+
+    return rows[0]?.value ?? null;
+  }
+
+  async set(key: string, value: string, ttl?: number): Promise<void> {
+    await this._ready;
+    const expiresAt = ttl === undefined ? null : Math.floor(Date.now() / 1000) + ttl;
+
+    await this._sql`
+      INSERT OR REPLACE INTO zerotal_cache (key, value, expires_at)
+      VALUES (${key}, ${value}, ${expiresAt})
+    `;
+  }
+
+  async forget(key: string): Promise<void> {
+    await this._ready;
+    await this._sql`
+      DELETE FROM zerotal_cache
+      WHERE key = ${key}
+    `;
+  }
+
+  async has(key: string): Promise<boolean> {
+    await this._ready;
+    const now = Math.floor(Date.now() / 1000);
+    const rows = await this._sql`
+      SELECT 1 AS found
+      FROM zerotal_cache
+      WHERE key = ${key}
+        AND (expires_at IS NULL OR expires_at > ${now})
+      LIMIT 1
+    `;
+
+    return rows.length > 0;
+  }
+
+  async flush(prefix?: string): Promise<void> {
+    await this._ready;
+    if (prefix === undefined) {
+      await this._sql`DELETE FROM zerotal_cache`;
+      return;
+    }
+
+    const pattern = `${prefix}%`;
+    await this._sql`
+      DELETE FROM zerotal_cache
+      WHERE key LIKE ${pattern}
+    `;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,32 @@
+import { ZerotalError } from "@zerotal/core";
+
+/** Base class for all @zerotal/cache errors. */
+export class CacheError extends ZerotalError {
+  constructor(message: string, code = "E_CACHE", status = 500, context?: Record<string, unknown>) {
+    super(message, code, status, context);
+  }
+}
+
+/** Thrown when a value cannot be JSON-serialized for storage. */
+export class CacheSerializationError extends CacheError {
+  constructor(key: string, cause: unknown) {
+    super(
+      `[Zerotal Cache] Failed to serialize value for key "${key}": ${(cause as Error)?.message ?? String(cause)}`,
+      "E_CACHE_SERIALIZATION",
+      500,
+      { key },
+    );
+  }
+}
+
+/** Thrown when a cached value cannot be JSON-parsed on read. */
+export class CacheDeserializationError extends CacheError {
+  constructor(key: string, cause: unknown) {
+    super(
+      `[Zerotal Cache] Failed to deserialize cached value for key "${key}": ${(cause as Error)?.message ?? String(cause)}`,
+      "E_CACHE_DESERIALIZATION",
+      500,
+      { key },
+    );
+  }
+}

package/src/events.ts

@@ -0,0 +1,32 @@
+/**
+ * The cache package's framework events, emitted on core's {@link FrameworkEvents}
+ * bus. Observability packages subscribe to them by kind (their class name).
+ */
+
+/**
+ * Emitted after a cache read, write, delete, flush, or existence check. `op`
+ * records which operation ran (a read is either `hit` or `miss`).
+ *
+ * @category Cache
+ */
+export class CacheQueried {
+  constructor(
+    readonly op: "hit" | "miss" | "write" | "forget" | "flush" | "has",
+    readonly key: string,
+    readonly ttl: number | undefined,
+    readonly durationMs: number,
+  ) {}
+}
+
+/**
+ * Emitted when a cache entry is removed by the driver — `reason` distinguishes
+ * TTL expiry, capacity eviction, and manual removal.
+ *
+ * @category Cache
+ */
+export class CacheEvicted {
+  constructor(
+    readonly key: string,
+    readonly reason: "ttl" | "capacity" | "manual",
+  ) {}
+}

package/src/facades/Cache.ts

@@ -0,0 +1,3 @@
+import { createFacade } from "@zerotal/core";
+
+export const Cache = createFacade("cache");

package/src/global.d.ts

@@ -0,0 +1,30 @@
+// Ambient declarations specific to this package.
+// Bun, Node (node:*), and bun:test types come from @types/bun (→ bun-types).
+// Only declarations bun-types does NOT provide are kept here.
+
+// ── Bun globals ───────────────────────────────────────────────────────────
+// Bun extends Request with native route params (e.g. /users/:id → { id: '42' })
+interface Request {
+  readonly params?: Record<string, string>;
+}
+
+// ── SQLInstance: callable tagged-template + DB methods ────────────────────
+interface SQLInstance {
+  <T = Record<string, unknown>>(
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<T[]>;
+  begin<T>(fn: (tx: SQLInstance) => Promise<T>): Promise<T>;
+  end(): Promise<void>;
+}
+
+// ── RedisInstance: minimal Bun.redis surface ──────────────────────────────
+interface RedisInstance {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  set(key: string, value: string, options: { ex: number }): Promise<void>;
+  del(...keys: string[]): Promise<number>;
+  expire(key: string, seconds: number): Promise<number>;
+  keys(pattern: string): Promise<string[]>;
+  flushdb(): Promise<void>;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+// @zerotal/cache — public API barrel
+
+export { CacheManager, TaggedCache } from "./CacheManager.ts";
+export { IdempotencyMiddleware } from "./IdempotencyMiddleware.ts";
+export type { IdempotencyOptions } from "./IdempotencyMiddleware.ts";
+export { CacheProvider } from "./provider/CacheProvider.ts";
+export { Cache } from "./facades/Cache.ts";
+
+// Driver exports — for custom driver registration
+export type { CacheDriver } from "./drivers/CacheDriver.ts";
+export { MemoryDriver } from "./drivers/MemoryDriver.ts";
+export { SqliteDriver } from "./drivers/SqliteDriver.ts";
+export { RedisDriver } from "./drivers/RedisDriver.ts";
+
+// Config factory
+export { CacheConfig } from "./config.ts";
+export type { CacheConfigShape } from "./config.ts";
+
+// Typed error vocabulary
+export * from "./errors.ts";
+
+// Framework instrumentation events (emitted on the core FrameworkEvents bus)
+export { CacheQueried, CacheEvicted } from "./events.ts";

package/src/observability.ts

@@ -0,0 +1,79 @@
+/**
+ * Cache → observer bridges. The cache emits its own `CacheQueried` / `CacheEvicted`
+ * framework events on the core `FrameworkEvents` bus; this module forwards them to
+ * whichever observer packages are installed.
+ *
+ * Each observer's write surface is resolved from the container by binding key and
+ * typed through a local structural interface, so the cache depends on none of the
+ * observer packages — installing or removing an observer requires no change here.
+ */
+import { FrameworkEvents, RequestContext } from "@zerotal/core";
+import type { Application } from "@zerotal/core";
+import { CacheQueried, CacheEvicted } from "./events.ts";
+
+/** The subset of the monitor store this bridge calls (bound as `monitor.store`). */
+interface MonitorSink {
+  recordCache(hit: boolean, key?: string): void;
+  recordEvent(e: {
+    kind: string;
+    label: string;
+    status?: "ok" | "warn" | "bad" | "info";
+    route?: string | null;
+    data?: Record<string, unknown>;
+  }): void;
+}
+
+/** The subset of the devtools trace sink this bridge calls (bound as `devtools.trace`). */
+interface DevtoolsSink {
+  bufferCache(
+    ctx: object,
+    c: {
+      op: "has" | "hit" | "miss" | "write" | "forget" | "flush";
+      key: string;
+      ttl?: number | undefined;
+      durationMs: number;
+    },
+  ): void;
+}
+
+/**
+ * Subscribe the cache's events to every installed observer. Returns a disposer that
+ * removes every subscription; call it from the cache provider's `onStopping()`.
+ */
+export function installCacheObservability(app: Application): () => void {
+  const unsubs: Array<() => void> = [];
+
+  const store = app.container.tryMake("monitor.store" as never) as MonitorSink | undefined;
+  if (store) {
+    unsubs.push(
+      FrameworkEvents.on(CacheQueried, (e) => {
+        if (e.op === "hit") store.recordCache(true, e.key);
+        else if (e.op === "miss") store.recordCache(false, e.key);
+      }),
+      FrameworkEvents.on(CacheEvicted, (e) =>
+        store.recordEvent({
+          kind: "cache_evict",
+          label: e.key,
+          status: "info",
+          route: null,
+          data: { detail: e.reason },
+        }),
+      ),
+    );
+  }
+
+  const trace = app.container.tryMake("devtools.trace" as never) as DevtoolsSink | undefined;
+  if (trace) {
+    unsubs.push(
+      FrameworkEvents.on(CacheQueried, (e) => {
+        const ctx = RequestContext.tryGet();
+        if (!ctx) return;
+        trace.bufferCache(ctx, { op: e.op, key: e.key, ttl: e.ttl, durationMs: e.durationMs });
+      }),
+    );
+  }
+
+  return () => {
+    for (const unsub of unsubs) unsub();
+  };
+}

package/src/provider/CacheProvider.ts

@@ -0,0 +1,83 @@
+import { ServiceProvider } from "@zerotal/core";
+import type { AppEnvironment } from "@zerotal/core";
+import type { ConfigManager } from "@zerotal/core/config";
+import type { LockManager } from "@zerotal/core/lock";
+import { CacheManager } from "../CacheManager.ts";
+import { MemoryDriver } from "../drivers/MemoryDriver.ts";
+import { SqliteDriver } from "../drivers/SqliteDriver.ts";
+import { RedisDriver } from "../drivers/RedisDriver.ts";
+import { installCacheObservability } from "../observability.ts";
+import { SQL } from "bun";
+
+// Extend the core container registry
+declare module "@zerotal/core" {
+  interface ContainerBindings {
+    cache: CacheManager;
+  }
+}
+
+export class CacheProvider extends ServiceProvider {
+  static override provides = ["cache"] as const;
+  static override environments: AppEnvironment[] = ["web", "console", "test", "repl"];
+
+  private _disposeObservability: (() => void) | undefined = undefined;
+
+  override onRegister(): void {
+    this.app.container.singleton("cache", () => {
+      const config = this.app.container.makeSync("config") as ConfigManager;
+
+      const driver = config.get<string>("cache.driver", "sqlite");
+      const prefix = config.get<string>("cache.prefix", "zerotal:");
+      const ttl = config.get<number>("cache.ttl", 3600);
+      const sqlitePath = config.get<string>("cache.sqlite.path", ":memory:");
+      const stampede = config.get<boolean>("cache.stampedeProtection", true);
+
+      // Cross-process stampede protection uses the lock primitive when LockProvider
+      // is registered; otherwise remember() degrades to in-process coalescing.
+      const lock = (this.app.container.tryMake("lock") as LockManager | null) ?? null;
+
+      switch (driver) {
+        case "redis":
+          return new CacheManager(new RedisDriver(prefix), "", ttl, lock, stampede);
+
+        case "memory":
+          return new CacheManager(new MemoryDriver(), prefix, ttl, lock, stampede);
+
+        case "sqlite":
+        default: {
+          const sqlInstance = new SQL(_toSqliteUrl(sqlitePath));
+          return new CacheManager(new SqliteDriver(sqlInstance), prefix, ttl, lock, stampede);
+        }
+      }
+    });
+  }
+
+  override async onBooted(): Promise<void> {
+    // Pre-resolve so the Cache facade (makeSync) works after boot.
+    await this.app.container.make("cache");
+
+    this._disposeObservability = installCacheObservability(this.app);
+
+    const runner = this.app.container.tryMake("commands");
+    if (!runner) return;
+
+    runner.registerLazy("cache:clear", () =>
+      import("../commands/CacheClearCommand.ts").then((m) => m.CacheClearCommand),
+    );
+  }
+
+  override async onStopping(): Promise<void> {
+    this._disposeObservability?.();
+    this._disposeObservability = undefined;
+  }
+}
+
+// Bun v1.3.x on Windows only opens SQLite when the URL starts with 'sqlite:'
+// or is ':memory:'. Bare file paths are treated as PostgreSQL URLs.
+function _toSqliteUrl(path: string): string {
+  if (!path || path === ":memory:") return path;
+  if (path.startsWith("sqlite:")) return path;
+  if (path.startsWith("sqlite://")) return path.replace("sqlite://", "sqlite:");
+  if (path.startsWith("file:")) return "sqlite:" + path.slice("file:".length);
+  return "sqlite:" + path;
+}