@prisma-next/middleware-cache 0.9.0-dev.6

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2026] [Prisma Data, Inc]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,152 @@
+# @prisma-next/middleware-cache
+
+A family-agnostic, opt-in caching middleware for Prisma Next runtimes.
+
+Built on the `intercept` hook on `RuntimeMiddleware` (added in TML-2143 M1): on a cache hit, the middleware short-circuits execution and returns the cached rows; the driver is never invoked. On a cache miss, the middleware buffers rows from the driver and commits them to the store on successful completion.
+
+The package depends only on `@prisma-next/framework-components/runtime` — no SQL or Mongo runtime dependency. Cache keys come from `RuntimeMiddlewareContext.contentHash(exec)`, which the family runtime populates, so SQL and Mongo runtimes both work out of the box.
+
+## Responsibilities
+
+- Provide an opt-in caching `RuntimeMiddleware` that short-circuits repeated reads via the `intercept` hook.
+- Define the `cacheAnnotation` handle (read-only) that lane terminals (SQL DSL `.annotate(...)`, ORM read terminals) use to attach per-query cache parameters (`ttl`, `skip`, `key`).
+- Resolve the cache key per execution: per-query `cacheAnnotation({ key })` override, otherwise `RuntimeMiddlewareContext.contentHash(exec)` from the family runtime.
+- Buffer driver rows on a miss and commit to the `CacheStore` only on successful completion (`completed: true && source: 'driver'`).
+- Bypass the cache when `RuntimeMiddlewareContext.scope` is `'connection'` or `'transaction'`.
+- Ship a default in-memory LRU-with-TTL `CacheStore` and expose the `CacheStore` interface for pluggable backends (Redis, Memcached, etc.).
+
+## Dependencies
+
+- `@prisma-next/framework-components/runtime` — the only production dependency. Provides `RuntimeMiddleware`, `RuntimeMiddlewareContext` (with `contentHash` and `scope`), `defineAnnotation`, `AfterExecuteResult`, and the orchestrator integration via `runWithMiddleware`.
+
+The package does **not** depend on `@prisma-next/sql-runtime`, `@prisma-next/mongo-runtime`, or any target adapter. It does not import `node:crypto` — hashing the canonical execution identity is the family runtime's responsibility (via `@prisma-next/utils/hash-identity` in the SQL and Mongo runtimes today).
+
+
+## Quick start
+
+```typescript
+import postgres from '@prisma-next/postgres/runtime';
+import {
+  cacheAnnotation,
+  createCacheMiddleware,
+} from '@prisma-next/middleware-cache';
+import type { Contract } from './contract.d';
+import contractJson from './contract.json' with { type: 'json' };
+
+const db = postgres<Contract>({
+  contractJson,
+  url: process.env['DATABASE_URL']!,
+  middleware: [createCacheMiddleware({ maxEntries: 1000 })],
+});
+
+// First call: hits the database, caches the raw rows.
+const first = await db.orm.User.first({ id: 1 }, (meta) =>
+  meta.annotate(cacheAnnotation({ ttl: 60_000 })),
+);
+
+// Second call with the identical plan: served from cache, driver
+// not invoked.
+const second = await db.orm.User.first({ id: 1 }, (meta) =>
+  meta.annotate(cacheAnnotation({ ttl: 60_000 })),
+);
+
+// Un-annotated queries are never cached — caching is strictly opt-in.
+const fresh = await db.orm.User.first({ id: 1 }); // always hits the DB
+```
+
+## Opt-in by annotation
+
+The cache middleware acts only on plans that carry a `cacheAnnotation` payload with a `ttl` set:
+
+| Annotation state | Behavior |
+|---|---|
+| No `cacheAnnotation` on the plan | Pass through; never cached. |
+| `cacheAnnotation({ })` (no `ttl`) | Pass through; never cached. |
+| `cacheAnnotation({ skip: true })` | Pass through; never cached. |
+| `cacheAnnotation({ ttl })` | Cache lookup; commit on miss + success. |
+| `cacheAnnotation({ ttl, key })` | As above, but use the supplied key verbatim. |
+
+The annotation is **read-only**: it declares `applicableTo: ['read']`, so the lane gate (TML-2143 M2) rejects passing it to write terminals at both type and runtime levels. "Cache a mutation" is structurally impossible without an `as any` cast bypass at both the type and runtime levels — the cache middleware itself ships without any mutation classifier.
+
+```typescript
+// ✓ ORM read terminal accepts the read-only annotation via the meta callback.
+await db.orm.User.first({ id }, (meta) => meta.annotate(cacheAnnotation({ ttl: 60_000 })));
+
+// ✓ Bare-configurator form on `first` — pass `undefined` as the filter to
+// attach an annotation without narrowing further. Also valid: chain
+// `.where(...)` before `.first(undefined, ...)`.
+await db.orm.User.first(undefined, (meta) => meta.annotate(cacheAnnotation({ ttl: 60_000 })));
+
+// ✗ Type error: write terminal rejects read-only annotation.
+await db.orm.User.create(input, (meta) => meta.annotate(cacheAnnotation({ ttl: 60_000 })));
+
+// ✓ SQL DSL: chainable on select / grouped builders.
+const plan = db.sql
+  .from(tables.user)
+  .select({ id: tables.user.columns.id })
+  .annotate(cacheAnnotation({ ttl: 60_000 }))
+  .build();
+```
+
+## Cache key composition
+
+Two-tier resolution:
+
+1. **Per-query override.** `cacheAnnotation({ key })` — the supplied string is used verbatim. The cache middleware does **not** rehash user-supplied keys; the caller is responsible for keeping the string bounded in size and free of sensitive data they do not want flowing into debug logs, Redis `KEYS` output, persistence dumps, or any user-supplied `CacheStore`. User-supplied keys also bypass the storage-hash discrimination below — if you fix a key, prefix it with something tied to your schema version (e.g. `` `${storageHash}:my-key` ``) to avoid serving stale-schema entries after a migration.
+2. **Default.** `RuntimeMiddlewareContext.contentHash(exec)` — the family runtime owns this. The SQL and Mongo runtimes today compose `meta.storageHash + '|' + …` and pipe the result through `hashContent` (SHA-512), producing a bounded, opaque digest of the form `sha512:HEXDIGEST`. The cache middleware uses the returned string directly as the `Map<string, …>` key.
+
+Two consequences worth pinning (both properties of the **default** key path — user-supplied keys above opt out of both):
+
+- **Storage-hash discrimination.** A schema migration changes `meta.storageHash`, which changes `contentHash`, which invalidates cached entries automatically. Stale-schema reads cannot leak across migrations.
+- **AST rewrites are part of the key.** Middleware that rewrite the plan via `beforeCompile` (e.g. soft-delete) run **upstream** of the cache. The cache sees the post-lowering plan, so the rewritten SQL is part of the content hash. Adding or removing a `beforeCompile` middleware changes which entries hit.
+
+## `CacheStore` pluggability
+
+The default in-memory store is per-process and **not** coherent across replicas. For shared caching, supply a custom `CacheStore`:
+
+```typescript
+import type { CacheStore, CachedEntry } from '@prisma-next/middleware-cache';
+
+const redis: CacheStore = {
+  async get(key) {
+    const raw = await redisClient.get(key);
+    return raw ? (JSON.parse(raw) as CachedEntry) : undefined;
+  },
+  async set(key, entry, ttlMs) {
+    await redisClient.set(key, JSON.stringify(entry), 'PX', ttlMs);
+  },
+};
+
+const middleware = createCacheMiddleware({ store: redis });
+```
+
+The interface is intentionally minimal — `get` returns the entry if present and not expired (implementations gating on TTL should treat expired as absent), `set` writes the entry under the key with the per-call `ttlMs`. Both are async to leave room for I/O-backed stores; the default in-memory store completes synchronously and wraps results in `Promise.resolve` for type conformance.
+
+## Transaction-scope guard
+
+The middleware bypasses the cache entirely when `RuntimeMiddlewareContext.scope` is `'connection'` or `'transaction'`. Only top-level `runtime.execute` (`scope === 'runtime'`) consults the store.
+
+This avoids two surprises:
+
+- Inside a transaction, the caller expects read-after-write coherence with their own writes — the cache cannot meaningfully serve those reads without tracking the transaction's pending writes, which is out of scope for this milestone.
+- On a checked-out connection (`runtime.connection().execute(...)`), the caller has explicitly stepped outside the shared runtime surface and likely does not expect the global cache to inject results.
+
+## TTL and LRU semantics
+
+The default `createInMemoryCacheStore({ maxEntries, clock? })`:
+
+- **TTL.** Each entry is committed with the per-query `ttl` (in milliseconds). The store evaluates expiry against its injected clock (defaults to `Date.now`); reads of expired entries return `undefined` and drop the entry as a side effect.
+- **LRU.** Iteration order is the LRU order. Reads and writes both bump recency. When the live count would exceed `maxEntries`, the oldest entry is evicted.
+- **Failure handling.** The middleware commits to the store only when `afterExecute` reports `completed: true && source: 'driver'`. Driver errors mid-stream and middleware-served executions never populate the cache.
+
+## Caveats
+
+- **Default store is not coherent across replicas.** Multiple processes / pods do not share state. Use a custom `CacheStore` (Redis, etc.) for cross-process coherence.
+- **Concurrent misses both populate the store.** Two concurrent first-time reads of the same key both run the driver and both commit; last writer wins. Single-flight / coalescing semantics are deferred to a follow-up.
+- **Reads of stale-on-arrival entries.** With a custom replicated store, a follower may serve a stale entry for a brief window after the writer commits. Use the storage-hash discrimination plus a sensible TTL.
+- **No invalidation beyond TTL.** Entries are not invalidated by writes; tag-based or event-based invalidation is out of scope for this milestone. If a write invalidates a cached read, choose a TTL short enough to bound the staleness window, or pass `cacheAnnotation({ skip: true })` on the read that needs to be authoritative.
+
+## See also
+
+- [Runtime & Middleware Framework](../../../docs/architecture%20docs/subsystems/4.%20Runtime%20&%20Middleware%20Framework.md) for the SPI and middleware lifecycle (including the `intercept` hook the cache uses).
+- [ADR 204 — Single-tier runtime](../../../docs/architecture%20docs/adrs/ADR%20204%20-%20Single-tier%20runtime.md) for why the cache middleware is family-agnostic by construction.

