voltaire-effect 0.2.23

package/src/services/Transport/TransportConfig.test.ts

@@ -0,0 +1,224 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Secret from "effect/Secret";
+import { QuickConfig, TransportConfig } from "./index.js";
+
+describe("TransportConfig", () => {
+	it("parses config from provider", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([
+				["rpc.url", "https://mainnet.infura.io/v3/KEY"],
+				["rpc.timeout", "60 seconds"],
+				["rpc.retryMaxAttempts", "5"],
+				["rpc.retryBaseDelay", "2 seconds"],
+			]),
+		);
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const config = await Effect.runPromise(program);
+		expect(config.url).toBe("https://mainnet.infura.io/v3/KEY");
+		expect(Duration.toMillis(config.timeout)).toBe(60000);
+		expect(config.retryMaxAttempts).toBe(5);
+		expect(Duration.toMillis(config.retryBaseDelay)).toBe(2000);
+	});
+
+	it("uses defaults for optional fields", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([["rpc.url", "https://rpc.example.com"]]),
+		);
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const config = await Effect.runPromise(program);
+		expect(config.url).toBe("https://rpc.example.com");
+		expect(Duration.toMillis(config.timeout)).toBe(30000);
+		expect(config.retryMaxAttempts).toBe(3);
+		expect(Duration.toMillis(config.retryBaseDelay)).toBe(1000);
+	});
+
+	it("validates URL scheme", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([["rpc.url", "ftp://invalid.com"]]),
+		);
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const exit = await Effect.runPromiseExit(program);
+		expect(exit._tag).toBe("Failure");
+	});
+
+	it("accepts http scheme", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([["rpc.url", "http://localhost:8545"]]),
+		);
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const config = await Effect.runPromise(program);
+		expect(config.url).toBe("http://localhost:8545");
+	});
+
+	it("accepts https scheme", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([["rpc.url", "https://mainnet.infura.io"]]),
+		);
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const config = await Effect.runPromise(program);
+		expect(config.url).toBe("https://mainnet.infura.io");
+	});
+
+	it("accepts ws scheme", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([["rpc.url", "ws://localhost:8545"]]),
+		);
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const config = await Effect.runPromise(program);
+		expect(config.url).toBe("ws://localhost:8545");
+	});
+
+	it("accepts wss scheme", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([["rpc.url", "wss://mainnet.infura.io/ws/v3/KEY"]]),
+		);
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const config = await Effect.runPromise(program);
+		expect(config.url).toBe("wss://mainnet.infura.io/ws/v3/KEY");
+	});
+
+	it("handles optional apiKey as Secret", async () => {
+		const configProvider = ConfigProvider.fromMap(
+			new Map([
+				["rpc.url", "https://rpc.example.com"],
+				["rpc.apiKey", "my-secret-key"],
+			]),
+		);
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const config = await Effect.runPromise(program);
+		expect(config.apiKey._tag).toBe("Some");
+		if (config.apiKey._tag === "Some") {
+			expect(Secret.value(config.apiKey.value)).toBe("my-secret-key");
+		}
+	});
+});
+
+describe("QuickConfig", () => {
+	it("creates infura mainnet config", async () => {
+		const configProvider = QuickConfig.infuraMainnet("MY_KEY");
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const config = await Effect.runPromise(program);
+		expect(config.url).toBe("https://mainnet.infura.io/v3/MY_KEY");
+	});
+
+	it("creates alchemy mainnet config", async () => {
+		const configProvider = QuickConfig.alchemyMainnet("MY_KEY");
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const config = await Effect.runPromise(program);
+		expect(config.url).toBe("https://eth-mainnet.g.alchemy.com/v2/MY_KEY");
+	});
+
+	it("creates localhost config", async () => {
+		const configProvider = QuickConfig.localhost();
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const config = await Effect.runPromise(program);
+		expect(config.url).toBe("http://localhost:8545");
+	});
+
+	it("creates localhost config with custom port", async () => {
+		const configProvider = QuickConfig.localhost(9545);
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const config = await Effect.runPromise(program);
+		expect(config.url).toBe("http://localhost:9545");
+	});
+
+	it("creates anvil config", async () => {
+		const configProvider = QuickConfig.anvil();
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const config = await Effect.runPromise(program);
+		expect(config.url).toBe("http://localhost:8545");
+	});
+
+	it("creates hardhat config", async () => {
+		const configProvider = QuickConfig.hardhat();
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const config = await Effect.runPromise(program);
+		expect(config.url).toBe("http://localhost:8545");
+	});
+
+	it("creates ganache config", async () => {
+		const configProvider = QuickConfig.ganache();
+
+		const program = Effect.gen(function* () {
+			const config = yield* TransportConfig;
+			return config;
+		}).pipe(Effect.provide(Layer.setConfigProvider(configProvider)));
+
+		const config = await Effect.runPromise(program);
+		expect(config.url).toBe("http://localhost:7545");
+	});
+});

