@classytic/repo-core 0.24.0 → 0.26.0

package/dist/cache/engine.d.mts

@@ -22,8 +22,36 @@ type SingleFlightClaim<T = unknown> = {
   readonly status: 'wait';
   readonly promise: Promise<T>;
 };
+/**
+ * Resolve the adapter to use for THIS call, or `undefined` for "no cache
+ * right now".
+ *
+ * Exists so a cache can be scoped to something narrower than the process —
+ * a request, a job run, a unit of work — without this package learning what
+ * any of those are. The resolver is the whole seam: repo-core asks "is there
+ * a store for the current scope?", and whoever owns the lifecycle answers.
+ *
+ * **`undefined` must mean INERT, never "make one".** A resolver that returns
+ * nothing outside its scope is the correct, safe answer for cron jobs,
+ * scripts and tests — the alternative (falling back to a process-wide store)
+ * is exactly the cross-request leak the scoping exists to prevent, and it
+ * would be invisible.
+ */
+type CacheAdapterResolver = () => CacheAdapter | undefined;
+/**
+ * Either a fixed adapter (process-lifetime, the original contract) or a
+ * resolver consulted per call. A bare adapter is sugar for `() => adapter`.
+ */
+type CacheAdapterSource = CacheAdapter | CacheAdapterResolver;
 declare class CacheEngine {
-  private readonly adapter;
+  /**
+   * Consulted PER CALL, never cached in a field.
+   *
+   * Memoising the first resolution would defeat the entire purpose: the
+   * second request would be served the first request's store. The whole
+   * point of the indirection is that the answer changes.
+   */
+  private readonly resolveAdapter;
   private readonly prefix;
   private readonly jitter;
   /**
@@ -34,7 +62,7 @@ declare class CacheEngine {
    * unbounded burst).
    */
   private readonly pending;
-  constructor(adapter: CacheAdapter, options?: CacheEngineOptions);
+  constructor(adapter: CacheAdapterSource, options?: CacheEngineOptions);
   /**
    * Read a cache entry under SWR + TTL semantics. Returns a
    * structured `CacheReadResult` describing freshness state — the
@@ -123,4 +151,4 @@ declare class CacheEngine {
   prefetch<TData>(key: string, opts: ResolvedCacheOptions, fetcher: () => Promise<TData>): Promise<TData>;
 }
 //#endregion
-export { CacheEngine, CacheEngineOptions, SingleFlightClaim };
+export { CacheAdapterResolver, CacheAdapterSource, CacheEngine, CacheEngineOptions, SingleFlightClaim };

package/dist/cache/engine.mjs

@@ -24,7 +24,14 @@ import { bumpModelVersion, getModelVersion } from "./version-store.mjs";
 * call it directly when they need fine-grained control.
 */
 var CacheEngine = class {
-	adapter;
+	/**
+	* Consulted PER CALL, never cached in a field.
+	*
+	* Memoising the first resolution would defeat the entire purpose: the
+	* second request would be served the first request's store. The whole
+	* point of the indirection is that the answer changes.
+	*/
+	resolveAdapter;
 	prefix;
 	jitter;
 	/**
@@ -36,7 +43,7 @@ var CacheEngine = class {
 	*/
 	pending = /* @__PURE__ */ new Map();
 	constructor(adapter, options = {}) {
-		this.adapter = adapter;
+		this.resolveAdapter = typeof adapter === "function" ? adapter : () => adapter;
 		this.prefix = options.prefix ?? "rc";
 		this.jitter = resolveJitter(options.jitter);
 	}
@@ -62,7 +69,12 @@ var CacheEngine = class {
 			status: "bypass",
 			data: void 0
 		};
-		const raw = await this.adapter.get(key);
+		const adapter = this.resolveAdapter();
+		if (!adapter) return {
+			status: "disabled",
+			data: void 0
+		};
+		const raw = await adapter.get(key);
 		const inspection = inspectEnvelope(raw);
 		if (inspection.state === "missing" || inspection.state === "expired") return {
 			status: "miss",
@@ -98,12 +110,14 @@ var CacheEngine = class {
 	*/
 	async set(key, value, opts) {
 		if (!opts.enabled) return;
+		const adapter = this.resolveAdapter();
+		if (!adapter) return;
 		const tags = opts.tags;
 		const envelope = buildEnvelope(value, opts.staleTime, opts.gcTime, tags);
 		const totalSeconds = opts.staleTime + opts.gcTime;
 		const ttl = this.jitter(totalSeconds);
-		await this.adapter.set(key, envelope, ttl);
-		if (tags.length > 0) await appendKeyToTags(this.adapter, this.prefix, key, tags, ttl);
+		await adapter.set(key, envelope, ttl);
+		if (tags.length > 0) await appendKeyToTags(adapter, this.prefix, key, tags, ttl);
 	}
 	/**
 	* Look up an in-flight fetch for `key`. Returns the promise the
@@ -157,7 +171,9 @@ var CacheEngine = class {
 	* the index. Returns the count of entries removed.
 	*/
 	async invalidateByTags(tags) {
-		return invalidateByTags(this.adapter, this.prefix, tags);
+		const adapter = this.resolveAdapter();
+		if (!adapter) return 0;
+		return invalidateByTags(adapter, this.prefix, tags);
 	}
 	/**
 	* Read a model's current version (optionally per-scope). Used by
@@ -165,7 +181,9 @@ var CacheEngine = class {
 	* version bump orphans the model's cache space.
 	*/
 	async getVersion(model, scopeKey) {
-		return getModelVersion(this.adapter, this.prefix, model, scopeKey);
+		const adapter = this.resolveAdapter();
+		if (!adapter) return 0;
+		return getModelVersion(adapter, this.prefix, model, scopeKey);
 	}
 	/**
 	* Bump the model's version (per-scope when `scopeKey` is supplied)
@@ -174,11 +192,15 @@ var CacheEngine = class {
 	* invalidation.
 	*/
 	async bumpVersion(model, scopeKey) {
-		return bumpModelVersion(this.adapter, this.prefix, model, scopeKey);
+		const adapter = this.resolveAdapter();
+		if (!adapter) return 0;
+		return bumpModelVersion(adapter, this.prefix, model, scopeKey);
 	}
 	/** Wipe the entire cache namespace (when the adapter supports `clear`). */
 	async clear() {
-		if (this.adapter.clear) await this.adapter.clear(`${this.prefix}:*`);
+		const adapter = this.resolveAdapter();
+		if (!adapter) return;
+		if (adapter.clear) await adapter.clear(`${this.prefix}:*`);
 	}
 	/** Expose the prefix so plugins building keys downstream stay aligned. */
 	get keyPrefix() {

package/dist/cache/index.d.mts

@@ -1,9 +1,9 @@
 import { CacheOptions, CacheReadResult } from "./options.mjs";
 import { CacheAdapter } from "./types.mjs";
-import { CacheEngine, CacheEngineOptions, SingleFlightClaim } from "./engine.mjs";
+import { CacheAdapterResolver, CacheAdapterSource, CacheEngine, CacheEngineOptions, SingleFlightClaim } from "./engine.mjs";
 import { MemoryCacheAdapterOptions, createMemoryCacheAdapter } from "./memory-adapter.mjs";
 import { DEFAULT_SHAPE_KEYS_BY_OP } from "./plugin/context.mjs";
 import { DEFAULT_CACHEABLE_OPS, DEFAULT_INVALIDATING_OPS, LogCallbacks, RepositoryCacheHandle, RepositoryCachePluginOptions, cachePlugin } from "./plugin/index.mjs";
 import { scheduleBackground } from "./runtime.mjs";
 import { CacheTimeoutError, TimeoutAdapterOptions, withTimeout } from "./timeout-adapter.mjs";
-export { type CacheAdapter, CacheEngine, type CacheEngineOptions, type CacheOptions, type CacheReadResult, CacheTimeoutError, DEFAULT_CACHEABLE_OPS, DEFAULT_INVALIDATING_OPS, DEFAULT_SHAPE_KEYS_BY_OP, type LogCallbacks, type MemoryCacheAdapterOptions, type RepositoryCacheHandle, type RepositoryCachePluginOptions, type SingleFlightClaim, type TimeoutAdapterOptions, cachePlugin, createMemoryCacheAdapter, scheduleBackground, withTimeout };
+export { type CacheAdapter, type CacheAdapterResolver, type CacheAdapterSource, CacheEngine, type CacheEngineOptions, type CacheOptions, type CacheReadResult, CacheTimeoutError, DEFAULT_CACHEABLE_OPS, DEFAULT_INVALIDATING_OPS, DEFAULT_SHAPE_KEYS_BY_OP, type LogCallbacks, type MemoryCacheAdapterOptions, type RepositoryCacheHandle, type RepositoryCachePluginOptions, type SingleFlightClaim, type TimeoutAdapterOptions, cachePlugin, createMemoryCacheAdapter, scheduleBackground, withTimeout };

package/dist/cache/plugin/index.d.mts

@@ -1,7 +1,6 @@
 import { Plugin } from "../../repository/plugin-types.mjs";
 import { CacheOptions, CacheReadResult } from "../options.mjs";
-import { CacheAdapter } from "../types.mjs";
-import { CacheEngine } from "../engine.mjs";
+import { CacheAdapterSource, CacheEngine } from "../engine.mjs";
 import { DEFAULT_SHAPE_KEYS_BY_OP } from "./context.mjs";
 //#region src/cache/plugin/index.d.ts
 /** Default read ops the plugin caches. Kits may override per resource. */
@@ -24,8 +23,27 @@ interface LogCallbacks {
   onInvalidate?: (model: string, version: number, tagCount: number) => void;
 }
 interface RepositoryCachePluginOptions {
-  /** Concrete adapter — Redis, in-memory, custom KV. */
-  readonly adapter: CacheAdapter;
+  /**
+   * Concrete adapter — Redis, in-memory, custom KV — OR a resolver consulted
+   * per call that returns the store for the current scope.
+   *
+   * The resolver form is what makes a cache narrower than the process
+   * possible (per-request, per-job, per-unit-of-work) without this package
+   * knowing what those are. Returning `undefined` means "no cache right now"
+   * and the call behaves exactly as `enabled: false` — it does not fall back
+   * to a shared store, because that fallback IS the cross-scope leak the
+   * scoping exists to prevent.
+   *
+   * @example Process-lifetime (unchanged)
+   * ```ts
+   * cachePlugin({ adapter: createMemoryCacheAdapter() })
+   * ```
+   * @example Request-scoped — dies with the request, no TTL needed
+   * ```ts
+   * cachePlugin({ adapter: () => requestScopedCache() })
+   * ```
+   */
+  readonly adapter: CacheAdapterSource;
   /** Read ops the plugin caches. Default: every op in `DEFAULT_CACHEABLE_OPS`. */
   readonly enabled?: readonly string[];
   /** Mutating ops that trigger invalidation. Default: every op in `DEFAULT_INVALIDATING_OPS`. */

package/dist/loader/batch-loader.d.mts

@@ -0,0 +1,94 @@
+//#region src/loader/batch-loader.d.ts
+/**
+ * Collapse many per-item reads issued in one operation into ONE round trip.
+ *
+ * The read-side counterpart of `bulkWrite`: a loop that awaits a read per item
+ * costs N round trips, and against a remote cluster the round trip IS the cost.
+ * Hand the loader the keys and it issues a single batched call per tick.
+ *
+ * ## Scope: per OPERATION, never process-lived
+ *
+ * A loader caches, so its lifetime is a correctness property. Create one per
+ * request / transaction / placement and let it die with that work. A loader
+ * held on a repository instance serves a stale value forever, which is the
+ * failure mode a plain memo already has — this primitive does not fix it, it
+ * inherits it, so scope is the caller's job.
+ *
+ * ## The contract `batch` MUST honour
+ *
+ * `batch(keys)` returns results POSITIONALLY: `result[i]` belongs to `keys[i]`.
+ * A length mismatch is refused rather than tolerated — silently zipping a short
+ * array assigns one key's value to a different key, and every downstream check
+ * still passes because the values are individually well-formed.
+ *
+ * @example
+ * const products = createBatchLoader<string, Product>({
+ *   batch: async (ids) => {
+ *     const rows = await repo.getAll({ filters: { _id: { $in: [...ids] } } });
+ *     const byId = new Map(rows.map((r) => [String(r._id), r]));
+ *     return ids.map((id) => byId.get(id));   // positional, same length
+ *   },
+ * });
+ * const [a, b] = await Promise.all([products.load('1'), products.load('2')]); // ONE query
+ *
+ * ## The trap: an awaited loop batches NOTHING
+ *
+ * The batch window is one microtask, so any `await` between two `load` calls
+ * closes it:
+ *
+ *     for (const id of ids) await loader.load(id);   // N batches, not 1
+ *
+ * That returns correct data and no error — only `stats.batches` shows it. Use
+ * `loadMany`, or issue the loads before awaiting them, and assert
+ * `stats.batches` when the round-trip count is the point.
+ */
+/** Default cap on one batched call — keeps a generated `$in` bounded. */
+declare const DEFAULT_MAX_BATCH_SIZE = 500;
+interface BatchLoaderOptions<K, V> {
+  /**
+   * Load every key in one call. MUST return one entry per key, in the same
+   * order. Use `undefined` for "no such key" — throwing rejects the whole batch.
+   */
+  batch: (keys: readonly K[]) => Promise<ReadonlyArray<V | undefined>>;
+  /**
+   * Cache identity for a key. Required when `K` is an object — the default
+   * (`String(key)`) collapses every object to `[object Object]`, which would
+   * merge unrelated keys into one entry.
+   */
+  keyOf?: (key: K) => string;
+  /** Split larger requests into several calls. Defaults to {@link DEFAULT_MAX_BATCH_SIZE}. */
+  maxBatchSize?: number;
+  /**
+   * Refuse a batch that resolved NOTHING for keys it was given.
+   *
+   * The length check catches a `.filter()`/`.slice()` mistake. It cannot catch
+   * the commoner one: a `Map` keyed on `ObjectId` while the keys are strings,
+   * or keyed on `_id` while the caller passes `skuRef`. That returns the right
+   * LENGTH and all `undefined` — and `undefined` is this loader's documented
+   * value for "no such key", so a total lookup failure is indistinguishable
+   * from "these rows do not exist".
+   *
+   * Set `true` when every key is expected to resolve (a `$in` over ids you just
+   * read). Leave it off for a genuine existence check.
+   */
+  requireAllResolved?: boolean;
+}
+interface BatchLoader<K, V> {
+  /** Queue one key; resolves when its batch settles. */
+  load(key: K): Promise<V | undefined>;
+  /** Queue many keys as one batch, positionally. */
+  loadMany(keys: readonly K[]): Promise<Array<V | undefined>>;
+  /** Seed a value the caller already holds, so it is never fetched. */
+  prime(key: K, value: V | undefined): void;
+  /** Drop one key, or the whole cache — use after a write invalidates a read. */
+  clear(key?: K): void;
+  /** Observability: how many batched calls this loader has made. */
+  readonly stats: {
+    batches: number;
+    keys: number;
+    cacheHits: number;
+  };
+}
+declare function createBatchLoader<K, V>(options: BatchLoaderOptions<K, V>): BatchLoader<K, V>;
+//#endregion
+export { BatchLoader, BatchLoaderOptions, DEFAULT_MAX_BATCH_SIZE, createBatchLoader };

package/dist/loader/batch-loader.mjs

@@ -0,0 +1,153 @@
+//#region src/loader/batch-loader.ts
+/**
+* Collapse many per-item reads issued in one operation into ONE round trip.
+*
+* The read-side counterpart of `bulkWrite`: a loop that awaits a read per item
+* costs N round trips, and against a remote cluster the round trip IS the cost.
+* Hand the loader the keys and it issues a single batched call per tick.
+*
+* ## Scope: per OPERATION, never process-lived
+*
+* A loader caches, so its lifetime is a correctness property. Create one per
+* request / transaction / placement and let it die with that work. A loader
+* held on a repository instance serves a stale value forever, which is the
+* failure mode a plain memo already has — this primitive does not fix it, it
+* inherits it, so scope is the caller's job.
+*
+* ## The contract `batch` MUST honour
+*
+* `batch(keys)` returns results POSITIONALLY: `result[i]` belongs to `keys[i]`.
+* A length mismatch is refused rather than tolerated — silently zipping a short
+* array assigns one key's value to a different key, and every downstream check
+* still passes because the values are individually well-formed.
+*
+* @example
+* const products = createBatchLoader<string, Product>({
+*   batch: async (ids) => {
+*     const rows = await repo.getAll({ filters: { _id: { $in: [...ids] } } });
+*     const byId = new Map(rows.map((r) => [String(r._id), r]));
+*     return ids.map((id) => byId.get(id));   // positional, same length
+*   },
+* });
+* const [a, b] = await Promise.all([products.load('1'), products.load('2')]); // ONE query
+*
+* ## The trap: an awaited loop batches NOTHING
+*
+* The batch window is one microtask, so any `await` between two `load` calls
+* closes it:
+*
+*     for (const id of ids) await loader.load(id);   // N batches, not 1
+*
+* That returns correct data and no error — only `stats.batches` shows it. Use
+* `loadMany`, or issue the loads before awaiting them, and assert
+* `stats.batches` when the round-trip count is the point.
+*/
+/** Default cap on one batched call — keeps a generated `$in` bounded. */
+const DEFAULT_MAX_BATCH_SIZE = 500;
+function createBatchLoader(options) {
+	const { batch } = options;
+	/**
+	* REFUSES an object key rather than stringifying it. `String({})` is
+	* `[object Object]` for every object, so the default would merge unrelated
+	* keys into one entry and hand the first one's value to all of them — and
+	* report the collisions as cache HITS, so the telemetry would say the loader
+	* was working well while line 2 received line 1's row.
+	*/
+	const keyOf = options.keyOf ?? ((k) => {
+		if (k !== null && typeof k === "object") throw new TypeError("batch loader: an object key needs an explicit `keyOf` — String(key) collides them all");
+		return String(k);
+	});
+	const requested = options.maxBatchSize ?? 500;
+	if (!Number.isInteger(requested) || requested < 1) throw new TypeError(`batch loader: maxBatchSize must be a positive integer, received ${String(requested)}`);
+	const maxBatchSize = requested;
+	/** Settled + in-flight results, keyed by cache identity. */
+	const cache = /* @__PURE__ */ new Map();
+	/** Keys queued for the next tick, with everyone waiting on each. */
+	let queue = [];
+	let scheduled = false;
+	const stats = {
+		batches: 0,
+		keys: 0,
+		cacheHits: 0
+	};
+	async function runBatch(entries) {
+		const keys = entries.map((e) => e.key);
+		stats.batches += 1;
+		stats.keys += keys.length;
+		try {
+			const results = await batch(keys);
+			if (results.length !== keys.length) throw new Error(`batch loader: batch() returned ${results.length} results for ${keys.length} keys — results must be positional and the same length`);
+			if (options.requireAllResolved && keys.length > 0 && results.every((r) => r === void 0)) throw new Error(`batch loader: batch() resolved NOTHING for ${keys.length} key(s) — likely a key-type mismatch between the keys and the lookup (ObjectId vs string, _id vs skuRef)`);
+			entries.forEach((entry, i) => {
+				for (const w of entry.waiters) w.resolve(results[i]);
+			});
+		} catch (err) {
+			for (const entry of entries) {
+				cache.delete(entry.id);
+				for (const w of entry.waiters) w.reject(err);
+			}
+		}
+	}
+	function schedule() {
+		if (scheduled) return;
+		scheduled = true;
+		queueMicrotask(() => {
+			scheduled = false;
+			const entries = queue;
+			queue = [];
+			if (entries.length === 0) return;
+			for (let i = 0; i < entries.length; i += maxBatchSize) runBatch(entries.slice(i, i + maxBatchSize));
+		});
+	}
+	/**
+	* No queue scan here. `load` writes the promise into `cache` synchronously,
+	* so a repeated key in the same tick is served from there and never reaches
+	* this function — a `queue.find` would be an unreachable O(n) per load, i.e.
+	* quadratic on exactly the large batch this primitive exists for.
+	*/
+	function enqueue(key, id) {
+		const promise = new Promise((resolve, reject) => {
+			queue.push({
+				key,
+				id,
+				waiters: [{
+					resolve,
+					reject
+				}]
+			});
+		});
+		schedule();
+		return promise;
+	}
+	function load(key) {
+		const id = keyOf(key);
+		const hit = cache.get(id);
+		if (hit) {
+			stats.cacheHits += 1;
+			return hit;
+		}
+		const promise = enqueue(key, id);
+		cache.set(id, promise);
+		return promise;
+	}
+	return {
+		load,
+		loadMany: (keys) => Promise.all(keys.map(load)),
+		prime(key, value) {
+			cache.set(keyOf(key), Promise.resolve(value));
+		},
+		/**
+		* Cache only — an in-flight fetch is left to settle for the caller already
+		* waiting on it. Dropping its queue entry would abandon that waiter
+		* forever. A load issued after this gets its own entry, because `enqueue`
+		* no longer joins by key (see the note there).
+		*/
+		clear(key) {
+			if (key === void 0) cache.clear();
+			else cache.delete(keyOf(key));
+		},
+		stats
+	};
+}
+//#endregion
+export { DEFAULT_MAX_BATCH_SIZE, createBatchLoader };

package/dist/loader/index.d.mts

@@ -0,0 +1,2 @@
+import { BatchLoader, BatchLoaderOptions, DEFAULT_MAX_BATCH_SIZE, createBatchLoader } from "./batch-loader.mjs";
+export { type BatchLoader, type BatchLoaderOptions, DEFAULT_MAX_BATCH_SIZE, createBatchLoader };

package/dist/loader/index.mjs

@@ -0,0 +1,2 @@
+import { DEFAULT_MAX_BATCH_SIZE, createBatchLoader } from "./batch-loader.mjs";
+export { DEFAULT_MAX_BATCH_SIZE, createBatchLoader };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
   "type": "module",
   "sideEffects": false,
@@ -98,6 +98,10 @@
       "types": "./dist/lock/index.d.mts",
       "default": "./dist/lock/index.mjs"
     },
+    "./loader": {
+      "types": "./dist/loader/index.d.mts",
+      "default": "./dist/loader/index.mjs"
+    },
     "./usage": {
       "types": "./dist/usage/index.d.mts",
       "default": "./dist/usage/index.mjs"