voltaire-effect 0.2.23

package/src/utils/Unit/Unit.test.ts

@@ -0,0 +1,337 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import {
+	formatEther,
+	formatGwei,
+	formatUnits,
+	parseEther,
+	parseGwei,
+	parseUnits,
+} from "./index.js";
+
+describe("Unit", () => {
+	describe("parseUnits", () => {
+		it("parses integer value", async () => {
+			const result = await Effect.runPromise(parseUnits("1", 18));
+			expect(result).toBe(1000000000000000000n);
+		});
+
+		it("parses decimal value", async () => {
+			const result = await Effect.runPromise(parseUnits("1.5", 18));
+			expect(result).toBe(1500000000000000000n);
+		});
+
+		it("parses value with leading zeros in decimal", async () => {
+			const result = await Effect.runPromise(parseUnits("1.005", 18));
+			expect(result).toBe(1005000000000000000n);
+		});
+
+		it("parses zero", async () => {
+			const result = await Effect.runPromise(parseUnits("0", 18));
+			expect(result).toBe(0n);
+		});
+
+		it("parses value with trailing zeros in decimal", async () => {
+			const result = await Effect.runPromise(parseUnits("1.500", 18));
+			expect(result).toBe(1500000000000000000n);
+		});
+
+		it("truncates excess decimal places", async () => {
+			const result = await Effect.runPromise(
+				parseUnits("1.123456789012345678901234567890", 18),
+			);
+			expect(result).toBe(1123456789012345678n);
+		});
+
+		it("parses negative value", async () => {
+			const result = await Effect.runPromise(parseUnits("-1.5", 18));
+			expect(result).toBe(-1500000000000000000n);
+		});
+
+		it("parses value with 6 decimals (USDC)", async () => {
+			const result = await Effect.runPromise(parseUnits("100.50", 6));
+			expect(result).toBe(100500000n);
+		});
+
+		it("parses value with 8 decimals (WBTC)", async () => {
+			const result = await Effect.runPromise(parseUnits("0.00000001", 8));
+			expect(result).toBe(1n);
+		});
+
+		it("parses value with 0 decimals", async () => {
+			const result = await Effect.runPromise(parseUnits("123", 0));
+			expect(result).toBe(123n);
+		});
+
+		it("parses decimal-only value", async () => {
+			const result = await Effect.runPromise(parseUnits(".5", 18));
+			expect(result).toBe(500000000000000000n);
+		});
+
+		it("handles whitespace", async () => {
+			const result = await Effect.runPromise(parseUnits("  1.5  ", 18));
+			expect(result).toBe(1500000000000000000n);
+		});
+
+		it("fails on empty string", async () => {
+			const result = await Effect.runPromiseExit(parseUnits("", 18));
+			expect(result._tag).toBe("Failure");
+		});
+
+		it("fails on whitespace-only string", async () => {
+			const result = await Effect.runPromiseExit(parseUnits("   ", 18));
+			expect(result._tag).toBe("Failure");
+		});
+
+		it("fails on multiple decimal points", async () => {
+			const result = await Effect.runPromiseExit(parseUnits("1.2.3", 18));
+			expect(result._tag).toBe("Failure");
+		});
+
+		it("fails on non-numeric characters", async () => {
+			const result = await Effect.runPromiseExit(parseUnits("1.5abc", 18));
+			expect(result._tag).toBe("Failure");
+		});
+
+		it("returns UnitError on failure", async () => {
+			const result = await Effect.runPromiseExit(parseUnits("invalid", 18));
+			if (result._tag === "Failure") {
+				const error = result.cause;
+				expect(error._tag).toBe("Fail");
+			}
+		});
+	});
+
+	describe("formatUnits", () => {
+		it("formats integer value", async () => {
+			const result = await Effect.runPromise(
+				formatUnits(1000000000000000000n, 18),
+			);
+			expect(result).toBe("1");
+		});
+
+		it("formats decimal value", async () => {
+			const result = await Effect.runPromise(
+				formatUnits(1500000000000000000n, 18),
+			);
+			expect(result).toBe("1.5");
+		});
+
+		it("formats value with leading zeros in decimal", async () => {
+			const result = await Effect.runPromise(
+				formatUnits(1005000000000000000n, 18),
+			);
+			expect(result).toBe("1.005");
+		});
+
+		it("formats zero", async () => {
+			const result = await Effect.runPromise(formatUnits(0n, 18));
+			expect(result).toBe("0");
+		});
+
+		it("formats small value (less than 1)", async () => {
+			const result = await Effect.runPromise(
+				formatUnits(500000000000000000n, 18),
+			);
+			expect(result).toBe("0.5");
+		});
+
+		it("formats very small value", async () => {
+			const result = await Effect.runPromise(formatUnits(1n, 18));
+			expect(result).toBe("0.000000000000000001");
+		});
+
+		it("formats negative value", async () => {
+			const result = await Effect.runPromise(
+				formatUnits(-1500000000000000000n, 18),
+			);
+			expect(result).toBe("-1.5");
+		});
+
+		it("formats value with 6 decimals (USDC)", async () => {
+			const result = await Effect.runPromise(formatUnits(100500000n, 6));
+			expect(result).toBe("100.5");
+		});
+
+		it("formats value with 8 decimals (WBTC)", async () => {
+			const result = await Effect.runPromise(formatUnits(1n, 8));
+			expect(result).toBe("0.00000001");
+		});
+
+		it("formats value with 0 decimals", async () => {
+			const result = await Effect.runPromise(formatUnits(123n, 0));
+			expect(result).toBe("123");
+		});
+
+		it("removes trailing zeros", async () => {
+			const result = await Effect.runPromise(
+				formatUnits(1000000000000000000n, 18),
+			);
+			expect(result).toBe("1");
+			expect(result).not.toContain(".");
+		});
+
+		it("fails on negative decimals", async () => {
+			const result = await Effect.runPromiseExit(formatUnits(100n, -1));
+			expect(result._tag).toBe("Failure");
+		});
+	});
+
+	describe("parseEther", () => {
+		it("parses 1 ETH", async () => {
+			const result = await Effect.runPromise(parseEther("1"));
+			expect(result).toBe(1000000000000000000n);
+		});
+
+		it("parses 1.5 ETH", async () => {
+			const result = await Effect.runPromise(parseEther("1.5"));
+			expect(result).toBe(1500000000000000000n);
+		});
+
+		it("parses 0.001 ETH (1 finney)", async () => {
+			const result = await Effect.runPromise(parseEther("0.001"));
+			expect(result).toBe(1000000000000000n);
+		});
+
+		it("parses 0.000000001 ETH (1 gwei)", async () => {
+			const result = await Effect.runPromise(parseEther("0.000000001"));
+			expect(result).toBe(1000000000n);
+		});
+
+		it("parses 0.000000000000000001 ETH (1 wei)", async () => {
+			const result = await Effect.runPromise(
+				parseEther("0.000000000000000001"),
+			);
+			expect(result).toBe(1n);
+		});
+
+		it("parses large value", async () => {
+			const result = await Effect.runPromise(parseEther("1000000"));
+			expect(result).toBe(1000000000000000000000000n);
+		});
+	});
+
+	describe("formatEther", () => {
+		it("formats 1 ETH", async () => {
+			const result = await Effect.runPromise(formatEther(1000000000000000000n));
+			expect(result).toBe("1");
+		});
+
+		it("formats 1.5 ETH", async () => {
+			const result = await Effect.runPromise(formatEther(1500000000000000000n));
+			expect(result).toBe("1.5");
+		});
+
+		it("formats 1 wei", async () => {
+			const result = await Effect.runPromise(formatEther(1n));
+			expect(result).toBe("0.000000000000000001");
+		});
+
+		it("formats 1 gwei", async () => {
+			const result = await Effect.runPromise(formatEther(1000000000n));
+			expect(result).toBe("0.000000001");
+		});
+
+		it("formats large value", async () => {
+			const result = await Effect.runPromise(
+				formatEther(1000000000000000000000000n),
+			);
+			expect(result).toBe("1000000");
+		});
+	});
+
+	describe("parseGwei", () => {
+		it("parses 1 gwei", async () => {
+			const result = await Effect.runPromise(parseGwei("1"));
+			expect(result).toBe(1000000000n);
+		});
+
+		it("parses 20.5 gwei", async () => {
+			const result = await Effect.runPromise(parseGwei("20.5"));
+			expect(result).toBe(20500000000n);
+		});
+
+		it("parses 0.000000001 gwei (1 wei)", async () => {
+			const result = await Effect.runPromise(parseGwei("0.000000001"));
+			expect(result).toBe(1n);
+		});
+
+		it("parses standard gas price", async () => {
+			const result = await Effect.runPromise(parseGwei("30"));
+			expect(result).toBe(30000000000n);
+		});
+	});
+
+	describe("formatGwei", () => {
+		it("formats 1 gwei", async () => {
+			const result = await Effect.runPromise(formatGwei(1000000000n));
+			expect(result).toBe("1");
+		});
+
+		it("formats 20.5 gwei", async () => {
+			const result = await Effect.runPromise(formatGwei(20500000000n));
+			expect(result).toBe("20.5");
+		});
+
+		it("formats 1 wei", async () => {
+			const result = await Effect.runPromise(formatGwei(1n));
+			expect(result).toBe("0.000000001");
+		});
+
+		it("formats standard gas price", async () => {
+			const result = await Effect.runPromise(formatGwei(30000000000n));
+			expect(result).toBe("30");
+		});
+	});
+
+	describe("roundtrip tests", () => {
+		it("parseEther -> formatEther roundtrip", async () => {
+			const original = "123.456789012345678";
+			const wei = await Effect.runPromise(parseEther(original));
+			const formatted = await Effect.runPromise(formatEther(wei));
+			expect(formatted).toBe("123.456789012345678");
+		});
+
+		it("parseGwei -> formatGwei roundtrip", async () => {
+			const original = "20.123456789";
+			const wei = await Effect.runPromise(parseGwei(original));
+			const formatted = await Effect.runPromise(formatGwei(wei));
+			expect(formatted).toBe("20.123456789");
+		});
+
+		it("formatEther -> parseEther roundtrip", async () => {
+			const original = 1234567890123456789n;
+			const formatted = await Effect.runPromise(formatEther(original));
+			const parsed = await Effect.runPromise(parseEther(formatted));
+			expect(parsed).toBe(original);
+		});
+
+		it("formatGwei -> parseGwei roundtrip", async () => {
+			const original = 12345678901n;
+			const formatted = await Effect.runPromise(formatGwei(original));
+			const parsed = await Effect.runPromise(parseGwei(formatted));
+			expect(parsed).toBe(original);
+		});
+	});
+
+	describe("edge cases", () => {
+		it("handles max safe integer equivalent", async () => {
+			const result = await Effect.runPromise(parseEther("9007199254740991"));
+			expect(result).toBe(9007199254740991000000000000000000n);
+		});
+
+		it("handles very large values", async () => {
+			const large =
+				"115792089237316195423570985008687907853269984665640564039457";
+			const result = await Effect.runPromise(parseUnits(large, 0));
+			expect(result).toBe(BigInt(large));
+		});
+
+		it("handles value with all decimal places used", async () => {
+			const result = await Effect.runPromise(
+				parseEther("1.123456789012345678"),
+			);
+			expect(result).toBe(1123456789012345678n);
+		});
+	});
+});

