@classytic/repo-core 0.3.0 → 0.4.0

package/dist/aggregate/normalize.d.mts

@@ -0,0 +1,24 @@
+import { AggRequest } from "../repository/types.mjs";
+
+//#region src/aggregate/normalize.d.ts
+/**
+ * Normalize `AggRequest['groupBy']` into a readonly string array.
+ * Returns `[]` for scalar aggregation (no groupBy). Downstream
+ * compilers treat `[]` uniformly — Mongo emits `$group: { _id: null }`,
+ * SQL emits a single SELECT without a GROUP BY clause.
+ */
+declare function normalizeGroupBy(groupBy: AggRequest['groupBy']): readonly string[];
+/**
+ * Fail loud on an empty measures bag — there's nothing to compute and
+ * the caller's code path is almost certainly a wiring bug (conditional
+ * collapsed, key renamed, etc.). Silently returning `{ rows: [] }`
+ * would mask it.
+ *
+ * The `kitName` prefix (`'mongokit'`, `'sqlitekit'`, ...) on the error
+ * message keeps stack-trace context legible — when a developer sees
+ * the throw they know which kit's compiler raised it without having
+ * to walk the trace.
+ */
+declare function validateMeasures(measures: AggRequest['measures'], kitName: string): void;
+//#endregion
+export { normalizeGroupBy, validateMeasures };

package/dist/aggregate/normalize.mjs

@@ -0,0 +1,28 @@
+//#region src/aggregate/normalize.ts
+/**
+* Normalize `AggRequest['groupBy']` into a readonly string array.
+* Returns `[]` for scalar aggregation (no groupBy). Downstream
+* compilers treat `[]` uniformly — Mongo emits `$group: { _id: null }`,
+* SQL emits a single SELECT without a GROUP BY clause.
+*/
+function normalizeGroupBy(groupBy) {
+	if (!groupBy) return [];
+	if (typeof groupBy === "string") return [groupBy];
+	return groupBy;
+}
+/**
+* Fail loud on an empty measures bag — there's nothing to compute and
+* the caller's code path is almost certainly a wiring bug (conditional
+* collapsed, key renamed, etc.). Silently returning `{ rows: [] }`
+* would mask it.
+*
+* The `kitName` prefix (`'mongokit'`, `'sqlitekit'`, ...) on the error
+* message keeps stack-trace context legible — when a developer sees
+* the throw they know which kit's compiler raised it without having
+* to walk the trace.
+*/
+function validateMeasures(measures, kitName) {
+	if (!measures || Object.keys(measures).length === 0) throw new Error(`${kitName}/aggregate: AggRequest requires at least one measure — empty measures bag is a wiring bug`);
+}
+//#endregion
+export { normalizeGroupBy, validateMeasures };

package/dist/better-auth/index.d.mts

