voltaire-effect 0.2.23

package/src/primitives/Uint64/Uint64Schema.ts

@@ -0,0 +1,122 @@
+/**
+ * @fileoverview Effect Schema definition for Uint64 validation and transformation.
+ *
+ * Provides type-safe schema for validating and transforming values into Uint64,
+ * supporting number, bigint, and string inputs with range validation (0 to 2^64-1).
+ *
+ * @module Uint64/Uint64Schema
+ * @since 0.0.1
+ */
+
+import { Uint64 } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Type representing a 64-bit unsigned integer (0 to 2^64-1).
+ *
+ * @description
+ * Branded type for Uint64 values, ensuring type safety at compile time.
+ * Values are validated to be within the range 0 to 18446744073709551615 inclusive.
+ *
+ * Min value: 0
+ * Max value: 18446744073709551615 (2^64 - 1)
+ *
+ * @example
+ * ```typescript
+ * import type { Uint64Type } from '@voltaire-effect/primitives/Uint64'
+ *
+ * function processValue(value: Uint64Type): void {
+ *   // Type-safe: only valid Uint64 values accepted
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ */
+export type Uint64Type = ReturnType<typeof Uint64.from>;
+
+/**
+ * Internal schema declaration for Uint64 type validation.
+ *
+ * @description
+ * Declares the Uint64 branded type for use in Effect Schema transformations.
+ * Validates that values are bigints within the valid Uint64 range.
+ *
+ * @internal
+ * @since 0.0.1
+ */
+const Uint64TypeSchema = S.declare<Uint64Type>(
+	(u): u is Uint64Type => {
+		if (typeof u !== "bigint") return false;
+		return Uint64.isValid(u);
+	},
+	{ identifier: "Uint64" },
+);
+
+/**
+ * Effect Schema for validating and transforming 64-bit unsigned integers.
+ *
+ * @description
+ * Accepts number, bigint, or string inputs and validates them as Uint64 values.
+ * Valid range: 0 to 18446744073709551615 (2^64 - 1).
+ *
+ * Input types:
+ * - `number`: Must be a non-negative integer (precision may be lost for values > 2^53-1)
+ * - `bigint`: Must be in range 0n to 18446744073709551615n
+ * - `string`: Must parse to an integer in the valid range
+ *
+ * Encoding converts the Uint64 back to a bigint for serialization.
+ *
+ * @example
+ * ```typescript
+ * import * as Schema from 'effect/Schema'
+ * import { Schema as Uint64Schema } from '@voltaire-effect/primitives/Uint64'
+ *
+ * // Decode from bigint
+ * const fromBigInt = Schema.decodeSync(Uint64Schema)(18446744073709551615n)
+ *
+ * // Decode from number (for safe integers)
+ * const fromNumber = Schema.decodeSync(Uint64Schema)(1000000000000)
+ *
+ * // Decode from string
+ * const fromString = Schema.decodeSync(Uint64Schema)('9223372036854775808')
+ *
+ * // Encode back to bigint
+ * const encoded = Schema.encodeSync(Uint64Schema)(fromBigInt)
+ * console.log(typeof encoded) // 'bigint'
+ *
+ * // Error cases
+ * Schema.decodeSync(Uint64Schema)(2n ** 64n)  // ParseError: out of range
+ * Schema.decodeSync(Uint64Schema)(-1n)        // ParseError: out of range
+ *
+ * // Use in Effect pipelines
+ * import * as Effect from 'effect/Effect'
+ * const parsed = Effect.runSync(Schema.decode(Uint64Schema)(1000000000000n))
+ * ```
+ *
+ * @throws {ParseError} When value is negative
+ * @throws {ParseError} When value exceeds 2^64-1
+ * @throws {ParseError} When string cannot be parsed as integer
+ *
+ * @see {@link Uint64Type} for the resulting type
+ *
+ * @since 0.0.1
+ */
+export const Schema: S.Schema<Uint64Type, number | bigint | string> =
+	S.transformOrFail(
+		S.Union(S.Number, S.BigIntFromSelf, S.String),
+		Uint64TypeSchema,
+		{
+			strict: true,
+			decode: (value, _options, ast) => {
+				try {
+					return ParseResult.succeed(Uint64.from(value));
+				} catch (e) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, value, (e as Error).message),
+					);
+				}
+			},
+			encode: (i) => ParseResult.succeed(i as bigint),
+		},
+	).annotations({ identifier: "Uint64Schema" });

package/src/primitives/Uint64/index.ts

@@ -0,0 +1,71 @@
+/**
+ * @module Uint64
+ * @description Effect Schemas for 64-bit unsigned integers (0 to 2^64-1).
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as Uint64 from 'voltaire-effect/primitives/Uint64'
+ *
+ * function setFileSize(bytes: Uint64.Uint64Type) {
+ *   // ...
+ * }
+ * ```
+ *
+ * ## Schemas
+ *
+ * | Schema | Input | Output |
+ * |--------|-------|--------|
+ * | `Uint64.String` | decimal string | Uint64Type |
+ * | `Uint64.Number` | number | Uint64Type |
+ * | `Uint64.BigInt` | bigint | Uint64Type |
+ * | `Uint64.Hex` | hex string | Uint64Type |
+ * | `Uint64.Bytes` | Uint8Array | Uint64Type |
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import * as Uint64 from 'voltaire-effect/primitives/Uint64'
+ * import * as S from 'effect/Schema'
+ *
+ * // Decode (parse input)
+ * const value = S.decodeSync(Uint64.BigInt)(18446744073709551615n)
+ *
+ * // Encode (format output)
+ * const bigint = S.encodeSync(Uint64.BigInt)(value)
+ * const hex = S.encodeSync(Uint64.Hex)(value)
+ * ```
+ *
+ * ## Pure Functions
+ *
+ * - `equals`, `plus`, `minus`, `times`
+ * - `toBigInt`, `toNumber`, `toHex`
+ * - Constants: `MAX`, `MIN`, `ZERO`, `ONE`
+ *
+ * @since 0.1.0
+ */
+
+// Schemas
+export { BigInt } from "./BigInt.js";
+export { Bytes } from "./Bytes.js";
+export { Hex } from "./Hex.js";
+export { Number } from "./Number.js";
+export { String } from "./String.js";
+
+// Re-export pure functions from voltaire
+import { Uint64 } from "@tevm/voltaire";
+
+export const equals = Uint64.equals;
+export const plus = Uint64.plus;
+export const minus = Uint64.minus;
+export const times = Uint64.times;
+export const toBigInt = Uint64.toBigInt;
+export const toNumber = Uint64.toNumber;
+export const toHex = Uint64.toHex;
+export const MAX = Uint64.MAX;
+export const MIN = Uint64.MIN;
+export const ZERO = Uint64.ZERO;
+export const ONE = Uint64.ONE;
+
+// Type export
+export type { Uint64Type } from "./Uint64Schema.js";

package/src/primitives/Uint8/BigInt.ts

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Schema for Uint8 encoded as a bigint.
+ * @module Uint8/BigInt
+ * @since 0.1.0
+ */
+
+import { BrandedUint8 } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+type Uint8Type = ReturnType<typeof BrandedUint8.from>;
+
+const Uint8TypeSchema = S.declare<Uint8Type>(
+	(u): u is Uint8Type => typeof u === "number" && BrandedUint8.isValid(u),
+	{ identifier: "Uint8" },
+);
+
+/**
+ * Schema for Uint8 encoded as a bigint.
+ *
+ * @example Decoding
+ * ```typescript
+ * import * as Uint8 from 'voltaire-effect/primitives/Uint8'
+ * import * as S from 'effect/Schema'
+ *
+ * const value = S.decodeSync(Uint8.BigInt)(255n)
+ * ```
+ *
+ * @example Encoding
+ * ```typescript
+ * const bigint = S.encodeSync(Uint8.BigInt)(value)
+ * // 255n
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const BigInt: S.Schema<Uint8Type, bigint> = S.transformOrFail(
+	S.BigIntFromSelf,
+	Uint8TypeSchema,
+	{
+		strict: true,
+		decode: (n, _options, ast) => {
+			try {
+				return ParseResult.succeed(
+					BrandedUint8.fromNumber(globalThis.Number(n)),
+				);
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, n, (e as Error).message),
+				);
+			}
+		},
+		encode: (uint, _options, _ast) => {
+			return ParseResult.succeed(BrandedUint8.toBigint(uint));
+		},
+	},
+).annotations({ identifier: "Uint8.BigInt" });