package/src/services/Transport/TransportConfig.ts

@@ -0,0 +1,285 @@
+/**
+ * @fileoverview Unified Effect.Config for transport configuration.
+ *
+ * @module TransportConfig
+ * @since 0.0.1
+ *
+ * @description
+ * Provides a unified configuration schema for all transport types.
+ * Uses Effect.Config for type-safe environment variable parsing.
+ *
+ * @see {@link HttpTransportConfig} - HTTP-specific configuration
+ * @see {@link WebSocketTransportConfig} - WebSocket-specific configuration
+ */
+
+import * as Config from "effect/Config";
+import type * as ConfigError from "effect/ConfigError";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schedule from "effect/Schedule";
+import * as Secret from "effect/Secret";
+import { HttpTransport } from "./HttpTransport.js";
+import type {
+	RequestInterceptor,
+	ResponseInterceptor,
+} from "./TransportInterceptor.js";
+import type { TransportService } from "./TransportService.js";
+
+/**
+ * Transport configuration schema.
+ *
+ * @description
+ * Unified configuration for transport layer. Reads from environment
+ * variables with sensible defaults.
+ *
+ * Environment variables:
+ * - `RPC_URL` - Required. The JSON-RPC endpoint URL
+ * - `RPC_TIMEOUT` - Optional. Request timeout (default: 30s)
+ * - `RPC_RETRIES` - Optional. Number of retry attempts (default: 3)
+ * - `RPC_RETRY_DELAY` - Optional. Delay between retries (default: 1s)
+ * - `RPC_API_KEY` - Optional. API key (stored as Secret)
+ *
+ * @since 0.0.1
+ *
+ * @example
+ * ```typescript
+ * import { Effect, ConfigProvider, Layer } from 'effect'
+ * import { TransportConfig, TransportFromConfig } from 'voltaire-effect'
+ *
+ * // Read from environment
+ * const program = Effect.gen(function* () {
+ *   const config = yield* TransportConfig
+ *   console.log('URL:', config.url)
+ *   console.log('Timeout:', config.timeout)
+ * })
+ * ```
+ */
+export const TransportConfig = Config.all({
+	url: Config.string("url").pipe(
+		Config.validate({
+			message: "URL must start with http://, https://, ws://, or wss://",
+			validation: (s) =>
+				s.startsWith("http://") ||
+				s.startsWith("https://") ||
+				s.startsWith("ws://") ||
+				s.startsWith("wss://"),
+		}),
+	),
+	timeout: Config.duration("timeout").pipe(
+		Config.withDefault(Duration.seconds(30)),
+	),
+	retryBaseDelay: Config.duration("retryBaseDelay").pipe(
+		Config.withDefault(Duration.seconds(1)),
+	),
+	retryMaxAttempts: Config.integer("retryMaxAttempts").pipe(
+		Config.withDefault(3),
+	),
+	apiKey: Config.secret("apiKey").pipe(Config.option),
+	onRequest: Config.succeed<RequestInterceptor | undefined>(undefined),
+	onResponse: Config.succeed<ResponseInterceptor | undefined>(undefined),
+	fetchOptions: Config.succeed<RequestInit | undefined>(undefined),
+	fetch: Config.succeed<typeof globalThis.fetch | undefined>(undefined),
+}).pipe(Config.nested("rpc"));
+
+/**
+ * Type representing the resolved transport configuration.
+ *
+ * @since 0.0.1
+ */
+export type TransportConfigType = Config.Config.Success<typeof TransportConfig>;
+
+/**
+ * Layer that creates a transport from Effect.Config.
+ *
+ * @description
+ * Reads configuration from the ConfigProvider and creates an appropriate
+ * transport layer. Automatically selects HTTP or WebSocket based on URL scheme.
+ *
+ * @since 0.0.1
+ *
+ * @example Environment variables
+ * ```typescript
+ * import { Effect, Layer, ConfigProvider } from 'effect'
+ * import { FetchHttpClient } from '@effect/platform'
+ * import { TransportFromConfig, TransportService } from 'voltaire-effect'
+ *
+ * // Set: RPC_URL=https://mainnet.infura.io/v3/KEY
+ *
+ * const program = Effect.gen(function* () {
+ *   const transport = yield* TransportService
+ *   return yield* transport.request('eth_blockNumber')
+ * }).pipe(
+ *   Effect.provide(TransportFromConfig),
+ *   Effect.provide(FetchHttpClient.layer),
+ *   Effect.provide(Layer.setConfigProvider(ConfigProvider.fromEnv()))
+ * )
+ * ```
+ *
+ * @example Programmatic config
+ * ```typescript
+ * import { Effect, Layer, ConfigProvider } from 'effect'
+ * import { FetchHttpClient } from '@effect/platform'
+ * import { TransportFromConfig, TransportService } from 'voltaire-effect'
+ *
+ * const configProvider = ConfigProvider.fromMap(new Map([
+ *   ['rpc.url', 'https://mainnet.infura.io/v3/KEY'],
+ *   ['rpc.timeout', '60s'],
+ *   ['rpc.retries', '5'],
+ * ]))
+ *
+ * const program = Effect.gen(function* () {
+ *   const transport = yield* TransportService
+ *   return yield* transport.request('eth_blockNumber')
+ * }).pipe(
+ *   Effect.provide(TransportFromConfig),
+ *   Effect.provide(FetchHttpClient.layer),
+ *   Effect.provide(Layer.setConfigProvider(configProvider))
+ * )
+ * ```
+ */
+export const TransportFromConfig: Layer.Layer<
+	TransportService,
+	ConfigError.ConfigError,
+	import("@effect/platform/HttpClient").HttpClient
+> = Layer.unwrapEffect(
+	Effect.gen(function* () {
+		const config = yield* TransportConfig;
+
+		// Build headers from optional API key
+		const headers: Record<string, string> | undefined = Option.match(
+			config.apiKey,
+			{
+				onNone: () => undefined,
+				onSome: (secret) => ({
+					Authorization: `Bearer ${Secret.value(secret)}`,
+				}),
+			},
+		);
+
+		// Currently only HTTP is supported from config
+		// WebSocket would require a scoped layer
+		if (config.url.startsWith("ws://") || config.url.startsWith("wss://")) {
+			// For WebSocket, return HTTP transport but warn
+			// A proper implementation would use WebSocketTransport
+			// but that requires additional dependencies (Socket.WebSocketConstructor)
+		}
+
+		// Build retry schedule from config: exponential backoff with jitter
+		const retrySchedule = Schedule.exponential(config.retryBaseDelay).pipe(
+			Schedule.jittered,
+			Schedule.intersect(Schedule.recurs(config.retryMaxAttempts)),
+		);
+
+		return HttpTransport({
+			url: config.url,
+			timeout: config.timeout,
+			retrySchedule,
+			headers,
+			onRequest: config.onRequest,
+			onResponse: config.onResponse,
+			fetchOptions: config.fetchOptions,
+			fetch: config.fetch,
+		});
+	}),
+);
+
+/**
+ * Creates a transport from config with FetchHttpClient bundled.
+ *
+ * @description
+ * Convenience layer that combines TransportFromConfig with FetchHttpClient.
+ *
+ * @since 0.0.1
+ */
+export const TransportFromConfigFetch: Layer.Layer<
+	TransportService,
+	ConfigError.ConfigError
+> = Layer.unwrapEffect(
+	Effect.gen(function* () {
+		const config = yield* TransportConfig;
+
+		const headers: Record<string, string> | undefined = Option.match(
+			config.apiKey,
+			{
+				onNone: () => undefined,
+				onSome: (secret) => ({
+					Authorization: `Bearer ${Secret.value(secret)}`,
+				}),
+			},
+		);
+
+		const { FetchHttpClient } = yield* Effect.promise(
+			() => import("@effect/platform"),
+		);
+
+		// Build retry schedule from config: exponential backoff with jitter
+		const retrySchedule = Schedule.exponential(config.retryBaseDelay).pipe(
+			Schedule.jittered,
+			Schedule.intersect(Schedule.recurs(config.retryMaxAttempts)),
+		);
+
+		return Layer.provide(
+			HttpTransport({
+				url: config.url,
+				timeout: config.timeout,
+				retrySchedule,
+				headers,
+				onRequest: config.onRequest,
+				onResponse: config.onResponse,
+				fetchOptions: config.fetchOptions,
+				fetch: config.fetch,
+			}),
+			FetchHttpClient.layer,
+		);
+	}),
+);
+
+/**
+ * Quick configuration for common setups.
+ *
+ * @since 0.0.1
+ */
+export const QuickConfig = {
+	/**
+	 * Create config for mainnet Infura.
+	 */
+	infuraMainnet: (apiKey: string) =>
+		ConfigProvider.fromMap(
+			new Map([["rpc.url", `https://mainnet.infura.io/v3/${apiKey}`]]),
+		),
+
+	/**
+	 * Create config for Alchemy.
+	 */
+	alchemyMainnet: (apiKey: string) =>
+		ConfigProvider.fromMap(
+			new Map([["rpc.url", `https://eth-mainnet.g.alchemy.com/v2/${apiKey}`]]),
+		),
+
+	/**
+	 * Create config for local node.
+	 */
+	localhost: (port = 8545) =>
+		ConfigProvider.fromMap(new Map([["rpc.url", `http://localhost:${port}`]])),
+
+	/**
+	 * Create config for Anvil.
+	 */
+	anvil: () => QuickConfig.localhost(8545),
+
+	/**
+	 * Create config for Hardhat.
+	 */
+	hardhat: () => QuickConfig.localhost(8545),
+
+	/**
+	 * Create config for Ganache.
+	 */
+	ganache: () => QuickConfig.localhost(7545),
+} as const;
+
+// Re-export ConfigProvider for convenience
+import { ConfigProvider } from "effect";
+export { ConfigProvider };