package/src/utils/Unit/errors.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Unit parsing/formatting error types.
+ * @module utils/Unit/errors
+ * @since 0.0.1
+ */
+
+import * as Data from "effect/Data";
+
+/**
+ * Error thrown when unit parsing or formatting fails.
+ */
+export class UnitError extends Data.TaggedError("UnitError")<{
+	readonly operation: string;
+	readonly message: string;
+	readonly cause?: unknown;
+}> {}

package/src/utils/Unit/formatEther.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Format wei to ether string (18 decimals).
+ * @module utils/Unit/formatEther
+ * @since 0.0.1
+ */
+
+import type * as Effect from "effect/Effect";
+import type { UnitError } from "./errors.js";
+import { formatUnits } from "./formatUnits.js";
+
+/**
+ * Formats wei to an ether string (18 decimals).
+ *
+ * @param value - Wei value as bigint
+ * @returns Effect yielding ether string
+ *
+ * @example
+ * ```typescript
+ * // Format 1500000000000000000n wei → "1.5" ETH
+ * const ether = yield* formatEther(1500000000000000000n)
+ * ```
+ */
+export const formatEther = (value: bigint): Effect.Effect<string, UnitError> =>
+	formatUnits(value, 18);

package/src/utils/Unit/formatGwei.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Format wei to gwei string (9 decimals).
+ * @module utils/Unit/formatGwei
+ * @since 0.0.1
+ */
+
+import type * as Effect from "effect/Effect";
+import type { UnitError } from "./errors.js";
+import { formatUnits } from "./formatUnits.js";
+
+/**
+ * Formats wei to a gwei string (9 decimals).
+ *
+ * @param value - Wei value as bigint
+ * @returns Effect yielding gwei string
+ *
+ * @example
+ * ```typescript
+ * // Format 20500000000n wei → "20.5" gwei
+ * const gwei = yield* formatGwei(20500000000n)
+ * ```
+ */
+export const formatGwei = (value: bigint): Effect.Effect<string, UnitError> =>
+	formatUnits(value, 9);

