@sdxc/cache 2026.10.12 → 2026.10.16

package/README.md

@@ -2,241 +2,305 @@
 
 Cache contract with adapters for memory and Cloudflare KV.
 
-One interface covers read, write, fetch and delete, and an adapter binds it to a store — an
-in-process map for tests, Workers KV in production. Nothing throws: every call answers with a
-`Result`, and each method takes the value's type on its own, so one instance serves a whole
-namespace whatever mix of types goes into it.
+One `Cache` interface covers read, write, fetch and delete, and an adapter binds it to a store:
+an in-process map for tests, Workers KV in production. Every call answers with a `Result`, and
+each method takes the value's type on its own, so one instance serves a whole namespace.
 
 ## Installation
 
-```bash
+```sh
 npm add @sdxc/cache
 ```
 
-Every call answers with a `Result` from
-[`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result), which is where `isFailure` and
-`isSuccess` come from. It installs alongside this package.
+Calls answer with a `Result` from [`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result),
+where `isFailure` and `isSuccess` come from; it installs alongside this package.
 
 ## Usage
 
-An instance is a store, not a type. Each method takes the value's type on its own, so one
-cache serves a whole namespace whatever mix of types goes into it. Nothing throws — every
-call answers with a `Result`:
+### Compute once, read many times
 
 ```typescript
-import { WorkerKVCache } from "@sdxc/cache/worker-kv";
+import { MemoryCache } from "@sdxc/cache/memory";
 import { isFailure } from "@sdxc/result";
 
-let cache = new WorkerKVCache(env.CACHE, { waitUntil: ctx.waitUntil.bind(ctx) });
-
-let post = await cache.fetch(
-	`post:${id}`,
-	async () => db.query.posts.findFirst({ where: eq(posts.id, id) }),
-	{ ttl: "5 minutes" },
-);
+let cache = new MemoryCache();
 
-if (isFailure(post)) return notFound();
-render(post.data);
+let post = await cache.fetch(`post:${id}`, async () => loadPost(id), { ttl: "5 minutes" });
+if (isFailure(post)) return new Response(null, { status: 500 });
+return Response.json(post.data);
 ```
 
-`fetch` takes the type from the loader, so nothing is annotated and nothing is cast. What
-comes back is what reads back out of the store, which is not always what went in:
+`fetch` returns the stored entry, or runs the loader on a miss and stores what it returns. The
+type comes from the loader, so nothing is annotated.
+
+### Read, write and delete entries
 
 ```typescript
-let session = await cache.fetch("session", async () => ({ at: new Date() }));
-//  Result<{ at: string }, CacheError> — a Date is written as the string it serializes to
-```
+import { isSuccess } from "@sdxc/result";
 
-Swap the adapter to cache in a test without a KV namespace or a Worker:
+await cache.write("post:1", { id: 1, title: "Hello" }, { ttl: "1 hour" });
 
-```typescript
-import { MemoryCache } from "@sdxc/cache/memory";
+let hit = await cache.read<{ id: number; title: string }>("post:1");
+if (isSuccess(hit) && hit.data !== null) console.info(hit.data.title);
 
-let cache = new MemoryCache();
+await cache.delete("post:1");
 ```
 
-## Nothing throws
+`read` succeeds with `null` for a missing or expired entry. A `ttl` is whole seconds or a
+duration string such as `"1 hour"`; without one the entry never expires.
 
-Every method answers with a `Result<_, CacheError>` from
-[`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result), and `CacheError.code` says
-which of three things happened:
+### Values come back as JSON
 
-| Code            | Means                                                    | Reached by                |
-| --------------- | -------------------------------------------------------- | ------------------------- |
-| `unavailable`   | The store could not be reached, or refused the operation | `read`, `write`, `delete` |
-| `invalid_value` | JSON could not write the value, or read the entry stored | every method              |
-| `load_failed`   | The loader a `fetch` was given failed                    | `fetch`                   |
+Entries are stored as JSON, and every method answers with the value as it reads back, so a hit
+and a miss have the same type:
 
-`unavailable` is the one a caller can ignore: the value is simply not cached, and computing
-it is the same recovery a miss asks for. A store failure is also recorded on the
-invocation's log through [`@sdxc/logger`](https://www.npmjs.com/package/@sdxc/logger), so
-discarding one still leaves a trace — store health is the package's own to report. A
-`load_failed` is not logged, because it is the caller's and travels in the `Result`.
+```typescript
+let session = await cache.fetch("session", async () => ({ at: new Date() }));
+// Result<{ at: string }, CacheError>: the Date reads back as its ISO string
+```
 
