voltaire-effect 0.2.23 → 0.2.24

package/src/primitives/Hex/fromBigInt.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Effect wrapper for Hex.fromBigInt.
+ * Converts a bigint to Hex string.
+ * @module voltaire-effect/primitives/Hex/fromBigInt
+ * @since 0.1.0
+ */
+
+import {
+	type HexType,
+	Hex as VoltaireHex,
+	NegativeNumberError,
+} from "@tevm/voltaire/Hex";
+import { Effect } from "effect";
+
+/**
+ * Convert bigint to Hex string.
+ *
+ * @param value - BigInt to convert
+ * @param size - Optional byte size for padding
+ * @returns Effect with HexType or NegativeNumberError
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ * import { Effect } from 'effect'
+ *
+ * const hex = yield* Hex.fromBigInt(255n)        // '0xff'
+ * const padded = yield* Hex.fromBigInt(255n, 2)  // '0x00ff'
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const fromBigInt = (
+	value: bigint,
+	size?: number,
+): Effect.Effect<HexType, NegativeNumberError> =>
+	Effect.try({
+		try: () => VoltaireHex.fromBigInt(value, size),
+		catch: (e) => e as NegativeNumberError,
+	});

package/src/primitives/Hex/fromBoolean.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Effect wrapper for Hex.fromBoolean.
+ * Converts a boolean to Hex string.
+ * @module voltaire-effect/primitives/Hex/fromBoolean
+ * @since 0.1.0
+ */
+
+import { type Sized, Hex as VoltaireHex } from "@tevm/voltaire/Hex";
+
+/**
+ * Convert boolean to Hex string.
+ *
+ * This is an infallible operation - booleans always convert cleanly.
+ *
+ * @param value - Boolean to convert
+ * @returns Hex string ('0x01' for true, '0x00' for false)
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ *
+ * Hex.fromBoolean(true)   // '0x01'
+ * Hex.fromBoolean(false)  // '0x00'
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const fromBoolean = (value: boolean): Sized<1> =>
+	VoltaireHex.fromBoolean(value);

package/src/primitives/Hex/fromNumber.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Effect wrapper for Hex.fromNumber.
+ * Converts a number to Hex string.
+ * @module voltaire-effect/primitives/Hex/fromNumber
+ * @since 0.1.0
+ */
+
+import {
+	type HexType,
+	Hex as VoltaireHex,
+	NegativeNumberError,
+	NonIntegerError,
+} from "@tevm/voltaire/Hex";
+import { Effect } from "effect";
+
+/**
+ * Convert number to Hex string.
+ *
+ * @param value - Number to convert (must be non-negative integer)
+ * @param size - Optional byte size for padding
+ * @returns Effect with HexType or error
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ * import { Effect } from 'effect'
+ *
+ * const hex = yield* Hex.fromNumber(255)      // '0xff'
+ * const padded = yield* Hex.fromNumber(255, 2)  // '0x00ff'
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const fromNumber = (
+	value: number,
+	size?: number,
+): Effect.Effect<HexType, NegativeNumberError | NonIntegerError> =>
+	Effect.try({
+		try: () => VoltaireHex.fromNumber(value, size),
+		catch: (e) => e as NegativeNumberError | NonIntegerError,
+	});

package/src/primitives/Hex/fromString.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Effect wrapper for Hex.fromString.
+ * Converts a UTF-8 string to Hex (encodes string bytes).
+ * @module voltaire-effect/primitives/Hex/fromString
+ * @since 0.1.0
+ */
+
+import { type HexType, Hex as VoltaireHex } from "@tevm/voltaire/Hex";
+
+/**
+ * Convert UTF-8 string to Hex (encodes string bytes).
+ *
+ * This is an infallible operation - any string can be encoded.
+ *
+ * @param value - UTF-8 string to encode
+ * @returns Hex-encoded string bytes
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ *
+ * Hex.fromString('hello')  // '0x68656c6c6f'
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const fromString = (value: string): HexType =>
+	VoltaireHex.fromString(value);

package/src/primitives/Hex/index.ts

@@ -1,6 +1,6 @@
 /**
  * @module Hex
- * @description Effect Schemas for Ethereum hex strings.
+ * @description Effect wrappers for Ethereum hex strings.
  *
  * ## Type Declarations
  *
@@ -19,64 +19,95 @@
  * | `Hex.String` | string | HexType |
  * | `Hex.Bytes` | Uint8Array | HexType |
  *
- * ## Usage
- *
- * ```typescript
- * import * as Hex from 'voltaire-effect/primitives/Hex'
- * import * as S from 'effect/Schema'
- *
- * // Decode (parse input)
- * const hex = S.decodeSync(Hex.String)('0xdeadbeef')
- *
- * // Encode (format output)
- * const str = S.encodeSync(Hex.String)(hex)
- *
- * // From bytes
- * const hexFromBytes = S.decodeSync(Hex.Bytes)(new Uint8Array([0xde, 0xad]))
- * const bytes = S.encodeSync(Hex.Bytes)(hex)
- * ```
- *
  * ## API Design
  *
- * This module follows Effect best practices for function signatures:
+ * This module follows Effect best practices:
  *
  * ### Direct Return (Infallible Operations)
- * Operations that cannot fail return their value directly:
  * - `clone(hex)` - HexType
  * - `equals(a, b)` - boolean
  * - `isHex(str)` - boolean
  * - `isSized(hex, size)` - boolean
  * - `zero(size)` - HexType
  * - `random(size)` - HexType
+ * - `fromBoolean(bool)` - Sized<1>
+ * - `fromString(str)` - HexType
+ * - `trim(hex)` - HexType
+ * - `size(hex)` - number
+ * - `toBigInt(hex)` - bigint
  *
  * ### Effect Return (Fallible Operations)
- * Operations that can fail return Effect with typed error:
- * - Schema decode/encode operations via `S.decodeSync(Hex.String)(...)` etc.
- *
- * @example
- * ```typescript
- * // Infallible - use directly
- * const cloned = Hex.clone(hex);
- * const isValid = Hex.isHex('0x1234');
- * const zeros = Hex.zero(32);
- * const rand = Hex.random(16);
- *
- * // Fallible - use Schema
- * const parsed = S.decodeSync(Hex.String)('0x...');
- * ```
+ * - `from(value)` - Effect<HexType, InvalidFormatError>
+ * - `fromBigInt(value, size?)` - Effect<HexType, NegativeNumberError>
+ * - `fromNumber(value, size?)` - Effect<HexType, NegativeNumberError | NonIntegerError>
+ * - `toBoolean(hex)` - Effect<boolean, InvalidBooleanHexError>
+ * - `toNumber(hex)` - Effect<number, UnsafeIntegerError>
+ * - `toStringHex(hex)` - Effect<string, InvalidFormatError>
+ * - `concat(...hexes)` - Effect<HexType, InvalidFormatError>
+ * - `pad(hex, size)` - Effect<HexType, SizeExceededError | InvalidSizeError>
+ * - `padRight(hex, size)` - Effect<HexType, InvalidSizeError>
+ * - `slice(hex, start, end?)` - Effect<HexType, InvalidSizeError>
+ * - `validate(value)` - Effect<HexType, InvalidFormatError>
+ * - `xor(hex, other)` - Effect<HexType, InvalidLengthError>
+ * - `assertSize(hex, size)` - Effect<Sized<T>, InvalidLengthError>
  *
  * @since 0.1.0
  */
 
