voltaire-effect 0.2.23

package/src/services/Cache/LookupCacheService.ts

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview Lookup-based cache service using effect/Cache.
+ *
+ * @module LookupCacheService
+ * @since 0.0.1
+ *
+ * @description
+ * Provides a lookup-based caching interface using Effect's built-in Cache module.
+ * Unlike CacheService which uses manual get/set, LookupCacheService automatically
+ * computes values on cache miss using a provided lookup function.
+ *
+ * This is the idiomatic Effect pattern for caching: you define a computation
+ * that produces a value, and the cache handles memoization, TTL, and LRU eviction.
+ *
+ * Use LookupCacheService when:
+ * - You have a function that computes values (e.g., RPC calls, DB queries)
+ * - You want automatic deduplication of concurrent requests for the same key
+ * - You want the Effect ecosystem's built-in cache semantics
+ *
+ * Use CacheService when:
+ * - You need explicit get/set control
+ * - Values come from external sources (e.g., user input, external APIs)
+ * - You're porting code that expects manual cache operations
+ *
+ * @see {@link CacheService} - Manual get/set cache interface
+ * @see {@link MemoryCache} - In-memory implementation of CacheService
+ */
+
+import * as Cache from "effect/Cache";
+import * as Context from "effect/Context";
+import type * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Option from "effect/Option";
+
+/**
+ * Shape of the lookup cache service.
+ *
+ * @description
+ * Wraps effect/Cache with a service interface. The cache is parameterized
+ * by Key, Value, and Error types, with automatic lookup on cache miss.
+ *
+ * @since 0.0.1
+ */
+export type LookupCacheShape<Key, Value, Error = never> = {
+	/**
+	 * Gets a value, computing it via the lookup function if not cached.
+	 * Concurrent requests for the same key share the same computation.
+	 */
+	readonly get: (key: Key) => Effect.Effect<Value, Error>;
+
+	/**
+	 * Gets a value only if it exists in the cache.
+	 * Does not trigger the lookup function.
+	 */
+	readonly getOption: (key: Key) => Effect.Effect<Option.Option<Value>, Error>;
+
+	/**
+	 * Manually sets a value in the cache.
+	 */
+	readonly set: (key: Key, value: Value) => Effect.Effect<void>;
+
+	/**
+	 * Forces recomputation of a value, updating the cache.
+	 * Existing cached value remains available during recomputation.
+	 */
+	readonly refresh: (key: Key) => Effect.Effect<void, Error>;
+
+	/**
+	 * Invalidates a specific key.
+	 */
+	readonly invalidate: (key: Key) => Effect.Effect<void>;
+
+	/**
+	 * Invalidates all cached values.
+	 */
+	readonly invalidateAll: Effect.Effect<void>;
+
+	/**
+	 * Returns cache statistics.
+	 */
+	readonly stats: Effect.Effect<Cache.CacheStats>;
+
+	/**
+	 * Returns the approximate number of cached values.
+	 */
+	readonly size: Effect.Effect<number>;
+};
+
+/**
+ * Lookup cache service tag.
+ *
+ * @description
+ * Context tag for LookupCacheService. Must be parameterized with Key, Value,
+ * and optional Error types when used.
+ *
+ * @since 0.0.1
+ *
+ * @example Creating a typed lookup cache
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { LookupCacheService, makeLookupCache } from 'voltaire-effect'
+ *
+ * // Define a cache for user lookups
+ * const UserCache = LookupCacheService<string, User, UserNotFoundError>()
+ *
+ * const program = Effect.gen(function* () {
+ *   const cache = yield* UserCache
+ *   // Automatically fetches from DB if not cached
+ *   const user = yield* cache.get('user:123')
+ *   return user
+ * })
+ * ```
+ */
+export const LookupCacheService = <Key, Value, Error = never>() =>
+	Context.GenericTag<LookupCacheShape<Key, Value, Error>>("LookupCacheService");
+
+/**
+ * Options for creating a lookup cache.
+ *
+ * @since 0.0.1
+ */
+export interface LookupCacheOptions<Key, Value, Error, R> {
+	/**
+	 * Maximum number of entries in the cache.
+	 */
+	readonly capacity: number;
+
+	/**
+	 * Time-to-live for cached entries.
+	 */
+	readonly timeToLive: Duration.DurationInput;
+
+	/**
+	 * Function to compute values on cache miss.
+	 * Receives the key and returns an Effect producing the value.
+	 */
+	readonly lookup: (key: Key) => Effect.Effect<Value, Error, R>;
+}
+
+/**
+ * Creates a lookup cache layer.
+ *
+ * @description
+ * Returns a Layer that provides a LookupCacheService backed by effect/Cache.
+ * The cache automatically:
+ * - Computes values using the lookup function on cache miss
+ * - Deduplicates concurrent requests for the same key
+ * - Evicts entries based on LRU when capacity is reached
+ * - Expires entries after timeToLive
+ *
+ * @param options - Cache configuration including lookup function
+ * @returns A Layer providing the typed LookupCacheService
+ *
+ * @since 0.0.1
+ *
+ * @example RPC result caching
+ * ```typescript
+ * import { Effect, Duration } from 'effect'
+ * import { makeLookupCache, LookupCacheService } from 'voltaire-effect'
+ *
+ * // Define the cache service tag
+ * const BlockCache = LookupCacheService<bigint, Block, RpcError>()
+ *
+ * // Create the layer with lookup function
+ * const BlockCacheLayer = makeLookupCache(BlockCache, {
+ *   capacity: 1000,
+ *   timeToLive: Duration.minutes(5),
+ *   lookup: (blockNumber) => rpcClient.getBlock(blockNumber)
+ * })
+ *
+ * const program = Effect.gen(function* () {
+ *   const cache = yield* BlockCache
+ *   // First call fetches from RPC, subsequent calls return cached
+ *   const block = yield* cache.get(123n)
+ *   return block
+ * }).pipe(
+ *   Effect.provide(BlockCacheLayer)
+ * )
+ * ```
+ */
+export const makeLookupCache = <Key, Value, Error, R>(
+	tag: Context.Tag<
+		LookupCacheShape<Key, Value, Error>,
+		LookupCacheShape<Key, Value, Error>
+	>,
+	options: LookupCacheOptions<Key, Value, Error, R>,
+): Layer.Layer<LookupCacheShape<Key, Value, Error>, never, R> =>
+	Layer.effect(
+		tag,
+		Effect.gen(function* () {
+			const cache = yield* Cache.make({
+				capacity: options.capacity,
+				timeToLive: options.timeToLive,
+				lookup: options.lookup,
+			});
+
+			return {
+				get: (key: Key) => cache.get(key),
+				getOption: (key: Key) => cache.getOption(key),
+				set: (key: Key, value: Value) => cache.set(key, value),
+				refresh: (key: Key) => cache.refresh(key),
+				invalidate: (key: Key) => cache.invalidate(key),
+				invalidateAll: cache.invalidateAll,
+				stats: cache.cacheStats,
+				size: cache.size,
+			};
+		}),
+	);