-Every failure carries the `key` it happened on, and the original error as `cause`. So a
-caller that would rather throw rethrows the cause and keeps its own error type:
+### Store entries in Workers KV
 
 ```typescript
-let stored = await cache.fetch(key, load, { ttl: TTL });
-if (isFailure(stored)) throw stored.error.cause ?? stored.error;
-return stored.data;
+import { WorkerKVCache } from "@sdxc/cache/worker-kv";
+
+let cache = new WorkerKVCache(env.CACHE, { waitUntil: ctx.waitUntil.bind(ctx) });
 ```
 
-**`fetch` absorbs everything the store does wrong**, because it can compute a value
-instead: an unreachable store, an entry that is not JSON, and a refused write all still
-answer with the value. So a `fetch` failure means the value could not be produced at all.
+With `waitUntil`, a write returns at once and the put finishes after the response; the instance
+answers reads of that key from memory until KV holds it. Create one instance per request.
 
 ## API
 
 ### `Cache`
 
-The contract both adapters implement.
+The contract every adapter implements, exported from `@sdxc/cache`.
 
-#### `read<T>(key): Promise<Result<JSONSerialized<T> | null, CacheError>>`
+#### `read<T = JSONValue>(key: string): Promise<Result<JSONSerialized<T> | null, CacheError>>`
 
-Reads an entry, succeeding with `null` when it is missing or expired.
+Reads an entry, succeeding with `null` when it is missing or expired. `T` is an assertion about
+what the store holds. A stored `null` also reads as `null`; use `fetch` where a cached `null` must
+count as a hit.
 
-`T` is an assertion. What a store holds under a key is a fact about the past, and no
-signature can check it, so the parameter states a claim rather than verifying one. It
-defaults to `JSONValue` for a caller who would rather narrow the result.
+#### `write<T>(key: string, value: T, options?: CacheWriteOptions): Promise<Result<void, CacheError>>`
 
-A stored `null` succeeds with `null` too, indistinguishable from a miss. Reach for `fetch`
-where a cached `null` has to count as a hit.
+Stores an entry, replacing any current value for the key. The entry is readable once the call
+succeeds.
 
-```typescript
-let hit = await cache.read<{ id: number }>("post:1");
-if (isSuccess(hit) && hit.data !== null) render(hit.data);
-```
+#### `fetch<T>(key: string, load: () => Promise<T>, options?: CacheWriteOptions): Promise<Result<JSONSerialized<T>, CacheError>>`
+
+Returns the stored entry, or computes, stores and returns it on a miss. A stored `null` is a
+hit. Store problems (unreachable store, an entry that is not JSON, a refused write) still answer
+with the computed value, so a failure means the value could not be produced: `load_failed` or
+`invalid_value`.
 
-#### `write<T>(key, value, options?): Promise<Result<void, CacheError>>`
+#### `delete(key: string): Promise<Result<void, CacheError>>`
 
-Writes an entry, replacing any current value for the key. Succeeds once the value is
-readable.
+Removes an entry, succeeding whether or not it exists.
 
-- `options.ttl` — how long the entry stays readable, as whole seconds or a duration string
-  such as `"1 hour"`. Omitted, the entry never expires.
+### `CacheError`
 
-```typescript
-await cache.write("post:1", { id: 1, publishedAt: new Date() }, { ttl: "1 hour" });
-```
+The error inside every failed `Result`: `code`, the `key` the call was made on, and the original
+error as `cause`.
 
-#### `fetch<T>(key, load, options?): Promise<Result<JSONSerialized<T>, CacheError>>`
+| `code`          | Means                                                       | Reached by                |
+| --------------- | ----------------------------------------------------------- | ------------------------- |
+| `unavailable`   | The store could not be reached, or refused the operation    | `read`, `write`, `delete` |
+| `invalid_value` | JSON could not write the value, or could not read the entry | every method but `delete` |
+| `load_failed`   | The loader given to `fetch` threw or rejected               | `fetch`                   |
 
