@voltro/cache 0.86.0 → 0.87.0

package/dist/index.d.ts

@@ -1,8 +1,12 @@
+import { CACHE_FENCE_RETENTION_MS } from '@voltro/kv/connection';
 import { Config } from 'effect';
 import { Context } from 'effect';
 import { Effect } from 'effect';
 import { Layer } from 'effect';
 import { Option } from 'effect';
+import { RedisConnections } from '@voltro/kv/connection';
+import { RespClient } from '@voltro/kv/connection';
+import { RespConnections } from '@voltro/kv/connection';
 import { Schema } from 'effect';
 import { Scope } from 'effect';
 import { Stream } from 'effect';
@@ -21,13 +25,26 @@ declare const Cache_base: Context.ServiceClass<Cache, "@voltro/Cache", {
     /** 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>;
+     *  snapshots warm from its live recompute. Pass the `fence()` observed
+     *  before the value was read, so an earlier, slower read can never
+     *  overwrite a later one. Resolves `false` when the fence voided it. */
+    readonly put: <A>(key: string, options: WrapOptions, value: A, fence?: CacheFence) => Effect.Effect<boolean, CacheError>;
+    /** The store's invalidation position — observe it before reading the
+     *  value you will `put`. */
+    readonly fence: () => Effect.Effect<CacheFence, 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>;
+    /** Cache-aside whose store decision the compute makes — see the
+     *  `wrapDynamic` note above. Best-effort: never fails on the cache. */
+    readonly wrapDynamic: <A, E, R>(key: string, options: DynamicWrapOptions, compute: Effect.Effect<DynamicComputed<A>, E, R>, read: (stored: unknown) => Effect.Effect<Option.Option<A>>) => Effect.Effect<{
+        readonly value: A;
+        readonly served: DynamicServed;
+    }, E, R>;
+    /** Per-label counters kept by `wrapDynamic`. */
+    readonly queryStats: () => Effect.Effect<Readonly<Record<string, DynamicLabelStats>>>;
     /** 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
@@ -39,6 +56,7 @@ declare const Cache_base: Context.ServiceClass<Cache, "@voltro/Cache", {
         hits: number;
         misses: number;
         hitRate: number;
+        voided: number;
     }>;
 }> & {
     readonly make: Effect.Effect<{
@@ -49,13 +67,26 @@ declare const Cache_base: Context.ServiceClass<Cache, "@voltro/Cache", {
         /** 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>;
+         *  snapshots warm from its live recompute. Pass the `fence()` observed
+         *  before the value was read, so an earlier, slower read can never
+         *  overwrite a later one. Resolves `false` when the fence voided it. */
+        readonly put: <A>(key: string, options: WrapOptions, value: A, fence?: CacheFence) => Effect.Effect<boolean, CacheError>;
+        /** The store's invalidation position — observe it before reading the
+         *  value you will `put`. */
+        readonly fence: () => Effect.Effect<CacheFence, 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>;
+        /** Cache-aside whose store decision the compute makes — see the
+         *  `wrapDynamic` note above. Best-effort: never fails on the cache. */
+        readonly wrapDynamic: <A, E, R>(key: string, options: DynamicWrapOptions, compute: Effect.Effect<DynamicComputed<A>, E, R>, read: (stored: unknown) => Effect.Effect<Option.Option<A>>) => Effect.Effect<{
+            readonly value: A;
+            readonly served: DynamicServed;
+        }, E, R>;
+        /** Per-label counters kept by `wrapDynamic`. */
+        readonly queryStats: () => Effect.Effect<Readonly<Record<string, DynamicLabelStats>>>;
         /** 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
@@ -67,10 +98,13 @@ declare const Cache_base: Context.ServiceClass<Cache, "@voltro/Cache", {
             hits: number;
             misses: number;
             hitRate: number;
+            voided: number;
         }>;
     }, never, CacheStore>;
 };
 
+export { CACHE_FENCE_RETENTION_MS }
+
 export declare class CacheError extends CacheError_base {
 }
 
@@ -84,8 +118,18 @@ declare const CacheError_base: Schema.Class<CacheError, Schema.TaggedStruct<"Cac
     readonly cause: Schema.String;
 }>, YieldableError>;
 
+/**
+ * The store's invalidation position, observed before a compute. Opaque: only
+ * hand it back to `setWithTags`. A fence older than
+ * `CACHE_FENCE_RETENTION_MS` proves nothing; `Cache.wrap` does not store such
+ * a compute.
+ */
+export declare type CacheFence = number;
+
 export declare namespace CacheLayer {
     export {
+        CacheStoreLayerOptions,
+        makeStoreLayer,
         storeLayer,
         layer
     }
@@ -126,6 +170,10 @@ export declare interface CacheSetWithTagsOptions extends CacheSetOptions {
     /** Tags this entry belongs to. `invalidateTag(tag)` drops every entry
      *  carrying that tag. */
     readonly tags?: ReadonlyArray<string>;
+    /** A `fence()` observed BEFORE the value was computed. When any of `tags`
+     *  was invalidated since — anywhere that shares this store — the write is
+     *  void: the value may predate the write behind that invalidation. */
+    readonly fence?: CacheFence;
 }
 
 export declare class CacheStore extends CacheStore_base {
@@ -133,6 +181,13 @@ export declare class CacheStore extends CacheStore_base {
 
 declare const CacheStore_base: Context.ServiceClass<CacheStore, "@voltro/CacheStore", CacheStoreShape>;
 
+declare interface CacheStoreLayerOptions {
+    readonly backend?: 'memory' | 'redis';
+    readonly connectionName?: string;
+    readonly keyPrefix?: string;
+    readonly connections?: RespConnections;
+}
+
 export declare interface CacheStoreShape {
     /** Read a value. `None` on miss OR expiry (expired entries are lazily
      *  evicted on read). */
@@ -140,8 +195,15 @@ export declare interface CacheStoreShape {
     /** Write a value with an optional ms TTL. Overwrites any existing entry
      *  (clearing its old tag memberships). */
     readonly set: (key: string, value: unknown, options?: CacheSetOptions) => Effect.Effect<void, CacheError>;
-    /** Write a value AND register it under the given tags. */
-    readonly setWithTags: (key: string, value: unknown, options: CacheSetWithTagsOptions) => Effect.Effect<void, CacheError>;
+    /** Write a value AND register it under the given tags. Resolves `false`
+     *  when `options.fence` voided the write (nothing was stored). */
+    readonly setWithTags: (key: string, value: unknown, options: CacheSetWithTagsOptions) => Effect.Effect<boolean, CacheError>;
+    /** Current invalidation position — see {@link CacheFence}. Every
+     *  `invalidateTag` advances it, for every participant sharing the store. */
+    readonly fence: () => Effect.Effect<CacheFence, CacheError>;
+    /** Claim `key` for `ttlMs` if nobody holds it — the cluster single-flight
+     *  lease. Optional: a process-local store has nothing to coordinate. */
+    readonly claim?: (key: string, ttlMs: number) => Effect.Effect<boolean, CacheError>;
     /** Delete one key (and its tag memberships). Resolves `true` if it existed. */
     readonly remove: (key: string) => Effect.Effect<boolean, CacheError>;
     /** Existence check honouring expiry, without deserializing the value. */
@@ -149,8 +211,9 @@ export declare interface CacheStoreShape {
     /** Drop every entry in this cache's namespace. Scoped to the backend's
      *  key-prefix — never a global flush on a shared server. */
     readonly clear: () => Effect.Effect<void, CacheError>;
-    /** Delete every key registered under `tag`, then drop the tag index.
-     *  Resolves the count of keys removed. */
+    /** Delete every key registered under `tag`, then drop the tag index, and
+     *  advance the fence for `tag` (also when nothing carried it). Resolves the
+     *  count of keys removed. `clear` does not reset the fence. */
     readonly invalidateTag: (tag: string) => Effect.Effect<number, CacheError>;
 }
 
@@ -187,6 +250,52 @@ export declare const cosineSimilarity: (a: ReadonlyArray<number>, b: ReadonlyArr
  */
 export declare const depsForChange: (c: ChangeSignal) => ReadonlyArray<string>;
 
+/** A `wrapDynamic` compute's result: the value for THIS caller, and whether
+ *  (and how) it may be stored for the next. */
+export declare interface DynamicComputed<A> {
+    readonly value: A;
+    readonly store?: DynamicStore | undefined;
+    /** The compute found the call is not a candidate for this cache at all (a
+     *  query whose handler returned a descriptor): nothing stored, and not
+     *  counted as a result the cache refused to keep. */
+    readonly notApplicable?: boolean | undefined;
+}
+
+export declare type DynamicEvent = keyof DynamicLabelStats;
+
+/** Per-label counters — `queryStats()`, the dashboard Cache panel and the
+ *  `voltro_query_cache_events_total{query,event}` series. */
+export declare interface DynamicLabelStats {
+    readonly hits: number;
+    readonly stale: number;
+    readonly misses: number;
+    readonly stored: number;
+    readonly voided: number;
+    readonly decodeMisses: number;
+    readonly uncacheable: number;
+    readonly oversized: number;
+}
+
+export declare type DynamicServed = 'hit' | 'stale' | 'miss';
+
+/** What a `wrapDynamic` compute stores, decided AFTER it ran: the encoded
+ *  value and the tags it actually depends on. Absent ⇒ not stored. */
+export declare interface DynamicStore {
+    readonly stored: unknown;
+    readonly tags: ReadonlyArray<string>;
+}
+
+export declare interface DynamicWrapOptions {
+    readonly ttlMs: number;
+    readonly swrMs?: number | undefined;
+    /** Cluster single-flight: on a miss, claim the key for this long on a
+     *  store that can (`CacheStore.claim`); other participants wait for the
+     *  claimant's value instead of computing it too, up to this bound. */
+    readonly leaseMs?: number | undefined;
+    /** Bounded label the per-label counters are kept under (a query name). */
+    readonly label: 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>;
@@ -214,7 +323,10 @@ declare const layer: Layer.Layer<Cache, Config.ConfigError | CacheError>;
 export declare const layerMemory: (options?: MemoryCacheOptions) => Layer.Layer<CacheStore>;
 
 /** `Layer<CacheStore>` backed by a RESP server (Redis/Valkey/KeyDB/Dragonfly/Upstash). */
-export declare const layerRedis: (options: RedisCacheOptions) => Layer.Layer<CacheStore, CacheError>;
+export declare const layerRedis: (options?: RedisCacheOptions) => Layer.Layer<CacheStore, CacheError, RedisConnections>;
+
+/** Cache semantics over a registry-owned client; never closes its socket. */
+export declare const makeRedisCacheStore: (client: RespClient, prefix?: string) => CacheStoreShape;
 
 /**
  * Build a {@link SemanticCacheShape} over a resolved {@link CacheStoreShape}.
@@ -225,8 +337,19 @@ export declare const layerRedis: (options: RedisCacheOptions) => Layer.Layer<Cac
  */
 export declare const makeSemanticCache: (store: CacheStoreShape, _options?: SemanticCacheOptions) => Effect.Effect<SemanticCacheShape>;
 
+/**
+ * `Layer<CacheStore>` whose backend (memory | redis) + connection are chosen
+ * from the environment. This is the STORE — value/TTL/tag storage — one level
+ * below `Cache`. Exposed so a caller can build MORE than one service on ONE
+ * store instance: `Layer.provide(storeLayer)` on a merged layer memoises a
+ * SINGLE `CacheStore`, shared by every consumer in it (that is how the query
+ * `Cache` and a `SemanticCache` end up over the same backend — see
+ * `cli/src/cacheFacade.ts`).
+ */
+declare const makeStoreLayer: (options?: CacheStoreLayerOptions) => Layer.Layer<CacheStore, Config.ConfigError | CacheError>;
+
 export declare interface MemoryCacheOptions {
-    /** Hard cap on live entry count. When exceeded, oldest-by-insertion
+    /** Hard cap on live entry count. When exceeded, least-recently-used
      *  entries are evicted — the backstop for entries that expired but were
      *  never read (lazy eviction never fired). Omit for unbounded. */
     readonly maxEntries?: number;
@@ -247,11 +370,8 @@ export declare interface PartitionDefaults {
 }
 
 export declare interface RedisCacheOptions {
-    readonly driver: 'resp' | 'http';
-    /** Connection URL (`redis://…` / `rediss://…` for RESP, the REST URL for http). */
-    readonly url: string;
-    /** Auth token — http (Upstash REST) driver only. */
-    readonly token?: string;
+    /** Named pooled connection; defaults to cache's environment convention. */
+    readonly connectionName?: string;
     readonly keyPrefix?: string;
 }
 
@@ -340,15 +460,6 @@ export declare interface SemanticPutOptions {
     readonly key?: string;
 }
 
-/**
- * `Layer<CacheStore>` whose backend (memory | redis) + connection are chosen
- * from the environment. This is the STORE — value/TTL/tag storage — one level
- * below `Cache`. Exposed so a caller can build MORE than one service on ONE
- * store instance: `Layer.provide(storeLayer)` on a merged layer memoises a
- * SINGLE `CacheStore`, shared by every consumer in it (that is how the query
- * `Cache` and a `SemanticCache` end up over the same backend — see
- * `cli/src/cacheFacade.ts`).
- */
 declare const storeLayer: Layer.Layer<CacheStore, Config.ConfigError | CacheError>;
 
 /** The dependency tag for a whole table. Coarser than {@link rowDep}: it also

package/dist/index.js

@@ -1,9 +1,9 @@
 import { CacheError as e } from "./errors.js";
-import { CacheStore as t } from "./CacheStore.js";
-import { layerMemory as n } from "./backendMemory.js";
-import { layerRedis as r } from "./backendRedis.js";
-import { Cache as i } from "./Cache.js";
-import { SemanticCache as a, cosineSimilarity as o, depsForChange as s, makeSemanticCache as c, rowDep as l, tableDep as u } from "./semantic.js";
-import { InvalidationBus as d } from "./invalidationBus.js";
-import { layer_exports as f } from "./layer.js";
-export { i as Cache, e as CacheError, f as CacheLayer, t as CacheStore, d as InvalidationBus, a as SemanticCache, o as cosineSimilarity, s as depsForChange, n as layerMemory, r as layerRedis, c as makeSemanticCache, l as rowDep, u as tableDep };
+import { CACHE_FENCE_RETENTION_MS as t, CacheStore as n } from "./CacheStore.js";
+import { layerMemory as r } from "./backendMemory.js";
+import { layerRedis as i, makeRedisCacheStore as a } from "./backendRedis.js";
+import { Cache as o } from "./Cache.js";
+import { SemanticCache as s, cosineSimilarity as c, depsForChange as l, makeSemanticCache as u, rowDep as d, tableDep as f } from "./semantic.js";
+import { InvalidationBus as p } from "./invalidationBus.js";
+import { layer_exports as m } from "./layer.js";
+export { t as CACHE_FENCE_RETENTION_MS, o as Cache, e as CacheError, m as CacheLayer, n as CacheStore, p as InvalidationBus, s as SemanticCache, c as cosineSimilarity, l as depsForChange, r as layerMemory, i as layerRedis, a as makeRedisCacheStore, u as makeSemanticCache, d as rowDep, f as tableDep };

package/dist/layer.js

@@ -3,23 +3,23 @@ import { layerMemory as t } from "./backendMemory.js";
 import { layerRedis as n } from "./backendRedis.js";
 import { Cache as r } from "./Cache.js";
 import { Config as i, Effect as a, Layer as o, Option as s } from "effect";
+import { RedisConnections as c, layerConnections as l } from "@voltro/kv/connection";
 //#region src/layer.ts
-var c = /* @__PURE__ */ e({
-	layer: () => f,
-	storeLayer: () => d
-}), l = a.gen(function* () {
+var u = /* @__PURE__ */ e({
+	layer: () => h,
+	makeStoreLayer: () => p,
+	storeLayer: () => m
+}), d = a.gen(function* () {
 	let e = yield* i.Int("CACHE_MAX_ENTRIES").pipe(i.option), n = s.isSome(e) ? { maxEntries: e.value } : {};
 	return t(n);
-}), u = a.gen(function* () {
-	let e = yield* i.String("CACHE_REDIS_URL").pipe(i.orElse(() => i.String("REDIS_URL"))), t = yield* i.Literals(["resp", "http"], "CACHE_REDIS_DRIVER").pipe(i.withDefault("resp")), r = yield* i.String("CACHE_REDIS_TOKEN").pipe(i.orElse(() => i.String("UPSTASH_REDIS_REST_TOKEN")), i.option), a = yield* i.String("CACHE_KEY_PREFIX").pipe(i.option), o = {
-		driver: t,
-		url: e,
-		...s.isSome(r) ? { token: r.value } : {},
-		...s.isSome(a) ? { keyPrefix: a.value } : {}
+}), f = (e) => a.gen(function* () {
+	let t = yield* i.String("CACHE_KEY_PREFIX").pipe(i.option), r = {
+		...e.connectionName === void 0 ? {} : { connectionName: e.connectionName },
+		...s.isSome(t) ? { keyPrefix: t.value } : e.keyPrefix === void 0 ? {} : { keyPrefix: e.keyPrefix }
 	};
-	return n(o);
-}), d = o.unwrap(a.gen(function* () {
-	return (yield* i.Literals(["memory", "redis"], "CACHE_BACKEND").pipe(i.withDefault("memory"))) === "redis" ? yield* u : yield* l;
-})), f = r.layer.pipe(o.provide(d));
+	return n(r).pipe(o.provide(e.connections === void 0 ? l : o.succeed(c, e.connections)));
+}), p = (e = {}) => o.unwrap(a.gen(function* () {
+	return (yield* i.Literals(["memory", "redis"], "CACHE_BACKEND").pipe(i.withDefault(e.backend ?? "memory"))) === "redis" ? yield* f(e) : yield* d;
+})), m = p(), h = r.layer.pipe(o.provide(m));
 //#endregion
-export { f as layer, c as layer_exports, d as storeLayer };
+export { h as layer, u as layer_exports, p as makeStoreLayer, m as storeLayer };

package/package.json

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