package/src/utils/Unit/formatUnits.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Format bigint to decimal string with specified decimals.
+ * @module utils/Unit/formatUnits
+ * @since 0.0.1
+ */
+
+import * as Effect from "effect/Effect";
+import { UnitError } from "./errors.js";
+
+/**
+ * Formats a bigint value to a decimal string with the specified number of decimals.
+ *
+ * @param value - The bigint value in the smallest unit
+ * @param decimals - Number of decimal places (e.g., 18 for ether)
+ * @returns Effect yielding the formatted decimal string
+ *
+ * @example
+ * ```typescript
+ * // Format 1500000000000000000n with 18 decimals → "1.5"
+ * const ether = yield* formatUnits(1500000000000000000n, 18)
+ * ```
+ */
+export const formatUnits = (
+	value: bigint,
+	decimals: number,
+): Effect.Effect<string, UnitError> =>
+	Effect.try({
+		try: () => {
+			if (decimals < 0) {
+				throw new Error("Decimals must be non-negative");
+			}
+
+			const negative = value < 0n;
+			const abs = negative ? -value : value;
+
+			const str = abs.toString().padStart(decimals + 1, "0");
+			const integerPart = str.slice(0, str.length - decimals) || "0";
+			const decimalPart = str.slice(str.length - decimals);
+
+			// Remove trailing zeros from decimal part
+			const trimmedDecimal = decimalPart.replace(/0+$/, "");
+
+			const result = trimmedDecimal
+				? `${integerPart}.${trimmedDecimal}`
+				: integerPart;
+
+			return negative ? `-${result}` : result;
+		},
+		catch: (e) =>
+			new UnitError({
+				operation: "formatUnits",
+				message: e instanceof Error ? e.message : String(e),
+				cause: e,
+			}),
+	});

