voltaire-effect 0.2.23 → 0.2.24

package/src/primitives/Hex/Hex.test.ts

@@ -1,5 +1,7 @@
+import { Effect, Exit } from "effect";
 import * as S from "effect/Schema";
 import { describe, expect, it } from "vitest";
+import type { HexType } from "@tevm/voltaire/Hex";
 import * as Hex from "./index.js";
 
 describe("Hex.String", () => {
@@ -159,62 +161,48 @@ describe("Hex.Bytes", () => {
 	});
 });
 
-describe("pure functions", () => {
+describe("pure functions (infallible)", () => {
 	describe("isHex", () => {
 		it("returns true for valid hex with prefix", () => {
-			const result = Hex.isHex("0x1234");
-			expect(result).toBe(true);
+			expect(Hex.isHex("0x1234")).toBe(true);
 		});
 
 		it("returns false for empty hex 0x", () => {
-			const result = Hex.isHex("0x");
-			expect(result).toBe(false);
+			expect(Hex.isHex("0x")).toBe(false);
 		});
 
 		it("returns false for hex without prefix", () => {
-			const result = Hex.isHex("1234");
-			expect(result).toBe(false);
+			expect(Hex.isHex("1234")).toBe(false);
 		});
 
 		it("returns false for invalid hex characters", () => {
-			const result = Hex.isHex("0xZZZZ");
-			expect(result).toBe(false);
+			expect(Hex.isHex("0xZZZZ")).toBe(false);
 		});
 
 		it("returns true for odd-length hex", () => {
-			const result = Hex.isHex("0xabc");
-			expect(result).toBe(true);
-		});
-
-		it("returns false for non-hex string", () => {
-			const result = Hex.isHex("hello");
-			expect(result).toBe(false);
+			expect(Hex.isHex("0xabc")).toBe(true);
 		});
 	});
 
 	describe("isSized", () => {
 		it("returns true for correct size", () => {
 			const hex = S.decodeSync(Hex.String)("0x1234");
-			const result = Hex.isSized(hex, 2);
-			expect(result).toBe(true);
+			expect(Hex.isSized(hex, 2)).toBe(true);
 		});
 
 		it("returns false for incorrect size", () => {
 			const hex = S.decodeSync(Hex.String)("0x1234");
-			const result = Hex.isSized(hex, 4);
-			expect(result).toBe(false);
+			expect(Hex.isSized(hex, 4)).toBe(false);
 		});
 
 		it("returns true for empty hex with size 0", () => {
 			const hex = S.decodeSync(Hex.String)("0x");
-			const result = Hex.isSized(hex, 0);
-			expect(result).toBe(true);
+			expect(Hex.isSized(hex, 0)).toBe(true);
 		});
 
 		it("checks 32-byte hex correctly", () => {
 			const hex = S.decodeSync(Hex.String)(`0x${"ab".repeat(32)}`);
-			const result = Hex.isSized(hex, 32);
-			expect(result).toBe(true);
+			expect(Hex.isSized(hex, 32)).toBe(true);
 		});
 	});
 
@@ -248,11 +236,6 @@ describe("pure functions", () => {
 			expect(result).toBe(`0x${"00".repeat(32)}`);
 			expect(result.length).toBe(66);
 		});
-
-		it("creates 1-byte zero hex", () => {
-			const result = Hex.zero(1);
-			expect(result).toBe("0x00");
-		});
 	});
 
 	describe("random", () => {
@@ -278,201 +261,329 @@ describe("pure functions", () => {
 			expect(result).toMatch(/^0x[0-9a-f]{16}$/);
 		});
 	});
-});
 
