voltaire-effect 0.2.23

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

@@ -0,0 +1,331 @@
+import { afterEach, describe, expect, it, vi } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import {
+	CustomTransport,
+	CustomTransportFromFn,
+	TransportError,
+	TransportService,
+} from "./index.js";
+
+describe("CustomTransport", () => {
+	const originalWindow = globalThis.window;
+
+	afterEach(() => {
+		(
+			globalThis as unknown as {
+				window?: typeof window;
+			}
+		).window = originalWindow;
+	});
+
+	it("wraps an EIP-1193 provider", async () => {
+		const mockProvider = {
+			request: vi.fn().mockResolvedValue("0x123"),
+		};
+
+		const program = Effect.gen(function* () {
+			const transport = yield* TransportService;
+			return yield* transport.request<string>("eth_blockNumber", []);
+		}).pipe(Effect.provide(CustomTransport({ provider: mockProvider })));
+
+		const result = await Effect.runPromise(program);
+		expect(result).toBe("0x123");
+		expect(mockProvider.request).toHaveBeenCalledWith({
+			method: "eth_blockNumber",
+			params: [],
+		});
+	});
+
+	it("accepts provider directly without config wrapper", async () => {
+		const mockProvider = {
+			request: vi.fn().mockResolvedValue("0x456"),
+		};
+
+		const program = Effect.gen(function* () {
+			const transport = yield* TransportService;
+			return yield* transport.request<string>("eth_chainId", []);
+		}).pipe(Effect.provide(CustomTransport(mockProvider)));
+
+		const result = await Effect.runPromise(program);
+		expect(result).toBe("0x456");
+	});
+
+	it("uses injected window.ethereum when provider omitted", async () => {
+		const mockProvider = {
+			request: vi.fn().mockResolvedValue("0x789"),
+		};
+		(
+			globalThis as unknown as {
+				window: { ethereum: { request: typeof mockProvider.request } };
+			}
+		).window = {
+			ethereum: mockProvider,
+		};
+
+		const program = Effect.gen(function* () {
+			const transport = yield* TransportService;
+			return yield* transport.request<string>("eth_chainId", []);
+		}).pipe(Effect.provide(CustomTransport()));
+
+		const result = await Effect.runPromise(program);
+		expect(result).toBe("0x789");
+		expect(mockProvider.request).toHaveBeenCalledWith({
+			method: "eth_chainId",
+			params: [],
+		});
+	});
+
+	it("prefers injected providers array when available", async () => {
+		const primaryProvider = {
+			request: vi.fn().mockResolvedValue("0x1"),
+		};
+		const secondaryProvider = {
+			request: vi.fn().mockResolvedValue("0x2"),
+		};
+		const aggregateRequest = vi.fn();
+		(
+			globalThis as unknown as {
+				window: {
+					ethereum: {
+						request: typeof aggregateRequest;
+						providers: Array<typeof primaryProvider>;
+					};
+				};
+			}
+		).window = {
+			ethereum: {
+				request: aggregateRequest,
+				providers: [primaryProvider, secondaryProvider],
+			},
+		};
+
+		const program = Effect.gen(function* () {
+			const transport = yield* TransportService;
+			return yield* transport.request<string>("eth_chainId", []);
+		}).pipe(Effect.provide(CustomTransport()));
+
+		const result = await Effect.runPromise(program);
+		expect(result).toBe("0x1");
+		expect(primaryProvider.request).toHaveBeenCalledWith({
+			method: "eth_chainId",
+			params: [],
+		});
+		expect(aggregateRequest).not.toHaveBeenCalled();
+		expect(secondaryProvider.request).not.toHaveBeenCalled();
+	});
+
+	it("handles provider errors with code and message", async () => {
+		const mockProvider = {
+			request: vi.fn().mockRejectedValue({
+				code: 4001,
+				message: "User rejected",
+			}),
+		};
+
+		const program = Effect.gen(function* () {
+			const transport = yield* TransportService;
+			return yield* transport.request<string>("eth_requestAccounts", []);
+		}).pipe(Effect.provide(CustomTransport({ provider: mockProvider })));
+
+		const exit = await Effect.runPromiseExit(program);
+		expect(exit._tag).toBe("Failure");
+		if (exit._tag === "Failure" && exit.cause._tag === "Fail") {
+			const error = exit.cause.error as TransportError;
+			expect(error.code).toBe(4001);
+			expect(error.message).toBe("User rejected");
+		}
+	});
+
+	it("fills default message for EIP-1193 errors without message", async () => {
+		const mockProvider = {
+			request: vi.fn().mockRejectedValue({
+				code: 4100,
+			}),
+		};
+
+		const program = Effect.gen(function* () {
+			const transport = yield* TransportService;
+			return yield* transport.request<string>("eth_requestAccounts", []);
+		}).pipe(Effect.provide(CustomTransport({ provider: mockProvider })));
+
+		const exit = await Effect.runPromiseExit(program);
+		expect(exit._tag).toBe("Failure");
+		if (exit._tag === "Failure" && exit.cause._tag === "Fail") {
+			const error = exit.cause.error as TransportError;
+			expect(error.code).toBe(4100);
+			expect(error.message).toBe("Unauthorized");
+		}
+	});
+
+	it("handles generic errors", async () => {
+		const mockProvider = {
+			request: vi.fn().mockRejectedValue(new Error("Network error")),
+		};
+
+		const program = Effect.gen(function* () {
+			const transport = yield* TransportService;
+			return yield* transport.request<string>("eth_blockNumber", []);
+		}).pipe(Effect.provide(CustomTransport({ provider: mockProvider })));
+
+		const exit = await Effect.runPromiseExit(program);
+		expect(exit._tag).toBe("Failure");
+		if (exit._tag === "Failure" && exit.cause._tag === "Fail") {
+			const error = exit.cause.error as TransportError;
+			expect(error.message).toContain("Network error");
+		}
+	});
+
+	it("calls onRequest interceptor", async () => {
+		const onRequest = vi.fn();
+		const mockProvider = {
+			request: vi.fn().mockResolvedValue("0x1"),
+		};
+
+		const program = Effect.gen(function* () {
+			const transport = yield* TransportService;
+			return yield* transport.request<string>("eth_blockNumber", []);
+		}).pipe(
+			Effect.provide(
+				CustomTransport({
+					provider: mockProvider,
+					onRequest,
+				}),
+			),
+		);
+
+		await Effect.runPromise(program);
+		expect(onRequest).toHaveBeenCalledWith("eth_blockNumber", []);
+	});
+
+	it("calls onResponse interceptor", async () => {
+		const onResponse = vi.fn();
+		const mockProvider = {
+			request: vi.fn().mockResolvedValue("0x100"),
+		};
+
+		const program = Effect.gen(function* () {
+			const transport = yield* TransportService;
+			return yield* transport.request<string>("eth_blockNumber", []);
+		}).pipe(
+			Effect.provide(
+				CustomTransport({
+					provider: mockProvider,
+					onResponse,
+				}),
+			),
+		);
+
+		await Effect.runPromise(program);
+		expect(onResponse).toHaveBeenCalledWith("eth_blockNumber", "0x100");
+	});
+
+	it("calls onError interceptor", async () => {
+		const onError = vi.fn();
+		const mockProvider = {
+			request: vi.fn().mockRejectedValue({
+				code: -32603,
+				message: "Internal error",
+			}),
+		};
+
+		const program = Effect.gen(function* () {
+			const transport = yield* TransportService;
+			return yield* transport.request<string>("eth_call", []);
+		}).pipe(
+			Effect.provide(
+				CustomTransport({
+					provider: mockProvider,
+					onError,
+				}),
+			),
+		);
+
+		await Effect.runPromiseExit(program);
+		expect(onError).toHaveBeenCalled();
+		const [method, error] = onError.mock.calls[0];
+		expect(method).toBe("eth_call");
+		expect(error).toBeInstanceOf(TransportError);
+	});
+
+	it("handles request timeout", async () => {
+		const mockProvider = {
+			request: vi.fn().mockImplementation(() => new Promise(() => {})),
+		};
+
+		const program = Effect.gen(function* () {
+			const transport = yield* TransportService;
+			return yield* transport.request<string>("eth_blockNumber", []);
+		}).pipe(
+			Effect.provide(
+				CustomTransport({
+					provider: mockProvider,
+					timeout: 50,
+				}),
+			),
+		);
+
+		const exit = await Effect.runPromiseExit(program);
+		expect(exit._tag).toBe("Failure");
+		if (exit._tag === "Failure" && exit.cause._tag === "Fail") {
+			const error = exit.cause.error as TransportError;
+			expect(error.message).toContain("timeout");
+		}
+	});
+
+	it("preserves error data field", async () => {
+		const mockProvider = {
+			request: vi.fn().mockRejectedValue({
+				code: -32000,
+				message: "execution reverted",
+				data: "0x08c379a0...",
+			}),
+		};
+
+		const program = Effect.gen(function* () {
+			const transport = yield* TransportService;
+			return yield* transport.request<string>("eth_call", []);
+		}).pipe(Effect.provide(CustomTransport({ provider: mockProvider })));
+
+		const exit = await Effect.runPromiseExit(program);
+		expect(exit._tag).toBe("Failure");
+		if (exit._tag === "Failure" && exit.cause._tag === "Fail") {
+			const error = exit.cause.error as TransportError;
+			expect(error.data).toBe("0x08c379a0...");
+		}
+	});
+});
+
+describe("CustomTransportFromFn", () => {
+	it("creates transport from request function", async () => {
+		const requestFn = vi.fn().mockResolvedValue("0x999");
+
+		const program = Effect.gen(function* () {
+			const transport = yield* TransportService;
+			return yield* transport.request<string>("eth_blockNumber", []);
+		}).pipe(Effect.provide(CustomTransportFromFn(requestFn)));
+
+		const result = await Effect.runPromise(program);
+		expect(result).toBe("0x999");
+		expect(requestFn).toHaveBeenCalledWith({
+			method: "eth_blockNumber",
+			params: [],
+		});
+	});
+
+	it("passes options through", async () => {
+		const onRequest = vi.fn();
+		const requestFn = vi.fn().mockResolvedValue("0x1");
+
+		const program = Effect.gen(function* () {
+			const transport = yield* TransportService;
+			return yield* transport.request<string>("eth_chainId", []);
+		}).pipe(
+			Effect.provide(
+				CustomTransportFromFn(requestFn, { onRequest, timeout: 60000 }),
+			),
+		);
+
+		await Effect.runPromise(program);
+		expect(onRequest).toHaveBeenCalledWith("eth_chainId", []);
+	});
+});

