@voltro/cache 0.84.0 → 0.86.0

package/THIRD-PARTY-NOTICES.md

@@ -1,6 +1,6 @@
 # Third-Party Notices — @voltro/cache
 
-This package depends on the open-source software listed below. Each is the
+This package uses the open-source software listed below. Each is the
 property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/cache itself, which is proprietary (see LICENSE).

package/dist/Cache.js

@@ -0,0 +1,89 @@
+import { CacheStore as e } from "./CacheStore.js";
+import { Clock as t, Context as n, Deferred as r, Effect as i, HashMap as a, Layer as o, Metric as s, Option as c, SynchronizedRef as l } from "effect";
+//#region src/Cache.ts
+var u = (e) => typeof e == "object" && !!e && e._voltroSwr === 1, d = class d extends n.Service()("@voltro/Cache", { make: i.gen(function* () {
+	let n = yield* e, o = yield* l.make(a.empty()), d = s.counter("voltro_cache_hits"), f = s.counter("voltro_cache_misses"), p = (e, r, a) => {
+		let o = a.tags === void 0 ? {} : { tags: a.tags }, s = a.swrMs;
+		if (s !== void 0) {
+			let c = a.ttlMs ?? 0;
+			return t.currentTimeMillis.pipe(i.flatMap((t) => n.setWithTags(e, {
+				_voltroSwr: 1,
+				v: r,
+				freshUntil: t + c
+			}, {
+				ttlMs: c + s,
+				...o
+			})));
+		}
+		let c = a.ttlMs === void 0 ? {} : { ttlMs: a.ttlMs };
+		return n.setWithTags(e, r, {
+			...c,
+			...o
+		});
+	}, m = (e, t, n) => n.pipe(i.tap((n) => p(e, n, t))), h = (e, t) => l.modifyEffect(o, (t) => {
+		let n = a.get(t, e);
+		return c.isSome(n) ? i.succeed([{
+			kind: "await",
+			deferred: n.value
+		}, t]) : r.make().pipe(i.map((n) => [{
+			kind: "own",
+			deferred: n
+		}, a.set(t, e, n)]));
+	}).pipe(i.flatMap((n) => {
+		if (n.kind === "await") return r.await(n.deferred);
+		let s = n.deferred;
+		return t.pipe(i.onExit((t) => r.done(s, t).pipe(i.andThen(l.update(o, (t) => a.remove(t, e))))));
+	})), g = (e, r, a) => n.get(e).pipe(i.flatMap((n) => {
+		if (c.isSome(n)) {
+			let o = n.value;
+			return u(o) ? s.update(d, 1).pipe(i.andThen(t.currentTimeMillis), i.flatMap((t) => {
+				if (t < o.freshUntil) return i.succeed(o.v);
+				let n = h(e, m(e, r, a)).pipe(i.catchCause(() => i.void));
+				return i.forkDetach(n).pipe(i.as(o.v));
+			})) : s.update(d, 1).pipe(i.as(o));
+		}
+		return s.update(f, 1).pipe(i.andThen(h(e, m(e, r, a))));
+	}));
+	return {
+		get: (e) => n.get(e),
+		set: (e, t, r) => n.set(e, t, r),
+		setWithTags: (e, t, r) => n.setWithTags(e, t, r),
+		put: (e, t, n) => p(e, n, t),
+		remove: n.remove,
+		has: n.has,
+		clear: n.clear,
+		invalidateTag: n.invalidateTag,
+		wrap: g,
+		partition: (e, t = {}) => {
+			let r = (t) => `${e}:${t}`, i = (e) => ({
+				...t.ttlMs === void 0 ? {} : { ttlMs: t.ttlMs },
+				...t.swrMs === void 0 ? {} : { swrMs: t.swrMs },
+				...t.tags === void 0 ? {} : { tags: t.tags },
+				...e
+			});
+			return {
+				get: (e) => n.get(r(e)),
+				set: (e, i, a) => n.set(r(e), i, a ?? (t.ttlMs === void 0 ? void 0 : { ttlMs: t.ttlMs })),
+				has: (e) => n.has(r(e)),
+				remove: (e) => n.remove(r(e)),
+				wrap: (e, t, n) => g(r(e), i(t), n),
+				invalidateTag: (e) => n.invalidateTag(e)
+			};
+		},
+		stats: () => i.all({
+			hits: s.value(d),
+			misses: s.value(f)
+		}).pipe(i.map(({ hits: e, misses: t }) => {
+			let n = Number(e.count), r = Number(t.count), i = n + r;
+			return {
+				hits: n,
+				misses: r,
+				hitRate: i === 0 ? 0 : n / i
+			};
+		}))
+	};
+}) }) {
+	static layer = o.effect(d, d.make);
+};
+//#endregion
+export { d as Cache };