-Returns the stored entry, computing and storing it on a miss. The type comes from `load`,
-and the value is returned as it reads back, so a hit and a miss answer with the same type.
+An `unavailable` failure is also logged as a warning on the current invocation's log from
+[`@sdxc/logger`](https://www.npmjs.com/package/@sdxc/logger), so a caller can treat it as a miss
+and still leave a trace.
 
-A stored `null` is a hit here, unlike in `read`.
+### `new MemoryCache(options?: MemoryCacheOptions)`
 
-```typescript
-let feed = await cache.fetch("feed", async () => buildFeed(), { ttl: "5 minutes" });
-```
+From `@sdxc/cache/memory`. Holds entries in a map for the life of the instance, serializing on
+write and parsing on read exactly as a remote store does; a value read back is a copy.
 
-#### `delete(key): Promise<Result<void, CacheError>>`
+- `options.now`: returns the current time in milliseconds, for expiring entries in a test.
+  Defaults to `Date.now`.
 
-Removes an entry, succeeding whether or not it exists.
+### `new WorkerKVCache(kv: KVNamespace, options?: WorkerKVCacheOptions)`
 
-### `CacheError`
+From `@sdxc/cache/worker-kv`. Stores entries in a Cloudflare KV namespace.
 
-The failure inside every `Result`. Carries `code`, the `key` it happened on, and the
-original error as `cause`.
+- `options.waitUntil`: extends the invocation past the response. Given one, writes are deferred
+  to it, the instance answers reads from those writes immediately, writes to one key land in
+  order, and a `delete` waits for a pending put.
 
-### `MemoryCache`
+KV rejects a TTL under 60 seconds: the entry is not written and the put reports `unavailable`.
 
-`@sdxc/cache/memory` — holds entries in a map for the life of the instance.
+### `conformance(options: ConformanceOptions): void`
 
-It is not a mock. It serializes on write and parses on read, so a `Date` comes back as a
-string here exactly as it would from a remote store, and it passes the same conformance
-suite every other adapter does. A value read back is a copy, so mutating it changes
-nothing that is stored.
+From `@sdxc/cache/conformance`. Registers Vitest tests asserting the `Cache` contract against an
+adapter you construct.
 
-```typescript
-new MemoryCache();
-new MemoryCache({ now: () => clock }); // expire an entry without waiting for one
-```
+- `options.name`: labels the registered suite.
+- `options.create`: builds the cache under test; called once per test.
+- `options.expire`: moves the adapter's clock forward by a number of seconds. Leave it out and
+  the expiry tests are skipped.
 
-- `options.now` — reads the current time in milliseconds. Defaults to `Date.now`.
+### Types
 
-### `WorkerKVCache`
+#### `CacheWriteOptions`
 
-`@sdxc/cache/worker-kv` — reads and writes entries in a KV namespace.
+`{ ttl?: DurationInput }`, where `DurationInput` from
+[`@sdxc/duration`](https://www.npmjs.com/package/@sdxc/duration) is whole seconds or a duration
+string.
+
+#### `CacheErrorCode`
+
+`"unavailable" | "invalid_value" | "load_failed"`.
+
+#### `CacheErrorOptions`
+
+What `new CacheError(message, options)` takes: `code`, `key`, and the standard `cause`. An
+adapter of your own builds its failures with it.
+
+#### `MemoryCacheOptions`, `WorkerKVCacheOptions`, `ConformanceOptions`
+
+The options objects described above.
+
+## Pattern: Accept Any Cache, Test With Memory
+
+Type a dependency as `Cache` so production passes the KV adapter and a test passes a memory one.
 
 ```typescript
-new WorkerKVCache(env.CACHE);
-new WorkerKVCache(env.CACHE, { waitUntil: ctx.waitUntil.bind(ctx) });
-```
+import type { Cache } from "@sdxc/cache";
+import { MemoryCache } from "@sdxc/cache/memory";
+import { isFailure } from "@sdxc/result";
+import { expect, test, vi } from "vitest";
+
+interface Post {
+	id: string;
+	title: string;
+}
+
+async function publishedPosts(cache: Cache, load: () => Promise<Post[]>) {
+	let posts = await cache.fetch("posts:published", load, { ttl: "5 minutes" });
+	return isFailure(posts) ? [] : posts.data;
+}
 
-- `options.waitUntil` — extends the invocation past the response. Given one, a write is
-  handed over and the caller is not made to wait for KV.
+test("loads the posts once", async () => {
+	let cache = new MemoryCache();
+	let load = vi.fn(async () => [{ id: "1", title: "Hello" }]);
 
-A deferred write is still readable the moment it succeeds: the value is held on the
-instance until the put lands, and an instance is per request, which is the scope over
-which reading your own writes is both achievable and worth anything. Two writes to one key
-land in the order they were made, and a `delete` waits for a put still in flight.
+	await publishedPosts(cache, load);
+	await publishedPosts(cache, load);
 
-KV refuses a TTL under 60 seconds, so a shorter one leaves the entry unwritten and reports
-`unavailable`. A caller wanting a shorter lifetime than that wants something other than a
-cache.
+	expect(load).toHaveBeenCalledTimes(1);
+});
+```
 
-### `conformance(options)`
+## Pattern: Expire Entries On A Test Clock
 
-`@sdxc/cache/conformance` — registers the suite that says what a cache is, as Vitest tests
-against whatever you construct. Run it against a new adapter and it is a cache, or it is
-not.
+Pass `now` to control time, and an entry expires without waiting for it.
 
 ```typescript
-import { conformance } from "@sdxc/cache/conformance";
+import { MemoryCache } from "@sdxc/cache/memory";
+import { unwrap } from "@sdxc/result";
+import { expect, test } from "vitest";
 
-conformance({
-	name: "MyCache",
-	create: () => new MyCache(),
-	expire: (seconds) => clock.advance(seconds),
+test("an entry expires after its ttl", async () => {
+	let clock = 0;
+	let cache = new MemoryCache({ now: () => clock });
+
+	unwrap(await cache.write("token", "abc", { ttl: "1 minute" }));
+	clock += 59_000;
+	expect(unwrap(await cache.read("token"))).toBe("abc");
+
+	clock += 1_000;
+	expect(unwrap(await cache.read("token"))).toBeNull();
 });
 ```
 
-- `name` — labels the registered suite.
-- `create` — builds the cache under test, called for every test so a mutable adapter starts
-  clean.
-- `expire` — moves the adapter's clock forward. An adapter that can only expire in real
-  time leaves it out, and the expiry tests are registered only for the adapters that can.
+## Pattern: Cache Per Request In A Worker
+
+Build the KV adapter inside the handler so read-your-own-writes stays scoped to one request, and
+key entries by what they hold so a shared namespace stays readable.
 
-## Pattern: keying by prefix
+```typescript
+import { WorkerKVCache } from "@sdxc/cache/worker-kv";
+import { isFailure } from "@sdxc/result";
+
+interface Env {
+	CACHE: KVNamespace;
+}
 
-Prefix a key by what it holds, so entries are recognizable in a namespace shared with other
-caches and a related group can be reasoned about together:
+export default {
+	async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+		let cache = new WorkerKVCache(env.CACHE, { waitUntil: ctx.waitUntil.bind(ctx) });
+		let locale = new URL(request.url).searchParams.get("locale") ?? "en";
+
+		let feed = await cache.fetch(`feed:${locale}`, async () => buildFeed(locale), {
+			ttl: "10 minutes",
+		});
+		if (isFailure(feed)) return new Response("Feed unavailable", { status: 503 });
+
+		return Response.json(feed.data);
+	},
+};
+```
+
+## Pattern: Invalidate After A Write
+
+Delete the cached entry when the source changes, and the next `fetch` recomputes it.
 
 ```typescript
-await cache.write(`post:${id}`, post, { ttl: "1 hour" });
-await cache.write(`feed:${locale}`, feed, { ttl: "5 minutes" });
+import type { Cache } from "@sdxc/cache";
+
+async function renamePost(cache: Cache, id: string, title: string) {
+	await savePostTitle(id, title);
+	await cache.delete(`post:${id}`);
+}
 ```
 
-## Pattern: a cache in a test
+## Pattern: Rethrow Failures
 
-Take `Cache` where a cache is used, and the test supplies a memory one:
+A caller that prefers exceptions rethrows the original error, keeping its own error type.
 
 ```typescript
-async function publishedPosts(cache: Cache): Promise<Post[]> {
-	let posts = await cache.fetch("posts", async () => db.query.posts.findMany(), {
-		ttl: "5 minutes",
-	});
+import type { Cache } from "@sdxc/cache";
+import { isFailure } from "@sdxc/result";
 
-	return isFailure(posts) ? [] : posts.data;
+async function cachedReport(cache: Cache, month: string) {
+	let report = await cache.fetch(`report:${month}`, async () => buildReport(month), {
+		ttl: "1 day",
+	});
+	if (isFailure(report)) throw report.error.cause ?? report.error;
+	return report.data;
 }
+```
 
-test("reads the posts once", async () => {
-	let cache = new MemoryCache();
+## Pattern: Verify A Custom Adapter
 
-	await publishedPosts(cache);
-	await publishedPosts(cache);
+Implement `Cache` over another store, answer its failures with a `CacheError`, and run the
+conformance suite against it in a test file.
 
-	expect(queries).toHaveLength(1);
+```typescript
+import type { Cache } from "@sdxc/cache";
+import { CacheError } from "@sdxc/cache";
+import { conformance } from "@sdxc/cache/conformance";
+import { failure } from "@sdxc/result";
+
+export function unavailable(key: string, cause: unknown) {
+	return failure(
+		new CacheError(`The store could not reach ${key}`, { code: "unavailable", key, cause }),
+	);
+}
+
+conformance({
+	name: "RedisCache",
+	create: (): Cache => new RedisCache(redis),
 });
 ```
 
 ## Versioning
 
-Releases are dated rather than semantic. A version is the UTC date it was published,
-written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one
-release goes out per day.
+Releases are dated rather than semantic. A version is the UTC date it was published, written
+`YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one release goes out per
+day.
 
 Those numbers say when, not what: a later date means a later release and carries no
 compatibility promise. Any release may change or remove an export.
@@ -251,8 +315,8 @@ Depend on one exact date, and move it when you are ready to take the change:
 }
 ```
 
-A caret or tilde range reads the date as major, minor and patch, so it accepts every
-later release in the same year. An exact version keeps the upgrade yours to schedule.
+A caret or tilde range reads the date as major, minor and patch, so it accepts every later
+release in the same year. An exact version keeps the upgrade yours to schedule.
 
 ## License
 

package/dist/adapters/worker-kv.d.ts

@@ -9,6 +9,17 @@
 import type { Result } from "@sdxc/result";
 import type { JSONSerialized, JSONValue } from "@sdxc/types";
 import type { Cache, CacheError, CacheWriteOptions } from "../index.js";
+/**
+ * The calls this cache makes on a Workers KV binding. Declared here so a binding typed by any
+ * source fits it: a Worker's generated types, `@cloudflare/workers-types`, or a test's own.
+ */
+export interface WorkerKVNamespace {
+    get(key: string, type: "text"): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
 /** How a Worker KV cache defers its writes. */
 export interface WorkerKVCacheOptions {
     /**
@@ -30,7 +41,7 @@ export declare class WorkerKVCache implements Cache {
      * @param kv The namespace entries are stored in.
      * @param options How writes are deferred.
      */
-    constructor(kv: KVNamespace, { waitUntil }?: WorkerKVCacheOptions);
+    constructor(kv: WorkerKVNamespace, { waitUntil }?: WorkerKVCacheOptions);
     read<T = JSONValue>(key: string): Promise<Result<JSONSerialized<T> | null, CacheError>>;
     write<T>(key: string, value: T, options?: CacheWriteOptions): Promise<Result<void, CacheError>>;
     fetch<T>(key: string, load: () => Promise<T>, options?: CacheWriteOptions): Promise<Result<JSONSerialized<T>, CacheError>>;

package/dist/testing/conformance.js

@@ -7,6 +7,7 @@
  * @copyright Sergio Xalambrí 2026
  */
 import { isSuccess, unwrap } from "@sdxc/result";
+import { generateUUID } from "@sdxc/uuid/v4";
 import { describe, expect, test, vi } from "vitest";
 /**
  * The shortest TTL the suite asks for. KV refuses anything under 60 seconds, so
@@ -20,7 +21,7 @@ const MIN_TTL_SECONDS = 60;
  */
 export function conformance({ name, create, expire }) {
     /** A key no other test has used, so adapters sharing a store cannot collide. */
-    let key = () => `conformance:${crypto.randomUUID()}`;
+    let key = () => `conformance:${generateUUID()}`;
     /** The error a call answered with, asserting that it answered with one. */
     let errorOf = (result) => {
         if (isSuccess(result))

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/cache",
-	"version": "2026.10.12",
+	"version": "2026.10.16",
 	"description": "Cache contract with adapters for memory and Cloudflare KV",
 	"license": "MIT",
 	"type": "module",
@@ -11,12 +11,13 @@
 		"./worker-kv": "./dist/adapters/worker-kv.js"
 	},
 	"dependencies": {
-		"@sdxc/duration": "2026.10.6",
-		"@sdxc/logger": "2026.10.12",
-		"@sdxc/result": "2026.10.6",
-		"@sdxc/types": "2026.10.2"
+		"@sdxc/duration": "2026.10.13",
+		"@sdxc/logger": "2026.10.16",
+		"@sdxc/result": "2026.10.13",
+		"@sdxc/types": "2026.10.13",
+		"@sdxc/uuid": "2026.10.13"
 	},
-	"gitHead": "857ef87ddb0b2484e28b46431d0740fcc80e5f33",
+	"gitHead": "1e547d8431568f5ed9bdb079ca3046c936240fde",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -25,7 +26,7 @@
 		"url": "git+https://github.com/sergiodxa/monorepo.git",
 		"directory": "packages/cache"
 	},
-	"homepage": "https://sdxc.sergiodxa.com/api/cache",
+	"homepage": "https://sdxc.dev/api/cache",
 	"author": {
 		"name": "Sergio Xalambrí",
 		"url": "https://sergiodxa.com"