voltaire-effect 0.2.23

package/src/services/BlockStream/BlockStream.ts

@@ -0,0 +1,125 @@
+/**
+ * @fileoverview Live implementation of BlockStreamService.
+ *
+ * @module BlockStream
+ * @since 0.2.12
+ *
+ * @description
+ * Provides the live implementation layer for BlockStreamService.
+ * Creates an EIP-1193 provider from TransportService and wraps core BlockStream.
+ */
+
+import {
+	type BackfillOptions,
+	type BlockInclude,
+	type BlockStreamEvent,
+	type BlocksEvent,
+	BlockStream as CoreBlockStream,
+	type WatchOptions,
+} from "@tevm/voltaire/block";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Runtime from "effect/Runtime";
+import * as Stream from "effect/Stream";
+import { TransportService } from "../Transport/TransportService.js";
+import { BlockStreamError } from "./BlockStreamError.js";
+import {
+	BlockStreamService,
+	type BlockStreamShape,
+} from "./BlockStreamService.js";
+
+/**
+ * Wraps an AsyncGenerator as an Effect Stream with cleanup on interruption.
+ */
+const fromAsyncGeneratorWithCleanup = <T>(
+	makeGenerator: () => AsyncGenerator<T>,
+	cleanup: () => void,
+): Stream.Stream<T, BlockStreamError> =>
+	Stream.acquireRelease(
+		Effect.sync(() => makeGenerator()),
+		() => Effect.sync(cleanup),
+	).pipe(
+		Stream.flatMap((generator) =>
+			Stream.fromAsyncIterable(
+				{ [Symbol.asyncIterator]: () => generator },
+				(error) =>
+					new BlockStreamError(
+						error instanceof Error ? error.message : "BlockStream error",
+						{ cause: error instanceof Error ? error : undefined },
+					),
+			),
+		),
+	);
+
+/**
+ * Build a BlockStream directly from TransportService without a service layer.
+ */
+export const makeBlockStream = (): Effect.Effect<
+	BlockStreamShape,
+	never,
+	TransportService
+> =>
+	Effect.gen(function* () {
+		const transport = yield* TransportService;
+		const runtime = yield* Effect.runtime<never>();
+
+		const provider = {
+			request: async ({
+				method,
+				params,
+			}: {
+				method: string;
+				params?: unknown[];
+			}) => Runtime.runPromise(runtime)(transport.request(method, params)),
+			on: () => {},
+			removeListener: () => {},
+		};
+
+		const coreStream = CoreBlockStream({ provider: provider as any });
+
+		const cleanup = () => {
+			(coreStream as unknown as { destroy?: () => void }).destroy?.();
+		};
+
+		return {
+			backfill: <TInclude extends BlockInclude = "header">(
+				options: BackfillOptions<TInclude>,
+			): Stream.Stream<BlocksEvent<TInclude>, BlockStreamError> =>
+				fromAsyncGeneratorWithCleanup(
+					() => coreStream.backfill(options),
+					cleanup,
+				),
+
+			watch: <TInclude extends BlockInclude = "header">(
+				options?: WatchOptions<TInclude>,
+			): Stream.Stream<BlockStreamEvent<TInclude>, BlockStreamError> =>
+				fromAsyncGeneratorWithCleanup(() => coreStream.watch(options), cleanup),
+		};
+	});
+
+/**
+ * Live implementation of BlockStreamService.
+ *
+ * @since 0.2.12
+ *
+ * @example
+ * ```typescript
+ * import { Effect, Stream } from 'effect';
+ * import { makeBlockStream, HttpTransport } from 'voltaire-effect/services';
+ *
+ * const program = Effect.gen(function* () {
+ *   const blockStream = yield* makeBlockStream();
+ *   yield* Stream.runForEach(
+ *     blockStream.watch(),
+ *     (event) => Effect.log(`Event: ${event.type}`)
+ *   );
+ * }).pipe(
+ *   Effect.provide(HttpTransport('https://...'))
+ * );
+ * ```
+ */
+export const BlockStream: Layer.Layer<
+	BlockStreamService,
+	never,
+	TransportService
+> = Layer.effect(BlockStreamService, makeBlockStream());