@@ -0,0 +1,110 @@
+//#region src/better-auth/index.d.ts
+/**
+ * Better Auth — kit-agnostic registry of which collections each plugin owns.
+ *
+ * This module ships **zero DB code**. It's the source of truth that every
+ * kit's `better-auth` overlay subpath consumes (`@classytic/mongokit/better-auth`,
+ * `@classytic/sqlitekit/better-auth`, future `@classytic/prismakit/better-auth`)
+ * so the per-kit overlays don't each maintain their own copy of the
+ * plugin → collection list.
+ *
+ * Why repo-core: kits depend on repo-core; arc/hosts consume kits. Putting the
+ * registry one level below the kit layer keeps it accessible to every kit
+ * without forcing kits to peer-dep each other or to peer-dep arc.
+ *
+ * @example
+ * ```ts
+ * import { resolveBetterAuthCollections } from '@classytic/repo-core/better-auth';
+ *
+ * const names = resolveBetterAuthCollections({
+ *   plugins: ['organization'],
+ *   extraCollections: ['passkey'],
+ * });
+ * // → ['user', 'session', 'account', 'verification', 'organization', 'member', 'invitation', 'passkey']
+ * ```
+ */
+/**
+ * Plugin keys that map to Better Auth collection sets.
+ *
+ * Only plugins that ship inside the **core `better-auth` package** are listed
+ * here. Plugins distributed as separate `@better-auth/*` packages
+ * (api-key, passkey, sso, oauth-provider, etc.) evolve independently and
+ * should be handled via `extraCollections` — see `resolveBetterAuthCollections`.
+ *
+ * Plugins that only add *fields* to existing tables (admin, username,
+ * phoneNumber, magicLink, emailOtp, anonymous, bearer, multiSession, siwe,
+ * lastLoginMethod, genericOAuth, etc.) don't need an entry — kit overlays
+ * register schemas with `strict: false` (Mongoose) or pass-through column
+ * mappings (SQL), so extra fields round-trip automatically.
+ *
+ * - `core` — always included; covers `user`, `session`, `account`, `verification`.
+ * - `organization` — adds `organization`, `member`, `invitation`.
+ * - `organization-teams` — adds `team`, `teamMember` (only when `teams.enabled`).
+ * - `twoFactor` — adds `twoFactor`.
+ * - `jwt` — adds `jwks`.
+ * - `oidcProvider` — adds `oauthApplication`, `oauthAccessToken`, `oauthConsent`.
+ * - `oauthProvider` — alias of `oidcProvider` (same schema).
+ * - `mcp` — MCP plugin reuses the oidcProvider schema (BA docs are explicit).
+ * - `deviceAuthorization` — adds `deviceCode` (RFC 8628 device authorization).
+ */
+type BetterAuthPluginKey = 'core' | 'organization' | 'organization-teams' | 'twoFactor' | 'jwt' | 'oidcProvider' | 'oauthProvider' | 'mcp' | 'deviceAuthorization';
+/**
+ * Canonical collection lists per plugin. `core` is always implied by
+ * `resolveBetterAuthCollections` — callers don't need to pass it.
+ *
+ * Naming follows BA's mongo adapter (`usePlural: false`) convention. Hosts
+ * that opted into `usePlural: true` should pass that flag to the kit overlay,
+ * which appends `s` to each name (`user` → `users`).
+ */
+declare const BA_COLLECTIONS_BY_PLUGIN: Record<BetterAuthPluginKey, readonly string[]>;
+/**
+ * Naive English pluralization that matches Better Auth's `usePlural` behavior:
+ * BA's mongo adapter just appends `s` (it doesn't handle irregular nouns —
+ * none of its collection names are irregular). Kit overlays mirror this.
+ */
+declare function pluralizeBetterAuthCollection(name: string): string;
+interface ResolveBetterAuthCollectionsOptions {
+  /**
+   * Which plugin collection sets to include. `core` is always implied —
+   * you don't need to pass it.
+   *
+   * @default []
+   */
+  plugins?: BetterAuthPluginKey[];
+  /**
+   * Additional collection names beyond the built-in plugin set.
+   *
+   * Use for plugins that ship as separate `@better-auth/*` packages — their
+   * collection names live in their own packages and are intentionally not
+   * hardcoded here so they can evolve independently.
+   *
+   * Known names for official separate-package plugins:
+   * - `@better-auth/passkey` → `'passkey'`
+   * - `@better-auth/sso` → `'ssoProvider'`
+   * - `@better-auth/oauth-provider` → already covered by `plugins: ['oauthProvider']`
+   *
+   * @default []
+   */
+  extraCollections?: string[];
+  /**
+   * When BA's adapter was configured with `usePlural: true`, every name is
+   * pluralized (`user` → `users`). Must match what you passed to BA's adapter.
+   *
+   * @default false
+   */
+  usePlural?: boolean;
+  /**
+   * Per-collection name override. Applies AFTER pluralization. Use when
+   * you've passed `user: { modelName: 'profile' }` (or similar) to
+   * `betterAuth()` — pass the same map here so downstream consumers
+   * (kit overlays, populate resolution) line up.
+   */
+  modelOverrides?: Partial<Record<string, string>>;
+}
+/**
+ * Resolve a plugin set + extras to a deduplicated, ordered list of
+ * collection names. `core` is always included.
+ */
+declare function resolveBetterAuthCollections(options?: ResolveBetterAuthCollectionsOptions): string[];
+//#endregion
+export { BA_COLLECTIONS_BY_PLUGIN, BetterAuthPluginKey, ResolveBetterAuthCollectionsOptions, pluralizeBetterAuthCollection, resolveBetterAuthCollections };