package/src/utils/Unit/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Unit utilities for parsing and formatting Ethereum denominations.
+ *
+ * @description
+ * Provides Effect-based utilities for converting between human-readable decimal
+ * strings and bigint values in wei.
+ *
+ * - **parseEther**: Parse ether string to wei (18 decimals)
+ * - **formatEther**: Format wei to ether string (18 decimals)
+ * - **parseGwei**: Parse gwei string to wei (9 decimals)
+ * - **formatGwei**: Format wei to gwei string (9 decimals)
+ * - **parseUnits**: Parse with custom decimals
+ * - **formatUnits**: Format with custom decimals
+ *
+ * @example
+ * ```typescript
+ * import * as Unit from 'voltaire-effect/utils/Unit'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   // Parse 1.5 ETH to wei
+ *   const wei = yield* Unit.parseEther("1.5")
+ *   // → 1500000000000000000n
+ *
+ *   // Format wei back to ETH
+ *   const eth = yield* Unit.formatEther(wei)
+ *   // → "1.5"
+ *
+ *   // Parse gas price in gwei
+ *   const gasWei = yield* Unit.parseGwei("20.5")
+ *   // → 20500000000n
+ *
+ *   // Custom decimals (e.g., USDC has 6)
+ *   const usdc = yield* Unit.parseUnits("100.50", 6)
+ *   // → 100500000n
+ * })
+ * ```
+ *
+ * @module utils/Unit
+ * @since 0.0.1
+ */
+
+export { UnitError } from "./errors.js";
+export { formatEther } from "./formatEther.js";
+export { formatGwei } from "./formatGwei.js";
+export { formatUnits } from "./formatUnits.js";
+export { parseEther } from "./parseEther.js";
+export { parseGwei } from "./parseGwei.js";
+export { parseUnits } from "./parseUnits.js";