package/src/primitives/Uint8/Bytes.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Schema for Uint8 encoded as bytes.
+ * @module Uint8/Bytes
+ * @since 0.1.0
+ */
+
+import { BrandedUint8 } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+type Uint8Type = ReturnType<typeof BrandedUint8.from>;
+
+const Uint8TypeSchema = S.declare<Uint8Type>(
+	(u): u is Uint8Type => typeof u === "number" && BrandedUint8.isValid(u),
+	{ identifier: "Uint8" },
+);
+
+/**
+ * Schema for Uint8 encoded as a Uint8Array (single byte).
+ *
+ * @example Decoding
+ * ```typescript
+ * import * as Uint8 from 'voltaire-effect/primitives/Uint8'
+ * import * as S from 'effect/Schema'
+ *
+ * const value = S.decodeSync(Uint8.Bytes)(new Uint8Array([255]))
+ * ```
+ *
+ * @example Encoding
+ * ```typescript
+ * const bytes = S.encodeSync(Uint8.Bytes)(value)
+ * // Uint8Array([255])
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const Bytes: S.Schema<Uint8Type, Uint8Array> = S.transformOrFail(
+	S.Uint8ArrayFromSelf,
+	Uint8TypeSchema,
+	{
+		strict: true,
+		decode: (bytes, _options, ast) => {
+			try {
+				return ParseResult.succeed(BrandedUint8.fromBytes(bytes));
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, bytes, (e as Error).message),
+				);
+			}
+		},
+		encode: (uint, _options, _ast) => {
+			return ParseResult.succeed(BrandedUint8.toBytes(uint));
+		},
+	},
+).annotations({ identifier: "Uint8.Bytes" });

package/src/primitives/Uint8/Hex.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Schema for Uint8 encoded as a hex string.
+ * @module Uint8/Hex
+ * @since 0.1.0
+ */
+
+import { BrandedUint8 } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+type Uint8Type = ReturnType<typeof BrandedUint8.from>;
+
+const Uint8TypeSchema = S.declare<Uint8Type>(
+	(u): u is Uint8Type => typeof u === "number" && BrandedUint8.isValid(u),
+	{ identifier: "Uint8" },
+);
+
+/**
+ * Schema for Uint8 encoded as a hex string.
+ *
+ * @example Decoding
+ * ```typescript
+ * import * as Uint8 from 'voltaire-effect/primitives/Uint8'
+ * import * as S from 'effect/Schema'
+ *
+ * const value = S.decodeSync(Uint8.Hex)('0xff')
+ * ```
+ *
+ * @example Encoding
+ * ```typescript
+ * const hex = S.encodeSync(Uint8.Hex)(value)
+ * // "0xff"
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const Hex: S.Schema<Uint8Type, string> = S.transformOrFail(
+	S.String,
+	Uint8TypeSchema,
+	{
+		strict: true,
+		decode: (hex, _options, ast) => {
+			try {
+				return ParseResult.succeed(BrandedUint8.fromHex(hex));
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, hex, (e as Error).message),
+				);
+			}
+		},
+		encode: (uint, _options, _ast) => {
+			return ParseResult.succeed(BrandedUint8.toHex(uint));
+		},
+	},
+).annotations({ identifier: "Uint8.Hex" });

package/src/primitives/Uint8/Number.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Schema for Uint8 encoded as a JavaScript number.
+ * @module Uint8/Number
+ * @since 0.1.0
+ */
+
+import { BrandedUint8 } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+type Uint8Type = ReturnType<typeof BrandedUint8.from>;
+
+const Uint8TypeSchema = S.declare<Uint8Type>(
+	(u): u is Uint8Type => typeof u === "number" && BrandedUint8.isValid(u),
+	{ identifier: "Uint8" },
+);
+
+/**
+ * Schema for Uint8 encoded as a JavaScript number (0-255).
+ *
+ * @example Decoding
+ * ```typescript
+ * import * as Uint8 from 'voltaire-effect/primitives/Uint8'
+ * import * as S from 'effect/Schema'
+ *
+ * const value = S.decodeSync(Uint8.Number)(255)
+ * ```
+ *
+ * @example Encoding
+ * ```typescript
+ * const num = S.encodeSync(Uint8.Number)(value)
+ * // 255
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const Number: S.Schema<Uint8Type, number> = S.transformOrFail(
+	S.Number,
+	Uint8TypeSchema,
+	{
+		strict: true,
+		decode: (n, _options, ast) => {
+			try {
+				return ParseResult.succeed(BrandedUint8.from(n));
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, n, (e as Error).message),
+				);
+			}
+		},
+		encode: (uint, _options, _ast) => {
+			return ParseResult.succeed(BrandedUint8.toNumber(uint));
+		},
+	},
+).annotations({ identifier: "Uint8.Number" });

package/src/primitives/Uint8/String.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Schema for Uint8 encoded as a decimal string.
+ * @module Uint8/String
+ * @since 0.1.0
+ */
+
+import { BrandedUint8 } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+type Uint8Type = ReturnType<typeof BrandedUint8.from>;
+
+const Uint8TypeSchema = S.declare<Uint8Type>(
+	(u): u is Uint8Type => typeof u === "number" && BrandedUint8.isValid(u),
+	{ identifier: "Uint8" },
+);
+
+/**
+ * Schema for Uint8 encoded as a decimal string.
+ *
+ * @example Decoding
+ * ```typescript
+ * import * as Uint8 from 'voltaire-effect/primitives/Uint8'
+ * import * as S from 'effect/Schema'
+ *
+ * const value = S.decodeSync(Uint8.String)('255')
+ * ```
+ *
+ * @example Encoding
+ * ```typescript
+ * const str = S.encodeSync(Uint8.String)(value)
+ * // "255"
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const String: S.Schema<Uint8Type, string> = S.transformOrFail(
+	S.String,
+	Uint8TypeSchema,
+	{
+		strict: true,
+		decode: (s, _options, ast) => {
+			try {
+				return ParseResult.succeed(BrandedUint8.from(s));
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, s, (e as Error).message),
+				);
+			}
+		},
+		encode: (uint, _options, _ast) => {
+			return ParseResult.succeed(BrandedUint8.toString(uint));
+		},
+	},
+).annotations({ identifier: "Uint8.String" });