package/src/services/Transport/CustomTransport.ts

@@ -0,0 +1,355 @@
+/**
+ * @fileoverview Custom transport for wrapping EIP-1193 providers.
+ *
+ * @module CustomTransport
+ * @since 0.0.1
+ *
+ * @description
+ * Provides a transport layer that wraps any EIP-1193 compatible provider.
+ * This allows using existing providers (ethers, web3.js, custom) with the
+ * Effect-based transport system.
+ *
+ * Features:
+ * - Wraps any EIP-1193 provider
+ * - Proper error conversion
+ * - Request/response interceptors
+ * - Optional request timeout
+ *
+ * Use CustomTransport when:
+ * - Integrating with existing provider instances
+ * - Need custom provider behavior
+ * - Wrapping third-party provider libraries
+ *
+ * @see {@link TransportService} - The service interface this implements
+ * @see {@link BrowserTransport} - For window.ethereum specifically
+ * @see {@link HttpTransport} - For HTTP-based JSON-RPC
+ */
+
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FiberRef from "effect/FiberRef";
+import * as Layer from "effect/Layer";
+import { timeoutRef, tracingRef } from "./config.js";
+import { TransportError } from "./TransportError.js";
+import { TransportService } from "./TransportService.js";
+
+/**
+ * EIP-1193 compatible Ethereum provider interface.
+ *
+ * @description
+ * Standard interface for Ethereum providers as defined in EIP-1193.
+ * All compliant providers (MetaMask, ethers, web3.js, etc.) implement this.
+ *
+ * @since 0.0.1
+ * @see https://eips.ethereum.org/EIPS/eip-1193
+ */
+export interface EIP1193Provider {
+	/**
+	 * Sends a JSON-RPC request to the provider.
+	 * @param args - Request arguments with method and optional params
+	 * @returns Promise resolving to the RPC result
+	 */
+	request: (args: {
+		method: string;
+		params?: readonly unknown[] | object;
+	}) => Promise<unknown>;
+}
+
+/**
+ * Configuration options for custom transport.
+ *
+ * @since 0.0.1
+ */
+export interface CustomTransportConfig {
+	/**
+	 * The EIP-1193 provider to wrap.
+	 * If omitted, CustomTransport will attempt to use an injected provider
+	 * (window.ethereum or globalThis.ethereum).
+	 */
+	provider?: EIP1193Provider;
+	/** Request timeout in milliseconds (default: 30000) */
+	timeout?: number;
+	/** Optional request interceptor */
+	onRequest?: (method: string, params: unknown[]) => void | Promise<void>;
+	/** Optional response interceptor */
+	onResponse?: (method: string, result: unknown) => void | Promise<void>;
+	/** Optional error interceptor */
+	onError?: (method: string, error: TransportError) => void | Promise<void>;
+}
+
+type InjectedEthereumProvider = EIP1193Provider & {
+	providers?: readonly EIP1193Provider[];
+};
+
+const isEip1193Provider = (value: unknown): value is EIP1193Provider =>
+	!!value &&
+	typeof value === "object" &&
+	"request" in value &&
+	typeof (value as { request: unknown }).request === "function";
+
+const EIP1193_ERROR_MESSAGES: Record<number, string> = {
+	4001: "User rejected the request",
+	4100: "Unauthorized",
+	4200: "Unsupported method",
+	4900: "Disconnected",
+	4901: "Chain disconnected",
+};
+
+const resolveInjectedProvider = (): EIP1193Provider | undefined => {
+	if (typeof window !== "undefined" && window.ethereum) {
+		const ethereum = window.ethereum as InjectedEthereumProvider;
+		if (Array.isArray(ethereum.providers) && ethereum.providers.length > 0) {
+			const provider = ethereum.providers.find(isEip1193Provider);
+			if (provider) return provider;
+		}
+		if (isEip1193Provider(ethereum)) return ethereum;
+	}
+
+	const globalEthereum = (globalThis as { ethereum?: InjectedEthereumProvider })
+		.ethereum;
+	if (globalEthereum) {
+		if (
+			Array.isArray(globalEthereum.providers) &&
+			globalEthereum.providers.length > 0
+		) {
+			const provider = globalEthereum.providers.find(isEip1193Provider);
+			if (provider) return provider;
+		}
+		if (isEip1193Provider(globalEthereum)) return globalEthereum;
+	}
+
+	return undefined;
+};
+
+const toTransportError = (error: unknown): TransportError => {
+	if (error instanceof TransportError) return error;
+
+	if (error && typeof error === "object") {
+		const record = error as {
+			code?: unknown;
+			message?: unknown;
+			data?: unknown;
+		};
+		const rawCode = record.code;
+		const code =
+			typeof rawCode === "string"
+				? Number(rawCode)
+				: (rawCode as number | undefined);
+		if (typeof code === "number" && Number.isFinite(code)) {
+			const message =
+				typeof record.message === "string" && record.message.length > 0
+					? record.message
+					: (EIP1193_ERROR_MESSAGES[code] ?? "Provider error");
+			return new TransportError({
+				code,
+				message,
+				data: record.data,
+			});
+		}
+	}
+
+	return new TransportError({
+		code: -32603,
+		message: error instanceof Error ? error.message : "Unknown provider error",
+	});
+};
+
+/**
+ * Creates a custom transport layer from an EIP-1193 provider.
+ *
+ * @description
+ * Wraps any EIP-1193 compatible provider to work with the TransportService.
+ * Supports optional interceptors for request/response logging or modification.
+ * If no provider is supplied, it attempts to use an injected provider
+ * (window.ethereum or globalThis.ethereum).
+ *
+ * The transport:
+ * - Delegates all requests to the wrapped provider
+ * - Converts provider errors to TransportError
+ * - Optionally times out requests
+ * - Calls interceptors at appropriate lifecycle points
+ *
+ * @param options - Provider or configuration object (optional)
+ * @returns Layer providing TransportService
+ *
+ * @throws {TransportError} When the provider rejects the request
+ * @throws {TransportError} When the request times out
+ *
+ * @since 0.0.1
+ *
+ * @example Simple provider wrapping
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { ethers } from 'ethers'
+ * import { CustomTransport, TransportService } from 'voltaire-effect'
+ *
+ * const ethersProvider = new ethers.JsonRpcProvider('https://mainnet.infura.io/v3/KEY')
+ *
+ * const transport = CustomTransport({ provider: ethersProvider })
+ *
+ * const program = Effect.gen(function* () {
+ *   const t = yield* TransportService
+ *   return yield* t.request<string>('eth_blockNumber')
+ * }).pipe(Effect.provide(transport))
+ * ```
+ *
+ * @example With interceptors for logging
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { CustomTransport, TransportService } from 'voltaire-effect'
+ *
+ * const transport = CustomTransport({
+ *   provider: myProvider,
+ *   timeout: 60000,
+ *   onRequest: (method, params) => {
+ *     console.log(`-> ${method}`, params)
+ *   },
+ *   onResponse: (method, result) => {
+ *     console.log(`<- ${method}`, result)
+ *   },
+ *   onError: (method, error) => {
+ *     console.error(`!! ${method}`, error.message)
+ *   }
+ * })
+ * ```
+ *
+ * @example Wrapping web3.js provider
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import Web3 from 'web3'
+ * import { CustomTransport, TransportService } from 'voltaire-effect'
+ *
+ * const web3 = new Web3('https://mainnet.infura.io/v3/KEY')
+ *
+ * // Web3 providers are EIP-1193 compatible
+ * const transport = CustomTransport({
+ *   provider: web3.currentProvider as EIP1193Provider
+ * })
+ * ```
+ */
+export const CustomTransport = (
+	options?: CustomTransportConfig | EIP1193Provider,
+): Layer.Layer<TransportService> => {
+	const config: CustomTransportConfig = (
+		options && "request" in options && typeof options.request === "function"
+			? { provider: options as EIP1193Provider }
+			: (options ?? {})
+	) as CustomTransportConfig;
+
+	const baseTimeout = Duration.millis(config.timeout ?? 30000);
+
+	return Layer.succeed(TransportService, {
+		request: <T>(
+			method: string,
+			params: unknown[] = [],
+		): Effect.Effect<T, TransportError> => {
+			return Effect.gen(function* () {
+				const timeoutOverride = yield* FiberRef.get(timeoutRef);
+				const tracingEnabled = yield* FiberRef.get(tracingRef);
+				const timeout = timeoutOverride ?? baseTimeout;
+				const timeoutMs = Duration.toMillis(timeout);
+				// Call request interceptor
+				const provider = config.provider ?? resolveInjectedProvider();
+				if (!provider) {
+					return yield* Effect.fail(
+						new TransportError({
+							code: -32603,
+							message:
+								"No EIP-1193 provider found. Provide a provider or install an injected wallet (window.ethereum).",
+						}),
+					);
+				}
+
+				if (config.onRequest) {
+					yield* Effect.tryPromise({
+						try: () => Promise.resolve(config.onRequest?.(method, params)),
+						catch: () => void 0,
+					});
+				}
+
+				if (tracingEnabled) {
+					yield* Effect.logDebug(`rpc ${method} -> custom transport`);
+				}
+
+				const resultEffect = Effect.tryPromise({
+					try: () => provider.request({ method, params }),
+					catch: toTransportError,
+				});
+
+				const result = yield* resultEffect.pipe(
+					Effect.timeout(timeout),
+					Effect.catchTag("TimeoutException", () =>
+						Effect.fail(
+							new TransportError({
+								code: -32603,
+								message: `Request timeout after ${timeoutMs}ms`,
+							}),
+						),
+					),
+					Effect.tapError((error) => {
+						if (config.onError && error instanceof TransportError) {
+							return Effect.tryPromise({
+								try: () => Promise.resolve(config.onError?.(method, error)),
+								catch: () => void 0,
+							});
+						}
+						return Effect.void;
+					}),
+				);
+
+				// Call response interceptor
+				if (config.onResponse) {
+					yield* Effect.tryPromise({
+						try: () => Promise.resolve(config.onResponse?.(method, result)),
+						catch: () => void 0,
+					});
+				}
+
+				return result as T;
+			}) as Effect.Effect<T, TransportError>;
+		},
+	});
+};
+
+/**
+ * Creates a custom transport from a raw request function.
+ *
+ * @description
+ * Alternative constructor that takes a raw request function instead of
+ * a full provider object. Useful for creating minimal custom transports.
+ *
+ * @param request - Function that makes the RPC request
+ * @param options - Optional configuration
+ * @returns Layer providing TransportService
+ *
+ * @since 0.0.1
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { CustomTransportFromFn, TransportService } from 'voltaire-effect'
+ *
+ * const transport = CustomTransportFromFn(
+ *   async ({ method, params }) => {
+ *     const response = await fetch('https://rpc.example.com', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params })
+ *     })
+ *     const json = await response.json()
+ *     return json.result
+ *   },
+ *   { timeout: 60000 }
+ * )
+ * ```
+ */
+export const CustomTransportFromFn = (
+	request: (args: {
+		method: string;
+		params?: readonly unknown[] | object;
+	}) => Promise<unknown>,
+	options?: Omit<CustomTransportConfig, "provider">,
+): Layer.Layer<TransportService> =>
+	CustomTransport({
+		provider: { request },
+		...options,
+	});