package/src/services/Cache/MemoryCache.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as TestClock from "effect/TestClock";
+import { CacheService } from "./CacheService.js";
+import { MemoryCache } from "./MemoryCache.js";
+
+describe("MemoryCache", () => {
+	describe("basic operations", () => {
+		it.effect("sets and gets a value", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key", "value");
+				const result = yield* cache.get("key");
+				expect(Option.isSome(result)).toBe(true);
+				expect(Option.getOrThrow(result)).toBe("value");
+			}).pipe(Effect.provide(MemoryCache())),
+		);
+
+		it.effect("returns none for missing key", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				const result = yield* cache.get("missing");
+				expect(Option.isNone(result)).toBe(true);
+			}).pipe(Effect.provide(MemoryCache())),
+		);
+
+		it.effect("deletes a key", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key", "value");
+				const deleted = yield* cache.delete("key");
+				const result = yield* cache.get("key");
+				expect(deleted).toBe(true);
+				expect(Option.isNone(result)).toBe(true);
+			}).pipe(Effect.provide(MemoryCache())),
+		);
+
+		it.effect("clears all entries", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key1", "value1");
+				yield* cache.set("key2", "value2");
+				yield* cache.clear();
+				const r1 = yield* cache.get("key1");
+				const r2 = yield* cache.get("key2");
+				expect(Option.isNone(r1)).toBe(true);
+				expect(Option.isNone(r2)).toBe(true);
+			}).pipe(Effect.provide(MemoryCache())),
+		);
+	});
+
+	describe("TTL with TestClock", () => {
+		it.effect("expires entries after TTL", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key", "value", 1000);
+
+				const before = yield* cache.get("key");
+				yield* TestClock.adjust(Duration.millis(1001));
+				const after = yield* cache.get("key");
+
+				expect(Option.isSome(before)).toBe(true);
+				expect(Option.isNone(after)).toBe(true);
+			}).pipe(Effect.provide(MemoryCache())),
+		);
+
+		it.effect("does not expire entries before TTL", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key", "value", 1000);
+
+				yield* TestClock.adjust(Duration.millis(999));
+				const result = yield* cache.get("key");
+				expect(Option.isSome(result)).toBe(true);
+			}).pipe(Effect.provide(MemoryCache())),
+		);
+
+		it.effect("uses default TTL when not specified", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key", "value");
+
+				const before = yield* cache.get("key");
+				yield* TestClock.adjust(Duration.millis(501));
+				const after = yield* cache.get("key");
+
+				expect(Option.isSome(before)).toBe(true);
+				expect(Option.isNone(after)).toBe(true);
+			}).pipe(Effect.provide(MemoryCache({ defaultTtl: 500 }))),
+		);
+	});
+
+	describe("Layer isolation", () => {
+		it.effect("separate Layer instances have separate caches", () =>
+			Effect.gen(function* () {
+				const layer1 = MemoryCache();
+				const layer2 = MemoryCache();
+
+				yield* Effect.gen(function* () {
+					const cache = yield* CacheService;
+					yield* cache.set("key", "value-from-layer1");
+				}).pipe(Effect.provide(layer1));
+
+				const result = yield* Effect.gen(function* () {
+					const cache = yield* CacheService;
+					return yield* cache.get("key");
+				}).pipe(Effect.provide(layer2));
+
+				expect(Option.isNone(result)).toBe(true);
+			}),
+		);
+	});
+
+	describe("LRU eviction", () => {
+		it.effect("evicts oldest entry when max size exceeded", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key1", "value1");
+				yield* cache.set("key2", "value2");
+				yield* cache.set("key3", "value3");
+
+				const r1 = yield* cache.get("key1");
+				const r2 = yield* cache.get("key2");
+				const r3 = yield* cache.get("key3");
+
+				expect(Option.isNone(r1)).toBe(true);
+				expect(Option.isSome(r2)).toBe(true);
+				expect(Option.isSome(r3)).toBe(true);
+			}).pipe(Effect.provide(MemoryCache({ maxSize: 2 }))),
+		);
+
+		it.effect("updates LRU order on get", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key1", "value1");
+				yield* cache.set("key2", "value2");
+
+				yield* cache.get("key1");
+
+				yield* cache.set("key3", "value3");
+
+				const r1 = yield* cache.get("key1");
+				const r2 = yield* cache.get("key2");
+				const r3 = yield* cache.get("key3");
+
+				expect(Option.isSome(r1)).toBe(true);
+				expect(Option.isNone(r2)).toBe(true);
+				expect(Option.isSome(r3)).toBe(true);
+			}).pipe(Effect.provide(MemoryCache({ maxSize: 2 }))),
+		);
+	});
+});