package/src/utils/Unit/parseEther.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Parse ether string to wei (18 decimals).
+ * @module utils/Unit/parseEther
+ * @since 0.0.1
+ */
+
+import type * as Effect from "effect/Effect";
+import type { UnitError } from "./errors.js";
+import { parseUnits } from "./parseUnits.js";
+
+/**
+ * Parses an ether string to wei (18 decimals).
+ *
+ * @param value - Ether string (e.g., "1.5")
+ * @returns Effect yielding wei as bigint
+ *
+ * @example
+ * ```typescript
+ * // Parse "1.5" ETH → 1500000000000000000n wei
+ * const wei = yield* parseEther("1.5")
+ * ```
+ */
+export const parseEther = (value: string): Effect.Effect<bigint, UnitError> =>
+	parseUnits(value, 18);

package/src/utils/Unit/parseGwei.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Parse gwei string to wei (9 decimals).
+ * @module utils/Unit/parseGwei
+ * @since 0.0.1
+ */
+
+import type * as Effect from "effect/Effect";
+import type { UnitError } from "./errors.js";
+import { parseUnits } from "./parseUnits.js";
+
+/**
+ * Parses a gwei string to wei (9 decimals).
+ *
+ * @param value - Gwei string (e.g., "20.5")
+ * @returns Effect yielding wei as bigint
+ *
+ * @example
+ * ```typescript
+ * // Parse "20.5" gwei → 20500000000n wei
+ * const wei = yield* parseGwei("20.5")
+ * ```
+ */
+export const parseGwei = (value: string): Effect.Effect<bigint, UnitError> =>
+	parseUnits(value, 9);

package/src/utils/Unit/parseUnits.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Parse decimal string to bigint with specified decimals.
+ * @module utils/Unit/parseUnits
+ * @since 0.0.1
+ */
+
+import * as Effect from "effect/Effect";
+import { UnitError } from "./errors.js";
+
+/**
+ * Parses a decimal string value to a bigint with the specified number of decimals.
+ *
+ * @param value - Decimal string (e.g., "1.5")
+ * @param decimals - Number of decimal places (e.g., 18 for ether)
+ * @returns Effect yielding the parsed bigint value
+ *
+ * @example
+ * ```typescript
+ * // Parse 1.5 with 18 decimals → 1500000000000000000n
+ * const wei = yield* parseUnits("1.5", 18)
+ * ```
+ */
+export const parseUnits = (
+	value: string,
+	decimals: number,
+): Effect.Effect<bigint, UnitError> =>
+	Effect.try({
+		try: () => {
+			const trimmed = value.trim();
+			if (trimmed === "") {
+				throw new Error("Empty value");
+			}
+
+			// Handle negative values
+			const negative = trimmed.startsWith("-");
+			const abs = negative ? trimmed.slice(1) : trimmed;
+
+			// Split by decimal point
+			const [integerPart = "0", decimalPart = ""] = abs.split(".");
+
+			if (abs.split(".").length > 2) {
+				throw new Error("Invalid number format: multiple decimal points");
+			}
+
+			// Validate parts contain only digits
+			if (!/^\d*$/.test(integerPart) || !/^\d*$/.test(decimalPart)) {
+				throw new Error("Invalid number format: non-digit characters");
+			}
+
+			// Truncate decimal part if longer than decimals
+			const truncatedDecimal = decimalPart.slice(0, decimals);
+
+			// Pad decimal part with zeros
+			const paddedDecimal = truncatedDecimal.padEnd(decimals, "0");
+
+			// Combine and parse
+			const combined = integerPart + paddedDecimal;
+			const result = BigInt(combined);
+
+			return negative ? -result : result;
+		},
+		catch: (e) =>
+			new UnitError({
+				operation: "parseUnits",
+				message: e instanceof Error ? e.message : String(e),
+				cause: e,
+			}),
+	});