package/dist/better-auth/index.mjs

@@ -0,0 +1,71 @@
+//#region src/better-auth/index.ts
+/**
+* Canonical collection lists per plugin. `core` is always implied by
+* `resolveBetterAuthCollections` — callers don't need to pass it.
+*
+* Naming follows BA's mongo adapter (`usePlural: false`) convention. Hosts
+* that opted into `usePlural: true` should pass that flag to the kit overlay,
+* which appends `s` to each name (`user` → `users`).
+*/
+const BA_COLLECTIONS_BY_PLUGIN = {
+	core: [
+		"user",
+		"session",
+		"account",
+		"verification"
+	],
+	organization: [
+		"organization",
+		"member",
+		"invitation"
+	],
+	"organization-teams": ["team", "teamMember"],
+	twoFactor: ["twoFactor"],
+	jwt: ["jwks"],
+	oidcProvider: [
+		"oauthApplication",
+		"oauthAccessToken",
+		"oauthConsent"
+	],
+	oauthProvider: [
+		"oauthApplication",
+		"oauthAccessToken",
+		"oauthConsent"
+	],
+	mcp: [
+		"oauthApplication",
+		"oauthAccessToken",
+		"oauthConsent"
+	],
+	deviceAuthorization: ["deviceCode"]
+};
+/**
+* Naive English pluralization that matches Better Auth's `usePlural` behavior:
+* BA's mongo adapter just appends `s` (it doesn't handle irregular nouns —
+* none of its collection names are irregular). Kit overlays mirror this.
+*/
+function pluralizeBetterAuthCollection(name) {
+	return name.endsWith("s") ? name : `${name}s`;
+}
+/**
+* Resolve a plugin set + extras to a deduplicated, ordered list of
+* collection names. `core` is always included.
+*/
+function resolveBetterAuthCollections(options = {}) {
+	const { plugins = [], extraCollections = [], usePlural = false, modelOverrides = {} } = options;
+	const pluginSet = new Set(["core", ...plugins]);
+	const collected = [];
+	for (const key of pluginSet) for (const name of BA_COLLECTIONS_BY_PLUGIN[key]) collected.push(name);
+	for (const name of extraCollections) collected.push(name);
+	const seen = /* @__PURE__ */ new Set();
+	const unique = [];
+	for (const canonical of collected) {
+		if (seen.has(canonical)) continue;
+		seen.add(canonical);
+		const finalName = modelOverrides[canonical] ?? (usePlural ? pluralizeBetterAuthCollection(canonical) : canonical);
+		unique.push(finalName);
+	}
+	return unique;
+}
+//#endregion
+export { BA_COLLECTIONS_BY_PLUGIN, pluralizeBetterAuthCollection, resolveBetterAuthCollections };

package/dist/cache/engine.d.mts