package/src/services/Cache/MemoryCache.ts

@@ -0,0 +1,175 @@
+/**
+ * @fileoverview In-memory LRU cache implementation for CacheService.
+ *
+ * @module MemoryCache
+ * @since 0.0.1
+ *
+ * @description
+ * Provides an in-memory cache with LRU eviction and optional TTL support.
+ * Uses a Map internally with entry timestamps for expiration tracking.
+ *
+ * Features:
+ * - LRU eviction when max size is reached
+ * - Per-entry TTL support (or default TTL)
+ * - O(1) get/set operations
+ *
+ * Why not effect/Cache?
+ * effect/Cache is designed for lookup-based caching where you provide a
+ * lookup function that computes values on cache miss. CacheService needs
+ * explicit get/set semantics where values are set manually, not computed.
+ * For lookup-based caching, use LookupCacheService instead.
+ *
+ * @see {@link CacheService} - The cache service interface
+ * @see {@link NoopCache} - No-op implementation for testing
+ * @see {@link LookupCacheService} - Lookup-based cache using effect/Cache
+ */
+
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as SynchronizedRef from "effect/SynchronizedRef";
+import { CacheService } from "./CacheService.js";
+
+/**
+ * Cache entry with value and expiration timestamp.
+ */
+interface CacheEntry<T> {
+	readonly value: T;
+	readonly expiresAt: number | undefined;
+	readonly createdAt: number;
+}
+
+/**
+ * Options for configuring the in-memory cache.
+ *
+ * @since 0.0.1
+ */
+export interface MemoryCacheOptions {
+	/**
+	 * Maximum number of entries in the cache.
+	 * When exceeded, oldest entries are evicted.
+	 * @default 1000
+	 */
+	readonly maxSize?: number;
+
+	/**
+	 * Default TTL in milliseconds for entries without explicit TTL.
+	 * @default undefined (no expiration)
+	 */
+	readonly defaultTtl?: number;
+}
+
+/**
+ * Creates an in-memory LRU cache layer.
+ *
+ * @description
+ * Returns a Layer that provides CacheService with an in-memory implementation.
+ * The cache uses LRU eviction when the max size is reached and supports
+ * per-entry TTL with optional default TTL.
+ *
+ * @param options - Cache configuration options
+ * @returns A Layer providing CacheService
+ *
+ * @since 0.0.1
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { CacheService, MemoryCache } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const cache = yield* CacheService
+ *   yield* cache.set('key', 'value')
+ *   return yield* cache.get('key')
+ * }).pipe(
+ *   Effect.provide(MemoryCache())
+ * )
+ * ```
+ *
+ * @example With custom options
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const cache = yield* CacheService
+ *   // All entries expire in 5 minutes by default
+ *   yield* cache.set('key', 'value')
+ *   // Override with 1 hour TTL
+ *   yield* cache.set('key2', 'value2', 60 * 60 * 1000)
+ *   return yield* cache.get('key')
+ * }).pipe(
+ *   Effect.provide(MemoryCache({
+ *     maxSize: 500,
+ *     defaultTtl: 5 * 60 * 1000
+ *   }))
+ * )
+ * ```
+ */
+export const MemoryCache = (
+	options?: MemoryCacheOptions,
+): Layer.Layer<CacheService> => {
+	const maxSize = options?.maxSize ?? 1000;
+	const defaultTtl = options?.defaultTtl;
+
+	return Layer.effect(
+		CacheService,
+		Effect.gen(function* () {
+			const cacheRef = yield* SynchronizedRef.make(
+				new Map<string, CacheEntry<unknown>>(),
+			);
+
+			return CacheService.of({
+				get: <T>(key: string) =>
+					SynchronizedRef.modifyEffect(cacheRef, (cache) =>
+						Effect.gen(function* () {
+							const entry = cache.get(key) as CacheEntry<T> | undefined;
+							if (!entry) return [Option.none<T>(), cache];
+
+							const now = yield* Clock.currentTimeMillis;
+							if (entry.expiresAt !== undefined && now > entry.expiresAt) {
+								const newCache = new Map(cache);
+								newCache.delete(key);
+								return [Option.none<T>(), newCache];
+							}
+
+							const newCache = new Map(cache);
+							newCache.delete(key);
+							newCache.set(key, entry);
+							return [Option.some(entry.value), newCache];
+						}),
+					),
+
+				set: <T>(key: string, value: T, ttlMs?: number) =>
+					SynchronizedRef.updateEffect(cacheRef, (cache) =>
+						Effect.gen(function* () {
+							const ttl = ttlMs ?? defaultTtl;
+							const now = yield* Clock.currentTimeMillis;
+							const newCache = new Map(cache);
+
+							if (newCache.size >= maxSize && !newCache.has(key)) {
+								const oldestKey = newCache.keys().next().value;
+								if (oldestKey !== undefined) newCache.delete(oldestKey);
+							}
+
+							newCache.delete(key);
+							newCache.set(key, {
+								value,
+								expiresAt: ttl !== undefined ? now + ttl : undefined,
+								createdAt: now,
+							});
+							return newCache;
+						}),
+					),
+
+				delete: (key: string) =>
+					SynchronizedRef.modify(cacheRef, (cache) => {
+						const existed = cache.has(key);
+						const newCache = new Map(cache);
+						newCache.delete(key);
+						return [existed, newCache];
+					}),
+
+				clear: () => SynchronizedRef.set(cacheRef, new Map()),
+			});
+		}),
+	);
+};

