voltaire-effect 0.2.23 → 0.2.24

package/src/primitives/Uint/dividedBy.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Effect-based Uint256 division.
+ * @module dividedBy
+ * @since 0.0.1
+ */
+
+import { Uint256, type Type as Uint256Type } from "@tevm/voltaire/Uint";
+import * as Effect from "effect/Effect";
+
+/**
+ * Divide two Uint256 values.
+ *
+ * @description
+ * Floor division (a / b). Fails if divisor is zero.
+ *
+ * @param a - Dividend
+ * @param b - Divisor
+ * @returns Effect yielding quotient
+ *
+ * @example
+ * ```typescript
+ * const quotient = Effect.runSync(Uint.dividedBy(a, b))
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const dividedBy = (
+	a: Uint256Type,
+	b: Uint256Type,
+): Effect.Effect<Uint256Type, Error> =>
+	Effect.try({
+		try: () => Uint256.dividedBy(a, b),
+		catch: (e) => (e instanceof Error ? e : new Error(String(e))),
+	});

package/src/primitives/Uint/from.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Effect-based Uint256 creation from various inputs.
+ * @module from
+ * @since 0.0.1
+ */
+
+import { Uint256, type Type as Uint256Type } from "@tevm/voltaire/Uint";
+import * as Effect from "effect/Effect";
+
+/**
+ * Create Uint256 from bigint, number, or string.
+ *
+ * @description
+ * Accepts decimal strings, hex strings (0x-prefixed), numbers, or bigints.
+ * Fails on invalid format, negative values, or overflow.
+ *
+ * @param value - Input value
+ * @returns Effect yielding Uint256
+ *
+ * @example
+ * ```typescript
+ * const a = Effect.runSync(Uint.from(100n))
+ * const b = Effect.runSync(Uint.from("0xff"))
+ * const c = Effect.runSync(Uint.from(42))
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const from = (
+	value: bigint | number | string,
+): Effect.Effect<Uint256Type, Error> =>
+	Effect.try({
+		try: () => Uint256.from(value),
+		catch: (e) => (e instanceof Error ? e : new Error(String(e))),
+	});

package/src/primitives/Uint/fromAbiEncoded.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Effect-based Uint256 creation from ABI-encoded bytes.
+ * @module fromAbiEncoded
+ * @since 0.0.1
+ */
+
+import { Uint256, type Type as Uint256Type } from "@tevm/voltaire/Uint";
+import * as Effect from "effect/Effect";
+
+/**
+ * Create Uint256 from ABI-encoded bytes (32 bytes, big-endian).
+ *
+ * @param data - 32-byte ABI-encoded data
+ * @returns Effect yielding Uint256
+ *
+ * @example
+ * ```typescript
+ * const value = Effect.runSync(Uint.fromAbiEncoded(bytes))
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const fromAbiEncoded = (
+	data: Uint8Array,
+): Effect.Effect<Uint256Type, Error> =>
+	Effect.try({
+		try: () => Uint256.fromAbiEncoded(data),
+		catch: (e) => (e instanceof Error ? e : new Error(String(e))),
+	});

package/src/primitives/Uint/fromBigInt.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Effect-based Uint256 creation from bigint.
+ * @module fromBigInt
+ * @since 0.0.1
+ */
+
+import { Uint256, type Type as Uint256Type } from "@tevm/voltaire/Uint";
+import * as Effect from "effect/Effect";
+
+/**
+ * Create Uint256 from bigint.
+ *
+ * @description
+ * Fails on negative values or values exceeding 2^256-1.
+ *
+ * @param value - bigint value
+ * @returns Effect yielding Uint256
+ *
+ * @example
+ * ```typescript
+ * const value = Effect.runSync(Uint.fromBigInt(1000000000000000000n))
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const fromBigInt = (value: bigint): Effect.Effect<Uint256Type, Error> =>
+	Effect.try({
+		try: () => Uint256.fromBigInt(value),
+		catch: (e) => (e instanceof Error ? e : new Error(String(e))),
+	});

package/src/primitives/Uint/fromBytes.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Effect-based Uint256 creation from bytes.
+ * @module fromBytes
+ * @since 0.0.1
+ */
+
+import { Uint256, type Type as Uint256Type } from "@tevm/voltaire/Uint";
+import * as Effect from "effect/Effect";
+
+/**
+ * Create Uint256 from bytes (big-endian).
+ *
+ * @description
+ * Interprets bytes as big-endian unsigned integer.
+ * Fails if bytes exceed 32 bytes.
+ *
+ * @param bytes - Input bytes
+ * @returns Effect yielding Uint256
+ *
+ * @example
+ * ```typescript
+ * const value = Effect.runSync(Uint.fromBytes(new Uint8Array([0xff])))
+ * // 255n
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const fromBytes = (bytes: Uint8Array): Effect.Effect<Uint256Type, Error> =>
+	Effect.try({
+		try: () => Uint256.fromBytes(bytes),
+		catch: (e) => (e instanceof Error ? e : new Error(String(e))),
+	});

package/src/primitives/Uint/fromHex.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Effect-based Uint256 creation from hex string.
+ * @module fromHex
+ * @since 0.0.1
+ */
+
+import { Uint256, type Type as Uint256Type } from "@tevm/voltaire/Uint";
+import * as Effect from "effect/Effect";
+
+/**
+ * Create Uint256 from hex string.
+ *
+ * @description
+ * Accepts hex strings with or without 0x prefix.
+ * Fails on invalid hex or overflow.
+ *
+ * @param hex - Hex string
+ * @returns Effect yielding Uint256
+ *
+ * @example
+ * ```typescript
+ * const value = Effect.runSync(Uint.fromHex("0xde0b6b3a7640000"))
+ * // 1000000000000000000n
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const fromHex = (hex: string): Effect.Effect<Uint256Type, Error> =>
+	Effect.try({
+		try: () => Uint256.fromHex(hex),
+		catch: (e) => (e instanceof Error ? e : new Error(String(e))),
+	});

package/src/primitives/Uint/fromNumber.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Effect-based Uint256 creation from number.
+ * @module fromNumber
+ * @since 0.0.1
+ */
+
+import { Uint256, type Type as Uint256Type } from "@tevm/voltaire/Uint";
+import * as Effect from "effect/Effect";
+
+/**
+ * Create Uint256 from number.
+ *
+ * @description
+ * Fails on negative, non-integer, or unsafe integer values.
+ *
+ * @param value - Number value
+ * @returns Effect yielding Uint256
+ *
+ * @example
+ * ```typescript
+ * const value = Effect.runSync(Uint.fromNumber(42))
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const fromNumber = (value: number): Effect.Effect<Uint256Type, Error> =>
+	Effect.try({
+		try: () => Uint256.fromNumber(value),
+		catch: (e) => (e instanceof Error ? e : new Error(String(e))),
+	});

package/src/primitives/Uint/index.ts

@@ -1,6 +1,6 @@
 /**
  * @module Uint
- * @description Effect Schemas for 256-bit unsigned integers (Uint256).
+ * @description Effect wrappers for 256-bit unsigned integers (Uint256).
  *
  * ## Schemas
  *
@@ -12,27 +12,43 @@
  * | `Uint.Hex` | hex string | Uint256Type |
  * | `Uint.Bytes` | Uint8Array | Uint256Type |
  *
- * ## Usage
+ * ## Constructors (Effect-wrapped)
  *
- * ```typescript
- * import * as Uint from 'voltaire-effect/primitives/Uint'
- * import * as S from 'effect/Schema'
+ * - `from`, `fromBigInt`, `fromNumber`, `fromHex`, `fromBytes`, `fromAbiEncoded`
+ * - `tryFrom` (returns Option)
  *
- * // Decode (parse input)
- * const value = S.decodeSync(Uint.BigInt)(1000000000000000000n)
+ * ## Type Guards (pure)
  *
- * // Encode (format output)
- * const bigint = S.encodeSync(Uint.BigInt)(value)
- * const hex = S.encodeSync(Uint.Hex)(value)
- * ```
+ * - `isUint256`, `isValid`
  *
- * ## Pure Functions
+ * ## Arithmetic (pure, wrapping)
+ *
+ * - `plus`, `minus`, `times`, `toPower`
+ *
+ * ## Arithmetic (Effect-wrapped, can fail)
+ *
+ * - `dividedBy`, `modulo` (division by zero)
+ *
+ * ## Bitwise (pure)
  *
- * Arithmetic, comparison, and bitwise operations are available as pure functions:
- * - `plus`, `minus`, `times`, `dividedBy`, `modulo`
- * - `equals`, `lessThan`, `greaterThan`, `lessThanOrEqual`, `greaterThanOrEqual`
  * - `bitwiseAnd`, `bitwiseOr`, `bitwiseXor`, `bitwiseNot`, `shiftLeft`, `shiftRight`
- * - `min`, `max`, `sum`, `product`, `gcd`, `lcm`
+ *
+ * ## Comparison (pure)
+ *
+ * - `equals`, `notEquals`, `lessThan`, `lessThanOrEqual`, `greaterThan`, `greaterThanOrEqual`, `isZero`
+ *
+ * ## Bit utilities (pure)
+ *
+ * - `bitLength`, `leadingZeros`, `popCount`, `isPowerOf2`
+ *
+ * ## Math utilities
+ *
+ * - `gcd`, `lcm`, `clone`
+ * - `min`, `max`, `minimum`, `maximum`, `sum`, `product` (Effect-wrapped)
+ *
+ * ## Converters (Effect-wrapped)
+ *
+ * - `toBigInt`, `toNumber`, `toHex`, `toBytes`, `toAbiEncoded`, `toString`
  *
  * @since 0.1.0
  */