package/src/services/BlockStream/BlockStreamError.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview BlockStream error type for voltaire-effect.
+ *
+ * @module BlockStreamError
+ * @since 0.2.12
+ */
+
+import * as Data from "effect/Data";
+
+/**
+ * Error thrown when a BlockStream operation fails.
+ *
+ * @since 0.2.12
+ */
+export class BlockStreamError extends Data.TaggedError("BlockStreamError")<{
+	readonly message: string;
+	readonly cause?: unknown;
+	readonly context?: Record<string, unknown>;
+}> {
+	constructor(
+		message: string,
+		options?: {
+			cause?: unknown;
+			context?: Record<string, unknown>;
+		},
+	) {
+		super({
+			message,
+			cause: options?.cause,
+			context: options?.context,
+		});
+	}
+}

package/src/services/BlockStream/BlockStreamService.ts

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview BlockStream service definition for Effect-native block streaming.
+ *
+ * @module BlockStreamService
+ * @since 0.2.12
+ *
+ * @description
+ * Provides Effect Stream integration for watching blocks with reorg support.
+ * Wraps voltaire core's BlockStream for fiber-safe, composable block streaming.
+ *
+ * @see {@link BlockStream} - The live implementation layer
+ * @see {@link TransportService} - Required dependency
+ */
+
+import type {
+	BackfillOptions,
+	BlockInclude,
+	BlockStreamEvent,
+	BlocksEvent,
+	WatchOptions,
+} from "@tevm/voltaire/block";
+import * as Context from "effect/Context";
+import type * as Stream from "effect/Stream";
+import type { BlockStreamError } from "./BlockStreamError.js";
+
+/**
+ * Shape of the BlockStream service.
+ *
+ * @since 0.2.12
+ */
+export type BlockStreamShape = {
+	/**
+	 * Backfill historical blocks within a range.
+	 *
+	 * @example
+	 * ```typescript
+	 * const program = Effect.gen(function* () {
+	 *   const stream = yield* BlockStreamService;
+	 *   yield* Stream.runForEach(
+	 *     stream.backfill({ fromBlock: 18000000n, toBlock: 18000100n }),
+	 *     (event) => Effect.log(`Got ${event.blocks.length} blocks`)
+	 *   );
+	 * });
+	 * ```
+	 */
+	readonly backfill: <TInclude extends BlockInclude = "header">(
+		options: BackfillOptions<TInclude>,
+	) => Stream.Stream<BlocksEvent<TInclude>, BlockStreamError>;
+
+	/**
+	 * Watch for new blocks with reorg detection.
+	 *
+	 * @example
+	 * ```typescript
+	 * const program = Effect.gen(function* () {
+	 *   const stream = yield* BlockStreamService;
+	 *   yield* Stream.runForEach(
+	 *     stream.watch({ include: 'transactions' }),
+	 *     (event) => {
+	 *       if (event.type === 'reorg') {
+	 *         return Effect.log(`Reorg: ${event.removed.length} blocks removed`);
+	 *       }
+	 *       return Effect.log(`New block: ${event.blocks[0]?.header.number}`);
+	 *     }
+	 *   );
+	 * });
+	 * ```
+	 */
+	readonly watch: <TInclude extends BlockInclude = "header">(
+		options?: WatchOptions<TInclude>,
+	) => Stream.Stream<BlockStreamEvent<TInclude>, BlockStreamError>;
+};
+
+/**
+ * BlockStream service for Effect-native block streaming.
+ *
+ * @since 0.2.12
+ *
+ * @example
+ * ```typescript
+ * import { Effect, Stream } from 'effect';
+ * import { BlockStreamService, BlockStream, HttpTransport } from 'voltaire-effect';
+ *
+ * const program = Effect.gen(function* () {
+ *   const blockStream = yield* BlockStreamService;
+ *
+ *   yield* Stream.runForEach(
+ *     blockStream.watch({ include: 'receipts' }),
+ *     (event) => {
+ *       if (event.type === 'reorg') {
+ *         return Effect.log(`Reorg detected`);
+ *       }
+ *       return Effect.log(`Block ${event.blocks[0]?.header.number}`);
+ *     }
+ *   );
+ * }).pipe(
+ *   Effect.provide(BlockStream),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * );
+ * ```
+ */
+export class BlockStreamService extends Context.Tag("BlockStreamService")<
+	BlockStreamService,
+	BlockStreamShape
+>() {}

