@voltro/cache 0.83.1 → 0.85.0

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

package/dist/index.js

@@ -12,10 +12,12 @@ var v = Object.defineProperty, y = (e, t) => {
 	operation: f.String,
 	key: f.String,
 	cause: f.String
-}) {}, x = class extends n.Tag("@voltro/CacheStore")() {}, S = {
+}) {}, x = class extends n.Service()("@voltro/CacheStore") {}, S = {
 	entries: a.empty(),
 	tagIndex: a.empty(),
-	seq: 0
+	seq: 0,
+	oldest: void 0,
+	newest: void 0
 }, C = (e, t, n) => {
 	let r = e;
 	for (let e of n) {
@@ -27,10 +29,28 @@ var v = Object.defineProperty, y = (e, t) => {
 	return r;
 }, w = (e, t) => {
 	let n = a.get(e.entries, t);
-	return l.isNone(n) ? e : {
-		entries: a.remove(e.entries, t),
+	if (l.isNone(n)) return e;
+	let { older: r, newer: i } = n.value, o = a.remove(e.entries, t);
+	if (r !== void 0) {
+		let e = a.get(o, r);
+		l.isSome(e) && (o = a.set(o, r, {
+			...e.value,
+			newer: i
+		}));
+	}
+	if (i !== void 0) {
+		let e = a.get(o, i);
+		l.isSome(e) && (o = a.set(o, i, {
+			...e.value,
+			older: r
+		}));
+	}
+	return {
+		entries: o,
 		tagIndex: C(e.tagIndex, t, n.value.tags),
-		seq: e.seq
+		seq: e.seq,
+		oldest: r === void 0 ? i : e.oldest,
+		newest: i === void 0 ? r : e.newest
 	};
 }, T = (e, t, n) => {
 	let r = a.get(e, t), i = l.isSome(r) ? o.add(r.value, n) : o.make(n);
@@ -38,30 +58,39 @@ var v = Object.defineProperty, y = (e, t) => {
 }, E = (e, t) => {
 	let n = a.size(e.entries) - t;
 	if (n <= 0) return e;
-	let r = [];
-	for (let [t, n] of e.entries) r.push([t, n.seq]);
-	r.sort((e, t) => e[1] - t[1]);
-	let i = e;
+	let r = e;
 	for (let e = 0; e < n; e++) {
-		let t = r[e];
-		if (t === void 0) break;
-		i = w(i, t[0]);
+		let e = r.oldest;
+		if (e === void 0) break;
+		r = w(r, e);
 	}
-	return i;
+	return r;
 }, D = (e, t, n, r, i, o) => {
-	let s = w(e, t), c = s.seq + 1, l = s.tagIndex;
-	for (let e of i) l = T(l, e, t);
-	let u = {
-		entries: a.set(s.entries, t, {
-			value: n,
-			expiresAt: r,
-			tags: i,
-			seq: c
-		}),
-		tagIndex: l,
-		seq: c
+	let s = w(e, t), c = s.seq + 1, u = s.tagIndex;
+	for (let e of i) u = T(u, e, t);
+	let d = a.set(s.entries, t, {
+		value: n,
+		expiresAt: r,
+		tags: i,
+		seq: c,
+		older: s.newest,
+		newer: void 0
+	});
+	if (s.newest !== void 0) {
+		let e = a.get(d, s.newest);
+		l.isSome(e) && (d = a.set(d, s.newest, {
+			...e.value,
+			newer: t
+		}));
+	}
+	let f = {
+		entries: d,
+		tagIndex: u,
+		seq: c,
+		oldest: s.oldest ?? t,
+		newest: t
 	};
-	return o === void 0 ? u : E(u, o);
+	return o === void 0 ? f : E(f, o);
 }, O = (e, t) => t === void 0 ? Infinity : e + t, k = (t) => i.gen(function* () {
 	let n = yield* d.make(S), r = t.maxEntries, o = t.now === void 0 ? e.currentTimeMillis : i.sync(t.now);
 	return {
@@ -139,7 +168,7 @@ var v = Object.defineProperty, y = (e, t) => {
 			return await n.del([o(e)]), i;
 		})))
 	};
-}), P = (e) => s.scoped(x, N(e)), F = (e) => typeof e == "object" && !!e && e._voltroSwr === 1, I = class extends i.Service()("@voltro/Cache", { effect: i.gen(function* () {
+}), P = (e) => s.effect(x, N(e)), F = (e) => typeof e == "object" && !!e && e._voltroSwr === 1, I = class t extends n.Service()("@voltro/Cache", { make: i.gen(function* () {
 	let t = yield* x, n = yield* h.make(a.empty()), o = c.counter("voltro_cache_hits"), s = c.counter("voltro_cache_misses"), u = (n, r, a) => {
 		let o = a.tags === void 0 ? {} : { tags: a.tags }, s = a.swrMs;
 		if (s !== void 0) {
@@ -170,17 +199,17 @@ var v = Object.defineProperty, y = (e, t) => {
 	}).pipe(i.flatMap((o) => {
 		if (o.kind === "await") return r.await(o.deferred);
 		let s = o.deferred;
-		return t.pipe(i.onExit((t) => r.done(s, t).pipe(i.zipRight(h.update(n, (t) => a.remove(t, e))))));
+		return t.pipe(i.onExit((t) => r.done(s, t).pipe(i.andThen(h.update(n, (t) => a.remove(t, e))))));
 	})), p = (n, r, a) => t.get(n).pipe(i.flatMap((t) => {
 		if (l.isSome(t)) {
 			let s = t.value;
-			return F(s) ? c.increment(o).pipe(i.zipRight(e.currentTimeMillis), i.flatMap((e) => {
+			return F(s) ? c.update(o, 1).pipe(i.andThen(e.currentTimeMillis), i.flatMap((e) => {
 				if (e < s.freshUntil) return i.succeed(s.v);
-				let t = f(n, d(n, r, a)).pipe(i.catchAllCause(() => i.void));
-				return i.forkDaemon(t).pipe(i.as(s.v));
-			})) : c.increment(o).pipe(i.as(s));
+				let t = f(n, d(n, r, a)).pipe(i.catchCause(() => i.void));
+				return i.forkDetach(t).pipe(i.as(s.v));
+			})) : c.update(o, 1).pipe(i.as(s));
 		}
-		return c.increment(s).pipe(i.zipRight(f(n, d(n, r, a))));
+		return c.update(s, 1).pipe(i.andThen(f(n, d(n, r, a))));
 	}));
 	return {
 		get: (e) => t.get(e),
@@ -220,7 +249,9 @@ var v = Object.defineProperty, y = (e, t) => {
 			};
 		}))
 	};
-}) }) {}, L = (e, t) => `row:${e}:${t}`, R = (e) => `table:${e}`, z = (e) => {
+}) }) {
+	static layer = s.effect(t, t.make);
+}, L = (e, t) => `row:${e}:${t}`, R = (e) => `table:${e}`, z = (e) => {
 	let t = R(e.table);
 	return e.op === "insert" || e.id === void 0 ? [t] : [L(e.table, e.id), t];
 }, B = (e, t) => {
@@ -272,18 +303,33 @@ var v = Object.defineProperty, y = (e, t) => {
 	};
 }, K = (e, t = {}) => i.gen(function* () {
 	let t = yield* d.make(H), n = (n, r) => i.gen(function* () {
-		let i = yield* d.get(t), a = [];
+		let i = yield* d.get(t), a = [], o = 0;
 		for (let [, e] of i.entries) {
 			let t = B(n, e.embedding);
-			t >= r.threshold && a.push([e, t]);
+			t >= r.threshold && a.push([
+				e,
+				t,
+				o
+			]), o++;
 		}
-		a.sort((e, t) => t[1] - e[1]);
-		for (let [n] of a) {
-			let r = yield* e.get(n.key);
-			if (l.isSome(r)) return yield* d.update(t, (e) => ({
+		let s = (e, t) => e[1] > t[1] || e[1] === t[1] && e[2] < t[2], c = (e) => {
+			let t = a[e];
+			for (; e * 2 + 1 < a.length;) {
+				let n = e * 2 + 1;
+				if (n + 1 < a.length && s(a[n + 1], a[n]) && n++, !s(a[n], t)) break;
+				a[e] = a[n], e = n;
+			}
+			a[e] = t;
+		};
+		for (let e = Math.floor(a.length / 2) - 1; e >= 0; e--) c(e);
+		for (; a.length > 0;) {
+			let [n] = a[0], r = a.pop();
+			a.length > 0 && (a[0] = r, c(0));
+			let i = yield* e.get(n.key);
+			if (l.isSome(i)) return yield* d.update(t, (e) => ({
 				...e,
 				hits: e.hits + 1
-			})), l.some(r.value);
+			})), l.some(i.value);
 			yield* d.update(t, (e) => W(e, n.key));
 		}
 		return yield* d.update(t, (e) => ({
@@ -319,38 +365,42 @@ var v = Object.defineProperty, y = (e, t) => {
 		evict: o,
 		onSourceChange: (e) => o(z(e)),
 		onTableChange: (e) => o([R(e)]),
-		clear: () => e.clear().pipe(i.zipRight(d.set(t, H))),
+		clear: () => e.clear().pipe(i.andThen(d.set(t, H))),
 		stats: () => d.get(t).pipe(i.map((e) => ({
 			hits: e.hits,
 			misses: e.misses,
 			size: a.size(e.entries)
 		})))
 	};
-}), q = class extends i.Service()("@voltro/SemanticCache", { effect: i.gen(function* () {
+}), q = class e extends n.Service()("@voltro/SemanticCache", { make: i.gen(function* () {
 	return yield* K(yield* x);
-}) }) {}, J = class extends i.Service()("@voltro/InvalidationBus", { scoped: i.gen(function* () {
+}) }) {
+	static layer = s.effect(e, e.make);
+}, J = class e extends n.Service()("@voltro/InvalidationBus", { make: i.gen(function* () {
 	let e = yield* u.unbounded(), t = yield* i.scope;
 	return {
 		publish: (t) => u.publish(e, t).pipe(i.asVoid),
 		changes: m.fromPubSub(e),
-		addSink: (n) => p.extend(u.subscribe(e), t).pipe(i.flatMap((e) => m.fromQueue(e).pipe(m.runForEach((e) => n(e).pipe(i.ignore)), i.forkIn(t))), i.asVoid)
+		addSink: (n) => p.provide(u.subscribe(e), t).pipe(i.flatMap((e) => m.fromSubscription(e).pipe(m.runForEach((e) => n(e).pipe(i.ignore)), i.forkIn(t))), i.asVoid)
 	};
-}) }) {}, Y = /* @__PURE__ */ y({
+}) }) {
+	static layer = s.effect(e, e.make);
+}, Y = /* @__PURE__ */ y({
 	layer: () => $,
 	storeLayer: () => Q
 }), X = i.gen(function* () {
-	let e = yield* t.integer("CACHE_MAX_ENTRIES").pipe(t.option);
+	let e = yield* t.Int("CACHE_MAX_ENTRIES").pipe(t.option);
 	return A(l.isSome(e) ? { maxEntries: e.value } : {});
 }), Z = i.gen(function* () {
-	let e = yield* t.string("CACHE_REDIS_URL").pipe(t.orElse(() => t.string("REDIS_URL"))), n = yield* t.literal("resp", "http")("CACHE_REDIS_DRIVER").pipe(t.withDefault("resp")), r = yield* t.string("CACHE_REDIS_TOKEN").pipe(t.orElse(() => t.string("UPSTASH_REDIS_REST_TOKEN")), t.option), i = yield* t.string("CACHE_KEY_PREFIX").pipe(t.option);
+	let e = yield* t.String("CACHE_REDIS_URL").pipe(t.orElse(() => t.String("REDIS_URL"))), n = yield* t.Literals(["resp", "http"], "CACHE_REDIS_DRIVER").pipe(t.withDefault("resp")), r = yield* t.String("CACHE_REDIS_TOKEN").pipe(t.orElse(() => t.String("UPSTASH_REDIS_REST_TOKEN")), t.option), i = yield* t.String("CACHE_KEY_PREFIX").pipe(t.option);
 	return P({
 		driver: n,
 		url: e,
 		...l.isSome(r) ? { token: r.value } : {},
 		...l.isSome(i) ? { keyPrefix: i.value } : {}
 	});
-}), Q = s.unwrapEffect(i.gen(function* () {
-	return (yield* t.literal("memory", "redis")("CACHE_BACKEND").pipe(t.withDefault("memory"))) === "redis" ? yield* Z : yield* X;
-})), $ = I.Default.pipe(s.provide(Q));
+}), Q = s.unwrap(i.gen(function* () {
+	return (yield* t.Literals(["memory", "redis"], "CACHE_BACKEND").pipe(t.withDefault("memory"))) === "redis" ? yield* Z : yield* X;
+})), $ = I.layer.pipe(s.provide(Q));
 //#endregion
 export { I as Cache, b as CacheError, Y as CacheLayer, x as CacheStore, J as InvalidationBus, q as SemanticCache, B as cosineSimilarity, z as depsForChange, A as layerMemory, P as layerRedis, K as makeSemanticCache, L as rowDep, R as tableDep };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cache",
-  "version": "0.83.1",
+  "version": "0.85.0",
   "description": "Effect-native cache primitive — memory + RESP (Redis/Valkey/KeyDB/Dragonfly/Upstash) backends, tag invalidation, single-flight wrap.",
   "keywords": [
     "voltro",
@@ -33,10 +33,10 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/kv": "0.83.1"
+    "@voltro/kv": "0.85.0"
   },
   "peerDependencies": {
-    "effect": "^3.22.2"
+    "effect": "4.0.1"
   },
   "publishConfig": {
     "access": "public"