@classytic/repo-core 0.2.0 → 0.4.0

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 };

package/dist/cache/keys.mjs

@@ -0,0 +1,131 @@
+import { stableStringify } from "./stable-stringify.mjs";
+//#region src/cache/keys.ts
+/**
+* Cache key derivation. Builds stable keys from operation context so
+* any kit + arc + Express/Nest hosts compute the same key for the
+* same logical request — letting one Redis serve a mixed-kit fleet.
+*
+* **Key shape:**
+*   `<prefix>:<op>:<model>:v<version>:<paramsHash>:<scopeHash>`
+*
+*   - `prefix`     — tenant of the cache namespace (`'rc'` default)
+*   - `op`         — repository operation name (`getById`, `aggregate`, ...)
+*   - `model`      — the entity model name
+*   - `version`    — collection version (bumped on writes; orphans all
+*                    keys for the model in O(1)). Per-scope when the
+*                    plugin extracts a scopeKey.
+*   - `paramsHash` — fnv1a64 of stable-stringified call params
+*                    (filter, id, sort, kit-specific options like
+*                    `lean`). The plugin's per-op allowlist decides
+*                    which fields participate.
+*   - `scopeHash`  — short hash of the auto-extracted scope tags
+*                    (`org:<id>` / `user:<id>`). Keeps the key short
+*                    while preserving cross-tenant isolation.
+*/
+/** Build the canonical cache key. */
+function buildCacheKey(input) {
+	const paramsHash = fnv1a64(stableStringify(input.params));
+	const scopeHash = input.scopeTags.length > 0 ? fnv1a64(input.scopeTags.join("|")) : "0";
+	return `${input.prefix}:${input.operation}:${input.model}:v${input.version}:${paramsHash}:${scopeHash}`;
+}
+/** Tag-index key — maps a tag to the set of cache keys carrying it. */
+function tagIndexKey(prefix, tag) {
+	return `${prefix}:tag:${tag}`;
+}
+/**
+* Collection-version key — bumped on writes to orphan all reads.
+*
+* Per-scope sharding when `scopeKey` is supplied — e.g. `'org:abc'`
+* keys to `<prefix>:ver:<model>:org:abc`, so writes inside `org:abc`
+* don't invalidate other tenants' cached reads. Without a scopeKey
+* the version is global (legacy semantic — invalidates all reads on
+* any write).
+*/
+function versionKey(prefix, model, scopeKey) {
+	return scopeKey ? `${prefix}:ver:${model}:${scopeKey}` : `${prefix}:ver:${model}`;
+}
+/**
+* Build a deterministic scope-key string from extracted scope tags.
+* Used to suffix `versionKey` so per-scope invalidation works.
+*
+* Returns `undefined` when no scope is present — caller falls back to
+* global version semantics.
+*/
+function scopeKeyFromTags(scopeTags) {
+	if (scopeTags.length === 0) return void 0;
+	return [...scopeTags].sort().join("|");
+}
+/**
+* Merge two tag lists, preserving first-seen order and deduping. Used
+* by the plugin to combine caller-supplied tags with auto-derived
+* scope tags into a single index-able set.
+*/
+function mergeTags(a, b) {
+	if (a.length === 0) return b;
+	if (b.length === 0) return a;
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const t of a) if (!seen.has(t)) {
+		seen.add(t);
+		out.push(t);
+	}
+	for (const t of b) if (!seen.has(t)) {
+		seen.add(t);
+		out.push(t);
+	}
+	return out;
+}
+/**
+* Extract scope tags from a hook context. Reads the canonical fields
+* multi-tenant + auth plugins inject (`organizationId`, `userId`).
+* Returns an empty array when no scope is present — public reads share
+* one cache slot.
+*
+* Looks at THREE locations in priority order:
+*   1. `context.filter.<field>`    — multi-tenant injects here
+*   2. `context.options.<field>`   — kit options bag (arc audit attribution)
+*   3. `context.<field>`           — top-level fallback
+*/
+function extractScopeTags(context) {
+	if (!context) return [];
+	const tags = [];
+	const orgId = pickScopeField(context, "organizationId");
+	if (orgId) tags.push(`org:${orgId}`);
+	const userId = pickScopeField(context, "userId");
+	if (userId) tags.push(`user:${userId}`);
+	return tags;
+}
+function pickScopeField(context, field) {
+	const filter = context["filter"];
+	if (filter && typeof filter[field] === "string") return filter[field];
+	const options = context["options"];
+	if (options && typeof options[field] === "string") return options[field];
+	if (typeof context[field] === "string") return context[field];
+}
+/**
+* FNV-1a 64-bit — non-cryptographic hash for cache-key shortening.
+* Emits stable base-36 strings (≤13 chars) for compact keys.
+*
+* **Why 64-bit, not 32-bit:** djb2 32-bit (~4B value space) hits ~50%
+* birthday-paradox collision probability around √(2^32) ≈ 65k distinct
+* keys — easily exceeded by a multi-tenant fleet. FNV-1a 64-bit pushes
+* that threshold to ~4B keys, which no realistic cache approaches.
+* Both are non-cryptographic; FNV-1a has better avalanche on short
+* ASCII strings (cache keys).
+*
+* BigInt is required — JS numbers lose precision past 2^53. The cost
+* is negligible at cache-key sizes (key strings are typically <1KB).
+*/
+const FNV_OFFSET_64 = 14695981039346656037n;
+const FNV_PRIME_64 = 1099511628211n;
+const FNV_MASK_64 = 18446744073709551615n;
+function fnv1a64(str) {
+	let hash = FNV_OFFSET_64;
+	for (let i = 0; i < str.length; i++) {
+		hash ^= BigInt(str.charCodeAt(i));
+		hash = hash * FNV_PRIME_64 & FNV_MASK_64;
+	}
+	return hash.toString(36);
+}
+//#endregion
+export { buildCacheKey, extractScopeTags, mergeTags, scopeKeyFromTags, tagIndexKey, versionKey };

