@sdxc/cache 0.0.0-pre.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Xalambrí
+
+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,263 @@
+# @sdxc/cache
+
+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.
+
+## Installation
+
+```bash
+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.
+
+## 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`:
+
+```typescript
+import { WorkerKVCache } from "@sdxc/cache/worker-kv";
+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" },
+);
+
+if (isFailure(post)) return notFound();
+render(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:
+
+```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
+```
+
+Swap the adapter to cache in a test without a KV namespace or a Worker:
+
+```typescript
+import { MemoryCache } from "@sdxc/cache/memory";
+
+let cache = new MemoryCache();
+```
+
+## Nothing throws
+
+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:
+
+| 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`                   |
+
+`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`.
+
+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:
+
+```typescript
+let stored = await cache.fetch(key, load, { ttl: TTL });
+if (isFailure(stored)) throw stored.error.cause ?? stored.error;
+return stored.data;
+```
+
+**`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.
+
+## API
+
+### `Cache`
+
+The contract both adapters implement.
+
+#### `read<T>(key): Promise<Result<JSONSerialized<T> | null, CacheError>>`
+
+Reads an entry, succeeding with `null` when it is missing or expired.
+
+`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.
+
+A stored `null` succeeds with `null` too, indistinguishable from a miss. Reach for `fetch`
+where a cached `null` has to count as a hit.
+
+```typescript
+let hit = await cache.read<{ id: number }>("post:1");
+if (isSuccess(hit) && hit.data !== null) render(hit.data);
+```
+
+#### `write<T>(key, value, options?): Promise<Result<void, CacheError>>`
+
+Writes an entry, replacing any current value for the key. Succeeds once the value is
+readable.
+
+- `options.ttl` — how long the entry stays readable, as whole seconds or a duration string
+  such as `"1 hour"`. Omitted, the entry never expires.
+
+```typescript
+await cache.write("post:1", { id: 1, publishedAt: new Date() }, { ttl: "1 hour" });
+```
+
+#### `fetch<T>(key, load, options?): Promise<Result<JSONSerialized<T>, CacheError>>`
+
+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.
+
+A stored `null` is a hit here, unlike in `read`.
+
+```typescript
+let feed = await cache.fetch("feed", async () => buildFeed(), { ttl: "5 minutes" });
+```
+
+#### `delete(key): Promise<Result<void, CacheError>>`
+
+Removes an entry, succeeding whether or not it exists.
+
+### `CacheError`
+
+The failure inside every `Result`. Carries `code`, the `key` it happened on, and the
+original error as `cause`.
+
+### `MemoryCache`
+
+`@sdxc/cache/memory` — holds entries in a map for the life of the instance.
+
+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.
+
+```typescript
+new MemoryCache();
+new MemoryCache({ now: () => clock }); // expire an entry without waiting for one
+```
+
+- `options.now` — reads the current time in milliseconds. Defaults to `Date.now`.
+
+### `WorkerKVCache`
+
+`@sdxc/cache/worker-kv` — reads and writes entries in a KV namespace.
+
+```typescript
+new WorkerKVCache(env.CACHE);
+new WorkerKVCache(env.CACHE, { waitUntil: ctx.waitUntil.bind(ctx) });
+```
+
+- `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.
+
+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.
+
+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.
+
+### `conformance(options)`
+
+`@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.
+
+```typescript
+import { conformance } from "@sdxc/cache/conformance";
+
+conformance({
+	name: "MyCache",
+	create: () => new MyCache(),
+	expire: (seconds) => clock.advance(seconds),
+});
+```
+
+- `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: keying by prefix
+
+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:
+
+```typescript
+await cache.write(`post:${id}`, post, { ttl: "1 hour" });
+await cache.write(`feed:${locale}`, feed, { ttl: "5 minutes" });
+```
+
+## Pattern: a cache in a test
+
+Take `Cache` where a cache is used, and the test supplies a memory one:
+
+```typescript
+async function publishedPosts(cache: Cache): Promise<Post[]> {
+	let posts = await cache.fetch("posts", async () => db.query.posts.findMany(), {
+		ttl: "5 minutes",
+	});
+
+	return isFailure(posts) ? [] : posts.data;
+}
+
+test("reads the posts once", async () => {
+	let cache = new MemoryCache();
+
+	await publishedPosts(cache);
+	await publishedPosts(cache);
+
+	expect(queries).toHaveLength(1);
+});
+```
+
+## 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.
+
+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.
+
+Depend on one exact date, and move it when you are ready to take the change:
+
+```json
+{
+	"dependencies": {
+		"@sdxc/cache": "2026.9.4"
+	}
+}
+```
+
+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
+
+MIT
+
+## Author
+
+[Sergio Xalambrí](https://sergiodxa.com)

package/dist/adapters/memory.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A cache whose store is a map, for tests and for anything wanting a cache
+ * without a platform behind it. It serializes what it holds and expires against
+ * an injectable clock, so it answers exactly as a remote store would.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { JSONSerialized, JSONValue } from "@sdxc/types";
+import type { Cache, CacheError, CacheWriteOptions } from "../index.js";
+/** How a memory cache tells the time. */
+export interface MemoryCacheOptions {
+    /**
+     * Reads the current time in milliseconds. A test supplies its own so an entry
+     * can be expired without waiting for one.
+     *
+     * @default Date.now
+     */
+    now?: () => number;
+}
+/**
+ * Holds entries in a map for the life of the instance.
+ *
+ * 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.
+ */
+export declare class MemoryCache implements Cache {
+    #private;
+    /**
+     * @param options How the cache tells the time.
+     */
+    constructor({ now }?: MemoryCacheOptions);
+    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>>;
+    delete(key: string): Promise<Result<void, CacheError>>;
+}

package/dist/adapters/memory.js

@@ -0,0 +1,86 @@
+/**
+ * A cache whose store is a map, for tests and for anything wanting a cache
+ * without a platform behind it. It serializes what it holds and expires against
+ * an injectable clock, so it answers exactly as a remote store would.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { isFailure, isSuccess, success } from "@sdxc/result";
+import { attemptLoad } from "../lib/attempt.js";
+import { parse, serialize } from "../lib/json.js";
+import { ttlSeconds } from "../lib/ttl.js";
+/** Milliseconds in the second a TTL is counted in. */
+const SECOND_MS = 1000;
+/**
+ * Holds entries in a map for the life of the instance.
+ *
+ * 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.
+ */
+export class MemoryCache {
+    #entries = new Map();
+    #now;
+    /**
+     * @param options How the cache tells the time.
+     */
+    constructor({ now = Date.now } = {}) {
+        this.#now = now;
+    }
+    async read(key) {
+        let text = this.#read(key);
+        if (text === null)
+            return success(null);
+        return parse(key, text);
+    }
+    async write(key, value, options = {}) {
+        let text = serialize(key, value);
+        if (isFailure(text))
+            return text;
+        this.#write(key, text.data, options);
+        return success(undefined);
+    }
+    async fetch(key, load, options = {}) {
+        let stored = this.#read(key);
+        if (stored !== null) {
+            let hit = parse(key, stored);
+            if (isSuccess(hit))
+                return hit;
+        }
+        let loaded = await attemptLoad(key, load);
+        if (isFailure(loaded))
+            return loaded;
+        let text = serialize(key, loaded.data);
+        if (isFailure(text))
+            return text;
+        this.#write(key, text.data, options);
+        return parse(key, text.data);
+    }
+    async delete(key) {
+        this.#entries.delete(key);
+        return success(undefined);
+    }
+    /**
+     * The stored text, or `null` when nothing readable is held. An expired entry is
+     * dropped as it is found, which is the only sweep the map gets.
+     */
+    #read(key) {
+        let entry = this.#entries.get(key);
+        if (entry === undefined)
+            return null;
+        if (entry.expiresAt !== undefined && this.#now() >= entry.expiresAt) {
+            this.#entries.delete(key);
+            return null;
+        }
+        return entry.text;
+    }
+    /** Stores the text against the expiry the TTL resolves to. */
+    #write(key, text, { ttl }) {
+        let seconds = ttlSeconds(ttl);
+        this.#entries.set(key, {
+            text,
+            expiresAt: seconds === undefined ? undefined : this.#now() + seconds * SECOND_MS,
+        });
+    }
+}

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

@@ -0,0 +1,38 @@
+/**
+ * A cache over a Cloudflare KV namespace, which is where entries go in
+ * production. Given a `waitUntil` it hands the put to it and answers from a
+ * buffer meanwhile, so a miss never waits on KV and a write is readable regardless.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { JSONSerialized, JSONValue } from "@sdxc/types";
+import type { Cache, CacheError, CacheWriteOptions } from "../index.js";
+/** How a Worker KV cache defers its writes. */
+export interface WorkerKVCacheOptions {
+    /**
+     * Extends the invocation past the response so a put can finish after it. Given
+     * one, a write is handed over and the caller is not made to wait for KV.
+     */
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * Reads and writes entries in a KV namespace.
+ *
+ * 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.
+ */
+export declare class WorkerKVCache implements Cache {
+    #private;
+    /**
+     * @param kv The namespace entries are stored in.
+     * @param options How writes are deferred.
+     */
+    constructor(kv: KVNamespace, { 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>>;
+    delete(key: string): Promise<Result<void, CacheError>>;
+}

package/dist/adapters/worker-kv.js

@@ -0,0 +1,101 @@
+/**
+ * A cache over a Cloudflare KV namespace, which is where entries go in
+ * production. Given a `waitUntil` it hands the put to it and answers from a
+ * buffer meanwhile, so a miss never waits on KV and a write is readable regardless.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { isFailure, isSuccess, success } from "@sdxc/result";
+import { attempt, attemptLoad } from "../lib/attempt.js";
+import { parse, serialize } from "../lib/json.js";
+import { ttlSeconds } from "../lib/ttl.js";
+/**
+ * Reads and writes entries in a KV namespace.
+ *
+ * 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.
+ */
+export class WorkerKVCache {
+    #kv;
+    #waitUntil;
+    /**
+     * Values written while their put is still in flight, so a read on this instance
+     * sees what was just written. The instance is per request, which is the scope
+     * over which reading your own writes is both achievable and worth anything.
+     */
+    #pending = new Map();
+    /**
+     * @param kv The namespace entries are stored in.
+     * @param options How writes are deferred.
+     */
+    constructor(kv, { waitUntil } = {}) {
+        this.#kv = kv;
+        this.#waitUntil = waitUntil;
+    }
+    async read(key) {
+        let text = await this.#load(key);
+        if (isFailure(text))
+            return text;
+        if (text.data === null)
+            return success(null);
+        return parse(key, text.data);
+    }
+    async write(key, value, options = {}) {
+        let text = serialize(key, value);
+        if (isFailure(text))
+            return text;
+        return this.#store(key, text.data, options);
+    }
+    async fetch(key, load, options = {}) {
+        let stored = await this.#load(key);
+        if (isSuccess(stored) && stored.data !== null) {
+            let hit = parse(key, stored.data);
+            if (isSuccess(hit))
+                return hit;
+        }
+        let loaded = await attemptLoad(key, load);
+        if (isFailure(loaded))
+            return loaded;
+        let text = serialize(key, loaded.data);
+        if (isFailure(text))
+            return text;
+        await this.#store(key, text.data, options);
+        return parse(key, text.data);
+    }
+    async delete(key) {
+        let inflight = this.#pending.get(key);
+        this.#pending.delete(key);
+        if (inflight !== undefined)
+            await inflight.settled;
+        return attempt("delete", key, () => this.#kv.delete(key));
+    }
+    /** The stored text, from the buffer when a put is still in flight. */
+    async #load(key) {
+        let buffered = this.#pending.get(key);
+        if (buffered !== undefined)
+            return success(buffered.text);
+        return attempt("read", key, () => this.#kv.get(key, "text"));
+    }
+    /**
+     * Stores the text, returning once it is readable: immediately when the put is
+     * deferred, since the buffer answers for it until KV does. A deferred put is
+     * chained after any put already in flight for the key, so two writes land in order.
+     */
+    async #store(key, text, { ttl }) {
+        let put = () => this.#kv.put(key, text, { expirationTtl: ttlSeconds(ttl) });
+        if (this.#waitUntil === undefined)
+            return attempt("write", key, put);
+        let previous = this.#pending.get(key)?.settled;
+        let settled = (previous ?? Promise.resolve()).then(async () => {
+            await attempt("write", key, put);
+        });
+        this.#pending.set(key, { text, settled });
+        this.#waitUntil(settled.finally(() => {
+            if (this.#pending.get(key)?.settled === settled)
+                this.#pending.delete(key);
+        }));
+        return success(undefined);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The single failure type every cache call reports: one normalized code, the
+ * key it happened on, and the original error as `cause`. It is the error inside
+ * every `Result` the contract returns, so no cache path throws.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Normalized reason a cache call failed. A caller branches on this; the original
+ * error travels alongside as `cause`.
+ */
+export type CacheErrorCode = 
+/** The store could not be reached, or refused the operation. */
+"unavailable"
+/** JSON could not write the value handed over, or read the entry stored. */
+ | "invalid_value"
+/** The loader a `fetch` was given failed, so there is no value to answer with. */
+ | "load_failed";
+/** What a cache states about a failure when it constructs the error. */
+export interface CacheErrorOptions extends ErrorOptions {
+    code: CacheErrorCode;
+    /** The entry the call was made on. */
+    key: string;
+}
+/**
+ * Failure carried by every cache `Result`.
+ *
+ * `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. `load_failed` is the
+ * one that matters, because it means the value could not be produced at all.
+ *
+ * @example
+ * failure(new CacheError("KV refused the put", { code: "unavailable", key }));
+ */
+export declare class CacheError extends Error {
+    name: string;
+    readonly code: CacheErrorCode;
+    /** The entry the failing call was made on. */
+    readonly key: string;
+    /**
+     * @param message What went wrong, for a log or a rethrow.
+     * @param options The code, the key, and the original error as `cause`.
+     */
+    constructor(message: string, { code, key, ...options }: CacheErrorOptions);
+}