-describe("edge cases", () => {
-	it("handles maximum safe integer bytes", () => {
-		const hex = S.decodeSync(Hex.String)("0xffffffffffffff");
-		const sized = Hex.isSized(hex, 7);
-		expect(sized).toBe(true);
+	describe("equals", () => {
+		it("returns true for equal hex", () => {
+			const a = S.decodeSync(Hex.String)("0xdeadbeef");
+			const b = S.decodeSync(Hex.String)("0xdeadbeef");
+			expect(Hex.equals(a, b)).toBe(true);
+		});
+
+		it("returns false for different hex", () => {
+			const a = S.decodeSync(Hex.String)("0xdeadbeef");
+			const b = S.decodeSync(Hex.String)("0x12345678");
+			expect(Hex.equals(a, b)).toBe(false);
+		});
 	});
 
-	it("handles all zeros", () => {
-		const hex = S.decodeSync(Hex.String)("0x0000000000");
-		expect(hex).toBe("0x0000000000");
+	describe("size", () => {
+		it("returns correct size for hex", () => {
+			const hex = S.decodeSync(Hex.String)("0xdeadbeef");
+			expect(Hex.size(hex)).toBe(4);
+		});
+
+		it("returns 0 for empty hex", () => {
+			const hex = S.decodeSync(Hex.String)("0x");
+			expect(Hex.size(hex)).toBe(0);
+		});
+
+		it("returns correct size for 32-byte hex", () => {
+			const hex = S.decodeSync(Hex.String)(`0x${"ab".repeat(32)}`);
+			expect(Hex.size(hex)).toBe(32);
+		});
 	});
 
-	it("handles all ones (ff)", () => {
-		const hex = S.decodeSync(Hex.String)("0xffffffffff");
-		expect(hex).toBe("0xffffffffff");
+	describe("trim", () => {
+		it("trims leading zeros", () => {
+			const hex = "0x00001234" as HexType;
+			expect(Hex.trim(hex)).toBe("0x1234");
+		});
+
+		it("preserves non-zero hex", () => {
+			const hex = "0xdeadbeef" as HexType;
+			expect(Hex.trim(hex)).toBe("0xdeadbeef");
+		});
 	});
 
-	it("preserves case for uppercase hex", () => {
-		const hex = S.decodeSync(Hex.String)("0xABCDEF");
-		expect(hex).toBe("0xABCDEF");
+	describe("fromBoolean", () => {
+		it("converts true to 0x01", () => {
+			expect(Hex.fromBoolean(true)).toBe("0x01");
+		});
+
+		it("converts false to 0x00", () => {
+			expect(Hex.fromBoolean(false)).toBe("0x00");
+		});
 	});
-});
 
-describe("error cases", () => {
-	describe("Hex.String errors", () => {
-		it("fails on null", () => {
-			expect(() =>
-				S.decodeSync(Hex.String)(null as unknown as string),
-			).toThrow();
+	describe("fromString", () => {
+		it("encodes string to hex", () => {
+			expect(Hex.fromString("hello")).toBe("0x68656c6c6f");
 		});
 
-		it("fails on undefined", () => {
-			expect(() =>
-				S.decodeSync(Hex.String)(undefined as unknown as string),
-			).toThrow();
+		it("encodes empty string", () => {
+			expect(Hex.fromString("")).toBe("0x");
 		});
+	});
 
-		it("fails on object", () => {
-			expect(() => S.decodeSync(Hex.String)({} as unknown as string)).toThrow();
+	describe("toBigInt", () => {
+		it("converts hex to bigint", () => {
+			const hex = S.decodeSync(Hex.String)("0xff");
+			expect(Hex.toBigInt(hex)).toBe(255n);
 		});
 
-		it("fails on array", () => {
-			expect(() => S.decodeSync(Hex.String)([] as unknown as string)).toThrow();
+		it("handles large values", () => {
+			const hex = S.decodeSync(Hex.String)("0xde0b6b3a7640000");
+			expect(Hex.toBigInt(hex)).toBe(1000000000000000000n);
 		});
+	});
+});
 
-		it("fails on empty string", () => {
-			expect(() => S.decodeSync(Hex.String)("")).toThrow();
+describe("Effect functions (fallible)", () => {
+	describe("from", () => {
+		it("parses valid hex string", async () => {
+			const result = await Effect.runPromise(Hex.from("0xdeadbeef"));
+			expect(result).toBe("0xdeadbeef");
 		});
 
-		it("fails on whitespace", () => {
-			expect(() => S.decodeSync(Hex.String)("  ")).toThrow();
+		it("parses bytes", async () => {
+			const result = await Effect.runPromise(
+				Hex.from(new Uint8Array([0xde, 0xad])),
+			);
+			expect(result).toBe("0xdead");
 		});
 
-		it("fails on 0x with spaces", () => {
-			expect(() => S.decodeSync(Hex.String)("0x 12")).toThrow();
+		it("fails on invalid hex", async () => {
+			const exit = await Effect.runPromiseExit(Hex.from("invalid"));
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+	});
+
+	describe("fromNumber", () => {
+		it("converts number to hex", async () => {
+			const result = await Effect.runPromise(Hex.fromNumber(255));
+			expect(result).toBe("0xff");
 		});
 
-		it("fails on special characters", () => {
-			expect(() => S.decodeSync(Hex.String)("0x!@#$")).toThrow();
+		it("pads to size", async () => {
+			const result = await Effect.runPromise(Hex.fromNumber(255, 2));
+			expect(result).toBe("0x00ff");
+		});
+
+		it("fails on negative number", async () => {
+			const exit = await Effect.runPromiseExit(Hex.fromNumber(-1));
+			expect(Exit.isFailure(exit)).toBe(true);
 		});
 	});
 
-	describe("Hex.Bytes errors", () => {
-		it("fails on null", () => {
-			expect(() =>
-				S.decodeSync(Hex.Bytes)(null as unknown as Uint8Array),
-			).toThrow();
+	describe("fromBigInt", () => {
+		it("converts bigint to hex", async () => {
+			const result = await Effect.runPromise(Hex.fromBigInt(255n));
+			expect(result).toBe("0xff");
 		});
 
-		it("fails on string input", () => {
-			expect(() =>
-				S.decodeSync(Hex.Bytes)("0xab" as unknown as Uint8Array),
-			).toThrow();
+		it("pads to size", async () => {
+			const result = await Effect.runPromise(Hex.fromBigInt(255n, 2));
+			expect(result).toBe("0x00ff");
+		});
+
+		it("fails on negative bigint", async () => {
+			const exit = await Effect.runPromiseExit(Hex.fromBigInt(-1n));
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+	});
+
+	describe("toNumber", () => {
+		it("converts hex to number", async () => {
+			const hex = S.decodeSync(Hex.String)("0xff");
+			const result = await Effect.runPromise(Hex.toNumber(hex));
+			expect(result).toBe(255);
 		});
 	});
-});
 
-describe("additional edge cases", () => {
-	describe("isHex edge cases", () => {
-		it("returns true for single char hex", () => {
-			const result = Hex.isHex("0xa");
+	describe("toBoolean", () => {
+		it("converts 0x01 to true", async () => {
+			const hex = "0x01" as HexType;
+			const result = await Effect.runPromise(Hex.toBoolean(hex));
 			expect(result).toBe(true);
 		});
 
-		it("returns false for just 0x prefix", () => {
-			const result = Hex.isHex("0x");
+		it("converts 0x00 to false", async () => {
+			const hex = "0x00" as HexType;
+			const result = await Effect.runPromise(Hex.toBoolean(hex));
 			expect(result).toBe(false);
 		});
 
-		it("returns false for string without prefix", () => {
-			const result = Hex.isHex("abcd");
-			expect(result).toBe(false);
+		it("fails on invalid boolean hex", async () => {
+			const hex = "0xff" as HexType;
+			const exit = await Effect.runPromiseExit(Hex.toBoolean(hex));
+			expect(Exit.isFailure(exit)).toBe(true);
 		});
 	});
 
-	describe("isSized edge cases", () => {
-		it("returns false for odd-length hex size calculation", () => {
-			const hex = S.decodeSync(Hex.String)("0xabc");
-			const result = Hex.isSized(hex, 1);
-			expect(result).toBe(false);
+	describe("toStringHex", () => {
+		it("decodes hex to string", async () => {
+			const hex = "0x68656c6c6f" as HexType;
+			const result = await Effect.runPromise(Hex.toStringHex(hex));
+			expect(result).toBe("hello");
 		});
+	});
 
-		it("handles large sizes", () => {
-			const hex = S.decodeSync(Hex.String)(`0x${"ab".repeat(1000)}`);
-			const result = Hex.isSized(hex, 1000);
-			expect(result).toBe(true);
+	describe("concat", () => {
+		it("concatenates hex strings", async () => {
+			const a = "0x1234" as HexType;
+			const b = "0x5678" as HexType;
+			const result = await Effect.runPromise(Hex.concat(a, b));
+			expect(result).toBe("0x12345678");
 		});
-	});
 
-	describe("zero edge cases", () => {
-		it("creates large zero hex", () => {
-			const result = Hex.zero(100);
-			expect(result).toBe(`0x${"00".repeat(100)}`);
+		it("concatenates multiple hex strings", async () => {
+			const a = "0x12" as HexType;
+			const b = "0x34" as HexType;
+			const c = "0x56" as HexType;
+			const result = await Effect.runPromise(Hex.concat(a, b, c));
+			expect(result).toBe("0x123456");
 		});
 	});
 
-	describe("random edge cases", () => {
-		it("random of size 1 produces valid hex", () => {
-			const result = Hex.random(1);
-			expect(result.length).toBe(4);
-			expect(result.startsWith("0x")).toBe(true);
+	describe("pad", () => {
+		it("left-pads hex to size", async () => {
+			const hex = "0x12" as HexType;
+			const result = await Effect.runPromise(Hex.pad(hex, 4));
+			expect(result).toBe("0x00000012");
 		});
 
-		it("random produces lowercase hex", () => {
-			const result = Hex.random(32);
-			expect(result).toMatch(/^0x[0-9a-f]+$/);
+		it("fails when hex exceeds target size", async () => {
+			const hex = "0x12345678" as HexType;
+			const exit = await Effect.runPromiseExit(Hex.pad(hex, 2));
+			expect(Exit.isFailure(exit)).toBe(true);
 		});
 	});
 
-	describe("clone edge cases", () => {
-		it("clones very long hex", () => {
-			const original = S.decodeSync(Hex.String)(`0x${"ab".repeat(1000)}`);
-			const cloned = Hex.clone(original);
-			expect(cloned).toBe(original);
+	describe("padRight", () => {
+		it("right-pads hex to size", async () => {
+			const hex = "0x12" as HexType;
+			const result = await Effect.runPromise(Hex.padRight(hex, 4));
+			expect(result).toBe("0x12000000");
 		});
 	});
 
-	describe("Bytes schema edge cases", () => {
-		it("decodes from large byte array", () => {
-			const bytes = new Uint8Array(10000).fill(0xab);
-			const hex = S.decodeSync(Hex.Bytes)(bytes);
-			expect(hex.length).toBe(20002);
+	describe("slice", () => {
+		it("slices hex from start", async () => {
+			const hex = "0x123456" as HexType;
+			const result = await Effect.runPromise(Hex.slice(hex, 1));
+			expect(result).toBe("0x3456");
 		});
 
-		it("encodes to bytes preserves values", () => {
-			const hex = S.decodeSync(Hex.String)(
-				"0x000102030405060708090a0b0c0d0e0f",
-			);
-			const bytes = S.encodeSync(Hex.Bytes)(hex);
-			for (let i = 0; i < 16; i++) {
-				expect(bytes[i]).toBe(i);
-			}
+		it("slices hex with range", async () => {
+			const hex = "0x123456" as HexType;
+			const result = await Effect.runPromise(Hex.slice(hex, 0, 1));
+			expect(result).toBe("0x12");
 		});
 	});
-});
 
-describe("API consistency - infallible ops return directly", () => {
-	it("clone returns HexType directly, not Effect", () => {
-		const hex = S.decodeSync(Hex.String)("0xdeadbeef");
-		const result = Hex.clone(hex);
-		// Direct value, not Effect
-		expect(typeof result).toBe("string");
-		expect(result.startsWith("0x")).toBe(true);
+	describe("validate", () => {
+		it("validates valid hex", async () => {
+			const result = await Effect.runPromise(Hex.validate("0x1234"));
+			expect(result).toBe("0x1234");
+		});
+
+		it("fails on invalid hex", async () => {
+			const exit = await Effect.runPromiseExit(Hex.validate("invalid"));
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
 	});
 
-	it("isHex returns boolean directly, not Effect", () => {
-		const result = Hex.isHex("0x1234");
-		expect(typeof result).toBe("boolean");
+	describe("xor", () => {
+		it("xors two hex strings", async () => {
+			const a = "0xff00" as HexType;
+			const b = "0x00ff" as HexType;
+			const result = await Effect.runPromise(Hex.xor(a, b));
+			expect(result).toBe("0xffff");
+		});
 	});
 
-	it("isSized returns boolean directly, not Effect", () => {
-		const hex = S.decodeSync(Hex.String)("0x1234");
-		const result = Hex.isSized(hex, 2);
-		expect(typeof result).toBe("boolean");
+	describe("assertSize", () => {
+		it("succeeds when size matches", async () => {
+			const hex = "0x1234" as HexType;
+			const result = await Effect.runPromise(Hex.assertSize(hex, 2));
+			expect(result).toBe("0x1234");
+		});
+
+		it("fails when size doesn't match", async () => {
+			const hex = "0x1234" as HexType;
+			const exit = await Effect.runPromiseExit(Hex.assertSize(hex, 4));
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
 	});
+});
 
-	it("zero returns HexType directly, not Effect", () => {
-		const result = Hex.zero(4);
-		expect(typeof result).toBe("string");
-		expect(result).toBe("0x00000000");
+describe("API consistency", () => {
+	it("infallible ops return directly, not Effect", () => {
+		const hex = S.decodeSync(Hex.String)("0xdeadbeef");
+
+		expect(typeof Hex.clone(hex)).toBe("string");
+		expect(typeof Hex.isHex("0x1234")).toBe("boolean");
+		expect(typeof Hex.isSized(hex, 4)).toBe("boolean");
+		expect(typeof Hex.zero(4)).toBe("string");
+		expect(typeof Hex.random(8)).toBe("string");
+		expect(typeof Hex.equals(hex, hex)).toBe("boolean");
+		expect(typeof Hex.size(hex)).toBe("number");
+		expect(typeof Hex.trim(hex)).toBe("string");
+		expect(typeof Hex.fromBoolean(true)).toBe("string");
+		expect(typeof Hex.fromString("hello")).toBe("string");
 	});
+});
 
-	it("random returns HexType directly, not Effect", () => {
-		const result = Hex.random(8);
-		expect(typeof result).toBe("string");
-		expect(result.startsWith("0x")).toBe(true);
+describe("error cases", () => {
+	describe("Hex.String errors", () => {
+		it("fails on null", () => {
+			expect(() =>
+				S.decodeSync(Hex.String)(null as unknown as string),
+			).toThrow();
+		});
+
+		it("fails on undefined", () => {
+			expect(() =>
+				S.decodeSync(Hex.String)(undefined as unknown as string),
+			).toThrow();
+		});
+
+		it("fails on object", () => {
+			expect(() => S.decodeSync(Hex.String)({} as unknown as string)).toThrow();
+		});
+
+		it("fails on array", () => {
+			expect(() => S.decodeSync(Hex.String)([] as unknown as string)).toThrow();
+		});
+
+		it("fails on empty string", () => {
+			expect(() => S.decodeSync(Hex.String)("")).toThrow();
+		});
+
+		it("fails on whitespace", () => {
+			expect(() => S.decodeSync(Hex.String)("  ")).toThrow();
+		});
+
+		it("fails on 0x with spaces", () => {
+			expect(() => S.decodeSync(Hex.String)("0x 12")).toThrow();
+		});
+
+		it("fails on special characters", () => {
+			expect(() => S.decodeSync(Hex.String)("0x!@#$")).toThrow();
+		});
 	});
 
-	it("equals returns boolean directly, not Effect", () => {
-		const a = S.decodeSync(Hex.String)("0xdeadbeef");
-		const b = S.decodeSync(Hex.String)("0xdeadbeef");
-		const result = Hex.equals(a, b);
-		expect(typeof result).toBe("boolean");
-		expect(result).toBe(true);
+	describe("Hex.Bytes errors", () => {
+		it("fails on null", () => {
+			expect(() =>
+				S.decodeSync(Hex.Bytes)(null as unknown as Uint8Array),
+			).toThrow();
+		});
+
+		it("fails on string input", () => {
+			expect(() =>
+				S.decodeSync(Hex.Bytes)("0xab" as unknown as Uint8Array),
+			).toThrow();
+		});
 	});
 });

package/src/primitives/Hex/assertSize.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Effect wrapper for Hex.assertSize.
+ * Asserts that Hex is exactly the specified size.
+ * @module voltaire-effect/primitives/Hex/assertSize
+ * @since 0.1.0
+ */
+
+import {
+	type HexType,
+	type Sized,
+	Hex as VoltaireHex,
+	InvalidLengthError,
+} from "@tevm/voltaire/Hex";
+import { Effect } from "effect";
+
+/**
+ * Assert that Hex is exactly the specified size.
+ *
+ * @param hex - Hex string to check
+ * @param targetSize - Expected size in bytes
+ * @returns Effect that succeeds with Sized<T> or fails with InvalidLengthError
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ * import { Effect } from 'effect'
+ *
+ * const sized = yield* Hex.assertSize('0x1234', 2)  // succeeds with Sized<2>
+ * yield* Hex.assertSize('0x1234', 4)  // fails with InvalidLengthError
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const assertSize = <TSize extends number>(
+	hex: HexType,
+	targetSize: TSize,
+): Effect.Effect<Sized<TSize>, InvalidLengthError> =>
+	Effect.try({
+		try: () => VoltaireHex.assertSize(hex, targetSize),
+		catch: (e) => e as InvalidLengthError,
+	});

package/src/primitives/Hex/concat.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Effect wrapper for Hex.concat.
+ * Concatenates multiple Hex strings.
+ * @module voltaire-effect/primitives/Hex/concat
+ * @since 0.1.0
+ */
+
+import {
+	type HexType,
+	Hex as VoltaireHex,
+	InvalidFormatError,
+} from "@tevm/voltaire/Hex";
+import { Effect } from "effect";
+
+/**
+ * Concatenate multiple Hex strings.
+ *
+ * @param hexes - Hex strings to concatenate
+ * @returns Effect with combined HexType or InvalidFormatError
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ * import { Effect } from 'effect'
+ *
+ * const combined = yield* Hex.concat('0x1234', '0x5678')  // '0x12345678'
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const concat = (
+	...hexes: readonly HexType[]
+): Effect.Effect<HexType, InvalidFormatError> =>
+	Effect.try({
+		try: () => VoltaireHex.concat(...hexes),
+		catch: (e) => e as InvalidFormatError,
+	});

package/src/primitives/Hex/from.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Effect wrapper for Hex.from.
+ * Parses any input to a validated Hex string.
+ * @module voltaire-effect/primitives/Hex/from
+ * @since 0.1.0
+ */
+
+import {
+	type HexType,
+	Hex as VoltaireHex,
+	InvalidFormatError,
+} from "@tevm/voltaire/Hex";
+import { Effect } from "effect";
+
+/**
+ * Parse any input (string or Uint8Array) to Hex.
+ *
+ * @param value - String or bytes to convert
+ * @returns Effect with HexType or InvalidFormatError
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ * import { Effect } from 'effect'
+ *
+ * const hex = yield* Hex.from('0xdeadbeef')
+ * const fromBytes = yield* Hex.from(new Uint8Array([0xde, 0xad]))
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const from = (
+	value: string | Uint8Array,
+): Effect.Effect<HexType, InvalidFormatError> =>
+	Effect.try({
+		try: () => VoltaireHex.from(value),
+		catch: (e) => e as InvalidFormatError,
+	});