package/src/services/BlockStream/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview BlockStream module exports for Effect-native block streaming.
+ *
+ * @module BlockStream
+ * @since 0.2.12
+ *
+ * @description
+ * Effect wrapper for voltaire core's BlockStream with reorg support.
+ *
+ * @example
+ * ```typescript
+ * import { Effect, Stream } from 'effect';
+ * import { makeBlockStream, HttpTransport } from 'voltaire-effect/services';
+ *
+ * const program = Effect.gen(function* () {
+ *   const stream = yield* makeBlockStream();
+ *   yield* Stream.runForEach(
+ *     stream.watch({ include: 'transactions' }),
+ *     (event) => Effect.log(`Event: ${event.type}`)
+ *   );
+ * }).pipe(
+ *   Effect.provide(HttpTransport('https://...'))
+ * );
+ * ```
+ */
+
+export { BlockStream, makeBlockStream } from "./BlockStream.js";
+export { BlockStreamError } from "./BlockStreamError.js";
+export {
+	BlockStreamService,
+	type BlockStreamShape,
+} from "./BlockStreamService.js";

package/src/services/Cache/CacheService.ts

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview Cache service definition for key-value caching operations.
+ *
+ * @module CacheService
+ * @since 0.0.1
+ *
+ * @description
+ * The CacheService provides a generic interface for caching values with optional TTL.
+ * It abstracts away the underlying cache implementation, allowing for different
+ * backends (in-memory, Redis, etc.) to be swapped transparently.
+ *
+ * @see {@link MemoryCache} - In-memory LRU cache implementation
+ * @see {@link NoopCache} - No-op implementation for testing/disabling cache
+ */
+
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Option from "effect/Option";
+
+/**
+ * Shape of the cache service.
+ *
+ * @description
+ * Defines all caching operations available through CacheService.
+ * The cache is generic and can store any serializable value type.
+ *
+ * @since 0.0.1
+ */
+export type CacheShape = {
+	/**
+	 * Gets a value from the cache by key.
+	 *
+	 * @param key - The cache key to look up
+	 * @returns Option.some(value) if found and not expired, Option.none() otherwise
+	 */
+	readonly get: <T>(key: string) => Effect.Effect<Option.Option<T>>;
+
+	/**
+	 * Sets a value in the cache.
+	 *
+	 * @param key - The cache key
+	 * @param value - The value to cache
+	 * @param ttlMs - Optional time-to-live in milliseconds (undefined = no expiration)
+	 */
+	readonly set: <T>(
+		key: string,
+		value: T,
+		ttlMs?: number,
+	) => Effect.Effect<void>;
+
+	/**
+	 * Deletes a value from the cache.
+	 *
+	 * @param key - The cache key to delete
+	 * @returns true if the key existed and was deleted, false otherwise
+	 */
+	readonly delete: (key: string) => Effect.Effect<boolean>;
+
+	/**
+	 * Clears all values from the cache.
+	 */
+	readonly clear: () => Effect.Effect<void>;
+};
+
+/**
+ * Cache service for key-value caching with optional TTL.
+ *
+ * @description
+ * Provides methods for getting, setting, and deleting cached values.
+ * This is an Effect Context.Tag that must be provided with a concrete
+ * implementation (MemoryCache, NoopCache, etc.) before running.
+ *
+ * @since 0.0.1
+ *
+ * @example Basic usage with MemoryCache
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { CacheService, MemoryCache } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const cache = yield* CacheService
+ *
+ *   // Set a value with 5 minute TTL
+ *   yield* cache.set('user:123', { name: 'Alice' }, 5 * 60 * 1000)
+ *
+ *   // Get the value back
+ *   const user = yield* cache.get('user:123')
+ *
+ *   return user
+ * }).pipe(
+ *   Effect.provide(MemoryCache({ maxSize: 1000 }))
+ * )
+ * ```
+ *
+ * @see {@link MemoryCache} - In-memory LRU cache implementation
+ * @see {@link NoopCache} - No-op implementation for testing/disabling cache
+ * @see {@link CacheShape} - The service interface shape
+ */
+export class CacheService extends Context.Tag("CacheService")<
+	CacheService,
+	CacheShape
+>() {}

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