package/dist/cache/memory-adapter.mjs

@@ -3,15 +3,20 @@
 function createMemoryCacheAdapter() {
 	const store = /* @__PURE__ */ new Map();
 	const now = () => Date.now();
+	function readUnexpired(key) {
+		const entry = store.get(key);
+		if (!entry) return void 0;
+		if (entry.expiresAt !== 0 && entry.expiresAt < now()) {
+			store.delete(key);
+			return;
+		}
+		return entry;
+	}
 	return {
 		get(key) {
-			const entry = store.get(key);
-			if (!entry) return void 0;
-			if (entry.expiresAt !== 0 && entry.expiresAt < now()) {
-				store.delete(key);
-				return;
-			}
-			return entry.value;
+			const value = readUnexpired(key)?.value;
+			if (value instanceof Set) return Array.from(value);
+			return value;
 		},
 		set(key, value, ttlSeconds = 60) {
 			const expiresAt = ttlSeconds === 0 ? 0 : now() + ttlSeconds * 1e3;
@@ -30,6 +35,35 @@ function createMemoryCacheAdapter() {
 			}
 			const prefix = pattern.endsWith("*") ? pattern.slice(0, -1) : pattern;
 			for (const key of store.keys()) if (key.startsWith(prefix)) store.delete(key);
+		},
+		addToSet(key, members, ttlSeconds = 60) {
+			const existing = readUnexpired(key);
+			let set;
+			if (existing && existing.value instanceof Set) set = existing.value;
+			else {
+				set = /* @__PURE__ */ new Set();
+				const expiresAt = existing?.expiresAt ?? (ttlSeconds === 0 ? 0 : now() + ttlSeconds * 1e3);
+				store.set(key, {
+					value: set,
+					expiresAt
+				});
+			}
+			let added = 0;
+			for (const m of members) if (!set.has(m)) {
+				set.add(m);
+				added++;
+			}
+			return added;
+		},
+		increment(key, by = 1, ttlSeconds = 60) {
+			const existing = readUnexpired(key);
+			const next = (existing && typeof existing.value === "number" && Number.isFinite(existing.value) ? existing.value : 0) + by;
+			const expiresAt = existing ? existing.expiresAt : ttlSeconds === 0 ? 0 : now() + ttlSeconds * 1e3;
+			store.set(key, {
+				value: next,
+				expiresAt
+			});
+			return next;
 		}
 	};
 }