@prisma/orm-extension-middleware-cache 8.0.0-rc.2-dev.3 → 8.0.0-rc.20

package/README.md

@@ -1,6 +1,6 @@
 # @prisma/orm-extension-middleware-cache
 
-Opt-in query caching for Prisma Next runtimes, for both the SQL and Mongo families.
+Opt-in query caching for Prisma 8 runtimes, for both the SQL and Mongo families.
 
 ```bash
 pnpm add @prisma/orm-extension-middleware-cache
@@ -9,15 +9,122 @@ pnpm add @prisma/orm-extension-middleware-cache
 The whole surface is the package root:
 
 ```ts
-import { cache, cacheAnnotation, type CacheStore } from '@prisma/orm-extension-middleware-cache';
+import {
+  cacheAnnotation,
+  createCacheMiddleware,
+  createInMemoryCacheStore,
+  deriveKeyFromContentHash,
+  invalidateAnnotation,
+  type CacheStore,
+} from '@prisma/orm-extension-middleware-cache';
 ```
 
 ## Responsibilities
 
-A runtime middleware that short-circuits repeated reads: on a hit it returns cached rows and never invokes the driver; on a miss it buffers the driver's rows and commits them to the store only when the execution completes successfully. Cache keys come from the family runtime's content hash of the execution, or from a per-query `cacheAnnotation({ key })` override; `ttl` and `skip` are per-query too. Connection- and transaction-scoped executions bypass the cache.
+A read-through cache middleware. An annotated ORM call, such as `db.orm.public.User.first(...)`, is cached as a whole: on a hit the middleware supplies the call's result and the ORM sends no statement; on a miss it stores the value the call returned. An annotated statement, such as a SQL builder query, is cached as rows: on a hit it returns the cached rows and never invokes the driver; on a miss it buffers the driver's rows and stores them when the read completes. A read opts in with `cacheAnnotation({ key?, meta?, bypass? })`: `key` names the entry; otherwise an ORM call is keyed by its content hash, a digest of the terminal method and the statement it sends, and a statement by the `deriveKey` option (default: the family runtime's content hash, `deriveKeyFromContentHash`); `meta` is handed to the store with the entry; `bypass: true` skips the cache for that call. A read inside a transaction or on a held connection, such as a Supabase role session, is neither served nor stored. A write annotated with `invalidateAnnotation({ keys?, meta? })` removes those entries once its effects are final.
 
-It ships an in-memory LRU-with-TTL store and exposes the `CacheStore` interface so Redis, Memcached, or any other backend can be dropped in.
+How long an entry lives is the store's policy. The default store, `createInMemoryCacheStore({ maxEntries?, ttlMs?, clock? })`, keeps up to 1000 values for 60 seconds each; `ttlMs: Infinity` never expires. A key's version is kept for `ttlMs` after the `unset` that moved it. Versions are not bounded by `maxEntries`. A forgotten version reads as 0, so with a finite `ttlMs` a read that takes longer than `ttlMs` and overlaps an `invalidate` can store stale rows. With `ttlMs: Infinity`, the versions of invalidated keys are never forgotten and grow with the number of distinct keys invalidated. A `maxEntries` that is not a positive integer or a `ttlMs` that is not positive throws `RUNTIME.ARGUMENT_INVALID`. Implement the `CacheStore` interface to use Redis, Memcached, or any other backend.
 
-## Dependencies
+## The store
 
-`@prisma/orm-framework` at an exact lockstep version, and nothing else. It depends on no family runtime and no target, which is why one middleware serves every database.
+The store is a cache of values; this middleware stores `CachedValue`, the raw rows of one statement or the result of one ORM call. The middleware tags each value `statement-rows` or `call-result` and serves it only to the same kind of read; under one key, a value with the other tag is a miss.
+
+```ts
+interface CacheEntry<TMeta = unknown, TValue = CachedValue> {
+  readonly key: string;
+  readonly meta: TMeta | undefined;
+  readonly version: number;
+  readonly data: { readonly empty: true } | { readonly empty: false; readonly value: TValue };
+}
+
+interface CacheStore<TMeta = unknown, TValue = CachedValue> {
+  get(target: {
+    readonly key: string;
+    readonly meta?: TMeta | undefined;
+  }): Promise<CacheEntry<TMeta, TValue>>;
+  set(entry: CacheEntry<TMeta, TValue>, value: TValue): Promise<boolean>;
+  unset(target: {
+    readonly keys?: readonly string[] | undefined;
+    readonly meta?: TMeta | undefined;
+  }): Promise<void>;
+}
+
+type CachedRows = readonly Record<string, unknown>[];
+
+type CachedValue =
+  | { readonly kind: 'statement-rows'; readonly rows: CachedRows }
+  | { readonly kind: 'call-result'; readonly result: unknown };
+```
+
+The store keeps a version per key, even for a key that holds no value; a key never seen has version 0, and only `unset` changes it. `get({ key, meta })` always returns a `CacheEntry` with the key, the read annotation's `meta`, the current version and `data`, which is `{ empty: true }` on a miss. A store that matches `meta` folds the versions of whatever `meta` names into that version, and does the same when `set` compares, so an `invalidate({ meta })` refuses an overlapping read's `set` even for a key the store has never seen. `set(entry, value)` stores `value` if and only if the key's version still equals `entry.version`, and returns whether it stored; there is no unconditional write, so a prefill is `get` then `set`. `unset` removes every value named in `keys` (`undefined` or non-empty) and every value that matches `meta`, increments the version of every key it removes or would remove, and an `unset` by key also drops that key from any `meta` index. A field the caller leaves out of `get` or `unset` means the same as `undefined`, and a store must not tell the two apart. `set` must be atomic against `unset`: one synchronous step in memory, or one script on a server. Keep a moved version at least as long as a read can take; the default store keeps it for `ttlMs`. The store interprets `meta` in all three methods; the middleware never does. A store that cannot act on a `meta` given to `unset` must throw: the default store throws `RUNTIME.CACHE_STORE_META_UNSUPPORTED`. `unset` must not run queries through the runtime that uses the middleware. An error from `get` or `set` fails the read, for statements and ORM calls alike, even when the database answered it; nothing is stored, so the next read fails the same way while the store keeps throwing. A store used with this middleware holds cached values: `createCacheMiddleware` takes a `CacheStore<TMeta, CachedValue>`, and a store of any other value type, `unknown` included, is a type error. `TValue` defaults to `CachedValue`, so `CacheStore<TMeta>` is a store of cached values; it exists so the same store type can serve other caches. A store must give back a value equivalent to the one it was given, `kind` included. An ORM call's result holds the values codecs decoded, such as `Date`, `bigint`, Temporal values and extension class instances, so a store that serializes needs an application-supplied serializer that rebuilds those types; `JSON.stringify` throws on a `bigint` and turns a `Date` into a string. A deploy that changes what a codec returns needs a new key prefix for a shared store, because the key does not cover how values are decoded. The default store, `createInMemoryCacheStore<TMeta>()`, holds cached values. It keeps statement rows and ORM call results differently. Statement rows are copied one level deep on `set` and `get`: the array, and each row object with its prototype. The driver's values in them, such as BSON `ObjectId`s or a `Buffer`, are kept by reference and shared with every hit; the runtime decodes them on each hit, and a codec that returns its wire value unchanged, such as a date or byte-array codec, hands every caller that same shared object. An ORM call's result has its plain structure copied on `set` and on every `get`: plain and null-prototype objects, arrays (their elements only; holes read as `undefined`), `Map`, `Set`, `Date`, `RegExp`, `ArrayBuffer`, typed arrays (a subclass such as Node's `Buffer` keeps its class) and `DataView` (copied as a plain `DataView`). Every other value in it, such as a class instance (a Temporal value, a decimal, a vector, a BSON value, an error) or a function, is shared by reference with the first caller and every hit. So, once the call has ended, changing the plain objects and arrays of a result changes no later hit; changing a shared value in place does, so codecs should return values that are not mutated in place. The store never refuses a value: `set` returns `false` only when the key's version moved. A miss copies the result once and each hit copies it again: about the work of decoding rows, linear in the size of the result. A custom store decides for itself whether to copy and what it can store.
+
+## Typed meta
+
+`CacheStore<TMeta>`, `createCacheMiddleware` and `cacheAnnotation<TMeta>` take the shape of `meta` as a type parameter; it defaults to `unknown`. `createCacheMiddleware` infers it from the store, so `invalidate` accepts only that shape:
+
+```typescript
+interface TagMeta {
+  tags: string[];
+}
+
+class TagStore implements CacheStore<TagMeta> {
+  // get({ key, meta }), set(entry, value) and unset({ keys, meta }), with meta: TagMeta | undefined
+}
+
+const cache = createCacheMiddleware({ store: new TagStore() }); // CacheMiddleware<TagMeta>
+await cache.invalidate({ meta: { tags: ['users'] } }); // compiles
+await cache.invalidate({ meta: { tag: 'users' } }); // type error
+```
+
+Nothing ties the annotation's `TMeta` to the store's at compile time, because the annotation is written where the query is and the store where the middleware is set up. A store package should therefore export a wrapper typed with its own meta, so the two agree:
+
+```typescript
+export const cached = (o: CacheAnnotationOptions<TagMeta>) => cacheAnnotation<TagMeta>(o);
+```
+
+## Deriving keys
+
+`createCacheMiddleware({ deriveKey })` computes the key of every cached statement whose annotation has no `key`. It takes the statement's execution plan, so it does not apply to an ORM call, which is keyed by its content hash. Build on the default to add a prefix:
+
+```ts
+const cache = createCacheMiddleware({
+  deriveKey: async (exec, ctx) => `users:${await deriveKeyFromContentHash(exec, ctx)}`,
+});
+```
+
+An explicit annotation `key` is used literally and bypasses `deriveKey`, so a tenant or namespace prefix must be part of it too. An app that relies on `deriveKey` to separate tenants must also separate them for annotated ORM calls, for example with a tenant-prefixed `key`; otherwise one tenant's cached ORM read can be served to another. A key belongs to one query and one terminal method: if `first()` and `all()` share a key, the one that reads the other's stored result fails with `ORM.INTERCEPTED_RESULT_INVALID` or returns the wrong shape. A derivation that returns the same key for different plans serves one plan's rows to the other, and one that drops the content hash no longer changes on a schema migration. If `deriveKey` throws, the read fails. A builder query and an ORM call that share a key evict each other's entries, so give each its own key.
+
+## Invalidation
+
+`invalidate({ keys?, meta? })` removes entries through one `store.unset({ keys, meta })` call, and does nothing when there are no keys and no `meta`.
+
+```ts
+const cache = createCacheMiddleware();
+
+await db.orm.public.User.first({ id: 1 }, (meta) =>
+  meta.annotate(cacheAnnotation({ key: 'user-1' })),
+);
+
+await db.orm.public.User.where({ id: 1 }).update({ name: 'Alicia' });
+await cache.invalidate({ keys: ['user-1'] });
+```
+
+A read that missed before an `invalidate` and finishes after it does not store its rows. Its `store.get` returned an empty entry with, say, version 3; the `unset` moves the key to version 4; `store.set(entry, rows)` then returns `false`. This works across processes that share a store, because the store owns the version. Call `invalidate` after the write has committed: inside a transaction, another request can put the old rows back in the cache before the commit. An error from the store propagates.
+
+A write can carry its invalidation instead. `invalidateAnnotation({ keys?, meta? })` takes the same `InvalidationTarget<TMeta>` as `invalidate`, and the middleware makes the same call from the runtime's `activityFinalized` event, once the write's effects are final:
+
+```ts
+await db.orm.public.User.where({ id: 1 }).update({ name: 'Alicia' }, (meta) =>
+  meta.annotate(invalidateAnnotation({ keys: ['user-1'] })),
+);
+```
+
+It applies to writes only: every SQL ORM write terminal and every SQL builder insert, update and delete accepts it, and a read rejects it at compile time and at run time. Outside a transaction it invalidates right after the write ends, after the write's own transaction when the ORM call runs one, such as an update with a relation callback or a create on a multi-table-inheritance variant. Inside `db.transaction(fn)` it invalidates when the transaction ends; until then the entry is still served. A rolled-back write does not invalidate. An `unknown` outcome, such as a failed write or a `COMMIT` that errored, does, since the write may have landed. Several annotated writes in one transaction each invalidate when it ends. The middleware reads the annotation from whatever activity carries it, an ORM call, an annotated builder statement or any client activity, and does not check the kind or the transaction. An error from `unset` is passed to `ctx.log.error` with the event `middleware.activityFinalized.error` and swallowed; the write has already happened. `postgres()`, `sqlite()` and `supabase()` drop these events unless the application passes `log`, for example `postgres({ contract: contractFromJson<Contract>(contractJson), url, middleware: [cache], log: console })`, so pass it to see a failed invalidation. So on a store that cannot act on `meta`, such as the default store, an annotation with `meta` removes nothing, not even its `keys`, and each such write only logs `RUNTIME.CACHE_STORE_META_UNSUPPORTED`. The write's promise, and `db.transaction(fn)`'s, resolve only after `store.unset` has settled, so a custom store must time out its own `unset`. A write whose activity never finalizes, such as a builder write whose row iterator is dropped without `return()`, or a process that stops between the commit and the invalidation, does not invalidate; its entries stay until they expire. The Mongo ORM's write methods take no annotations, so on Mongo call `invalidate` after the write. Because the middleware implements `activityFinalized`, a runtime that uses it keeps every transaction's finished statements until the transaction ends, whether or not any write is annotated: measured on Postgres, about 2.9 KB per statement, about 55 MB for a transaction of 20,000 statements, all released at the commit. Split a long batch import into several transactions, or run it on a client without the cache middleware.
+
+A tag scheme is a store policy: `cacheAnnotation({ meta: { tags: ['users'] } })` on the read, a store that indexes `meta.tags` in `set`, and `cache.invalidate({ meta: { tags: ['users'] } })` after the write.
+
+## Scope
+
+The middleware is a read-through cache with a control surface: keys and `deriveKey`, `meta`, `bypass`, `invalidate` and `invalidateAnnotation`, and the `CacheStore` interface. It carries data between the annotations and the store and never interprets it. Lifetime and the meaning of `meta` are the store's; the middleware decides when the invalidation a write carries runs, once the write's effects are final; deciding what a write should invalidate, for example by table, request coalescing and routing between several stores belong in extensions built on these primitives.
+
+Serve-stale strategies such as stale-while-revalidate need the hit-or-miss decision, which only the middleware makes.

package/dist/index.d.mts

@@ -1,219 +1,274 @@
-import { CrossFamilyMiddleware } from "@prisma/orm-framework/components/runtime";
+import { ActivityContext, AnnotationHandle, AnnotationValue, CrossFamilyMiddleware, ExecutionPlan } from "@prisma/orm-framework/components/runtime";
 //#region ../../../3-extensions/middleware-cache/dist/index.d.mts
 //#region src/cache-annotation.d.ts
 /**
- * Payload accepted when calling the `cacheAnnotation` handle.
- *
- * - `ttl` — Time-to-live for the cached entry, in milliseconds. When
- *   omitted, the cache middleware passes the query through untouched —
- *   presence of the annotation alone is not sufficient to enable caching.
- *   This makes the cache strictly opt-in per query.
- * - `skip` — When `true`, the cache middleware passes the query through
- *   untouched even if a `ttl` is set. Useful for selectively bypassing
- *   the cache on a per-call basis without removing the annotation
- *   entirely (e.g. a "force refresh" knob in user code).
- * - `key` — Per-query override of the cache key. When supplied, replaces
- *   the default `RuntimeMiddlewareContext.contentHash(exec)` digest.
- *   The supplied string is stored as-is — the cache middleware does
- *   **not** rehash it, so the caller is responsible for ensuring the
- *   string is bounded in size and free of sensitive data they do not
- *   want flowing into logs / Redis `KEYS` / persistence dumps.
- */
-interface CachePayload {
-  readonly ttl?: number;
-  readonly skip?: boolean;
-  readonly key?: string;
+ * Options for a read annotated with `cacheAnnotation`. A read with the annotation, in runtime scope
+ * and not bypassed, is cached; how long the entry lives is the store's policy.
+ *
+ * - `key` — the entry's key. When absent, the middleware's `deriveKey` computes it. The key is
+ *   stored and logged as given, so keep it bounded and free of secrets.
+ * - `meta` — any value, passed by reference to the store's `set` with the entry. The middleware
+ *   never reads it. Stores use it to group entries (for example by tag) or to set a lifetime.
+ * - `bypass` — when `true`, the read neither reads from nor writes to the cache.
+ *
+ * `TMeta` is the shape of `meta`; pass the store's `TMeta` so the two agree.
+ */
+interface CacheAnnotationOptions<TMeta = unknown> {
+  readonly key?: string | undefined;
+  readonly meta?: TMeta | undefined;
+  readonly bypass?: boolean | undefined;
 }
 /**
- * Read-only annotation handle for the cache middleware.
- *
- * Declared with `applicableTo: ['read']`. Write terminals supply
- * `K = 'write'` to the type-level `ValidAnnotations<'write', As>` gate
- * (and the runtime `assertAnnotationsApplicable(annotations, 'write', ...)`
- * check); the join `K extends Kinds` fails for this annotation, making
- * "cache a mutation" structurally impossible without an `as any` cast
- * bypass at both type *and* runtime levels.
+ * The type of `cacheAnnotation`: a call generic in `TMeta`, plus the read-only `namespace`,
+ * `applicableTo` and `read` of the underlying annotation handle.
+ */
+type CacheAnnotationHandle = (<TMeta = unknown>(options: CacheAnnotationOptions<TMeta>) => AnnotationValue<CacheAnnotationOptions, 'read'>) & {
+  readonly namespace: string;
+  readonly applicableTo: ReadonlySet<'read'>;
+  readonly read: AnnotationHandle<CacheAnnotationOptions, 'read'>['read'];
+};
+/**
+ * Marks a read for the cache middleware. It applies to reads only: a write terminal refuses it at
+ * compile time and at run time. The middleware reads it from a statement plan's `meta.annotations.cache`, or from the annotations of a client activity, such as an ORM read, which is then cached as a whole.
  *
- * Stored under namespace `'cache'` in `plan.meta.annotations`. The cache
- * middleware reads it via `cacheAnnotation.read(plan)`.
+ * `TMeta` types `meta` for this call only. Nothing ties it to the store's `TMeta`, so a store
+ * package should export a wrapper typed with its own meta, such as
+ * `(o: CacheAnnotationOptions<TagMeta>) => cacheAnnotation<TagMeta>(o)`.
  *
  * @example
  * ```typescript
  * import { cacheAnnotation } from '@internal/middleware-cache';
  *
  * // ORM read terminal — accepts the read-only annotation via the meta callback.