@@ -0,0 +1,305 @@
+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 Ref from "effect/Ref";
+import * as TestClock from "effect/TestClock";
+import { LookupCacheService, makeLookupCache } from "./LookupCacheService.js";
+
+const StringCache = LookupCacheService<string, string, never>();
+
+describe("LookupCacheService", () => {
+	describe("basic operations", () => {
+		it.effect("computes value on cache miss", () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+
+				const layer = makeLookupCache(StringCache, {
+					capacity: 100,
+					timeToLive: Duration.minutes(5),
+					lookup: (key) =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							return `value-for-${key}`;
+						}),
+				});
+
+				const result = yield* Effect.gen(function* () {
+					const cache = yield* StringCache;
+					return yield* cache.get("key1");
+				}).pipe(Effect.provide(layer));
+
+				const count = yield* Ref.get(callCount);
+
+				expect(result).toBe("value-for-key1");
+				expect(count).toBe(1);
+			}),
+		);
+
+		it.effect("returns cached value on subsequent calls", () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+
+				const layer = makeLookupCache(StringCache, {
+					capacity: 100,
+					timeToLive: Duration.minutes(5),
+					lookup: (key) =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							return `value-for-${key}`;
+						}),
+				});
+
+				const program = Effect.gen(function* () {
+					const cache = yield* StringCache;
+					const r1 = yield* cache.get("key1");
+					const r2 = yield* cache.get("key1");
+					return [r1, r2] as const;
+				}).pipe(Effect.provide(layer));
+
+				const [r1, r2] = yield* program;
+				const count = yield* Ref.get(callCount);
+
+				expect(r1).toBe("value-for-key1");
+				expect(r2).toBe("value-for-key1");
+				expect(count).toBe(1);
+			}),
+		);
+
+		it.effect("getOption returns none for uncached key", () =>
+			Effect.gen(function* () {
+				const layer = makeLookupCache(StringCache, {
+					capacity: 100,
+					timeToLive: Duration.minutes(5),
+					lookup: (key) => Effect.succeed(`value-for-${key}`),
+				});
+
+				const result = yield* Effect.gen(function* () {
+					const cache = yield* StringCache;
+					return yield* cache.getOption("key1");
+				}).pipe(Effect.provide(layer));
+
+				expect(Option.isNone(result)).toBe(true);
+			}),
+		);
+
+		it.effect("getOption returns some for cached key", () =>
+			Effect.gen(function* () {
+				const layer = makeLookupCache(StringCache, {
+					capacity: 100,
+					timeToLive: Duration.minutes(5),
+					lookup: (key) => Effect.succeed(`value-for-${key}`),
+				});
+
+				const result = yield* Effect.gen(function* () {
+					const cache = yield* StringCache;
+					yield* cache.get("key1");
+					return yield* cache.getOption("key1");
+				}).pipe(Effect.provide(layer));
+
+				expect(Option.isSome(result)).toBe(true);
+				expect(Option.getOrThrow(result)).toBe("value-for-key1");
+			}),
+		);
+
+		it.effect("set manually stores a value", () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+
+				const layer = makeLookupCache(StringCache, {
+					capacity: 100,
+					timeToLive: Duration.minutes(5),
+					lookup: (key) =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							return `computed-${key}`;
+						}),
+				});
+
+				const result = yield* Effect.gen(function* () {
+					const cache = yield* StringCache;
+					yield* cache.set("key1", "manual-value");
+					return yield* cache.get("key1");
+				}).pipe(Effect.provide(layer));
+
+				const count = yield* Ref.get(callCount);
+
+				expect(result).toBe("manual-value");
+				expect(count).toBe(0);
+			}),
+		);
+	});
+
+	describe("invalidation", () => {
+		it.effect("invalidate removes a key", () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+
+				const layer = makeLookupCache(StringCache, {
+					capacity: 100,
+					timeToLive: Duration.minutes(5),
+					lookup: (_key) =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							return `value-${yield* Ref.get(callCount)}`;
+						}),
+				});
+
+				const program = Effect.gen(function* () {
+					const cache = yield* StringCache;
+					const r1 = yield* cache.get("key1");
+					yield* cache.invalidate("key1");
+					const r2 = yield* cache.get("key1");
+					return [r1, r2] as const;
+				}).pipe(Effect.provide(layer));
+
+				const [r1, r2] = yield* program;
+				const count = yield* Ref.get(callCount);
+
+				expect(r1).toBe("value-1");
+				expect(r2).toBe("value-2");
+				expect(count).toBe(2);
+			}),
+		);
+
+		it.effect("invalidateAll clears all keys", () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+
+				const layer = makeLookupCache(StringCache, {
+					capacity: 100,
+					timeToLive: Duration.minutes(5),
+					lookup: () =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							return `value-${yield* Ref.get(callCount)}`;
+						}),
+				});
+
+				const program = Effect.gen(function* () {
+					const cache = yield* StringCache;
+					yield* cache.get("key1");
+					yield* cache.get("key2");
+					yield* cache.invalidateAll;
+					const r1 = yield* cache.get("key1");
+					const r2 = yield* cache.get("key2");
+					return [r1, r2] as const;
+				}).pipe(Effect.provide(layer));
+
+				const [r1, r2] = yield* program;
+				const count = yield* Ref.get(callCount);
+
+				expect(r1).toBe("value-3");
+				expect(r2).toBe("value-4");
+				expect(count).toBe(4);
+			}),
+		);
+	});
+
+	describe("refresh", () => {
+		it.effect("refresh recomputes value", () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+
+				const layer = makeLookupCache(StringCache, {
+					capacity: 100,
+					timeToLive: Duration.minutes(5),
+					lookup: () =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							return `value-${yield* Ref.get(callCount)}`;
+						}),
+				});
+
+				const program = Effect.gen(function* () {
+					const cache = yield* StringCache;
+					const r1 = yield* cache.get("key1");
+					yield* cache.refresh("key1");
+					const r2 = yield* cache.get("key1");
+					return [r1, r2] as const;
+				}).pipe(Effect.provide(layer));
+
+				const [r1, r2] = yield* program;
+
+				expect(r1).toBe("value-1");
+				expect(r2).toBe("value-2");
+			}),
+		);
+	});
+
+	describe("stats", () => {
+		it.effect("returns cache statistics", () =>
+			Effect.gen(function* () {
+				const layer = makeLookupCache(StringCache, {
+					capacity: 100,
+					timeToLive: Duration.minutes(5),
+					lookup: (key) => Effect.succeed(`value-for-${key}`),
+				});
+
+				const stats = yield* Effect.gen(function* () {
+					const cache = yield* StringCache;
+					yield* cache.get("key1");
+					yield* cache.get("key1");
+					yield* cache.get("key2");
+					return yield* cache.stats;
+				}).pipe(Effect.provide(layer));
+
+				expect(stats.size).toBe(2);
+				expect(stats.hits).toBeGreaterThanOrEqual(1);
+			}),
+		);
+
+		it.effect("returns cache size", () =>
+			Effect.gen(function* () {
+				const layer = makeLookupCache(StringCache, {
+					capacity: 100,
+					timeToLive: Duration.minutes(5),
+					lookup: (key) => Effect.succeed(`value-for-${key}`),
+				});
+
+				const size = yield* Effect.gen(function* () {
+					const cache = yield* StringCache;
+					yield* cache.get("key1");
+					yield* cache.get("key2");
+					yield* cache.get("key3");
+					return yield* cache.size;
+				}).pipe(Effect.provide(layer));
+
+				expect(size).toBe(3);
+			}),
+		);
+	});
+
+	describe("TTL expiration", () => {
+		it.effect("expires entries after TTL", () =>
+			Effect.gen(function* () {
+				const callCount = yield* Ref.make(0);
+
+				const layer = makeLookupCache(StringCache, {
+					capacity: 100,
+					timeToLive: Duration.seconds(1),
+					lookup: () =>
+						Effect.gen(function* () {
+							yield* Ref.update(callCount, (n) => n + 1);
+							return `value-${yield* Ref.get(callCount)}`;
+						}),
+				});
+
+				const program = Effect.gen(function* () {
+					const cache = yield* StringCache;
+					const r1 = yield* cache.get("key1");
+					yield* TestClock.adjust(Duration.seconds(2));
+					const r2 = yield* cache.get("key1");
+					return [r1, r2] as const;
+				}).pipe(Effect.provide(layer));
+
+				const [r1, r2] = yield* program;
+				const count = yield* Ref.get(callCount);
+
+				expect(r1).toBe("value-1");
+				expect(r2).toBe("value-2");
+				expect(count).toBe(2);
+			}),
+		);
+	});
+});