@classytic/repo-core 0.26.1 → 0.27.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `@classytic/repo-core` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.27.0] - 2026-09-09
+
+### Added
+
+- **`createTtlMemo(load, { ttlMs, keyOf?, maxEntries? })`** on `./cache` — the
+  one way to memoise a keyed async load for a while. It is `CacheEngine.prefetch`
+  over the memory adapter, so concurrent misses for one key share ONE load, a
+  thrown load caches nothing, and a `null` result is an answer.
+
+  Four packages had each hand-rolled `Map<key, { at, value }>` with a TTL, and
+  every one wrote its entry AFTER the await. Under parallel event dispatch N
+  callers reach the await together, all miss, and the cache only ever helps the
+  caller after them — a 30 s TTL that measured nine reads of one row per event.
+  `tests/unit/cache/ttl-memo.test.ts` pins single flight, expiry, invalidation,
+  `ttlMs: 0` = off, and refuses an object key without `keyOf` (an
+  identity-compared key never hits and reads as a caching bug).
+
 ## [0.26.1] - 2026-09-08
 
 ### Fixed

package/dist/cache/index.d.mts

@@ -1,9 +1,10 @@
 import { CacheOptions, CacheReadResult } from "./options.mjs";
 import { CacheAdapter } from "./types.mjs";
 import { CacheAdapterResolver, CacheAdapterSource, CacheEngine, CacheEngineOptions, SingleFlightClaim } from "./engine.mjs";
+import { TtlMemo, TtlMemoOptions, createTtlMemo } from "./memo.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, 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 };
+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, type TtlMemo, type TtlMemoOptions, cachePlugin, createMemoryCacheAdapter, createTtlMemo, scheduleBackground, withTimeout };

package/dist/cache/index.mjs

@@ -1,7 +1,8 @@
 import { CacheEngine } from "./engine.mjs";
 import { createMemoryCacheAdapter } from "./memory-adapter.mjs";
+import { createTtlMemo } from "./memo.mjs";
 import { DEFAULT_SHAPE_KEYS_BY_OP } from "./plugin/context.mjs";
 import { scheduleBackground } from "./runtime.mjs";
 import { DEFAULT_CACHEABLE_OPS, DEFAULT_INVALIDATING_OPS, cachePlugin } from "./plugin/index.mjs";
 import { CacheTimeoutError, withTimeout } from "./timeout-adapter.mjs";
-export { CacheEngine, CacheTimeoutError, DEFAULT_CACHEABLE_OPS, DEFAULT_INVALIDATING_OPS, DEFAULT_SHAPE_KEYS_BY_OP, cachePlugin, createMemoryCacheAdapter, scheduleBackground, withTimeout };
+export { CacheEngine, CacheTimeoutError, DEFAULT_CACHEABLE_OPS, DEFAULT_INVALIDATING_OPS, DEFAULT_SHAPE_KEYS_BY_OP, cachePlugin, createMemoryCacheAdapter, createTtlMemo, scheduleBackground, withTimeout };

package/dist/cache/memo.d.mts

@@ -0,0 +1,30 @@
+//#region src/cache/memo.d.ts
+/**
+ * `createTtlMemo` — memoise a keyed async load for `ttlMs`, single-flight.
+ *
+ * Use this instead of a `Map<key, { at, value }>`. Every hand-rolled one wrote
+ * its entry AFTER the await, so N concurrent callers all missed and the cache
+ * only ever helped the caller after them. This is `CacheEngine.prefetch` over
+ * the memory adapter: concurrent misses share one load, a thrown load caches
+ * nothing, and a `null` result is an answer.
+ */
+interface TtlMemoOptions<K> {
+  /** Freshness window. `0` disables memoisation — every call loads. */
+  readonly ttlMs: number;
+  /**
+   * Key derivation. REQUIRED for non-primitive keys: an object key would be
+   * identity-compared, never hit, and read as a caching bug. Fold anything that
+   * changes the answer into it (a revision counter, a tenant).
+   */
+  readonly keyOf?: (key: K) => string;
+  /** LRU ceiling. Default 10,000. */
+  readonly maxEntries?: number;
+}
+interface TtlMemo<K, V> {
+  get(key: K): Promise<V>;
+  /** Drop one key, or everything. */
+  invalidate(key?: K): Promise<void>;
+}
+declare function createTtlMemo<K, V>(load: (key: K) => Promise<V>, options: TtlMemoOptions<K>): TtlMemo<K, V>;
+//#endregion
+export { TtlMemo, TtlMemoOptions, createTtlMemo };

package/dist/cache/memo.mjs

@@ -0,0 +1,47 @@
+import { CacheEngine } from "./engine.mjs";
+import { createMemoryCacheAdapter } from "./memory-adapter.mjs";
+//#region src/cache/memo.ts
+/**
+* `createTtlMemo` — memoise a keyed async load for `ttlMs`, single-flight.
+*
+* Use this instead of a `Map<key, { at, value }>`. Every hand-rolled one wrote
+* its entry AFTER the await, so N concurrent callers all missed and the cache
+* only ever helped the caller after them. This is `CacheEngine.prefetch` over
+* the memory adapter: concurrent misses share one load, a thrown load caches
+* nothing, and a `null` result is an answer.
+*/
+const PREFIX = "memo";
+function createTtlMemo(load, options) {
+	const { ttlMs, keyOf, maxEntries } = options;
+	const adapter = createMemoryCacheAdapter({ maxEntries: maxEntries ?? 1e4 });
+	const engine = new CacheEngine(adapter, { prefix: PREFIX });
+	const resolved = {
+		staleTime: Math.max(0, ttlMs) / 1e3,
+		gcTime: 0,
+		tags: [],
+		bypass: false,
+		swr: false,
+		enabled: ttlMs > 0
+	};
+	const toKey = (key) => {
+		if (keyOf) return `${PREFIX}:${keyOf(key)}`;
+		const t = typeof key;
+		if (t === "string" || t === "number" || t === "boolean") return `${PREFIX}:${String(key)}`;
+		throw new TypeError(`createTtlMemo: a ${key === null ? "null" : t} key needs keyOf(...) — an identity-compared key never hits`);
+	};
+	return {
+		get(key) {
+			const k = toKey(key);
+			return engine.prefetch(k, resolved, () => load(key));
+		},
+		async invalidate(key) {
+			if (key === void 0) {
+				await engine.clear();
+				return;
+			}
+			await adapter.delete(toKey(key));
+		}
+	};
+}
+//#endregion
+export { createTtlMemo };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.26.1",
+  "version": "0.27.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,