@@ -40,46 +56,75 @@
 // Schemas
 export { BigInt } from "./BigInt.js";
 export { Bytes } from "./Bytes.js";
-// Bit utilities (infallible)
+export { Hex } from "./Hex.js";
+export { Number } from "./Number.js";
+export { String } from "./String.js";
+
+// Constructors (fallible)
+export { from } from "./from.js";
+export { fromAbiEncoded } from "./fromAbiEncoded.js";
+export { fromBigInt } from "./fromBigInt.js";
+export { fromBytes } from "./fromBytes.js";
+export { fromHex } from "./fromHex.js";
+export { fromNumber } from "./fromNumber.js";
+export { tryFrom } from "./tryFrom.js";
+
+// Type guards (pure)
+export { isUint256 } from "./isUint256.js";
+export { isValid } from "./isValid.js";
+
+// Bit utilities (pure)
 export { bitLength } from "./bitLength.js";
-// Bitwise (infallible)
+export { leadingZeros } from "./leadingZeros.js";
+export { popCount } from "./popCount.js";
+export { isPowerOf2 } from "./isPowerOf2.js";
+
+// Bitwise (pure)
 export { bitwiseAnd } from "./bitwiseAnd.js";
 export { bitwiseNot } from "./bitwiseNot.js";
 export { bitwiseOr } from "./bitwiseOr.js";
 export { bitwiseXor } from "./bitwiseXor.js";