package/dist/index.d.mts

@@ -0,0 +1,219 @@
+import * as _$_prisma_next_framework_components_runtime0 from "@prisma-next/framework-components/runtime";
+import { CrossFamilyMiddleware } from "@prisma-next/framework-components/runtime";
+
+//#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;
+}
+/**
+ * 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.
+ *
+ * Stored under namespace `'cache'` in `plan.meta.annotations`. The cache
+ * middleware reads it via `cacheAnnotation.read(plan)`.
+ *
+ * @example
+ * ```typescript
+ * import { cacheAnnotation } from '@prisma-next/middleware-cache';
+ *
+ * // ORM read terminal — accepts the read-only annotation via the meta callback.
+ * const user = await db.User.first(
+ *   { id },
+ *   (meta) => meta.annotate(cacheAnnotation({ ttl: 60_000 })),
+ * );
+ *
+ * // SQL DSL select builder — chainable.
+ * const plan = db.sql
+ *   .from(tables.user)
+ *   .annotate(cacheAnnotation({ ttl: 60_000 }))
+ *   .select({ id: tables.user.columns.id })
+ *   .build();
+ * ```
+ */
+declare const cacheAnnotation: _$_prisma_next_framework_components_runtime0.AnnotationHandle<CachePayload, "read">;
+//#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;
+}
+/**
+ * Pluggable cache backend used by the cache middleware.
+ *
+ * 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.
+ *
+ * The interface is intentionally minimal:
+ *
+ * - `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.
+ *
+ * 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.
+ */
+interface CacheStore {
+  get(key: string): Promise<CachedEntry | undefined>;
+  set(key: string, entry: CachedEntry, ttlMs: number): Promise<void>;
+}
+/**
+ * Options accepted by `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.
+ */
+interface InMemoryCacheStoreOptions {
+  readonly maxEntries: 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.).
+ */
+declare function createInMemoryCacheStore(options: InMemoryCacheStoreOptions): CacheStore;
+//#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;
+}
+/**
+ * Creates a family-agnostic caching middleware.
+ *
+ * The middleware uses three hooks:
+ *
+ * - `intercept` — on each execution, checks the cache. On a hit, returns
+ *   the cached raw rows; the runtime skips `beforeExecute`, `runDriver`,
+ *   and `onRow`, 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.
+ * - `afterExecute` — 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
+ * `@prisma-next/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.
+ *
+ * @example
+ * ```typescript
+ * import { createCacheMiddleware, cacheAnnotation } from '@prisma-next/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 })),
+ * );
+ * ```
+ */
+declare function createCacheMiddleware(options?: CacheMiddlewareOptions): CrossFamilyMiddleware;
+//#endregion
+export { type CacheMiddlewareOptions, type CachePayload, type CacheStore, type CachedEntry, type InMemoryCacheStoreOptions, cacheAnnotation, createCacheMiddleware, createInMemoryCacheStore };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/cache-annotation.ts","../src/cache-store.ts","../src/cache-middleware.ts"],"mappings":";;;;;;;;AAoBA;;;;;;;;;AAqCA;;;;;UArCiB,YAAA;EAAA,SACN,GAAA;EAAA,SACA,IAAA;EAAA,SACA,GAAA;AAAA;;;;;;;;ACoBX;;;;;;;;;;;;;;;;;;;;;AAeA;;;cDDa,eAAA,EAAe,4CAAA,CAAA,gBAAA,CAAA,YAAA;;;;;;;AArC5B;;;;;;;;;AAqCA;UC3CiB,WAAA;EAAA,SACN,IAAA,WAAe,MAAA;EAAA,SACf,QAAA;AAAA;;;;AAFX;;;;;;;;;AA6BA;;;;;;;;;;;;UAAiB,UAAA;EACf,GAAA,CAAI,GAAA,WAAc,OAAA,CAAQ,WAAA;EAC1B,GAAA,CAAI,GAAA,UAAa,KAAA,EAAO,WAAA,EAAa,KAAA,WAAgB,OAAA;AAAA;;;;;;AAavD;;;;;UAAiB,yBAAA;EAAA,SACN,UAAA;EAAA,SACA,KAAA;AAAA;;;;;;;;;ACpCX;;;;;;;;;;AAwHA;;;;;iBDrDgB,wBAAA,CAAyB,OAAA,EAAS,yBAAA,GAA4B,UAAA;;;;;ADvE9E;;;;;;;;;AAqCA;;;;UEjCiB,sBAAA;EAAA,SACN,KAAA,GAAQ,UAAA;EAAA,SACR,UAAA;EAAA,SACA,KAAA;AAAA;;;;;;;;;ADgBX;;;;;;;;;;;;;;;;;;;;;AAeA;;;;;AAiCA;;;;;;;;;;;;ACnEA;;iBAwHgB,qBAAA,CAAsB,OAAA,GAAU,sBAAA,GAAyB,qBAAA"}