package/dist/CacheStore.js

@@ -0,0 +1,5 @@
+import { Context as e } from "effect";
+//#region src/CacheStore.ts
+var t = class extends e.Service()("@voltro/CacheStore") {};
+//#endregion
+export { t as CacheStore };

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,11 @@
+//#region \0rolldown/runtime.js
+var e = Object.defineProperty, t = (t, n) => {
+	let r = {};
+	for (var i in t) e(r, i, {
+		get: t[i],
+		enumerable: !0
+	});
+	return n || e(r, Symbol.toStringTag, { value: "Module" }), r;
+};
+//#endregion
+export { t as __exportAll };

package/dist/backendMemory.js

@@ -0,0 +1,114 @@
+import { CacheStore as e } from "./CacheStore.js";
+import { Clock as t, Effect as n, HashMap as r, HashSet as i, Layer as a, Option as o, Ref as s } from "effect";
+//#region src/backendMemory.ts
+var c = {
+	entries: r.empty(),
+	tagIndex: r.empty(),
+	seq: 0,
+	oldest: void 0,
+	newest: void 0
+}, l = (e, t, n) => {
+	let a = e;
+	for (let e of n) {
+		let n = r.get(a, e);
+		if (o.isNone(n)) continue;
+		let s = i.remove(n.value, t);
+		a = i.size(s) === 0 ? r.remove(a, e) : r.set(a, e, s);
+	}
+	return a;
+}, u = (e, t) => {
+	let n = r.get(e.entries, t);
+	if (o.isNone(n)) return e;
+	let { older: i, newer: a } = n.value, s = r.remove(e.entries, t);
+	if (i !== void 0) {
+		let e = r.get(s, i);
+		o.isSome(e) && (s = r.set(s, i, {
+			...e.value,
+			newer: a
+		}));
+	}
+	if (a !== void 0) {
+		let e = r.get(s, a);
+		o.isSome(e) && (s = r.set(s, a, {
+			...e.value,
+			older: i
+		}));
+	}
+	return {
+		entries: s,
+		tagIndex: l(e.tagIndex, t, n.value.tags),
+		seq: e.seq,
+		oldest: i === void 0 ? a : e.oldest,
+		newest: a === void 0 ? i : e.newest
+	};
+}, d = (e, t, n) => {
+	let a = r.get(e, t), s = o.isSome(a) ? i.add(a.value, n) : i.make(n);
+	return r.set(e, t, s);
+}, f = (e, t) => {
+	let n = r.size(e.entries) - t;
+	if (n <= 0) return e;
+	let i = e;
+	for (let e = 0; e < n; e++) {
+		let e = i.oldest;
+		if (e === void 0) break;
+		i = u(i, e);
+	}
+	return i;
+}, p = (e, t, n, i, a, s) => {
+	let c = u(e, t), l = c.seq + 1, p = c.tagIndex;
+	for (let e of a) p = d(p, e, t);
+	let m = r.set(c.entries, t, {
+		value: n,
+		expiresAt: i,
+		tags: a,
+		seq: l,
+		older: c.newest,
+		newer: void 0
+	});
+	if (c.newest !== void 0) {
+		let e = r.get(m, c.newest);
+		o.isSome(e) && (m = r.set(m, c.newest, {
+			...e.value,
+			newer: t
+		}));
+	}
+	let h = {
+		entries: m,
+		tagIndex: p,
+		seq: l,
+		oldest: c.oldest ?? t,
+		newest: t
+	};
+	return s === void 0 ? h : f(h, s);
+}, m = (e, t) => t === void 0 ? Infinity : e + t, h = (e) => n.gen(function* () {
+	let i = yield* s.make(c), a = e.maxEntries, l = e.now === void 0 ? t.currentTimeMillis : n.sync(e.now);
+	return {
+		get: (e) => l.pipe(n.flatMap((t) => s.modify(i, (n) => {
+			let i = r.get(n.entries, e);
+			return o.isNone(i) ? [o.none(), n] : i.value.expiresAt <= t ? [o.none(), u(n, e)] : [o.some(i.value.value), n];
+		}))),
+		set: (e, t, r) => l.pipe(n.flatMap((n) => s.update(i, (i) => p(i, e, t, m(n, r?.ttlMs), [], a)))),
+		setWithTags: (e, t, r) => l.pipe(n.flatMap((n) => s.update(i, (i) => p(i, e, t, m(n, r.ttlMs), r.tags ?? [], a)))),
+		remove: (e) => l.pipe(n.flatMap((t) => s.modify(i, (n) => {
+			let i = r.get(n.entries, e);
+			return o.isNone(i) ? [!1, n] : [i.value.expiresAt > t, u(n, e)];
+		}))),
+		has: (e) => l.pipe(n.flatMap((t) => s.modify(i, (n) => {
+			let i = r.get(n.entries, e);
+			return o.isNone(i) ? [!1, n] : i.value.expiresAt <= t ? [!1, u(n, e)] : [!0, n];
+		}))),
+		clear: () => s.set(i, c),
+		invalidateTag: (e) => s.modify(i, (t) => {
+			let n = r.get(t.tagIndex, e);
+			if (o.isNone(n)) return [0, t];
+			let i = t, a = 0;
+			for (let e of n.value) i = u(i, e), a += 1;
+			return [a, {
+				...i,
+				tagIndex: r.remove(i.tagIndex, e)
+			}];
+		})
+	};
+}), g = (t = {}) => a.effect(e, h(t));
+//#endregion
+export { g as layerMemory };