-export { clone } from "./clone.js";
-// Arithmetic (failable - division by zero)
-// Comparison (infallible)
+export { shiftLeft } from "./shiftLeft.js";
+export { shiftRight } from "./shiftRight.js";
+
+// Comparison (pure)
 export { equals } from "./equals.js";
-// Math utilities (infallible)
-export { gcd } from "./gcd.js";
+export { notEquals } from "./notEquals.js";
+export { lessThan } from "./lessThan.js";
+export { lessThanOrEqual } from "./lessThanOrEqual.js";
 export { greaterThan } from "./greaterThan.js";
 export { greaterThanOrEqual } from "./greaterThanOrEqual.js";
-export { Hex } from "./Hex.js";
-export { isPowerOf2 } from "./isPowerOf2.js";
 export { isZero } from "./isZero.js";
+
+// Arithmetic (wrapping, pure)
+export { plus } from "./plus.js";
+export { minus } from "./minus.js";
+export { times } from "./times.js";
+export { toPower } from "./toPower.js";
+
+// Arithmetic (fallible - division by zero)
+export { dividedBy } from "./dividedBy.js";
+export { modulo } from "./modulo.js";
+
+// Math utilities (pure)
+export { gcd } from "./gcd.js";
 export { lcm } from "./lcm.js";
-export { leadingZeros } from "./leadingZeros.js";
-export { lessThan } from "./lessThan.js";
-export { lessThanOrEqual } from "./lessThanOrEqual.js";
-export { max } from "./max.js";
-export { maximum } from "./maximum.js";
+export { clone } from "./clone.js";
+
+// Min/Max (Effect-wrapped)
 export { min } from "./min.js";
-// Min/Max (infallible)
+export { max } from "./max.js";
 export { minimum } from "./minimum.js";
-export { minus } from "./minus.js";
-export { Number } from "./Number.js";
-export { notEquals } from "./notEquals.js";
-// Arithmetic (wrapping, infallible)
-export { plus } from "./plus.js";
-export { popCount } from "./popCount.js";
-export { product } from "./product.js";
-export { String } from "./String.js";
-export { shiftLeft } from "./shiftLeft.js";
-export { shiftRight } from "./shiftRight.js";
-// Aggregate (infallible)
+export { maximum } from "./maximum.js";
+
+// Aggregate (Effect-wrapped)
 export { sum } from "./sum.js";