-export type { Hex as HexBrand, HexType } from "@tevm/voltaire/Hex";
+export type { Hex as HexBrand, HexType, Sized } from "@tevm/voltaire/Hex";
+
+// Re-export error types for typed error handling
+export {
+	InvalidBooleanHexError,
+	InvalidCharacterError,
+	InvalidFormatError,
+	InvalidHexCharacterError,
+	InvalidHexFormatError,
+	InvalidHexLengthError,
+	InvalidLengthError,
+	InvalidSizeError,
+	NegativeNumberError,
+	NonIntegerError,
+	OddLengthError,
+	OddLengthHexError,
+	SizeExceededError,
+	UnsafeIntegerError,
+} from "@tevm/voltaire/Hex";
+
+// Re-export direct conversion functions from voltaire for convenience
+export { fromBytes, toBytes } from "@tevm/voltaire/Hex";
+
+// Re-export the Hex namespace constructor
+export { Hex } from "@tevm/voltaire/Hex";
 
 // Schemas
 export { Bytes } from "./Bytes.js";
-// Pure functions
+export { String } from "./String.js";
+
+// Pure functions (infallible)
 export { clone } from "./clone.js";
 export { equals } from "./equals.js";
+export { fromBoolean } from "./fromBoolean.js";
+export { fromString } from "./fromString.js";
 export { isHex } from "./isHex.js";
 export { isSized } from "./isSized.js";
 export { random } from "./random.js";