- * const user = await db.User.first(
+ * const user = await db.orm.public.User.first(
  *   { id },
- *   (meta) => meta.annotate(cacheAnnotation({ ttl: 60_000 })),
+ *   (meta) => meta.annotate(cacheAnnotation({ key: `user-${id}` })),
  * );
  *
  * // SQL DSL select builder — chainable.
  * const plan = db.sql
  *   .from(tables.user)
- *   .annotate(cacheAnnotation({ ttl: 60_000 }))
+ *   .annotate(cacheAnnotation({}))
  *   .select({ id: tables.user.columns.id })
  *   .build();
  * ```
  */
-declare const cacheAnnotation: import("@prisma/orm-framework/components/runtime").AnnotationHandle<CachePayload, "read">;
+declare const cacheAnnotation: CacheAnnotationHandle;
+/**
+ * What to invalidate: the argument of the cache middleware's `invalidate`, and the payload of `invalidateAnnotation`, which the middleware passes to the same call once the write's effects are final.
+ *
+ * `TMeta` is the shape of `meta`; pass the store's `TMeta` so the two agree.
+ */
+interface InvalidationTarget<TMeta = unknown> {
+  readonly keys?: readonly string[] | undefined;
+  readonly meta?: TMeta | undefined;
+}
+/**
+ * The type of `invalidateAnnotation`: a call generic in `TMeta`, plus the read-only `namespace`,
+ * `applicableTo` and `read` of the underlying annotation handle.
+ */
+type InvalidateAnnotationHandle = (<TMeta = unknown>(options: InvalidationTarget<TMeta>) => AnnotationValue<InvalidationTarget, 'write'>) & {
+  readonly namespace: string;
+  readonly applicableTo: ReadonlySet<'write'>;
+  readonly read: AnnotationHandle<InvalidationTarget, 'write'>['read'];
+};
+/**
+ * Marks a write whose cache entries the cache middleware invalidates once the write's effects are final: right after the write outside a transaction, or when the outermost enclosing transaction ends. It does not invalidate when the write is rolled back, and does when the outcome is unknown. It applies to writes only: a read terminal refuses it at compile time and at run time.
+ *
+ * `TMeta` types `meta` for this call only. Nothing ties it to the store's `TMeta`, so a store package should export a wrapper typed with its own meta, such as `(o: InvalidationTarget<TagMeta>) => invalidateAnnotation<TagMeta>(o)`.
+ *
+ * @example
+ * ```typescript
+ * await db.orm.public.User.where({ id: 1 }).update({ name: 'Alicia' }, (meta) =>
+ *   meta.annotate(invalidateAnnotation({ keys: ['user-1'] })),
+ * );
+ * ```
+ */
+declare const invalidateAnnotation: InvalidateAnnotationHandle;
 //#endregion
 //#region src/cache-store.d.ts
 /**
- * A cached set of rows produced by a single execution.
- *
- * - `rows` are stored raw (undecoded). The SQL runtime's `decodeRow` pass
- *   wraps the orchestrator output, so intercepted rows go through the
- *   same codec decoding as driver rows on the way to the consumer. The
- *   cache stores wire-format values; decoding happens once per consumer
- *   read regardless of where the rows came from.
- * - `storedAt` is the clock value at the moment the entry was committed
- *   to the store. It is informational metadata for callers (debugging,
- *   telemetry) and is **not** used by the in-memory store itself for
- *   expiry — TTL is driven by the store's own clock plus the `ttlMs`
- *   passed to `set`. Custom stores may use it differently.
- */
-interface CachedEntry {
-  readonly rows: readonly Record<string, unknown>[];
-  readonly storedAt: number;
+ * The rows one statement produced, stored raw (undecoded). The SQL runtime decodes intercepted rows
+ * the same way as driver rows, so a hit and a miss yield the same values to the consumer.
+ */
+type CachedRows = readonly Record<string, unknown>[];
+/**
+ * The value type the cache middleware stores: a statement's raw rows, or the result of a client activity, such as an ORM call. The middleware tags each value with what produced it: `statement-rows` for a statement's rows, `call-result` for a client activity's result. It serves `statement-rows` only to a statement and `call-result` only to a client activity; under one key, a value with the other tag is a miss.
+ */
+type CachedValue = {
+  readonly kind: 'statement-rows';
+  readonly rows: CachedRows;
+} | {
+  readonly kind: 'call-result';
+  readonly result: unknown;
+};
+/**
+ * One key of a `CacheStore`, as `get` saw it.
+ *
+ * - `key` and `meta` — what `get` was asked for. `meta` is the read annotation's `meta`, or
+ *   `undefined`.
+ * - `version` — the key's version when `get` ran. A store that matches `meta` folds the versions
+ *   of whatever `meta` names into it.
+ * - `data` — `{ empty: true }` when the store holds no live value for the key, otherwise that
+ *   value.
+ */
+interface CacheEntry<TMeta = unknown, TValue = CachedValue> {
+  readonly key: string;
+  readonly meta: TMeta | undefined;
+  readonly version: number;
+  readonly data: {
+    readonly empty: true;
+  } | {
+    readonly empty: false;
+    readonly value: TValue;
+  };
 }
 /**
- * Pluggable cache backend used by the cache middleware.
+ * A cache of values that the cache middleware reads from and writes to. The middleware stores
+ * `CachedValue`.
+ *
+ * The store keeps a version per key, an integer it keeps even for a key that holds no value. A key
+ * never seen, or forgotten, has version 0. Only `unset` changes a version.
  *
- * The default implementation is an in-memory LRU with TTL produced by
- * `createInMemoryCacheStore`. Users can supply Redis, Memcached, or any
- * other backend by implementing this interface.
+ * - `get` always returns an entry: the live value or `{ empty: true }`, and the current version.
+ *   A store that matches `meta` folds the versions of whatever `meta` names into that version, and
+ *   does the same when `set` compares, so an `unset` by `meta` refuses a read's `set` even for a
+ *   key it has never seen.
+ * - `set(entry, value)` stores `value` under `entry.key` with `entry.meta`, if and only if the
+ *   key's current version still equals `entry.version`, and returns whether it stored. `entry` is
+ *   the one `get` returned, empty or not. There is no unconditional write: to prefill, `get` then
+ *   `set`. The compare and the write must be atomic with respect to `unset`, for example one
+ *   synchronous step in memory or one script on a server.
+ * - `unset` removes every value named in `keys` and every value that matches `meta`, and
+ *   increments the version of every key it removes or would remove, including keys that hold no
+ *   value. `keys` is `undefined` or non-empty. A field the caller leaves out of `get` or `unset`
+ *   means the same as `undefined`, and a store must not tell the two apart. A store that cannot act on a `meta` it is given
+ *   must throw rather than ignore it. An `unset` by key must also drop that key from any `meta`
+ *   index the store keeps.
  *
- * The interface is intentionally minimal:
+ * `get` must give back a value equivalent to the one `set` was given, `kind` included. A call result holds the values codecs decoded, such as a `Date`, a `bigint`, a Temporal value or an extension's class instance, so a store that serializes needs a serializer that rebuilds those types; JSON does not.
  *
- * - `get` returns the entry if it exists and has not expired, or
- *   `undefined` otherwise. Implementations that gate on TTL should
- *   treat an expired entry as absent (return `undefined`) and may
- *   evict it as a side effect.
- * - `set` writes the entry under the key with an associated TTL in
- *   milliseconds. Implementations may evict other entries to make
- *   room (LRU, LFU, etc.) and may treat the operation as fire-and-
- *   forget at scale; the cache middleware does not rely on `set`
- *   completing before subsequent `get`s.
+ * Lifetime, eviction and whether values are copied are the store's policy; the middleware hands `set` the value it returns to its caller, so a store that keeps references shares that object. A version that `unset` moved must be kept at least as long as a read can take, so that a read that started before the `unset` cannot store. `unset` must not run queries through the runtime that uses the middleware.
  *
- * Both methods are async to leave the door open for I/O-backed stores
- * (Redis, S3, etc.). The default in-memory store completes
- * synchronously and wraps the result in `Promise.resolve` for type
- * conformance.
+ * `TMeta` is the shape of `meta` the store understands. The middleware does not check that a read
+ * annotation's `meta` has this shape; see `cacheAnnotation`.
  */
-interface CacheStore {
-  get(key: string): Promise<CachedEntry | undefined>;
-  set(key: string, entry: CachedEntry, ttlMs: number): Promise<void>;
+interface CacheStore<TMeta = unknown, TValue = CachedValue> {
+  get(target: {
+    readonly key: string;
+    readonly meta?: TMeta | undefined;
+  }): Promise<CacheEntry<TMeta, TValue>>;
+  set(entry: CacheEntry<TMeta, TValue>, value: TValue): Promise<boolean>;
+  unset(target: {
+    readonly keys?: readonly string[] | undefined;
+    readonly meta?: TMeta | undefined;
+  }): Promise<void>;
 }
 /**
- * Options accepted by `createInMemoryCacheStore`.
+ * Options for `createInMemoryCacheStore`.
  *
- * - `maxEntries` — hard cap on the number of live entries. Once the cap
- *   is exceeded, the least recently used entry is evicted. Reads and
- *   writes both count as "uses" for ordering purposes.
- * - `clock` — injectable time source for TTL math. Defaults to
- *   `Date.now`. Tests inject a controlled clock to verify expiry without
- *   real-time waits.
+ * - `maxEntries` — the most values kept, a positive integer; the least recently used is evicted
+ *   first. Default 1000.
+ * - `ttlMs` — how long a value lives after its `set`, and how long a key's version is kept after
+ *   the `unset` that moved it, a positive number of milliseconds. Default 60 000. Versions are not
+ *   bounded by `maxEntries`. A forgotten version reads as 0, so a read that takes longer than
+ *   `ttlMs` and overlaps an `invalidate` can store stale rows. `Infinity` never expires values or
+ *   versions: the versions of invalidated keys are never forgotten, and grow with the number of
+ *   distinct keys invalidated.
+ * - `clock` — the time source for expiry. Default `Date.now`.
  */
 interface InMemoryCacheStoreOptions {
-  readonly maxEntries: number;
+  readonly maxEntries?: number;
+  readonly ttlMs?: number;
   readonly clock?: () => number;
 }
 /**
- * Default cache backend. An LRU with per-entry TTL, backed by a `Map`.
- *
- * Eviction policy:
- *
- * - On `set` of a fresh key whose insertion would push the live count
- *   above `maxEntries`, the least recently used entry is evicted.
- *   Setting an existing key updates the entry in place and refreshes its
- *   recency without changing the live count.
- * - On `get` of an existing key, recency is bumped (so the entry is no
- *   longer the LRU candidate).
- * - On `get` of an expired entry, the entry is removed from the map and
- *   `undefined` is returned. The slot becomes available for new writes
- *   without counting against `maxEntries`.
- *
- * `Map` insertion order is the LRU order: the first key is the LRU
- * candidate; the last key is the most recently used. Bumping recency is
- * a delete-then-set on the underlying map.
- *
- * The default store is **not** coherent across processes or replicas —
- * each process holds its own Map. Users who need a shared cache supply
- * their own `CacheStore` (Redis, Memcached, etc.).
+ * The default cache store: a least-recently-used map of `CachedValue` with one lifetime for every value, local to the process. Statement rows are copied one level deep on `set` and `get`: the array, and each row object with its prototype. The driver's values in them are kept by reference and shared with every hit; the runtime decodes them on each hit, and a codec that returns its wire value unchanged, such as a date or byte-array codec, hands that shared object to the caller. A call result has its plain structure copied on `set` and on every `get`: plain and null-prototype objects, arrays (their elements only; holes read as `undefined`), `Map`, `Set`, `Date`, `RegExp`, `ArrayBuffer`, typed arrays (a subclass such as Node's `Buffer` keeps its class) and `DataView` (copied as a plain `DataView`). Every other value in it, such as a class instance (a Temporal value, a BSON value, an error) or a function, is shared by reference. So after `set` returns, a change to the plain structure of the value `set` was given, or of a value `get` returned, reaches no later `get`; a change made to a shared value, or made before `set`, does. It never refuses a value: `set` returns `false` only when the version moved. A key's version is kept for `ttlMs` after the `unset` that moved it (see `InMemoryCacheStoreOptions`). It ignores `meta` in `get` and `set`, and its `unset` rejects any `meta`, including `null`, before changing anything. It throws `RUNTIME.ARGUMENT_INVALID` for a `maxEntries` or `ttlMs` outside the ranges above.
  */
-declare function createInMemoryCacheStore(options: InMemoryCacheStoreOptions): CacheStore;
+declare function createInMemoryCacheStore<TMeta = unknown>(options?: InMemoryCacheStoreOptions): CacheStore<TMeta, CachedValue>;
 //#endregion
 //#region src/cache-middleware.d.ts
 /**
  * Options accepted by `createCacheMiddleware`.
  *
- * - `store` — pluggable cache backend. Defaults to an in-process LRU
- *   produced by `createInMemoryCacheStore`. Users supply Redis,
- *   Memcached, or any other backend by implementing the `CacheStore`
- *   interface.
- * - `maxEntries` — only consulted when `store` is omitted. Sets the
- *   `maxEntries` cap on the default in-memory store. Defaults to 1000.
- * - `clock` — injectable time source for `storedAt` stamping on
- *   committed entries. Defaults to `Date.now`. Tests inject a controlled
- *   clock to make commit-time observable. Note: TTL math lives inside
- *   the store, not the middleware — supplying a clock here only affects
- *   the `storedAt` field on committed `CachedEntry` values.
- */
-interface CacheMiddlewareOptions {
-  readonly store?: CacheStore;
-  readonly maxEntries?: number;
-  readonly clock?: () => number;
+ * - `store` — the cache backend. Defaults to `createInMemoryCacheStore()`: 1000 values, 60 s.
+ * - `deriveKey` — computes the key of a cached statement whose annotation has no `key`. Defaults
+ *   to `deriveKeyFromContentHash`. It runs on every such statement, hit or miss, and an error from
+ *   it fails the statement. It must return different keys whenever the rows can differ; build on
+ *   `deriveKeyFromContentHash` to keep the statement, parameters and storage hash. It does not
+ *   apply to a client activity, such as an ORM call, which has no execution plan: a client
+ *   activity whose annotation has no `key` is keyed by `activity.contentHash()`. A `deriveKey` that
+ *   separates tenants does not separate ORM calls; give each annotated ORM call a tenant-prefixed
+ *   `key`, or one tenant's cached ORM read can be served to another.
+ *
+ * `TMeta` is the store's meta type; `createCacheMiddleware` infers it from `store`. The store holds
+ * `CachedValue`.
+ */
+interface CacheMiddlewareOptions<TMeta = unknown> {
+  readonly store?: CacheStore<TMeta, CachedValue>;
+  readonly deriveKey?: (exec: ExecutionPlan, ctx: ActivityContext) => string | Promise<string>;
 }
 /**
- * Creates a family-agnostic caching middleware.
- *
- * The middleware uses three hooks:
- *
- * - `interceptQuery` — on each execution, checks the cache. On a hit, returns
- *   the cached raw rows; the runtime skips `runDriver` and `onRow`
- *   (`beforeQuery` is not affected — it has already run for every
- *   middleware before any `interceptQuery` is consulted) and yields the
- *   cached rows to the consumer (which, in the SQL runtime, sees them
- *   after the standard `decodeRow` pass — i.e. the cache stores
- *   wire-format values). On a miss, records a pending buffer keyed on
- *   the `exec` object identity and returns `undefined` (passthrough).
- * - `onRow` — on the miss path, appends each row yielded by the driver
- *   to the pending buffer.
- * - `afterQuery` — on the miss path, commits the buffer to the store
- *   if and only if `result.completed === true && result.source === 'driver'`.
- *   Failed executions and middleware-served executions never populate
- *   the cache. The pending buffer is cleared in all branches so a stale
- *   `WeakMap` entry cannot leak between executions sharing an `exec`.
- *
- * The middleware bypasses the cache entirely when:
- * - the plan has no `cache` annotation, or
- * - the annotation has `skip: true`, or
- * - the annotation has no `ttl`, or
- * - `ctx.scope !== 'runtime'` (connection / transaction scopes opt out).
- *
- * Returns a cross-family `RuntimeMiddleware` (no `familyId` /
- * `targetId`). The package depends only on
- * `@internal/framework-components/runtime`; cache keys come from
- * `ctx.contentHash(exec)`, populated by the family runtime, so SQL and
- * Mongo runtimes both work out of the box.
+ * The cache middleware.
+ *
+ * `invalidate` removes entries through one `store.unset({ keys, meta })` call. It does nothing
+ * when `keys` is empty or absent and `meta` is absent. The store moves the version of every key it
+ * removes, so a read that missed before the call and finishes after it does not store its rows:
+ * its conditional `store.set` returns `false`. This holds across processes that share a store. An
+ * error from the store propagates.
+ *
+ * A write annotated with `invalidateAnnotation({ keys, meta })` makes the same call from `activityFinalized`, once the write's effects are final, unless they were rolled back.
+ *
+ * `TMeta` is the store's meta type, which `invalidate`'s `meta` must have.
+ */
+type CacheMiddleware<TMeta = unknown> = CrossFamilyMiddleware & {
+  readonly invalidate: (target: InvalidationTarget<TMeta>) => Promise<void>;
+};
+/**
+ * The default `deriveKey`: the family runtime's content hash of the plan, which covers the
+ * statement, its parameters and the storage hash.
+ */
+declare function deriveKeyFromContentHash(exec: ExecutionPlan, ctx: ActivityContext): Promise<string>;
+/**
+ * Creates a read-through cache middleware that works with every family runtime. It also invalidates entries for writes annotated with `invalidateAnnotation`.
+ *
+ * It caches an activity that carries `cacheAnnotation` without `bypass` and runs in runtime scope,
+ * outside any transaction: never on a held connection, whose session may change what a read
+ * returns, and never inside a transaction, which must read its own uncommitted writes. Two kinds
+ * of activity are cached:
+ *
+ * - A statement whose plan carries the annotation, such as an annotated SQL builder query. Its key
+ *   is the annotation's `key`, else `deriveKey(exec, ctx)`; its value is the raw rows.
+ * - A client activity that carries the annotation, such as an annotated ORM read. Its key is the
+ *   annotation's `key`, else `await activity.contentHash()`; its value is the result the client
+ *   ended the activity with. It is served as a whole, so a hit sends no statement.
+ *
+ * The middleware tags each stored value `statement-rows` or `call-result` and serves `statement-rows` only to a statement and `call-result` only to a client activity; under the same key, a value with the other tag is a miss, and the read stores its own value in its place. A key therefore belongs to one query and one terminal method: an ORM call served another method's result under a shared key fails with `ORM.INTERCEPTED_RESULT_INVALID` or returns the wrong shape.
+ *
+ * - `intercept.onQuery` and `intercept.onActivity` — on a hit, return the stored rows or result,
+ *   and nothing runs. On a miss, record the pending entry.
+ * - `onRow` — collects each row of a statement miss.
+ * - `activityEnded` — when the driver completed the statement, or the client ended the call
+ *   `succeeded` with a result (`null` is a result), calls `store.set(entry, value)` with the entry
+ *   `store.get` returned, which stores only if the key's version has not moved. If an `unset` moved
+ *   it meanwhile, `set` returns `false` and the middleware logs `middleware.cache.store-skipped`.
+ * - `activityFinalized` — for any activity that carries `invalidateAnnotation`, whatever its kind or transaction, calls `invalidate` with the annotation's `keys` and `meta`, unless the outcome is `rolled-back`. An `unknown` outcome invalidates, since the write may have landed. A store error is thrown, and the runtime logs it.
  *
  * @example
  * ```typescript
- * import { createCacheMiddleware, cacheAnnotation } from '@internal/middleware-cache';
+ * const cache = createCacheMiddleware();
+ * const db = postgres({ contract, url, middleware: [cache] });
  *
- * const db = postgres({
- *   contractJson,
- *   url: process.env['DATABASE_URL']!,
- *   middleware: [createCacheMiddleware({ maxEntries: 1000 })],
- * });
- *
- * const user = await db.User.first(
- *   { id },
- *   (meta) => meta.annotate(cacheAnnotation({ ttl: 60_000 })),
+ * const user = await db.orm.public.User.first(
+ *   { id: 1 },
+ *   (meta) => meta.annotate(cacheAnnotation({ key: 'user-1' })),
+ * );
+ * await db.orm.public.User.where({ id: 1 }).update({ name: 'Alicia' }, (meta) =>
+ *   meta.annotate(invalidateAnnotation({ keys: ['user-1'] })),
  * );
  * ```
  */
-declare function createCacheMiddleware(options?: CacheMiddlewareOptions): CrossFamilyMiddleware;
+declare function createCacheMiddleware<TMeta = unknown>(options?: CacheMiddlewareOptions<TMeta>): CacheMiddleware<TMeta>;
 //#endregion
-export { type CacheMiddlewareOptions, type CachePayload, type CacheStore, type CachedEntry, type InMemoryCacheStoreOptions, cacheAnnotation, createCacheMiddleware, createInMemoryCacheStore };
+export { type CacheAnnotationHandle, type CacheAnnotationOptions, type CacheEntry, type CacheMiddleware, type CacheMiddlewareOptions, type CacheStore, type CachedRows, type CachedValue, type InMemoryCacheStoreOptions, type InvalidateAnnotationHandle, type InvalidationTarget, cacheAnnotation, createCacheMiddleware, createInMemoryCacheStore, deriveKeyFromContentHash, invalidateAnnotation };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../3-extensions/middleware-cache/dist/index.d.mts"],"mappings":";;;;;;;;;;;;;;;;;;;;;UAoBU;WACC;WACA;WACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAiCG,kEAAkE,iBAAiB;;;;;;;;;;;;;;;;;UAiBvF;WACC,eAAe;WACf;;;;;;;;;;;;;;;;;;;;;;;;;;UA0BD;EACR,IAAI,cAAc,QAAQ;EAC1B,IAAI,aAAa,OAAO,aAAa,gBAAgB;;;;;;;;;;;;UAY7C;WACC;WACA;;;;;;;;;;;;;;;;;;;;;;;;;iBAyBM,yBAAyB,SAAS,4BAA4B;;;;;;;;;;;;;;;;;;UAkBrE;WACC,QAAQ;WACR;WACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmDM,sBAAsB,UAAU,yBAAyB"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../3-extensions/middleware-cache/dist/index.d.mts"],"mappings":";;;;;;;;;;;;;;;UAcU,uBAAuB;WACtB;WACA,OAAO;WACP;;;;;;KAMN,0BAA0B,iBAAiB,SAAS,uBAAuB,WAAW,gBAAgB;WAChG;WACA,cAAc;WACd,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA4BpB,iBAAiB;;;;;;UAMrB,mBAAmB;WAClB;WACA,OAAO;;;;;;KAMb,+BAA+B,iBAAiB,SAAS,mBAAmB,WAAW,gBAAgB;WACjG;WACA,cAAc;WACd,MAAM,iBAAiB;;;;;;;;;;;;;;cAcpB,sBAAsB;;;;;;;KAO/B,sBAAsB;;;;KAItB;WACM;WACA,MAAM;;WAEN;WACA;;;;;;;;;;;;UAYD,WAAW,iBAAiB,SAAS;WACpC;WACA,MAAM;WACN;WACA;aACE;;aAEA;aACA,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAiCV,WAAW,iBAAiB,SAAS;EAC7C,IAAI;aACO;aACA,OAAO;MACd,QAAQ,WAAW,OAAO;EAC9B,IAAI,OAAO,WAAW,OAAO,SAAS,OAAO,SAAS;EACtD,MAAM;aACK;aACA,OAAO;MACd;;;;;;;;;;;;;;;UAeI;WACC;WACA;WACA;;;;;iBAKM,yBAAyB,iBAAiB,UAAU,4BAA4B,WAAW,OAAO;;;;;;;;;;;;;;;;;;;UAmBzG,uBAAuB;WACtB,QAAQ,WAAW,OAAO;WAC1B,aAAa,MAAM,eAAe,KAAK,6BAA6B;;;;;;;;;;;;;;;KAe1E,gBAAgB,mBAAmB;WAC7B,aAAa,QAAQ,mBAAmB,WAAW;;;;;;iBAM7C,yBAAyB,MAAM,eAAe,KAAK,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwCrE,sBAAsB,iBAAiB,UAAU,uBAAuB,SAAS,gBAAgB"}