-export { times } from "./times.js";
+export { product } from "./product.js";
+
+// Converters (Effect-wrapped)
 export { toAbiEncoded } from "./toAbiEncoded.js";
-// Converters (infallible)
-export { toPower } from "./toPower.js";
+export { toBigInt } from "./toBigInt.js";
+export { toBytes } from "./toBytes.js";
+export { toHex } from "./toHex.js";
+export { toNumber } from "./toNumber.js";
+export { toString } from "./toString.js";

package/src/primitives/Uint/isUint256.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Uint256 type guard.
+ * @module isUint256
+ * @since 0.0.1
+ */
+
+import { Uint256, type Type as Uint256Type } from "@tevm/voltaire/Uint";
+
+/**
+ * Type guard for Uint256.
+ *
+ * @param value - Value to check
+ * @returns true if value is valid Uint256
+ *
+ * @example
+ * ```typescript
+ * if (Uint.isUint256(value)) {
+ *   const hex = Uint.toHex(value)
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const isUint256 = (value: unknown): value is Uint256Type =>
+	Uint256.isValid(value);

package/src/primitives/Uint/isValid.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Uint256 validation check.
+ * @module isValid
+ * @since 0.0.1
+ */
+
+import { Uint256, type Type as Uint256Type } from "@tevm/voltaire/Uint";
+
+/**
+ * Check if value is a valid Uint256.
+ *
+ * @param value - Value to check
+ * @returns true if value is valid Uint256
+ *
+ * @example
+ * ```typescript
+ * Uint.isValid(100n) // true
+ * Uint.isValid(-1n) // false
+ * Uint.isValid("hello") // false
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const isValid = (value: unknown): value is Uint256Type =>
+	Uint256.isValid(value);

package/src/primitives/Uint/modulo.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Effect-based Uint256 modulo operation.
+ * @module modulo
+ * @since 0.0.1
+ */
+
+import { Uint256, type Type as Uint256Type } from "@tevm/voltaire/Uint";
+import * as Effect from "effect/Effect";
+
+/**
+ * Modulo operation on Uint256 values.
+ *
+ * @description
+ * Computes remainder (a % b). Fails if divisor is zero.
+ *
+ * @param a - Dividend
+ * @param b - Divisor
+ * @returns Effect yielding remainder
+ *
+ * @example
+ * ```typescript
+ * const remainder = Effect.runSync(Uint.modulo(a, b))
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const modulo = (
+	a: Uint256Type,
+	b: Uint256Type,
+): Effect.Effect<Uint256Type, Error> =>
+	Effect.try({
+		try: () => Uint256.modulo(a, b),
+		catch: (e) => (e instanceof Error ? e : new Error(String(e))),
+	});

package/src/primitives/Uint/toHex.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Effect-based Uint256 to hex string conversion.
+ * @module toHex
+ * @since 0.0.1
+ */
+
+import { Uint256, type Type as Uint256Type } from "@tevm/voltaire/Uint";
+import * as Effect from "effect/Effect";
+
+/**
+ * Converts a Uint256 to hex string.
+ *
+ * @param uint - The Uint256 to convert
+ * @param padded - Whether to pad to 64 characters (default true)
+ * @returns Effect yielding hex string with 0x prefix
+ *
+ * @example
+ * ```typescript
+ * const hex = Effect.runSync(Uint.toHex(uint))
+ * // "0x00000000000000000000000000000000000000000000000000000000000000ff"
+ *
+ * const unpadded = Effect.runSync(Uint.toHex(uint, false))
+ * // "0xff"
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const toHex = (
+	uint: Uint256Type,
+	padded?: boolean,
+): Effect.Effect<string> => Effect.sync(() => Uint256.toHex(uint, padded));

package/src/primitives/Uint/tryFrom.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Effect-based Uint256 try-from with Option result.
+ * @module tryFrom
+ * @since 0.0.1
+ */
+
+import { Uint256, type Type as Uint256Type } from "@tevm/voltaire/Uint";
+import * as Option from "effect/Option";
+
+/**
+ * Try to create Uint256, returns Option.
+ *
+ * @description
+ * Returns Some(value) on success, None on failure.
+ * Does not throw.
+ *
+ * @param value - Input value
+ * @returns Option of Uint256
+ *
+ * @example
+ * ```typescript
+ * const result = Uint.tryFrom(100n) // Some(100n)
+ * const invalid = Uint.tryFrom(-1n) // None
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const tryFrom = (
+	value: bigint | number | string,
+): Option.Option<Uint256Type> => Option.fromNullable(Uint256.tryFrom(value));