package/dist/backendRedis.js

@@ -0,0 +1,56 @@
+import { CacheError as e } from "./errors.js";
+import { CacheStore as t } from "./CacheStore.js";
+import { Clock as n, Effect as r, Layer as i, Option as a } from "effect";
+import { commandRetry as o, connect as s } from "@voltro/kv/connection";
+//#region src/backendRedis.ts
+var c = (t) => s({
+	url: t.url,
+	driver: t.driver,
+	...t.token === void 0 ? {} : { token: t.token }
+}).pipe(r.mapError((t) => new e({
+	operation: "connect",
+	key: "",
+	cause: String(t)
+}))), l = "\nlocal NOEXP = 9000000000000000\nlocal ttl = tonumber(ARGV[1])\nlocal now = tonumber(ARGV[2])\nlocal score\nif ttl < 0 then score = NOEXP else score = now + ttl end\nredis.call('ZADD', KEYS[1], score, ARGV[3])\nlocal top = redis.call('ZREVRANGE', KEYS[1], 0, 0, 'WITHSCORES')\nlocal maxScore = tonumber(top[2])\nif maxScore >= NOEXP then\n  redis.call('PERSIST', KEYS[1])\nelse\n  local rem = maxScore - now\n  if rem < 1 then rem = 1 end\n  redis.call('PEXPIRE', KEYS[1], rem)\nend\nreturn 1\n", u = (t) => r.gen(function* () {
+	let i = yield* r.acquireRelease(c(t), (e) => r.promise(() => e.close().catch(() => void 0))), s = t.keyPrefix ?? "voltro:cache", u = (e) => `${s}:v:${e}`, d = (e) => `${s}:t:${e}`, f = (t, n, a) => r.tryPromise({
+		try: () => a(i),
+		catch: (r) => new e({
+			operation: t,
+			key: n,
+			cause: String(r)
+		})
+	}).pipe(r.retry(o)), p = (t, n) => r.try({
+		try: () => JSON.stringify(n),
+		catch: (n) => new e({
+			operation: "serialize",
+			key: t,
+			cause: String(n)
+		})
+	}), m = (t, n) => r.try({
+		try: () => a.some(JSON.parse(n)),
+		catch: (n) => new e({
+			operation: "deserialize",
+			key: t,
+			cause: String(n)
+		})
+	}), h = (e) => f("clear", "", (t) => t.scan(e, `${s}:*`, 200)).pipe(r.flatMap(({ cursor: e, keys: t }) => (t.length > 0 ? f("clear", "", (e) => e.del(t)) : r.succeed(0)).pipe(r.flatMap(() => e === "0" ? r.void : h(e))))), g = (e, t, n) => p(e, t).pipe(r.flatMap((t) => n !== void 0 && n > 0 ? f("set", e, (r) => r.psetex(u(e), Math.ceil(n), t)) : f("set", e, (n) => n.set(u(e), t))), r.asVoid);
+	return {
+		get: (e) => f("get", e, (t) => t.get(u(e))).pipe(r.flatMap((t) => t === null ? r.succeed(a.none()) : m(e, t))),
+		set: (e, t, n) => g(e, t, n?.ttlMs),
+		setWithTags: (e, t, i) => g(e, t, i.ttlMs).pipe(r.flatMap(() => {
+			let t = i.tags ?? [];
+			if (t.length === 0) return r.void;
+			let a = i.ttlMs !== void 0 && i.ttlMs > 0 ? Math.ceil(i.ttlMs) : -1;
+			return n.currentTimeMillis.pipe(r.flatMap((n) => r.forEach(t, (t) => f("setWithTags", e, (r) => r.eval(l, 1, d(t), a, n, e)), { discard: !0 })));
+		})),
+		remove: (e) => f("remove", e, (t) => t.del([u(e)])).pipe(r.map((e) => e > 0)),
+		has: (e) => f("has", e, (t) => t.exists(u(e))).pipe(r.map((e) => e > 0)),
+		clear: () => h("0"),
+		invalidateTag: (e) => f("invalidateTag", e, (t) => t.zrange(d(e))).pipe(r.flatMap((t) => f("invalidateTag", e, async (n) => {
+			let r = t.map(u), i = r.length > 0 ? await n.del(r) : 0;
+			return await n.del([d(e)]), i;
+		})))
+	};
+}), d = (e) => i.effect(t, u(e));
+//#endregion
+export { d as layerRedis };