@@ -0,0 +1,127 @@
+import { CacheReadResult, ResolvedCacheOptions } from "./options.mjs";
+import { CacheAdapter } from "./types.mjs";
+
+//#region src/cache/engine.d.ts
+interface CacheEngineOptions {
+  /** Cache key namespace prefix. Default: `'rc'`. */
+  prefix?: string;
+  /**
+   * TTL jitter — randomizes the actual stored TTL so cache stampedes
+   * don't synchronize across many entries written together. Pass a
+   * number in `(0, 1]` for symmetric fractional jitter (`0.1` =
+   * uniform ±10%) or a function for custom logic. Default: `0` (off).
+   */
+  jitter?: number | ((ttl: number) => number);
+}
+/**
+ * In-flight claim outcome. `'claimed'` → caller owns the fetch;
+ * `'wait'` → caller awaits an already-in-flight fetch.
+ */
+type SingleFlightClaim<T = unknown> = {
+  readonly status: 'claimed';
+} | {
+  readonly status: 'wait';
+  readonly promise: Promise<T>;
+};
+declare class CacheEngine {
+  private readonly adapter;
+  private readonly prefix;
+  private readonly jitter;
+  /**
+   * In-flight fetches keyed by cache-key. Process-local (lives in this
+   * engine instance) — server restart clears it; cross-pod fanout is
+   * fine because each pod runs its own single-flight, and downstream
+   * load is bounded to N-pods worst case (a huge improvement over
+   * unbounded burst).
+   */
+  private readonly pending;
+  constructor(adapter: CacheAdapter, options?: CacheEngineOptions);
+  /**
+   * Read a cache entry under SWR + TTL semantics. Returns a
+   * structured `CacheReadResult` describing freshness state — the
+   * caller decides whether to serve, revalidate, or fetch fresh.
+   *
+   * **State table:**
+   *   - `enabled: false`  → `{ status: 'disabled' }` — caller fetches
+   *   - `bypass: true`    → `{ status: 'bypass' }`   — caller fetches
+   *   - missing / expired → `{ status: 'miss' }`     — caller fetches
+   *   - fresh             → `{ status: 'fresh', data }`
+   *   - stale + swr=true  → `{ status: 'stale', data }` — caller serves + bg-refreshes
+   *   - stale + swr=false → `{ status: 'miss' }`        — caller fetches
+   */
+  get<TData>(key: string, opts: ResolvedCacheOptions): Promise<CacheReadResult<TData>>;
+  /**
+   * Write `value` under `key` with the resolved options. Skips silently
+   * when `enabled: false` (no cache pollution from disabled calls).
+   *
+   * Side effect: appends `key` to the tag side-index for every tag in
+   * `opts.tags` so future `invalidateByTags` calls find it.
+   */
+  set<TData>(key: string, value: TData, opts: ResolvedCacheOptions): Promise<void>;
+  /**
+   * Look up an in-flight fetch for `key`. Returns the promise the
+   * first miss-claimer registered, or `undefined` when no fetch is
+   * pending.
+   */
+  getPending<T = unknown>(key: string): Promise<T> | undefined;
+  /**
+   * Atomically claim `key` for a fetch. Returns `'claimed'` when this
+   * caller owns the fetch (it must call `resolvePending` or
+   * `rejectPending` when done) or `{ status: 'wait', promise }` when
+   * another caller already claimed — the returned promise resolves
+   * with the first claimer's result.
+   */
+  claimPending<T = unknown>(key: string): SingleFlightClaim<T>;
+  /** Resolve an in-flight claim with the fresh result + clear it. */
+  resolvePending<T>(key: string, value: T): void;
+  /**
+   * Reject an in-flight claim — waiters fail-fast (they DON'T retry
+   * inline; they get the same error as the claimer). Caller's choice
+   * whether to retry on a higher level.
+   */
+  rejectPending(key: string, error: unknown): void;
+  /** Internal — number of in-flight fetches; observability hook. */
+  get pendingCount(): number;
+  /**
+   * Invalidate every entry tagged with ANY of the provided tags. Reads
+   * each tag's index, deletes the listed cache entries, and clears
+   * the index. Returns the count of entries removed.
+   */
+  invalidateByTags(tags: readonly string[]): Promise<number>;
+  /**
+   * Read a model's current version (optionally per-scope). Used by
+   * the plugin to embed `v<version>` into every cache key so a single
+   * version bump orphans the model's cache space.
+   */
+  getVersion(model: string, scopeKey?: string): Promise<number>;
+  /**
+   * Bump the model's version (per-scope when `scopeKey` is supplied)
+   * to invalidate every cached read for it. Per-scope bumps don't
+   * affect other tenants' caches — TanStack-style targeted
+   * invalidation.
+   */
+  bumpVersion(model: string, scopeKey?: string): Promise<number>;
+  /** Wipe the entire cache namespace (when the adapter supports `clear`). */
+  clear(): Promise<void>;
+  /** Expose the prefix so plugins building keys downstream stay aligned. */
+  get keyPrefix(): string;
+  /**
+   * Warm the cache for `key` if it's not already populated. On hit
+   * (fresh OR stale) returns the cached value; on miss runs `fetcher`,
+   * stores the result, and returns it. Single-flight guarantees apply
+   * — concurrent `prefetch` calls for the same key share one fetcher
+   * invocation.
+   *
+   * **Use case:** preload dashboards before the user request lands
+   * (route-level `prefetch` after auth, scheduled-job warmup, server-
+   * push hints from a CDN edge).
+   *
+   * **Difference from `engine.get` + manual write:** this one method
+   * handles the miss-fetch-store sequence atomically, with single-
+   * flight dedup. Mirrors TanStack Query's
+   * `queryClient.prefetchQuery({ queryKey, queryFn })`.
+   */
+  prefetch<TData>(key: string, opts: ResolvedCacheOptions, fetcher: () => Promise<TData>): Promise<TData>;
+}
+//#endregion
+export { CacheEngine, CacheEngineOptions, SingleFlightClaim };