-export { String } from "./String.js";
+export { size } from "./size.js";
+export { toBigInt } from "./toBigInt.js";
+export { trim } from "./trim.js";
 export { zero } from "./zero.js";
+
+// Effect-returning functions (fallible)
+export { assertSize } from "./assertSize.js";
+export { concat } from "./concat.js";
+export { from } from "./from.js";
+export { fromBigInt } from "./fromBigInt.js";
+export { fromNumber } from "./fromNumber.js";
+export { pad } from "./pad.js";
+export { padRight } from "./padRight.js";
+export { slice } from "./slice.js";
+export { toBoolean } from "./toBoolean.js";
+export { toNumber } from "./toNumber.js";
+export { toStringHex } from "./toStringHex.js";
+export { validate } from "./validate.js";
+export { xor } from "./xor.js";

package/src/primitives/Hex/pad.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Effect wrapper for Hex.pad.
+ * Left-pads Hex to target size with zeros.
+ * @module voltaire-effect/primitives/Hex/pad
+ * @since 0.1.0
+ */
+
+import {
+	type HexType,
+	Hex as VoltaireHex,
+	SizeExceededError,
+	InvalidSizeError,
+} from "@tevm/voltaire/Hex";
+import { Effect } from "effect";
+
+/**
+ * Left-pad Hex to target size with zeros.
+ *
+ * @param hex - Hex string to pad
+ * @param targetSize - Target size in bytes
+ * @returns Effect with padded HexType or SizeExceededError/InvalidSizeError
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ * import { Effect } from 'effect'
+ *
+ * const padded = yield* Hex.pad('0x12', 4)  // '0x00000012'
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const pad = (
+	hex: HexType,
+	targetSize: number,
+): Effect.Effect<HexType, SizeExceededError | InvalidSizeError> =>
+	Effect.try({
+		try: () => VoltaireHex.pad(hex, targetSize) as HexType,
+		catch: (e) => e as SizeExceededError | InvalidSizeError,
+	});

package/src/primitives/Hex/padRight.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Effect wrapper for Hex.padRight.
+ * Right-pads Hex to target size with zeros.
+ * @module voltaire-effect/primitives/Hex/padRight
+ * @since 0.1.0
+ */
+
+import {
+	type HexType,
+	Hex as VoltaireHex,
+	InvalidSizeError,
+} from "@tevm/voltaire/Hex";
+import { Effect } from "effect";
+
+/**
+ * Right-pad Hex to target size with zeros.
+ *
+ * @param hex - Hex string to pad
+ * @param targetSize - Target size in bytes
+ * @returns Effect with padded HexType or InvalidSizeError
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ * import { Effect } from 'effect'
+ *
+ * const padded = yield* Hex.padRight('0x12', 4)  // '0x12000000'
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const padRight = (
+	hex: HexType,
+	targetSize: number,
+): Effect.Effect<HexType, InvalidSizeError> =>
+	Effect.try({
+		try: () => VoltaireHex.padRight(hex, targetSize) as HexType,
+		catch: (e) => e as InvalidSizeError,
+	});

package/src/primitives/Hex/size.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Hex size function.
+ * Returns the byte size of a Hex string.
+ * @module voltaire-effect/primitives/Hex/size
+ * @since 0.1.0
+ */
+
+import { type HexType, Hex as VoltaireHex } from "@tevm/voltaire/Hex";
+
+/**
+ * Get the byte size of a Hex string.
+ *
+ * This is an infallible operation.
+ *
+ * @param hex - Hex string
+ * @returns Size in bytes
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ *
+ * Hex.size('0x1234')      // 2
+ * Hex.size('0xdeadbeef')  // 4
+ * Hex.size('0x')          // 0
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const size = (hex: HexType): number => VoltaireHex.size(hex);

package/src/primitives/Hex/slice.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Effect wrapper for Hex.slice.
+ * Extracts a portion of Hex by byte indices.
+ * @module voltaire-effect/primitives/Hex/slice
+ * @since 0.1.0
+ */
+
+import {
+	type HexType,
+	Hex as VoltaireHex,
+	InvalidSizeError,
+} from "@tevm/voltaire/Hex";
+import { Effect } from "effect";
+
+/**
+ * Slice Hex string by byte indices.
+ *
+ * @param hex - Hex string to slice
+ * @param start - Start byte index
+ * @param end - End byte index (optional)
+ * @returns Effect with sliced HexType or InvalidSizeError
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ * import { Effect } from 'effect'
+ *
+ * const sliced = yield* Hex.slice('0x123456', 1)      // '0x3456'
+ * const range = yield* Hex.slice('0x123456', 0, 1)   // '0x12'
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const slice = (
+	hex: HexType,
+	start: number,
+	end?: number,
+): Effect.Effect<HexType, InvalidSizeError> =>
+	Effect.try({
+		try: () => VoltaireHex.slice(hex, start, end),
+		catch: (e) => e as InvalidSizeError,
+	});

package/src/primitives/Hex/toBigInt.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Effect wrapper for Hex.toBigInt.
+ * Converts Hex to bigint.
+ * @module voltaire-effect/primitives/Hex/toBigInt
+ * @since 0.1.0
+ */
+
+import { type HexType, Hex as VoltaireHex } from "@tevm/voltaire/Hex";
+
+/**
+ * Convert Hex to bigint.
+ *
+ * This is an infallible operation - hex always converts to bigint.
+ *
+ * @param hex - Hex string to convert
+ * @returns bigint value
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ *
+ * Hex.toBigInt('0xff' as HexType)  // 255n
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const toBigInt = (hex: HexType): bigint => VoltaireHex.toBigInt(hex);

package/src/primitives/Hex/toBoolean.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Effect wrapper for Hex.toBoolean.
+ * Converts Hex to boolean.
+ * @module voltaire-effect/primitives/Hex/toBoolean
+ * @since 0.1.0
+ */
+
+import {
+	type HexType,
+	Hex as VoltaireHex,
+	InvalidBooleanHexError,
+} from "@tevm/voltaire/Hex";
+import { Effect } from "effect";
+
+/**
+ * Convert Hex to boolean.
+ *
+ * @param hex - Hex string ('0x01'/'0x1' for true, '0x00'/'0x0' for false)
+ * @returns Effect with boolean or InvalidBooleanHexError
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ * import { Effect } from 'effect'
+ *
+ * const t = yield* Hex.toBoolean('0x01')  // true
+ * const f = yield* Hex.toBoolean('0x00')  // false
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const toBoolean = (
+	hex: HexType,
+): Effect.Effect<boolean, InvalidBooleanHexError> =>
+	Effect.try({
+		try: () => VoltaireHex.toBoolean(hex),
+		catch: (e) => e as InvalidBooleanHexError,
+	});

package/src/primitives/Hex/toNumber.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Effect wrapper for Hex.toNumber.
+ * Converts Hex to number.
+ * @module voltaire-effect/primitives/Hex/toNumber
+ * @since 0.1.0
+ */
+
+import {
+	type HexType,
+	Hex as VoltaireHex,
+	UnsafeIntegerError,
+} from "@tevm/voltaire/Hex";
+import { Effect } from "effect";
+
+/**
+ * Convert Hex to number.
+ *
+ * @param hex - Hex string to convert
+ * @returns Effect with number or UnsafeIntegerError
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ * import { Effect } from 'effect'
+ *
+ * const value = yield* Hex.toNumber('0xff')  // 255
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const toNumber = (
+	hex: HexType,
+): Effect.Effect<number, UnsafeIntegerError> =>
+	Effect.try({
+		try: () => VoltaireHex.toNumber(hex),
+		catch: (e) => e as UnsafeIntegerError,
+	});

package/src/primitives/Hex/toStringHex.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Effect wrapper for Hex.toString.
+ * Decodes Hex to UTF-8 string.
+ * @module voltaire-effect/primitives/Hex/toStringHex
+ * @since 0.1.0
+ */
+
+import {
+	type HexType,
+	Hex as VoltaireHex,
+	InvalidFormatError,
+} from "@tevm/voltaire/Hex";
+import { Effect } from "effect";
+
+/**
+ * Decode Hex to UTF-8 string.
+ *
+ * Note: Named `toStringHex` to avoid conflict with native `toString`.
+ *
+ * @param hex - Hex string to decode
+ * @returns Effect with decoded string or InvalidFormatError
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ * import { Effect } from 'effect'
+ *
+ * const str = yield* Hex.toStringHex('0x68656c6c6f')  // 'hello'
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const toStringHex = (
+	hex: HexType,
+): Effect.Effect<string, InvalidFormatError> =>
+	Effect.try({
+		try: () => VoltaireHex.toString(hex),
+		catch: (e) => e as InvalidFormatError,
+	});

package/src/primitives/Hex/trim.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Effect wrapper for Hex.trim.
+ * Trims leading zeros from Hex.
+ * @module voltaire-effect/primitives/Hex/trim
+ * @since 0.1.0
+ */
+
+import { type HexType, Hex as VoltaireHex } from "@tevm/voltaire/Hex";
+
+/**
+ * Trim leading zeros from Hex.
+ *
+ * This is an infallible operation.
+ *
+ * @param hex - Hex string to trim
+ * @returns Trimmed HexType
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ *
+ * Hex.trim('0x00001234')  // '0x1234'
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const trim = (hex: HexType): HexType => VoltaireHex.trim(hex);

package/src/primitives/Hex/validate.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Effect wrapper for Hex.validate.
+ * Validates and returns Hex string.
+ * @module voltaire-effect/primitives/Hex/validate
+ * @since 0.1.0
+ */
+
+import {
+	type HexType,
+	Hex as VoltaireHex,
+	InvalidFormatError,
+} from "@tevm/voltaire/Hex";
+import { Effect } from "effect";
+
+/**
+ * Validate and return Hex string.
+ *
+ * @param value - String to validate
+ * @returns Effect with validated HexType or InvalidFormatError
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ * import { Effect } from 'effect'
+ *
+ * const valid = yield* Hex.validate('0x1234')
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const validate = (
+	value: string,
+): Effect.Effect<HexType, InvalidFormatError> =>
+	Effect.try({
+		try: () => VoltaireHex.validate(value),
+		catch: (e) => e as InvalidFormatError,
+	});

package/src/primitives/Hex/xor.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Effect wrapper for Hex.xor.
+ * XORs two Hex strings.
+ * @module voltaire-effect/primitives/Hex/xor
+ * @since 0.1.0
+ */
+
+import {
+	type HexType,
+	Hex as VoltaireHex,
+	InvalidLengthError,
+} from "@tevm/voltaire/Hex";
+import { Effect } from "effect";
+
+/**
+ * XOR two Hex strings.
+ *
+ * @param hex - First Hex string
+ * @param other - Second Hex string
+ * @returns Effect with XOR result or InvalidLengthError if lengths don't match
+ *
+ * @example
+ * ```ts
+ * import * as Hex from 'voltaire-effect/primitives/Hex'
+ * import { Effect } from 'effect'
+ *
+ * const result = yield* Hex.xor('0xff00', '0x00ff')  // '0xffff'
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const xor = (
+	hex: HexType,
+	other: HexType,
+): Effect.Effect<HexType, InvalidLengthError> =>
+	Effect.try({
+		try: () => VoltaireHex.xor(hex, other),
+		catch: (e) => e as InvalidLengthError,
+	});