package/dist/errors.js

@@ -0,0 +1,9 @@
+import { Schema as e } from "effect";
+//#region src/errors.ts
+var t = class extends e.TaggedError()("CacheError", {
+	operation: e.String,
+	key: e.String,
+	cause: e.String
+}) {};
+//#endregion
+export { t as CacheError };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ConfigError } from 'effect';
+import { Config } from 'effect';
 import { Context } from 'effect';
 import { Effect } from 'effect';
 import { Layer } from 'effect';
@@ -6,12 +6,42 @@ import { Option } from 'effect';
 import { Schema } from 'effect';
 import { Scope } from 'effect';
 import { Stream } from 'effect';
+import { YieldableError } from 'effect/Cause';
 
 export declare class Cache extends Cache_base {
+    /** `Cache` over whatever `CacheStore` is provided. */
+    static readonly layer: Layer.Layer<Cache, never, CacheStore>;
 }
 
-declare const Cache_base: Effect.Service.Class<Cache, "@voltro/Cache", {
-    readonly effect: Effect.Effect<{
+declare const Cache_base: Context.ServiceClass<Cache, "@voltro/Cache", {
+    /** Read a typed value. `None` on miss/expiry. */
+    readonly get: <A = unknown>(key: string) => Effect.Effect<Option.Option<A>, CacheError>;
+    readonly set: <A>(key: string, value: A, options?: CacheSetOptions) => Effect.Effect<void, CacheError>;
+    readonly setWithTags: <A>(key: string, value: A, options: CacheSetWithTagsOptions) => Effect.Effect<void, CacheError>;
+    /** Write-through with the SAME storage shape `wrap` uses (incl. the
+     *  SWR envelope) — so a value written here is read back identically
+     *  by a later `wrap`. The dispatcher uses this to keep cached
+     *  snapshots warm from its live recompute. */
+    readonly put: <A>(key: string, options: WrapOptions, value: A) => Effect.Effect<void, CacheError>;
+    readonly remove: (key: string) => Effect.Effect<boolean, CacheError>;
+    readonly has: (key: string) => Effect.Effect<boolean, CacheError>;
+    readonly clear: () => Effect.Effect<void, CacheError>;
+    readonly invalidateTag: (tag: string) => Effect.Effect<number, CacheError>;
+    readonly wrap: <A, E, R>(key: string, options: WrapOptions, compute: Effect.Effect<A, E, R>) => Effect.Effect<A, E | CacheError, R>;
+    /** A named, key-prefixed partition with its own default ttl/swr/tags.
+     *  Keys become `<name>:<key>`; per-call options override the defaults;
+     *  tags stay global (unprefixed) so bus invalidation still reaches
+     *  partitioned entries. */
+    readonly partition: (name: string, defaults?: PartitionDefaults) => CachePartition;
+    /** Read the hit/miss counters + derived hit-rate (0–1). Drives the
+     *  dashboard cache panel. */
+    readonly stats: () => Effect.Effect<{
+        hits: number;
+        misses: number;
+        hitRate: number;
+    }>;
+}> & {
+    readonly make: Effect.Effect<{
         /** Read a typed value. `None` on miss/expiry. */
         readonly get: <A = unknown>(key: string) => Effect.Effect<Option.Option<A>, CacheError>;
         readonly set: <A>(key: string, value: A, options?: CacheSetOptions) => Effect.Effect<void, CacheError>;
@@ -39,22 +69,20 @@ declare const Cache_base: Effect.Service.Class<Cache, "@voltro/Cache", {
             hitRate: number;
         }>;
     }, never, CacheStore>;
-}>;
+};
 
 export declare class CacheError extends CacheError_base {
 }
 
-declare const CacheError_base: Schema.TaggedErrorClass<CacheError, "CacheError", {
-    readonly _tag: Schema.tag<"CacheError">;
-} & {
+declare const CacheError_base: Schema.Class<CacheError, Schema.TaggedStruct<"CacheError", {
     /** Which op failed: 'get' | 'set' | 'setWithTags' | 'remove' | 'has' |
      *  'clear' | 'invalidateTag' | 'connect' | 'serialize' | 'deserialize'. */
-    operation: typeof Schema.String;
+    readonly operation: Schema.String;
     /** The cache key (or tag) involved; '' for clear / connect. */
-    key: typeof Schema.String;
+    readonly key: Schema.String;
     /** `String(originalError)` — round-trip-safe diagnostic form. */
-    cause: typeof Schema.String;
-}>;
+    readonly cause: Schema.String;
+}>, YieldableError>;
 
 export declare namespace CacheLayer {
     export {
@@ -103,7 +131,7 @@ export declare interface CacheSetWithTagsOptions extends CacheSetOptions {
 export declare class CacheStore extends CacheStore_base {
 }
 
-declare const CacheStore_base: Context.TagClass<CacheStore, "@voltro/CacheStore", CacheStoreShape>;
+declare const CacheStore_base: Context.ServiceClass<CacheStore, "@voltro/CacheStore", CacheStoreShape>;
 
 export declare interface CacheStoreShape {
     /** Read a value. `None` on miss OR expiry (expired entries are lazily
@@ -160,21 +188,27 @@ export declare const cosineSimilarity: (a: ReadonlyArray<number>, b: ReadonlyArr
 export declare const depsForChange: (c: ChangeSignal) => ReadonlyArray<string>;
 
 export declare class InvalidationBus extends InvalidationBus_base {
+    /** The bus with its own scope: sinks live as long as the layer. */
+    static readonly layer: Layer.Layer<InvalidationBus, never, never>;
 }
 
-declare const InvalidationBus_base: Effect.Service.Class<InvalidationBus, "@voltro/InvalidationBus", {
-    readonly scoped: Effect.Effect<{
+declare const InvalidationBus_base: Context.ServiceClass<InvalidationBus, "@voltro/InvalidationBus", {
+    readonly publish: (table: string) => Effect.Effect<void>;
+    readonly changes: Stream.Stream<string, never, never>;
+    readonly addSink: (handle: (table: string) => Effect.Effect<unknown, unknown>) => Effect.Effect<void>;
+}> & {
+    readonly make: Effect.Effect<{
         readonly publish: (table: string) => Effect.Effect<void>;
         readonly changes: Stream.Stream<string, never, never>;
         readonly addSink: (handle: (table: string) => Effect.Effect<unknown, unknown>) => Effect.Effect<void>;
     }, never, Scope.Scope>;
-}>;
+};
 
 /**
  * `Layer<Cache>` whose backend is chosen from the environment. Provide
  * this in the app's layer stack so handlers can `yield* Cache`.
  */
-declare const layer: Layer.Layer<Cache, ConfigError.ConfigError | CacheError>;
+declare const layer: Layer.Layer<Cache, Config.ConfigError | CacheError>;
 
 /** `Layer<CacheStore>` backed by an in-process `Ref`. */
 export declare const layerMemory: (options?: MemoryCacheOptions) => Layer.Layer<CacheStore>;
@@ -231,15 +265,17 @@ export declare const rowDep: (table: string, id: string) => string;
  * `CacheStore` in context — mirror of how `Cache` is built on `CacheStore`.
  *
  * ```ts
- * const layer = SemanticCache.Default.pipe(Layer.provide(CacheLayer.layer))
+ * const layer = SemanticCache.layer.pipe(Layer.provide(CacheLayer.layer))
  * ```
  */
 export declare class SemanticCache extends SemanticCache_base {
+    /** `SemanticCache` over whatever `CacheStore` is provided. */
+    static readonly layer: Layer.Layer<SemanticCache, never, CacheStore>;
 }
 
-declare const SemanticCache_base: Effect.Service.Class<SemanticCache, "@voltro/SemanticCache", {
-    readonly effect: Effect.Effect<SemanticCacheShape, never, CacheStore>;
-}>;
+declare const SemanticCache_base: Context.ServiceClass<SemanticCache, "@voltro/SemanticCache", SemanticCacheShape> & {
+    readonly make: Effect.Effect<SemanticCacheShape, never, CacheStore>;
+};
 
 export declare interface SemanticCacheOptions {
     /** Default similarity threshold when a `lookup` omits one. Default 0.95. */
@@ -313,7 +349,7 @@ export declare interface SemanticPutOptions {
  * `Cache` and a `SemanticCache` end up over the same backend — see
  * `cli/src/cacheFacade.ts`).
  */
-declare const storeLayer: Layer.Layer<CacheStore, ConfigError.ConfigError | CacheError>;
+declare const storeLayer: Layer.Layer<CacheStore, Config.ConfigError | CacheError>;
 
 /** The dependency tag for a whole table. Coarser than {@link rowDep}: it also
  *  catches INSERTs (a new matching row the cached answer never read, so no