package/src/services/Cache/NoopCache.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { CacheService } from "./CacheService.js";
+import { NoopCache } from "./NoopCache.js";
+
+describe("NoopCache", () => {
+	describe("get", () => {
+		it.effect("always returns none", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				const result = yield* cache.get("any-key");
+				expect(Option.isNone(result)).toBe(true);
+			}).pipe(Effect.provide(NoopCache)),
+		);
+
+		it.effect("returns none even after set", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key", "value");
+				const result = yield* cache.get("key");
+				expect(Option.isNone(result)).toBe(true);
+			}).pipe(Effect.provide(NoopCache)),
+		);
+
+		it.effect("returns none for complex values", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key", { nested: { data: [1, 2, 3] } });
+				const result = yield* cache.get<{ nested: { data: number[] } }>("key");
+				expect(Option.isNone(result)).toBe(true);
+			}).pipe(Effect.provide(NoopCache)),
+		);
+	});
+
+	describe("set", () => {
+		it.effect("completes without error", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key", "value");
+			}).pipe(Effect.provide(NoopCache)),
+		);
+
+		it.effect("completes with TTL without error", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key", "value", 1000);
+			}).pipe(Effect.provide(NoopCache)),
+		);
+
+		it.effect("handles multiple sets", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key1", "value1");
+				yield* cache.set("key2", "value2");
+				yield* cache.set("key3", "value3");
+			}).pipe(Effect.provide(NoopCache)),
+		);
+	});
+
+	describe("delete", () => {
+		it.effect("always returns false", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				const result = yield* cache.delete("any-key");
+				expect(result).toBe(false);
+			}).pipe(Effect.provide(NoopCache)),
+		);
+
+		it.effect("returns false even after set", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key", "value");
+				const result = yield* cache.delete("key");
+				expect(result).toBe(false);
+			}).pipe(Effect.provide(NoopCache)),
+		);
+	});
+
+	describe("clear", () => {
+		it.effect("completes without error", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.clear();
+			}).pipe(Effect.provide(NoopCache)),
+		);
+
+		it.effect("can be called multiple times", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.clear();
+				yield* cache.clear();
+				yield* cache.clear();
+			}).pipe(Effect.provide(NoopCache)),
+		);
+	});
+
+	describe("layer behavior", () => {
+		it.effect("same layer instance always returns none", () =>
+			Effect.gen(function* () {
+				const cache = yield* CacheService;
+				yield* cache.set("key", "value");
+				const r1 = yield* cache.get("key");
+				const r2 = yield* cache.get("key");
+				const r3 = yield* cache.get("key");
+				expect(Option.isNone(r1)).toBe(true);
+				expect(Option.isNone(r2)).toBe(true);
+				expect(Option.isNone(r3)).toBe(true);
+			}).pipe(Effect.provide(NoopCache)),
+		);
+	});
+
+	describe("use case: testing without cache interference", () => {
+		it.effect("function that uses cache works with NoopCache", () =>
+			Effect.gen(function* () {
+				const fetchWithCache = (key: string) =>
+					Effect.gen(function* () {
+						const cache = yield* CacheService;
+						const cached = yield* cache.get<string>(key);
+						if (Option.isSome(cached)) {
+							return { source: "cache", value: cached.value };
+						}
+						const fetched = `fetched-${key}`;
+						yield* cache.set(key, fetched, 60000);
+						return { source: "fetch", value: fetched };
+					});
+
+				const result = yield* fetchWithCache("test-key");
+				expect(result.source).toBe("fetch");
+				expect(result.value).toBe("fetched-test-key");
+			}).pipe(Effect.provide(NoopCache)),
+		);
+
+		it.effect("always fetches fresh with NoopCache", () =>
+			Effect.gen(function* () {
+				let fetchCount = 0;
+				const fetchWithCache = (key: string) =>
+					Effect.gen(function* () {
+						const cache = yield* CacheService;
+						const cached = yield* cache.get<string>(key);
+						if (Option.isSome(cached)) {
+							return cached.value;
+						}
+						fetchCount++;
+						const value = `value-${fetchCount}`;
+						yield* cache.set(key, value);
+						return value;
+					});
+
+				const r1 = yield* fetchWithCache("key");
+				const r2 = yield* fetchWithCache("key");
+				const r3 = yield* fetchWithCache("key");
+
+				expect([r1, r2, r3]).toEqual(["value-1", "value-2", "value-3"]);
+				expect(fetchCount).toBe(3);
+			}).pipe(Effect.provide(NoopCache)),
+		);
+	});
+});