package/dist/cache/engine.mjs

@@ -0,0 +1,235 @@
+import { buildEnvelope, inspectEnvelope } from "./envelope.mjs";
+import { appendKeyToTags, invalidateByTags } from "./tag-index.mjs";
+import { bumpModelVersion, getModelVersion } from "./version-store.mjs";
+//#region src/cache/engine.ts
+/**
+* `CacheEngine` — the SWR + TTL + tag-invalidation behavior on top of
+* a `CacheAdapter`. ONE implementation of the cache-flow primitives,
+* shared across every kit + arc + Express/Nest hosts.
+*
+* Replaces three independent implementations:
+*   - mongokit's `withAggCache` (TTL/SWR/tag flow for aggregate)
+*   - mongokit's CRUD `cachePlugin` (TTL + version-bump for getById/getAll)
+*   - arc's `QueryCache` (TTL + SWR + version-bump + tag-version)
+*
+* **Production hardening (TanStack-inspired):**
+*   - **Single-flight on miss** — concurrent misses for the same key
+*     wait on the first fetch's promise (no cache stampede).
+*   - **Per-scope version-bump** — writes only invalidate the writing
+*     scope's cache, not other tenants' (targeted invalidation).
+*   - **Strictly-monotonic version** — same-millisecond writes never
+*     collide.
+*
+* Hosts compose this via `cachePlugin` (declarative, hook-driven) or
+* call it directly when they need fine-grained control.
+*/
+var CacheEngine = class {
+	adapter;
+	prefix;
+	jitter;
+	/**
+	* In-flight fetches keyed by cache-key. Process-local (lives in this
+	* engine instance) — server restart clears it; cross-pod fanout is
+	* fine because each pod runs its own single-flight, and downstream
+	* load is bounded to N-pods worst case (a huge improvement over
+	* unbounded burst).
+	*/
+	pending = /* @__PURE__ */ new Map();
+	constructor(adapter, options = {}) {
+		this.adapter = adapter;
+		this.prefix = options.prefix ?? "rc";
+		this.jitter = resolveJitter(options.jitter);
+	}
+	/**
+	* Read a cache entry under SWR + TTL semantics. Returns a
+	* structured `CacheReadResult` describing freshness state — the
+	* caller decides whether to serve, revalidate, or fetch fresh.
+	*
+	* **State table:**
+	*   - `enabled: false`  → `{ status: 'disabled' }` — caller fetches
+	*   - `bypass: true`    → `{ status: 'bypass' }`   — caller fetches
+	*   - missing / expired → `{ status: 'miss' }`     — caller fetches
+	*   - fresh             → `{ status: 'fresh', data }`
+	*   - stale + swr=true  → `{ status: 'stale', data }` — caller serves + bg-refreshes
+	*   - stale + swr=false → `{ status: 'miss' }`        — caller fetches
+	*/
+	async get(key, opts) {
+		if (!opts.enabled) return {
+			status: "disabled",
+			data: void 0
+		};
+		if (opts.bypass) return {
+			status: "bypass",
+			data: void 0
+		};
+		const inspection = inspectEnvelope(await this.adapter.get(key));
+		if (inspection.state === "missing" || inspection.state === "expired") return {
+			status: "miss",
+			data: void 0
+		};
+		const env = inspection.envelope;
+		if (!env) return {
+			status: "miss",
+			data: void 0
+		};
+		const ageSeconds = Math.floor((Date.now() - env.createdAt) / 1e3);
+		if (inspection.state === "fresh") return {
+			status: "fresh",
+			data: env.data,
+			age: ageSeconds
+		};
+		if (opts.swr) return {
+			status: "stale",
+			data: env.data,
+			age: ageSeconds
+		};
+		return {
+			status: "miss",
+			data: void 0
+		};
+	}
+	/**
+	* Write `value` under `key` with the resolved options. Skips silently
+	* when `enabled: false` (no cache pollution from disabled calls).
+	*
+	* Side effect: appends `key` to the tag side-index for every tag in
+	* `opts.tags` so future `invalidateByTags` calls find it.
+	*/
+	async set(key, value, opts) {
+		if (!opts.enabled) 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);
+	}
+	/**
+	* Look up an in-flight fetch for `key`. Returns the promise the
+	* first miss-claimer registered, or `undefined` when no fetch is
+	* pending.
+	*/
+	getPending(key) {
+		return this.pending.get(key)?.promise;
+	}
+	/**
+	* Atomically claim `key` for a fetch. Returns `'claimed'` when this
+	* caller owns the fetch (it must call `resolvePending` or
+	* `rejectPending` when done) or `{ status: 'wait', promise }` when
+	* another caller already claimed — the returned promise resolves
+	* with the first claimer's result.
+	*/
+	claimPending(key) {
+		const existing = this.pending.get(key);
+		if (existing) return {
+			status: "wait",
+			promise: existing.promise
+		};
+		this.pending.set(key, Promise.withResolvers());
+		return { status: "claimed" };
+	}
+	/** Resolve an in-flight claim with the fresh result + clear it. */
+	resolvePending(key, value) {
+		const deferred = this.pending.get(key);
+		if (!deferred) return;
+		this.pending.delete(key);
+		deferred.resolve(value);
+	}
+	/**
+	* Reject an in-flight claim — waiters fail-fast (they DON'T retry
+	* inline; they get the same error as the claimer). Caller's choice
+	* whether to retry on a higher level.
+	*/
+	rejectPending(key, error) {
+		const deferred = this.pending.get(key);
+		if (!deferred) return;
+		this.pending.delete(key);
+		deferred.reject(error);
+	}
+	/** Internal — number of in-flight fetches; observability hook. */
+	get pendingCount() {
+		return this.pending.size;
+	}
+	/**
+	* Invalidate every entry tagged with ANY of the provided tags. Reads
+	* each tag's index, deletes the listed cache entries, and clears
+	* the index. Returns the count of entries removed.
+	*/
+	async invalidateByTags(tags) {
+		return invalidateByTags(this.adapter, this.prefix, tags);
+	}
+	/**
+	* Read a model's current version (optionally per-scope). Used by
+	* the plugin to embed `v<version>` into every cache key so a single
+	* version bump orphans the model's cache space.
+	*/
+	async getVersion(model, scopeKey) {
+		return getModelVersion(this.adapter, this.prefix, model, scopeKey);
+	}
+	/**
+	* Bump the model's version (per-scope when `scopeKey` is supplied)
+	* to invalidate every cached read for it. Per-scope bumps don't
+	* affect other tenants' caches — TanStack-style targeted
+	* invalidation.
+	*/
+	async bumpVersion(model, scopeKey) {
+		return bumpModelVersion(this.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}:*`);
+	}
+	/** Expose the prefix so plugins building keys downstream stay aligned. */
+	get keyPrefix() {
+		return this.prefix;
+	}
+	/**
+	* Warm the cache for `key` if it's not already populated. On hit
+	* (fresh OR stale) returns the cached value; on miss runs `fetcher`,
+	* stores the result, and returns it. Single-flight guarantees apply
+	* — concurrent `prefetch` calls for the same key share one fetcher
+	* invocation.
+	*
+	* **Use case:** preload dashboards before the user request lands
+	* (route-level `prefetch` after auth, scheduled-job warmup, server-
+	* push hints from a CDN edge).
+	*
+	* **Difference from `engine.get` + manual write:** this one method
+	* handles the miss-fetch-store sequence atomically, with single-
+	* flight dedup. Mirrors TanStack Query's
+	* `queryClient.prefetchQuery({ queryKey, queryFn })`.
+	*/
+	async prefetch(key, opts, fetcher) {
+		const result = await this.get(key, opts);
+		if (result.status === "fresh" || result.status === "stale") return result.data;
+		if (result.status === "miss") {
+			const claim = this.claimPending(key);
+			if (claim.status === "wait") return await claim.promise;
+			try {
+				const value = await fetcher();
+				await this.set(key, value, opts);
+				this.resolvePending(key, value);
+				return value;
+			} catch (err) {
+				this.rejectPending(key, err);
+				throw err;
+			}
+		}
+		const value = await fetcher();
+		if (opts.enabled) await this.set(key, value, opts);
+		return value;
+	}
+};
+function resolveJitter(jitter) {
+	if (!jitter) return (ttl) => ttl;
+	if (typeof jitter === "function") return (ttl) => Math.max(1, Math.round(jitter(ttl)));
+	const fraction = Math.min(1, Math.max(0, jitter));
+	if (fraction === 0) return (ttl) => ttl;
+	return (ttl) => {
+		const delta = ttl * fraction;
+		const jittered = ttl - delta + Math.random() * 2 * delta;
+		return Math.max(1, Math.round(jittered));
+	};
+}
+//#endregion
+export { CacheEngine };

package/dist/cache/envelope.mjs

@@ -0,0 +1,32 @@
+//#region src/cache/envelope.ts
+/** Build an envelope from raw data + freshness windows (seconds). */
+function buildEnvelope(data, staleTimeSeconds, gcTimeSeconds, tags, now = Date.now()) {
+	const staleAfter = now + Math.max(0, staleTimeSeconds) * 1e3;
+	return {
+		version: 1,
+		data,
+		createdAt: now,
+		staleAfter,
+		expiresAt: staleAfter + Math.max(0, gcTimeSeconds) * 1e3,
+		tags
+	};
+}
+/**
+* Inspect an envelope against the current wall-clock time. Returns
+* structured freshness state — caller chooses how to act on `'stale'`
+* (serve + revalidate vs treat as miss) based on its SWR config.
+*/
+function inspectEnvelope(envelope, now = Date.now()) {
+	if (!envelope || envelope.version !== 1) return { state: "missing" };
+	if (now >= envelope.expiresAt) return { state: "expired" };
+	if (now < envelope.staleAfter) return {
+		state: "fresh",
+		envelope
+	};
+	return {
+		state: "stale",
+		envelope
+	};
+}
+//#endregion
+export { buildEnvelope, inspectEnvelope };

package/dist/cache/index.d.mts

@@ -1,4 +1,9 @@
+import { CacheOptions, CacheReadResult } from "./options.mjs";
 import { CacheAdapter } from "./types.mjs";
+import { CacheEngine, CacheEngineOptions, SingleFlightClaim } from "./engine.mjs";
 import { createMemoryCacheAdapter } from "./memory-adapter.mjs";
-import { stableStringify } from "./stable-stringify.mjs";
-export { type CacheAdapter, createMemoryCacheAdapter, stableStringify };
+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 RepositoryCacheHandle, type RepositoryCachePluginOptions, type SingleFlightClaim, type TimeoutAdapterOptions, cachePlugin, createMemoryCacheAdapter, scheduleBackground, withTimeout };

package/dist/cache/index.mjs

@@ -1,3 +1,7 @@
+import { CacheEngine } from "./engine.mjs";
 import { createMemoryCacheAdapter } from "./memory-adapter.mjs";
-import { stableStringify } from "./stable-stringify.mjs";
-export { createMemoryCacheAdapter, stableStringify };
+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 };