package/dist/errors.js

@@ -0,0 +1,33 @@
+/**
+ * The single failure type every cache call reports: one normalized code, the
+ * key it happened on, and the original error as `cause`. It is the error inside
+ * every `Result` the contract returns, so no cache path throws.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Failure carried by every cache `Result`.
+ *
+ * `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. `load_failed` is the
+ * one that matters, because it means the value could not be produced at all.
+ *
+ * @example
+ * failure(new CacheError("KV refused the put", { code: "unavailable", key }));
+ */
+export class CacheError extends Error {
+    name = "CacheError";
+    code;
+    /** The entry the failing call was made on. */
+    key;
+    /**
+     * @param message What went wrong, for a log or a rethrow.
+     * @param options The code, the key, and the original error as `cause`.
+     */
+    constructor(message, { code, key, ...options }) {
+        super(message, options);
+        this.code = code;
+        this.key = key;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The cache contract every adapter implements: read, write, fetch and delete
+ * over string keys. The value's type is taken per call rather than per instance,
+ * so one instance serves a whole store whatever mix of types goes into it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { DurationInput } from "@sdxc/duration";
+import type { Result } from "@sdxc/result";
+import type { JSONSerialized, JSONValue } from "@sdxc/types";
+import type { CacheError } from "./errors.js";
+export type { CacheErrorCode, CacheErrorOptions } from "./errors.js";
+export { CacheError } from "./errors.js";
+/** Expiration a write carries. */
+export interface CacheWriteOptions {
+    /**
+     * A bare number is whole seconds — the unit a store counts — while a duration
+     * string states its own unit. Omitted means the entry never expires.
+     */
+    ttl?: DurationInput;
+}
+/**
+ * A key/value store holding values a caller would rather not compute twice.
+ *
+ * Nothing here throws: every method answers with a `Result`, and a store that
+ * cannot be reached is an `unavailable` failure a caller is free to treat as a
+ * miss. A store failure is also recorded on the invocation's log, so discarding
+ * one still leaves a trace of it.
+ *
+ * A value is held as JSON, and the caller is trusted to hand over one JSON can
+ * write. The type is not constrained to `JSONSerializable`, because as a constraint
+ * it rejects an ordinary interface and any field typed `unknown` — both of which
+ * cache perfectly well. A value JSON genuinely cannot write is `invalid_value`.
+ */
+export interface Cache {
+    /**
+     * Reads an entry, succeeding with `null` when it is missing or expired.
+     *
+     * `T` is an assertion: what a store holds under a key is a fact about the past,
+     * and no signature can check it. A stored `null` succeeds with `null` too, so
+     * reach for {@link Cache.fetch} where a cached `null` has to count as a hit.
+     */
+    read<T = JSONValue>(key: string): Promise<Result<JSONSerialized<T> | null, CacheError>>;
+    /** Writes an entry, replacing any current value for the key. */
+    write<T>(key: string, value: T, options?: CacheWriteOptions): Promise<Result<void, CacheError>>;
+    /**
+     * Returns the stored entry, computing and storing it on a miss.
+     *
+     * The value is returned as it reads back, so a hit and a miss answer with the
+     * same type. A stored `null` is a hit, unlike in {@link Cache.read}.
+     *
+     * Everything the store does wrong is absorbed here, because a value can be
+     * computed instead: an unreachable store, an entry that is not JSON, and a
+     * refused write all still answer with the value. So a failure means the value
+     * could not be produced — `load_failed` when the loader failed, `invalid_value`
+     * when what it produced cannot be written.
+     */
+    fetch<T>(key: string, load: () => Promise<T>, options?: CacheWriteOptions): Promise<Result<JSONSerialized<T>, CacheError>>;
+    /** Removes an entry, succeeding whether or not it exists. */
+    delete(key: string): Promise<Result<void, CacheError>>;
+}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * The cache contract every adapter implements: read, write, fetch and delete
+ * over string keys. The value's type is taken per call rather than per instance,
+ * so one instance serves a whole store whatever mix of types goes into it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { CacheError } from "./errors.js";

package/dist/lib/attempt.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Runs the two kinds of work a cache does that can fail: a store operation, and
+ * the loader a `fetch` was given. A store failure is recorded on the invocation's
+ * log, because store health is the package's own to report; a loader's is not.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import { CacheError } from "../errors.js";
+/** The operations a store performs, which name the log entry a failure writes. */
+export type StoreOperation = "read" | "write" | "delete";
+/**
+ * @param operation What was being attempted.
+ * @param key The entry it was attempted on.
+ * @param work The store operation.
+ * @returns What the store answered, or `unavailable` when it could not.
+ */
+export declare function attempt<T>(operation: StoreOperation, key: string, work: () => Promise<T>): Promise<Result<T, CacheError>>;
+/**
+ * Runs the loader a `fetch` was given.
+ *
+ * Nothing is logged: the failure is the caller's own and travels in the `Result`,
+ * where the original error is reachable as `cause`.
+ *
+ * @param key The entry the value was being computed for.
+ * @param produce Computes the value.
+ * @returns The value, or `load_failed` when the loader threw.
+ */
+export declare function attemptLoad<T>(key: string, produce: () => Promise<T>): Promise<Result<T, CacheError>>;

package/dist/lib/attempt.js

@@ -0,0 +1,54 @@
+/**
+ * Runs the two kinds of work a cache does that can fail: a store operation, and
+ * the loader a `fetch` was given. A store failure is recorded on the invocation's
+ * log, because store health is the package's own to report; a loader's is not.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { currentLog } from "@sdxc/logger";
+import { failure, success } from "@sdxc/result";
+import { CacheError } from "../errors.js";
+/**
+ * @param operation What was being attempted.
+ * @param key The entry it was attempted on.
+ * @param work The store operation.
+ * @returns What the store answered, or `unavailable` when it could not.
+ */
+export async function attempt(operation, key, work) {
+    try {
+        return success(await work());
+    }
+    catch (cause) {
+        let reason = cause instanceof Error ? cause.message : String(cause);
+        currentLog()?.warn(`cache.${operation}.failed`, { key, reason });
+        return failure(new CacheError(`The store could not ${operation} ${key}: ${reason}`, {
+            code: "unavailable",
+            key,
+            cause,
+        }));
+    }
+}
+/**
+ * Runs the loader a `fetch` was given.
+ *
+ * Nothing is logged: the failure is the caller's own and travels in the `Result`,
+ * where the original error is reachable as `cause`.
+ *
+ * @param key The entry the value was being computed for.
+ * @param produce Computes the value.
+ * @returns The value, or `load_failed` when the loader threw.
+ */
+export async function attemptLoad(key, produce) {
+    try {
+        return success(await produce());
+    }
+    catch (cause) {
+        let reason = cause instanceof Error ? cause.message : String(cause);
+        return failure(new CacheError(`The value for ${key} could not be computed: ${reason}`, {
+            code: "load_failed",
+            key,
+            cause,
+        }));
+    }
+}

package/dist/lib/json.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Reads and writes the JSON a store holds, answering with a `Result` so a value
+ * JSON cannot write and an entry it cannot read are reported rather than thrown.
+ * Both halves live here so every adapter serializes a value the same way.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { JSONSerialized } from "@sdxc/types";
+import { CacheError } from "../errors.js";
+/**
+ * Writes the value as the text a store holds.
+ *
+ * @param key The entry being written, which the failure names.
+ * @param value What the caller handed over.
+ * @returns The text, or `invalid_value` when JSON cannot write it.
+ */
+export declare function serialize(key: string, value: unknown): Result<string, CacheError>;
+/**
+ * Reads a stored entry back.
+ *
+ * @param key The entry being read, which the failure names.
+ * @param text What the store held.
+ * @returns The value, or `invalid_value` when the entry is not JSON.
+ */
+export declare function parse<T>(key: string, text: string): Result<JSONSerialized<T>, CacheError>;

package/dist/lib/json.js

@@ -0,0 +1,56 @@
+/**
+ * Reads and writes the JSON a store holds, answering with a `Result` so a value
+ * JSON cannot write and an entry it cannot read are reported rather than thrown.
+ * Both halves live here so every adapter serializes a value the same way.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { CacheError } from "../errors.js";
+/**
+ * Writes the value as the text a store holds.
+ *
+ * @param key The entry being written, which the failure names.
+ * @param value What the caller handed over.
+ * @returns The text, or `invalid_value` when JSON cannot write it.
+ */
+export function serialize(key, value) {
+    let text;
+    try {
+        text = JSON.stringify(value);
+    }
+    catch (cause) {
+        return failure(new CacheError(`The value for ${key} cannot be written as JSON.`, {
+            code: "invalid_value",
+            key,
+            cause,
+        }));
+    }
+    if (text === undefined) {
+        return failure(new CacheError(`The value for ${key} has no JSON notation.`, {
+            code: "invalid_value",
+            key,
+        }));
+    }
+    return success(text);
+}
+/**
+ * Reads a stored entry back.
+ *
+ * @param key The entry being read, which the failure names.
+ * @param text What the store held.
+ * @returns The value, or `invalid_value` when the entry is not JSON.
+ */
+export function parse(key, text) {
+    try {
+        return success(JSON.parse(text));
+    }
+    catch (cause) {
+        return failure(new CacheError(`The entry stored for ${key} is not JSON.`, {
+            code: "invalid_value",
+            key,
+            cause,
+        }));
+    }
+}

package/dist/lib/ttl.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Turns the TTL a caller writes into the whole seconds a store counts, so a
+ * number and a duration string produce the same expiry and every adapter
+ * measures a lifetime the same way.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { DurationInput } from "@sdxc/duration";
+/**
+ * A bare number passes through unchanged, so a numeric call site keeps its exact
+ * expiry, and a duration string converts, so `3600` and `"1 hour"` agree.
+ *
+ * @param ttl How long the entry stays readable, or `undefined` for no expiry.
+ * @returns Whole seconds, or `undefined` when the entry never expires.
+ */
+export declare function ttlSeconds(ttl: DurationInput | undefined): number | undefined;

package/dist/lib/ttl.js

@@ -0,0 +1,23 @@
+/**
+ * Turns the TTL a caller writes into the whole seconds a store counts, so a
+ * number and a duration string produce the same expiry and every adapter
+ * measures a lifetime the same way.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { toSeconds } from "@sdxc/duration";
+/**
+ * A bare number passes through unchanged, so a numeric call site keeps its exact
+ * expiry, and a duration string converts, so `3600` and `"1 hour"` agree.
+ *
+ * @param ttl How long the entry stays readable, or `undefined` for no expiry.
+ * @returns Whole seconds, or `undefined` when the entry never expires.
+ */
+export function ttlSeconds(ttl) {
+    if (ttl === undefined)
+        return undefined;
+    if (typeof ttl === "number")
+        return ttl;
+    return toSeconds(ttl);
+}

package/dist/testing/conformance.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The suite that says what a cache is, registered as Vitest tests against
+ * whatever the caller constructs. Every adapter runs it, which is what makes one
+ * a substitute for another rather than something that merely resembles it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Cache } from "../index.js";
+/** What the suite needs to exercise an adapter. */
+export interface ConformanceOptions {
+    /** Adapter name, which labels the registered suite. */
+    name: string;
+    /**
+     * Builds the cache under test. It is called for every test, so an adapter
+     * holding mutable state starts each one clean.
+     */
+    create: () => Cache | Promise<Cache>;
+    /**
+     * Moves the adapter's clock forward, which is what an expiry assertion needs.
+     * An adapter that can only expire in real time leaves it out, and the suite
+     * registers the expiry tests against the adapters that can.
+     */
+    expire?: (seconds: number) => void | Promise<void>;
+}
+/**
+ * Registers the suite every cache has to pass.
+ *
+ * @param options The adapter under test.
+ */
+export declare function conformance({ name, create, expire }: ConformanceOptions): void;

package/dist/testing/conformance.js

@@ -0,0 +1,161 @@
+/**
+ * The suite that says what a cache is, registered as Vitest tests against
+ * whatever the caller constructs. Every adapter runs it, which is what makes one
+ * a substitute for another rather than something that merely resembles it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { isSuccess, unwrap } from "@sdxc/result";
+import { describe, expect, test, vi } from "vitest";
+/**
+ * The shortest TTL the suite asks for. KV refuses anything under 60 seconds, so
+ * a suite every adapter can pass cannot assert a shorter lifetime than that.
+ */
+const MIN_TTL_SECONDS = 60;
+/**
+ * Registers the suite every cache has to pass.
+ *
+ * @param options The adapter under test.
+ */
+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()}`;
+    /** The error a call answered with, asserting that it answered with one. */
+    let errorOf = (result) => {
+        if (isSuccess(result))
+            throw new Error("expected a failure, got a success");
+        return result.error;
+    };
+    describe(`${name} conformance`, () => {
+        test("reads back what was written", async () => {
+            let cache = await create();
+            let k = key();
+            unwrap(await cache.write(k, { id: 1, tags: ["news"] }));
+            expect(unwrap(await cache.read(k))).toStrictEqual({ id: 1, tags: ["news"] });
+        });
+        test("succeeds with null for a key it holds nothing for", async () => {
+            let cache = await create();
+            expect(unwrap(await cache.read(key()))).toBeNull();
+        });
+        test("is readable as soon as a write resolves", async () => {
+            let cache = await create();
+            let k = key();
+            unwrap(await cache.write(k, "value"));
+            expect(unwrap(await cache.read(k))).toBe("value");
+        });
+        test("replaces the value a key already holds", async () => {
+            let cache = await create();
+            let k = key();
+            unwrap(await cache.write(k, "first"));
+            unwrap(await cache.write(k, "second"));
+            expect(unwrap(await cache.read(k))).toBe("second");
+        });
+        test("removes an entry, and removing a missing one succeeds", async () => {
+            let cache = await create();
+            let k = key();
+            unwrap(await cache.write(k, "value"));
+            unwrap(await cache.delete(k));
+            unwrap(await cache.delete(k));
+            expect(unwrap(await cache.read(k))).toBeNull();
+        });
+        test("returns what it holds without computing", async () => {
+            let cache = await create();
+            let k = key();
+            let load = vi.fn(async () => "computed");
+            unwrap(await cache.write(k, "stored"));
+            expect(unwrap(await cache.fetch(k, load))).toBe("stored");
+            expect(load).not.toHaveBeenCalled();
+        });
+        test("computes once on a miss and stores what it computed", async () => {
+            let cache = await create();
+            let k = key();
+            let load = vi.fn(async () => "computed");
+            expect(unwrap(await cache.fetch(k, load))).toBe("computed");
+            expect(unwrap(await cache.fetch(k, load))).toBe("computed");
+            expect(load).toHaveBeenCalledTimes(1);
+        });
+        test("answers a hit and a miss with the same type", async () => {
+            let cache = await create();
+            let k = key();
+            let load = async () => ({ at: new Date("2026-09-07T00:00:00.000Z") });
+            let miss = unwrap(await cache.fetch(k, load));
+            let hit = unwrap(await cache.fetch(k, load));
+            expect(miss).toStrictEqual({ at: "2026-09-07T00:00:00.000Z" });
+            expect(hit).toStrictEqual(miss);
+        });
+        test("counts a stored null as a hit", async () => {
+            let cache = await create();
+            let k = key();
+            let load = vi.fn(async () => null);
+            expect(unwrap(await cache.fetch(k, load))).toBeNull();
+            expect(unwrap(await cache.fetch(k, load))).toBeNull();
+            expect(load).toHaveBeenCalledTimes(1);
+        });
+        test("reports a failed loader as load_failed, carrying what it threw", async () => {
+            let cache = await create();
+            let thrown = new Error("loader failed");
+            let error = errorOf(await cache.fetch(key(), async () => {
+                throw thrown;
+            }));
+            expect(error.code).toBe("load_failed");
+            expect(error.cause).toBe(thrown);
+        });
+        test("reports a value JSON cannot write as invalid_value", async () => {
+            let cache = await create();
+            let cyclic = [];
+            cyclic.push(cyclic);
+            expect(errorOf(await cache.write(key(), cyclic)).code).toBe("invalid_value");
+            expect(errorOf(await cache.fetch(key(), async () => cyclic)).code).toBe("invalid_value");
+        });
+        test("names the key on every failure it reports", async () => {
+            let cache = await create();
+            let k = key();
+            let error = errorOf(await cache.fetch(k, async () => {
+                throw new Error("loader failed");
+            }));
+            expect(error.key).toBe(k);
+        });
+        test("keeps an entry written without a ttl", async () => {
+            let cache = await create();
+            let k = key();
+            unwrap(await cache.write(k, "value"));
+            expect(unwrap(await cache.read(k))).toBe("value");
+        });
+        if (expire === undefined)
+            return;
+        test("hides an entry once its ttl has passed", async () => {
+            let cache = await create();
+            let k = key();
+            unwrap(await cache.write(k, "value", { ttl: MIN_TTL_SECONDS }));
+            await expire(MIN_TTL_SECONDS);
+            expect(unwrap(await cache.read(k))).toBeNull();
+        });
+        test("keeps an entry until its ttl has passed", async () => {
+            let cache = await create();
+            let k = key();
+            unwrap(await cache.write(k, "value", { ttl: MIN_TTL_SECONDS }));
+            await expire(MIN_TTL_SECONDS - 1);
+            expect(unwrap(await cache.read(k))).toBe("value");
+        });
+        test("counts a duration string and its seconds as the same lifetime", async () => {
+            let cache = await create();
+            let seconds = key();
+            let duration = key();
+            unwrap(await cache.write(seconds, "value", { ttl: 60 }));
+            unwrap(await cache.write(duration, "value", { ttl: "1 minute" }));
+            await expire(MIN_TTL_SECONDS);
+            expect(unwrap(await cache.read(seconds))).toBeNull();
+            expect(unwrap(await cache.read(duration))).toBeNull();
+        });
+        test("recomputes through fetch once the entry has expired", async () => {
+            let cache = await create();
+            let k = key();
+            let load = vi.fn(async () => "computed");
+            unwrap(await cache.fetch(k, load, { ttl: MIN_TTL_SECONDS }));
+            await expire(MIN_TTL_SECONDS);
+            unwrap(await cache.fetch(k, load, { ttl: MIN_TTL_SECONDS }));
+            expect(load).toHaveBeenCalledTimes(2);
+        });
+    });
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@sdxc/cache",
+	"version": "0.0.0-pre.1",
+	"description": "Cache contract with adapters for memory and Cloudflare KV",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js",
+		"./conformance": "./dist/testing/conformance.js",
+		"./memory": "./dist/adapters/memory.js",
+		"./worker-kv": "./dist/adapters/worker-kv.js"
+	},
+	"dependencies": {
+		"@sdxc/duration": "2026.9.11",
+		"@sdxc/logger": "2026.9.11",
+		"@sdxc/result": "2026.9.11",
+		"@sdxc/types": "2026.9.11"
+	},
+	"gitHead": "e96a064f9208eb667923f57374e2cdaac73c72fb",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/cache"
+	}
+}