package/src/services/Transport/TransportError.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it } from "@effect/vitest";
+import { TransportError } from "./TransportError.js";
+
+describe("TransportError", () => {
+	describe("constructor", () => {
+		it("creates error with code and message", () => {
+			const error = new TransportError({
+				code: -32603,
+				message: "Internal error",
+			});
+
+			expect(error.code).toBe(-32603);
+			expect(error.message).toBe("Internal error");
+			expect(error.name).toBe("TransportError");
+			expect(error._tag).toBe("TransportError");
+		});
+
+		it("stores data", () => {
+			const errorData = {
+				revertReason: "0x08c379a0...",
+				details: { gas: 21000 },
+			};
+			const error = new TransportError({
+				code: -32000,
+				message: "reverted",
+				data: errorData,
+			});
+
+			expect(error.data).toEqual(errorData);
+		});
+
+		it("stores context object", () => {
+			const context = { method: "eth_call", params: ["0x123"] };
+			const error = new TransportError(
+				{ code: -32603, message: "Error" },
+				undefined,
+				{ context },
+			);
+
+			expect(error.context).toEqual(context);
+		});
+
+		it("stores cause", () => {
+			const originalError = new Error("Original error");
+			const error = new TransportError(
+				{ code: -32603, message: "Wrapped error" },
+				undefined,
+				{ cause: originalError },
+			);
+
+			expect(error.cause).toBe(originalError);
+		});
+	});
+
+	describe("instanceof checks", () => {
+		it("is instanceof Error", () => {
+			const error = new TransportError({ code: -32603, message: "Error" });
+			expect(error instanceof Error).toBe(true);
+		});
+
+		it("is instanceof TransportError", () => {
+			const error = new TransportError({ code: -32603, message: "Error" });
+			expect(error instanceof TransportError).toBe(true);
+		});
+	});
+
+	describe("standard JSON-RPC error codes", () => {
+		it("handles parse error -32700", () => {
+			const error = new TransportError({
+				code: -32700,
+				message: "Parse error",
+			});
+			expect(error.code).toBe(-32700);
+		});
+
+		it("handles invalid request -32600", () => {
+			const error = new TransportError({
+				code: -32600,
+				message: "Invalid Request",
+			});
+			expect(error.code).toBe(-32600);
+		});
+
+		it("handles method not found -32601", () => {
+			const error = new TransportError({
+				code: -32601,
+				message: "Method not found",
+			});
+			expect(error.code).toBe(-32601);
+		});
+
+		it("handles invalid params -32602", () => {
+			const error = new TransportError({
+				code: -32602,
+				message: "Invalid params",
+			});
+			expect(error.code).toBe(-32602);
+		});
+
+		it("handles internal error -32603", () => {
+			const error = new TransportError({
+				code: -32603,
+				message: "Internal error",
+			});
+			expect(error.code).toBe(-32603);
+		});
+
+		it("handles server error range -32000 to -32099", () => {
+			const error32000 = new TransportError({
+				code: -32000,
+				message: "Server error",
+			});
+			const error32099 = new TransportError({
+				code: -32099,
+				message: "Server error",
+			});
+			expect(error32000.code).toBe(-32000);
+			expect(error32099.code).toBe(-32099);
+		});
+	});
+
+	describe("stack trace", () => {
+		it("has stack trace", () => {
+			const error = new TransportError({ code: -32603, message: "Error" });
+			expect(error.stack).toBeDefined();
+			expect(error.stack).toContain("TransportError");
+		});
+	});
+
+	describe("edge cases", () => {
+		it("handles empty message", () => {
+			const error = new TransportError({ code: -32603, message: "" });
+			expect(error.message).toBe("");
+		});
+
+		it("handles undefined data", () => {
+			const error = new TransportError({ code: -32603, message: "Error" });
+			expect(error.data).toBeUndefined();
+		});
+
+		it("handles null data", () => {
+			const error = new TransportError({
+				code: -32603,
+				message: "Error",
+				data: null,
+			});
+			expect(error.data).toBeNull();
+		});
+
+		it("handles complex nested data", () => {
+			const nestedData = {
+				level1: {
+					level2: {
+						array: [1, 2, { nested: true }],
+					},
+				},
+			};
+			const error = new TransportError({
+				code: -32603,
+				message: "Error",
+				data: nestedData,
+			});
+			expect(error.data).toEqual(nestedData);
+		});
+	});
+});