@evolu/common 5.4.7 → 6.0.0

package/dist/src/Type.js

@@ -0,0 +1,2002 @@
+/**
+ * 🧩 Validation, Parsing, and Transformation
+ *
+ * ## Intro
+ *
+ * You probably know [Zod](https://zod.dev). Evolu has {@link Type}.
+ *
+ * Evolu Type exists because no existing validation/parsing/transformation
+ * library fully met our needs:
+ *
+ * - **Result-based error handling**: Leveraging {@link Result} instead of throwing
+ *   exceptions.
+ * - **Consistent constraints**: Enforcing {@link Brand} for all constraints.
+ * - **Typed errors with decoupled formatters**: Avoiding coupling error messages
+ *   with validators.
+ * - **No user-land chaining**: Designed with ES pipe operator in mind.
+ * - **Selective validation/transformation**: Skipping parent Type validations and
+ *   transformations when TypeScript's type system can be relied upon.
+ * - **Bidirectional transformations**: Supporting transformations in both
+ *   directions.
+ * - **Minimal and transparent code**: No runtime dependencies or hidden magic.
+ *
+ * **Note**: A proper quickstart guide is on the way. In the meantime, each type
+ * includes its own usage example, and you can (and should) check the tests for
+ * practical demonstrations of the API. Or dang, just read the code. It's
+ * simple.
+ *
+ * - Evolu `Type` is:
+ *
+ * - A TypeScript type with a {@link Brand} whenever it's possible.
+ * - A function to create a value of that type, which may fail.
+ * - A function to transform value back to its original representation, which
+ *   cannot fail.
+ *
+ * Types are chainable. The chain starts with a Base Type that refines an
+ * unknown value into something and can continue with further refinements or
+ * transformations. For example, `NonEmptyTrimmedString100` chain looks like
+ * this:
+ *
+ * `Unknown` -> `String` -> `TrimmedString` -> `NonEmptyTrimmedString100`
+ *
+ * For `NonEmptyTrimmedString100`, the parent Type is `TrimmedString`. For
+ * `TrimmedString`, the parent Type is `String`.
+ *
+ * The parent of the `String` Type is the `String` Type itself. All Base Types
+ * `fromParent` functions are just a typed alias to `fromUnknown` to ensure that
+ * `fromParent` and `toParent` can be called on any Type.
+ *
+ * Speaking of `fromParent` and `toParent`, those functions exist to bypass
+ * parent Types when we can rely on TypeScript types.
+ *
+ * `Type` transformations should be reversible. If you need an irreversible
+ * transformation, such as `TrimString` (trimming is not reversible as `untrim`
+ * can't know what has been trimmed), you can do that, but note in JSDoc that
+ * `to` will not restore the original representation. You can also use
+ * {@link assert}: `assert(false, "Untrim is not possible")`.
+ *
+ * ### Tip
+ *
+ * If necessary, write `globalThis.String` instead of `String` to avoid naming
+ * clashes with Base Types.
+ *
+ * ### Design Decision:
+ *
+ * While the `from` function can fail, the `to` function cannot. This simplifies
+ * the model by ensuring that every valid input has a corresponding valid
+ * output, eliminating the risk of edge cases caused by irreversible
+ * operations.
+ *
+ * @module
+ */
+import * as bip39 from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english";
+import { assert } from "./Assert.js";
+import { identity } from "./Function.js";
+import { isPlainObject } from "./Object.js";
+import { err, ok, trySync } from "./Result.js";
+import { safelyStringifyUnknownValue } from "./String.js";
+const EvoluTypeSymbol = Symbol("evolu.Type");
+/**
+ * Checks if the given value is an {@link Type}.
+ *
+ * @category Utilities
+ */
+export const isType = (value) => typeof value === "object" && value !== null && EvoluTypeSymbol in value;
+const createType = (name, definition) => ({
+    ...definition,
+    name,
+    is: (value) => definition.fromUnknown(value).ok,
+    from: definition.fromUnknown,
+    [EvoluTypeSymbol]: true,
+    Type: undefined,
+    Input: undefined,
+    Error: undefined,
+    Parent: undefined,
+    ParentError: undefined,
+    Errors: undefined,
+});
+/**
+ * Creates a formatter function for {@link TypeError}.
+ *
+ * The formatter generates human-readable error messages using a custom
+ * formatting function and a safely stringified error value.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const formatStringError = createTypeErrorFormatter<StringError>(
+ *   (value) => `A value ${value} is not a string.`,
+ * );
+ * ```
+ *
+ * @category Utilities
+ */
+export const createTypeErrorFormatter = (format) => (error) => format({ ...error, value: safelyStringifyUnknownValue(error.value) });
+/**
+ * Base {@link Type}.
+ *
+ * A Base Type validates that a value conforms to a specific TypeScript type.
+ * Unlike refinements or transformations, Base Types establish the fundamental
+ * shape of a value before any branding or transformation occurs.
+ *
+ * - To **refine** a Base Type further, use the {@link brand} Type Factory.
+ * - To **transform** a Base Type into a different representation, use the
+ *   {@link transform} Type Factory.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const String = base("String", (value) =>
+ *   typeof value === "string"
+ *     ? ok(value)
+ *     : err<StringError>({ type: "String", value }),
+ * );
+ *
+ * interface StringError extends TypeError<"String"> {}
+ *
+ * const formatStringError = createTypeErrorFormatter<StringError>(
+ *   (error) => `A value ${error.value} is not a string`,
+ * );
+ * ```
+ *
+ * @category Base Factories
+ */
+export const base = (name, fromUnknown) => createType(name, {
+    fromUnknown,
+    to: identity,
+    fromParent: (ok), // `fromParent` relies on types, so it can't fail for the Base Type
+    toParent: identity,
+});
+/**
+ * Creates a formatter function for a base {@link TypeError}.
+ *
+ * This formatter is specifically for Base Types that only need a simple error
+ * message indicating that the value is not of the expected type.
+ *
+ * ### Example
+ *
+ * ```ts
+ * export const formatStringError =
+ *   createBaseTypeErrorFormatter<StringError>();
+ * ```
+ *
+ * @category Utilities
+ */
+export const createBaseTypeErrorFormatter = () => createTypeErrorFormatter((error) => `A value ${error.value} is not a ${error.type.toLowerCase()}.`);
+/** @category Base Types */
+export const Unknown = base("Unknown", ok);
+/**
+ * @category Base Types
+ * @category String
+ */
+export const String = base("String", (value) => typeof value === "string"
+    ? ok(value)
+    : err({ type: "String", value }));
+export const formatStringError = createBaseTypeErrorFormatter();
+/** @category Base Types */
+export const Number = base("Number", (value) => typeof value === "number"
+    ? ok(value)
+    : err({ type: "Number", value }));
+export const formatNumberError = createBaseTypeErrorFormatter();
+/** @category Base Types */
+export const BigInt = base("BigInt", (value) => typeof value === "bigint"
+    ? ok(value)
+    : err({ type: "BigInt", value }));
+export const formatBigIntError = createBaseTypeErrorFormatter();
+/** @category Base Types */
+export const Boolean = base("Boolean", (value) => typeof value === "boolean"
+    ? ok(value)
+    : err({ type: "Boolean", value }));
+export const formatBooleanError = createBaseTypeErrorFormatter();
+/** @category Base Types */
+export const Undefined = base("Undefined", (value) => value === undefined
+    ? ok(value)
+    : err({ type: "Undefined", value }));
+export const formatUndefinedError = createBaseTypeErrorFormatter();
+/** @category Base Types */
+export const Null = base("Null", (value) => value === null ? ok(value) : err({ type: "Null", value }));
+export const formatNullError = createBaseTypeErrorFormatter();
+/** @category Base Types */
+export const Function = base("Function", (value) => typeof value === "function"
+    ? ok(value)
+    : err({ type: "Function", value }));
+export const formatFunctionError = createBaseTypeErrorFormatter();
+/** @category Base Types */
+export const Uint8Array = base("Uint8Array", (value) => value instanceof globalThis.Uint8Array
+    ? ok(value)
+    : err({ type: "Uint8Array", value }));
+export const formatUint8ArrayError = createBaseTypeErrorFormatter();
+/**
+ * `instanceof` {@link Type}.
+ *
+ * Ensures that a value is an instance of the given class constructor.
+ *
+ * ### Example
+ *
+ * ```ts
+ * class User {
+ *   constructor(public name: string) {}
+ * }
+ *
+ * const UserInstance = instanceOf(User);
+ *
+ * const result = UserInstance.from(new User("Alice")); // ok
+ * const error = UserInstance.from({}); // err
+ * ```
+ *
+ * @category Base Factories
+ */
+export const instanceOf = (ctor) => ({
+    ...base("InstanceOf", (value) => value instanceof ctor
+        ? ok(value)
+        : err({ type: "InstanceOf", value, ctor: ctor.name })),
+    ctor,
+});
+export const formatInstanceOfError = createTypeErrorFormatter((error) => `Value ${error.value} is not an instance of ${error.ctor}`);
+/**
+ * JavaScript Date.
+ *
+ * @category Base Types
+ */
+export const Date = instanceOf(globalThis.Date);
+/**
+ * Validates that an unknown value is an Evolu {@link Type} (i.e., satisfies
+ * `AnyType`).
+ *
+ * ### Example
+ *
+ * ```ts
+ * const result = EvoluType.from(String); // ok(String)
+ * const error = EvoluType.from("not a Type"); // err
+ * ```
+ */
+// TODO: Rename to TypeInstance or something like that.
+export const EvoluType = base("EvoluType", (value) => isType(value)
+    ? ok(value)
+    : err({
+        type: "EvoluType",
+        value,
+    }));
+export const formatIsTypeError = createTypeErrorFormatter((error) => `Value ${error.value} is not a valid Evolu Type.`);
+export function brand(name, parent, refine) {
+    const fromUnknown = refine
+        ? (value) => {
+            const parentResult = parent.fromUnknown(value);
+            if (!parentResult.ok)
+                return parentResult;
+            return refine(parentResult.value);
+        }
+        : (value) => {
+            const parentResult = parent.fromUnknown(value);
+            if (!parentResult.ok)
+                return err({
+                    type: name,
+                    value,
+                    parentError: parentResult.error,
+                });
+            return ok(parentResult.value);
+        };
+    return {
+        ...createType("Brand", {
+            fromUnknown,
+            to: identity,
+            fromParent: (refine ?? ok),
+            toParent: identity,
+        }),
+        brand: name,
+        parentType: parent,
+    };
+}
+/**
+ * A three-letter ISO 4217 currency code (e.g., USD, EUR).
+ *
+ * @category String
+ */
+export const CurrencyCode = brand("CurrencyCode", String, (value) => /^[A-Z]{3}$/.test(value)
+    ? ok(value)
+    : err({ type: "CurrencyCode", value }));
+export const formatCurrencyCodeError = createTypeErrorFormatter((error) => `Invalid currency code: ${error.value}`);
+/**
+ * ISO 8601 date-time string.
+ *
+ * This {@link Type} represents a date-time string that follows the ISO 8601
+ * format and is compatible with SQLite, which lacks a native date type and
+ * relies on ISO 8601 strings for sorting. Enforcing a 24-character format
+ * ensures correct lexicographic ordering.
+ *
+ * It must be a valid JavaScript Date string that can be parsed.
+ *
+ * Valid range: `"0000-01-01T00:00:00.000Z"` to `"9999-12-31T23:59:59.999Z"`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const result = DateIsoString.from("2023-01-01T12:00:00.000Z"); // ok
+ * const error = DateIsoString.from("10000-01-01T00:00:00.000Z"); // err
+ * ```
+ *
+ * @category String
+ */
+export const DateIsoString = brand("DateIso", String, (value) => {
+    if (value.length !== 24) {
+        return err({ type: "DateIsoString", value });
+    }
+    if (isNaN(globalThis.Date.parse(value))) {
+        return err({ type: "DateIsoString", value });
+    }
+    return ok(value);
+});
+export const formatDateIsoStringError = createTypeErrorFormatter((error) => `The value ${error.value} is not a valid ISO 8601 date string.`);
+/**
+ * Trimmed string.
+ *
+ * This Type Factory does not transform; it only validates whether a string has
+ * no leading or trailing whitespaces. To trim a string, use {@link trim} Type
+ * Factory.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * // this Type already exists
+ * const TrimmedString = trimmed(String);
+ * type TrimmedString = typeof TrimmedString.Type;
+ *
+ * // we can make any branded Type trimmed:
+ * const TrimmedNonEmptyString = trimmed(minLength(1)(String));
+ * // string & Brand<"MinLength1"> & Brand<"Trimmed">
+ * type TrimmedNonEmptyString = typeof TrimmedNonEmptyString.Type;
+ * ```
+ *
+ * @category String
+ */
+export const trimmed = (parent) => brand("Trimmed", parent, (value) => value.trim().length === value.length
+    ? ok(value)
+    : err({ type: "Trimmed", value }));
+export const formatTrimmedError = createTypeErrorFormatter((error) => `A value ${error.value} is not trimmed`);
+/**
+ * Trims leading and trailing whitespace from a string.
+ *
+ * This Type Factory **transforms** the input string by removing whitespace from
+ * both ends. For validation only, use {@link trimmed} Type Factory.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const TrimString = trim(String);
+ * expect(TrimString.from("a ")).toEqual(ok("a"));
+ * expect(TrimString.fromParent("a ").value).toEqual("a");
+ *
+ * const TrimNonEmptyString = trim(NonEmptyString);
+ * expect(TrimNonEmptyString.from("a " as NonEmptyString)).toEqual(ok("a"));
+ * expect(
+ *   TrimNonEmptyString.fromParent("a " as NonEmptyString).value,
+ * ).toEqual("a");
+ * ```
+ *
+ * **Note:** This transformation is irreversible. Calling `toParent` will not
+ * restore the original representation.
+ *
+ * @category String
+ */
+export const trim = (parent) => transform(parent, trimmed(parent), (value) => ok(value.trim()), (value) => value);
+/**
+ * Trimmed string
+ *
+ * - Use `TrimmedString.is` to check if an unknown value is trimmed.
+ * - Use `TrimmedString.from` to check if a string is trimmed.
+ *
+ * @category String
+ */
+export const TrimmedString = trimmed(String);
+/**
+ * Minimum length.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // string & Brand<"MinLength1">
+ * const NonEmptyString = minLength(1)(String);
+ * ```
+ *
+ * @category String
+ * @category Array
+ */
+export const minLength = (min) => (parent) => brand(`MinLength${min}`, parent, (value) => value.length >= min ? ok(value) : err({ type: "MinLength", value, min }));
+export const formatMinLengthError = createTypeErrorFormatter((error) => `Value ${error.value} does not meet the minimum length of ${error.min}.`);
+/**
+ * Maximum length.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // string & Brand<"MaxLength100">
+ * const String100 = maxLength(100)(String);
+ * ```
+ *
+ * @category String
+ * @category Array
+ */
+export const maxLength = (max) => (parent) => brand(`MaxLength${max}`, parent, (value) => value.length <= max ? ok(value) : err({ type: "MaxLength", value, max }));
+export const formatMaxLengthError = createTypeErrorFormatter((error) => `Value ${error.value} exceeds the maximum length of ${error.max}.`);
+/**
+ * Exact length.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // string & Brand<"Length1">
+ * const Length1String = length(1)(String);
+ * ```
+ *
+ * @category String
+ * @category Array
+ */
+export const length = (exact) => (parent) => brand(`Length${exact}`, parent, (value) => value.length === exact
+    ? ok(value)
+    : err({ type: "Length", value, exact }));
+export const formatLengthError = createTypeErrorFormatter((error) => `Value ${error.value} does not have the required length of ${error.exact}.`);
+/** @category String */
+export const NonEmptyString = minLength(1)(String);
+/** @category String */
+export const String100 = maxLength(100)(String);
+/** @category String */
+export const String1000 = maxLength(1000)(String);
+/** @category String */
+export const NonEmptyString100 = minLength(1)(String100);
+/** @category String */
+export const NonEmptyString1000 = minLength(1)(String1000);
+/** @category String */
+export const NonEmptyTrimmedString = minLength(1)(TrimmedString);
+/** @category String */
+export const TrimmedString100 = maxLength(100)(TrimmedString);
+/** @category String */
+export const TrimmedString1000 = maxLength(1000)(TrimmedString);
+/** @category String */
+export const NonEmptyTrimmedString100 = minLength(1)(TrimmedString100);
+/** @category String */
+export const NonEmptyTrimmedString1000 = minLength(1)(TrimmedString1000);
+/**
+ * The mnemonic, also known as a "seed phrase," is a set of 12 words in a
+ * specific order chosen from a predefined list (BIP39). It provides a
+ * human-readable way to store a private key securely. The mnemonic is generated
+ * safely on the user's device using cryptographically secure random number
+ * generation, ensuring it remains private and unique.
+ *
+ * @category String
+ */
+export const Mnemonic = brand("Mnemonic", NonEmptyTrimmedString, (value) => bip39.validateMnemonic(value, wordlist)
+    ? ok(value)
+    : err({ type: "Mnemonic", value }));
+export const formatMnemonicError = createTypeErrorFormatter((error) => `Invalid BIP39 mnemonic: ${error.value}`);
+/**
+ * String matching a regular expression.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const Alphanumeric = regex("Alphanumeric", /^[a-z0-9]+$/i)(String);
+ * ```
+ *
+ * @category String
+ */
+export const regex = (name, pattern) => {
+    // Clone the regex to avoid shared state.
+    const clonedPattern = new RegExp(pattern.source, pattern.flags);
+    return (parent) => brand(name, parent, (value) => {
+        // Reset `lastIndex` before each use to ensure the regex starts matching
+        // from the beginning of the string.
+        clonedPattern.lastIndex = 0;
+        return clonedPattern.test(value)
+            ? ok(value)
+            : err({ type: "Regex", name, value, pattern });
+    });
+};
+export const formatRegexError = createTypeErrorFormatter((error) => `Value ${error.value} does not match the pattern for ${error.name}: ${error.pattern}`);
+/**
+ * URL-safe Base64 string.
+ *
+ * A `Base64Url` string uses a limited alphabet that is URL-safe:
+ *
+ * - Uppercase letters (`A-Z`)
+ * - Lowercase letters (`a-z`)
+ * - Digits (`0-9`)
+ * - Dash (`-`)
+ * - Underscore (`_`)
+ *
+ * ### Example
+ *
+ * ```ts
+ * const result = Base64Url.from("abc123_-");
+ * if (result.ok) {
+ *   console.log("Valid Base64Url string:", result.value);
+ * } else {
+ *   console.error("Invalid Base64Url string:", result.error);
+ * }
+ * ```
+ *
+ * @category String
+ */
+export const Base64Url = regex("Base64Url", /^[A-Za-z0-9_-]+$/)(String);
+/**
+ * Simple alphanumeric string for naming.
+ *
+ * A `SimpleName` string uses a limited, safe alphabet for naming purposes:
+ *
+ * - Uppercase letters (`A-Z`)
+ * - Lowercase letters (`a-z`)
+ * - Digits (`0-9`)
+ * - Dash (`-`)
+ *
+ * The string must be between 1 and 42 characters.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const result = SimpleName.from("data-report-123");
+ * if (result.ok) {
+ *   console.log("Valid SimpleName string:", result.value);
+ * } else {
+ *   console.error("Invalid SimpleName string:", result.error);
+ * }
+ * ```
+ *
+ * @category String
+ */
+export const SimpleName = regex("SimpleName", /^[a-z0-9-]{1,42}$/i)(String);
+/**
+ * Default NanoId.
+ *
+ * @category String
+ */
+export const NanoId = regex("NanoId", /^[A-Za-z0-9_-]{21}$/)(String);
+/**
+ * Trimmed string between 8 and 64 characters, branded as `SimplePassword`.
+ *
+ * @category String
+ */
+export const SimplePassword = brand("SimplePassword", minLength(8)(maxLength(64)(TrimmedString)));
+export const formatSimplePasswordError = (formatTypeError) => createTypeErrorFormatter((error) => `Invalid password: ${formatTypeError(error.parentError)}`);
+/**
+ * `Id` {@link Type}.
+ *
+ * Represents a unique identifier with exactly 21 characters, using NanoID's
+ * standard format (`A-Za-z0-9_-`).
+ *
+ * @category String
+ */
+export const Id = regex("Id", /^[A-Za-z0-9_-]{21}$/)(String);
+export const idTypeValueLength = 21;
+/**
+ * Creates an {@link Id}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // string & Brand<"Id">
+ * const id = createId(deps);
+ * ```
+ */
+export const createId = (deps) => deps.nanoIdLib.nanoid();
+/**
+ * Type Factory to create branded {@link Id} Type for a specific table.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const TodoId = id("Todo");
+ * // string & Brand<"Id"> & Brand<"Todo">
+ * type TodoId = typeof TodoId.Type;
+ * ```
+ *
+ * @category String
+ */
+export const id = (table) => {
+    const fromParent = (value) => {
+        const idResult = Id.fromParent(value);
+        if (!idResult.ok) {
+            return err({ type: "Id", value, table });
+        }
+        return ok(idResult.value);
+    };
+    const fromUnknown = (value) => {
+        const parentResult = String.fromUnknown(value);
+        if (!parentResult.ok)
+            return parentResult;
+        return fromParent(parentResult.value);
+    };
+    return {
+        ...createType("Id", {
+            fromUnknown,
+            to: (value) => value,
+            fromParent,
+            toParent: (value) => value,
+        }),
+        table,
+    };
+};
+export const formatIdError = createTypeErrorFormatter((error) => `Invalid ${error.type} table Id: ${error.value}`);
+/**
+ * Positive number.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const PositiveNumber = positive(Number);
+ *
+ * const result = PositiveNumber.from(42); // ok
+ * const errorResult = PositiveNumber.from(-5); // err
+ * ```
+ *
+ * @category Number
+ */
+export const positive = (parent) => brand("Positive", parent, (value) => value > 0 ? ok(value) : err({ type: "Positive", value }));
+export const formatPositiveError = createTypeErrorFormatter((error) => `The value ${error.value} is not positive.`);
+/**
+ * Negative number.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const NegativeNumber = negative(Number);
+ * ```
+ *
+ * @category Number
+ */
+export const negative = (parent) => brand("Negative", parent, (value) => value < 0 ? ok(value) : err({ type: "Negative", value }));
+export const formatNegativeError = createTypeErrorFormatter((error) => `The value ${error.value} is not negative.`);
+/**
+ * Non-positive number.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const NonPositiveNumber = nonPositive(Number);
+ * ```
+ *
+ * @category Number
+ */
+export const nonPositive = (parent) => brand("NonPositive", parent, (value) => value <= 0
+    ? ok(value)
+    : err({ type: "NonPositive", value }));
+export const formatNonPositiveError = createTypeErrorFormatter((error) => `The value ${error.value} is not non-positive.`);
+/**
+ * Non-negative number.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const NonNegativeNumber = nonNegative(Number);
+ * ```
+ *
+ * @category Number
+ */
+export const nonNegative = (parent) => brand("NonNegative", parent, (value) => value >= 0
+    ? ok(value)
+    : err({ type: "NonNegative", value }));
+export const formatNonNegativeError = createTypeErrorFormatter((error) => `The value ${error.value} is not non-negative.`);
+/** @category Number */
+export const NonNegativeNumber = nonNegative(Number);
+/** @category Number */
+export const PositiveNumber = positive(NonNegativeNumber);
+/** @category Number */
+export const NonPositiveNumber = nonPositive(Number);
+/** @category Number */
+export const NegativeNumber = negative(NonPositiveNumber);
+/**
+ * Integer within the safe range of JavaScript numbers.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const Int = int(Number);
+ * ```
+ *
+ * @category Number
+ */
+export const int = (parent) => brand("Int", parent, (value) => globalThis.Number.isSafeInteger(value)
+    ? ok(value)
+    : err({ type: "Int", value }));
+export const formatIntError = createTypeErrorFormatter((error) => `The value ${error.value} is not an integer.`);
+/**
+ * Integer within the safe range of JavaScript numbers.
+ *
+ * @category Number
+ */
+export const Int = int(Number);
+/** @category Number */
+export const NonNegativeInt = nonNegative(Int);
+/** @category Number */
+export const PositiveInt = positive(NonNegativeInt);
+/** @category Number */
+export const NonPositiveInt = nonPositive(Int);
+/** @category Number */
+export const NegativeInt = negative(NonPositiveInt);
+/**
+ * Number greater than a specified value.
+ *
+ * @category Number
+ */
+export const greaterThan = (min) => (parent) => brand(`GreaterThan${min}`, parent, (value) => value > min ? ok(value) : err({ type: "GreaterThan", value, min }));
+export const formatGreaterThanError = createTypeErrorFormatter((error) => `The value ${error.value} is not > ${error.min}.`);
+/**
+ * Number less than a specified value.
+ *
+ * @category Number
+ */
+export const lessThan = (max) => (parent) => brand(`LessThan${max}`, parent, (value) => value < max ? ok(value) : err({ type: "LessThan", value, max }));
+export const formatLessThanError = createTypeErrorFormatter((error) => `The value ${error.value} is not < ${error.max}.`);
+/**
+ * Number ≥ a specified value.
+ *
+ * @category Number
+ */
+export const greaterThanOrEqualTo = (min) => (parent) => brand(`GreaterThanOrEqualTo${min}`, parent, (value) => value >= min
+    ? ok(value)
+    : err({ type: "GreaterThanOrEqualTo", value, min }));
+export const formatGreaterThanOrEqualToError = createTypeErrorFormatter((error) => `The value ${error.value} is not >= ${error.min}.`);
+/**
+ * Number ≤ a specified value.
+ *
+ * @category Number
+ */
+export const lessThanOrEqualTo = (max) => (parent) => brand(`LessThanOrEqualTo${max}`, parent, (value) => value <= max ? ok(value) : err({ type: "LessThanOrEqualTo", value, max }));
+export const formatLessThanOrEqualToError = createTypeErrorFormatter((error) => `The value ${error.value} is not <= ${error.max}.`);
+/**
+ * Number that is not NaN.
+ *
+ * @category Number
+ */
+export const nonNaN = (parent) => brand("NonNaN", parent, (value) => !globalThis.Number.isNaN(value)
+    ? ok(value)
+    : err({ type: "NonNaN", value }));
+export const formatNonNaNError = createTypeErrorFormatter((error) => `The value ${error.value} is NaN (not a number).`);
+/** @category Number */
+export const NonNaNNumber = nonNaN(Number);
+/**
+ * Finite number.
+ *
+ * @category Number
+ */
+export const finite = (parent) => brand("Finite", parent, (value) => globalThis.Number.isFinite(value)
+    ? ok(value)
+    : err({ type: "Finite", value }));
+export const formatFiniteError = createTypeErrorFormatter((error) => `The value ${error.value} is not finite.`);
+/**
+ * Finite number.
+ *
+ * This Type ensures that a number is finite.
+ *
+ * **Why is this important?**
+ *
+ * `JSON.stringify` serializes JavaScript numbers into `null` if they are not
+ * finite (e.g., `Infinity`, `-Infinity`, or `NaN`). Using `FiniteNumber` helps
+ * prevent these unexpected behaviors when working with JSON serialization.
+ *
+ * @category Number
+ */
+export const FiniteNumber = finite(Number);
+/**
+ * Number that is a multiple of a divisor.
+ *
+ * @category Number
+ */
+export const multipleOf = (divisor) => (parent) => brand(`MultipleOf${divisor}`, parent, (value) => value % divisor === 0
+    ? ok(value)
+    : err({ type: "MultipleOf", value, divisor }));
+export const formatMultipleOfError = createTypeErrorFormatter((error) => `The value ${error.value} is not a multiple of ${error.divisor}.`);
+/**
+ * Number within a range, inclusive.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const Between1And10 = between(1, 10)(PositiveNumber);
+ * const result = Between1And10.from(5); // ok(5)
+ * const errorResult = Between1And10.from(11); // err
+ * ```
+ *
+ * @category Number
+ */
+export const between = (min, max) => (parent) => brand(`Between${min}-${max}`, parent, (value) => value >= min && value <= max
+    ? ok(value)
+    : err({ type: "Between", value, min, max }));
+export const formatBetweenError = createTypeErrorFormatter((error) => `The value ${error.value} is not between ${error.min} and ${error.max}, inclusive.`);
+/** @category Number */
+export const Between1And10 = between(1, 10)(Number);
+/**
+ * Literal {@link Type}.
+ *
+ * https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types
+ *
+ * ### Example
+ *
+ * ```ts
+ * const LiteralHello = literal("Hello");
+ * const result = LiteralHello.from("Hello"); // ok("Hello")
+ * const errorResult = LiteralHello.from("World"); // err
+ * ```
+ *
+ * TODO: Add JsonValue
+ *
+ * @category Base Factories
+ */
+export const literal = (expected) => {
+    const fromUnknown = (value) => value === expected
+        ? ok(expected)
+        : err({ type: "Literal", value, expected });
+    return {
+        ...createType("Literal", {
+            fromUnknown,
+            to: identity,
+            fromParent: ok,
+            toParent: identity,
+        }),
+        expected,
+    };
+};
+export const formatLiteralError = createTypeErrorFormatter((error) => `The value ${error.value} is not strictly equal to the expected literal: ${globalThis.String(error.expected)}.`);
+/**
+ * {@link Type} that transforms values between `FromType` and `ToType`.
+ *
+ * - `fromParent`: Converts `FromType` to `ToType`, may fail.
+ * - `toParent`: Converts `ToType` back to `FromType`, must not fail.
+ *
+ * ### Example
+ *
+ * // TODO: Examples
+ *
+ * @category Base Factories
+ */
+export const transform = (fromType, toType, fromParent, toParent) => {
+    const fromUnknown = (value) => {
+        const parentResult = fromType.fromUnknown(value);
+        if (!parentResult.ok)
+            return parentResult;
+        return fromParent(parentResult.value);
+    };
+    const to = (value) => fromType.to(toParent(value));
+    return {
+        ...createType("Transform", {
+            fromUnknown,
+            to,
+            fromParent,
+            toParent,
+        }),
+        is: toType.is,
+        fromType,
+        toType,
+    };
+};
+/**
+ * Trims leading and trailing whitespace from a string.
+ *
+ * ### Example
+ *
+ * ```ts
+ * expect(TrimString.from("a ")).toEqual(ok("a"));
+ * expect(TrimString.fromParent("a ").value).toEqual("a");
+ * ```
+ *
+ * @category String
+ */
+export const TrimString = trim(String);
+/**
+ * Transforms a {@link Date} into a {@link DateIsoString} string and vice versa.
+ *
+ * ### Example
+ *
+ * TODO:
+ *
+ * @category String
+ */
+export const DateIso = transform(Date, DateIsoString, (value) => DateIsoString.fromParent(value.toISOString()), (value) => new globalThis.Date(value));
+/**
+ * Transforms a {@link NonEmptyTrimmedString} into a {@link FiniteNumber}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * NumberFromString.from("42"); // ok(42)
+ * NumberFromString.from("abc"); // err({ type: "NumberFromString", value: "abc" })
+ * ```
+ *
+ * @category Number
+ */
+export const NumberFromString = transform(NonEmptyTrimmedString, FiniteNumber, (value) => {
+    const result = FiniteNumber.fromParent(globalThis.Number(value));
+    if (!result.ok)
+        return err({ type: "NumberFromString", value });
+    return result;
+}, (num) => num.toString());
+export const formatNumberFromStringError = createTypeErrorFormatter((error) => {
+    return `The value ${error.value} could not be converted to a finite number.`;
+});
+/**
+ * Array of a specific {@link Type}.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const NumberArray = array(Number);
+ *
+ * const result1 = NumberArray.from([1, 2, 3]); // ok([1, 2, 3])
+ * const result2 = NumberArray.from(["a", "b"]); // err(...)
+ * ```
+ *
+ * @category Base Factories
+ * @category Array
+ */
+export const array = (element) => {
+    const fromUnknown = (value) => {
+        if (!Array.isArray(value)) {
+            return err({
+                type: "Array",
+                value,
+                reason: { kind: "NotArray" },
+            });
+        }
+        const result = [];
+        for (let i = 0; i < value.length; i++) {
+            const elementResult = element.fromUnknown(value[i]);
+            if (!elementResult.ok) {
+                return err({
+                    type: "Array",
+                    value,
+                    reason: {
+                        kind: "Element",
+                        index: i,
+                        error: elementResult.error,
+                    },
+                });
+            }
+            result.push(elementResult.value);
+        }
+        return ok(result);
+    };
+    const to = (value) => value.map(element.to);
+    const fromParent = (value) => {
+        const result = [];
+        for (let i = 0; i < value.length; i++) {
+            const elementResult = element.fromParent(value[i]);
+            if (!elementResult.ok) {
+                return err({
+                    type: "Array",
+                    value,
+                    reason: {
+                        kind: "Element",
+                        index: i,
+                        error: elementResult.error,
+                    },
+                });
+            }
+            result.push(elementResult.value);
+        }
+        return ok(result);
+    };
+    const toParent = (values) => values.map(element.toParent);
+    return {
+        ...createType("Array", {
+            fromUnknown,
+            to,
+            fromParent,
+            toParent,
+        }),
+        element,
+    };
+};
+export const formatArrayError = (formatTypeError) => createTypeErrorFormatter((error) => {
+    switch (error.reason.kind) {
+        case "NotArray":
+            return `Expected an array but received ${error.value}.`;
+        case "Element":
+            return `Invalid element at index ${error.reason.index}: ${formatTypeError(error.reason.error)}`;
+    }
+});
+/**
+ * Record of a key {@link Type} and value {@link Type}.
+ *
+ * - The input must be a plain object (validated by {@link isPlainObject}).
+ * - Each key is validated/transformed by the `key` Type.
+ * - Each value is validated/transformed by the `value` Type.
+ *
+ * The resulting type is `Readonly<Record<KeyT, ValueT>>`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const StringToNumberRecord = record(String, Number);
+ *
+ * // ok({ "a": 1, "b": 2 })
+ * StringToNumberRecord.from({ a: 1, b: 2 });
+ *
+ * // err => "Key" because 42 is not a string key
+ * StringToNumberRecord.from({ 42: 1, b: 2 });
+ *
+ * // err => "Value" because "x" is not a number
+ * StringToNumberRecord.from({ a: "x", b: 2 });
+ * ```
+ *
+ * @category Base Factories
+ * @category Object
+ */
+export const record = (keyType, valueType) => {
+    const fromUnknown = (value) => {
+        if (!isPlainObject(value)) {
+            return err({
+                type: "Record",
+                value,
+                reason: { kind: "NotRecord" },
+            });
+        }
+        const result = {};
+        for (const [rawKey, rawValue] of Object.entries(value)) {
+            const keyResult = keyType.fromUnknown(rawKey);
+            if (!keyResult.ok) {
+                return err({
+                    type: "Record",
+                    value,
+                    reason: { kind: "Key", key: rawKey, error: keyResult.error },
+                });
+            }
+            const valueResult = valueType.fromUnknown(rawValue);
+            if (!valueResult.ok) {
+                return err({
+                    type: "Record",
+                    value,
+                    reason: {
+                        kind: "Value",
+                        key: rawKey,
+                        error: valueResult.error,
+                    },
+                });
+            }
+            result[keyResult.value] = valueResult.value;
+        }
+        return ok(result);
+    };
+    const to = (value) => Object.fromEntries(Object.entries(value).map(([key, val]) => [
+        keyType.to(key),
+        valueType.to(val),
+    ]));
+    const fromParent = (value) => {
+        const result = {};
+        for (const [rawKey, rawValue] of Object.entries(value)) {
+            const keyResult = keyType.fromParent(rawKey);
+            if (!keyResult.ok) {
+                return err({
+                    type: "Record",
+                    value,
+                    reason: {
+                        kind: "Key",
+                        key: rawKey,
+                        error: keyResult.error,
+                    },
+                });
+            }
+            const valueResult = valueType.fromParent(rawValue);
+            if (!valueResult.ok) {
+                return err({
+                    type: "Record",
+                    value,
+                    reason: {
+                        kind: "Value",
+                        key: keyResult.value,
+                        error: valueResult.error,
+                    },
+                });
+            }
+            result[keyResult.value] = valueResult.value;
+        }
+        return ok(result);
+    };
+    const toParent = (value) => Object.fromEntries(Object.entries(value).map(([key, val]) => [
+        keyType.toParent(key),
+        valueType.toParent(val),
+    ]));
+    return {
+        ...createType("Record", {
+            fromUnknown,
+            to,
+            fromParent,
+            toParent,
+        }),
+        key: keyType,
+        value: valueType,
+    };
+};
+export const formatRecordError = (formatTypeError) => createTypeErrorFormatter((error) => {
+    switch (error.reason.kind) {
+        case "NotRecord":
+            return `Expected a record (plain object) but received ${error.value}.`;
+        case "Key":
+            return `Invalid key ${error.reason.key}: ${formatTypeError(error.reason.error)}`;
+        case "Value":
+            return `Invalid value for key ${error.reason.key}: ${formatTypeError(error.reason.error)}`;
+    }
+});
+export function object(props, record) {
+    /* eslint-disable */
+    const propKeys = Object.keys(props);
+    const fromUnknown = (value) => {
+        if (!isPlainObject(value)) {
+            return err({
+                type: record ? "ObjectWithRecord" : "Object",
+                value,
+                reason: { kind: "NotObject" },
+            });
+        }
+        const errors = {};
+        const result = {};
+        for (const key of propKeys) {
+            if (!(key in value) && isOptionalType(props[key])) {
+                continue;
+            }
+            const propResult = props[key].fromUnknown(value[key]);
+            if (!propResult.ok) {
+                errors[key] = propResult.error;
+            }
+            else {
+                result[key] = propResult.value;
+            }
+        }
+        const extraKeys = Object.keys(value).filter((key) => !propKeys.includes(key));
+        if (record) {
+            for (const key of extraKeys) {
+                const keyResult = record.key.fromUnknown(key);
+                if (!keyResult.ok) {
+                    return err({
+                        type: "ObjectWithRecord",
+                        value,
+                        reason: {
+                            kind: "IndexKey",
+                            key,
+                            error: keyResult.error,
+                        },
+                    });
+                }
+                const valueResult = record.value.fromUnknown(value[key]);
+                if (!valueResult.ok) {
+                    return err({
+                        type: "ObjectWithRecord",
+                        value,
+                        reason: {
+                            kind: "IndexValue",
+                            key,
+                            error: valueResult.error,
+                        },
+                    });
+                }
+                result[keyResult.value] = valueResult.value;
+            }
+        }
+        else if (extraKeys.length > 0) {
+            return err({
+                type: "Object",
+                value,
+                reason: { kind: "ExtraKeys", extraKeys },
+            });
+        }
+        if (Object.keys(errors).length > 0) {
+            return err({
+                type: record ? "ObjectWithRecord" : "Object",
+                value,
+                reason: { kind: "Props", errors },
+            });
+        }
+        return ok(result);
+    };
+    const to = (value) => {
+        const entries = [];
+        for (const key of propKeys) {
+            if (!(key in value) && isOptionalType(props[key])) {
+                continue;
+            }
+            entries.push([key, props[key].to(value[key])]);
+        }
+        if (record) {
+            const recordEntries = Object.entries(value).filter(([key]) => !propKeys.includes(key));
+            for (const [key, val] of recordEntries) {
+                entries.push([record.key.to(key), record.value.to(val)]);
+            }
+        }
+        return Object.fromEntries(entries);
+    };
+    const fromParent = (value) => {
+        const errors = {};
+        const result = {};
+        for (const key of propKeys) {
+            if (!(key in value) && isOptionalType(props[key])) {
+                continue;
+            }
+            const propResult = props[key].fromParent(value[key]);
+            if (!propResult.ok) {
+                errors[key] = propResult.error;
+            }
+            else {
+                result[key] = propResult.value;
+            }
+        }
+        if (record) {
+            for (const [key, val] of Object.entries(value)) {
+                if (!propKeys.includes(key)) {
+                    const keyResult = record.key.fromParent(key);
+                    if (!keyResult.ok) {
+                        return err({
+                            type: "ObjectWithRecord",
+                            value,
+                            reason: { kind: "IndexKey", key, error: keyResult.error },
+                        });
+                    }
+                    const valueResult = record.value.fromParent(val);
+                    if (!valueResult.ok) {
+                        return err({
+                            type: "ObjectWithRecord",
+                            value,
+                            reason: { kind: "IndexValue", key, error: valueResult.error },
+                        });
+                    }
+                    result[keyResult.value] = valueResult.value;
+                }
+            }
+        }
+        if (Object.keys(errors).length > 0) {
+            return err({
+                type: record ? "ObjectWithRecord" : "Object",
+                value,
+                reason: { kind: "Props", errors },
+            });
+        }
+        return ok(result);
+    };
+    const toParent = (value) => {
+        const entries = [];
+        for (const key of propKeys) {
+            if (!(key in value) && isOptionalType(props[key])) {
+                continue;
+            }
+            entries.push([key, props[key].toParent(value[key])]);
+        }
+        if (record) {
+            const recordEntries = Object.entries(value).filter(([key]) => !propKeys.includes(key));
+            for (const [key, val] of recordEntries) {
+                entries.push([record.key.toParent(key), record.value.toParent(val)]);
+            }
+        }
+        return Object.fromEntries(entries);
+    };
+    return {
+        ...createType(record ? "ObjectWithRecord" : "Object", {
+            fromUnknown,
+            to,
+            fromParent,
+            toParent,
+        }),
+        props,
+        ...(record ? { record } : {}),
+    };
+    /* eslint-enable */
+}
+export const formatObjectError = (formatTypeError) => createTypeErrorFormatter((error) => {
+    switch (error.reason.kind) {
+        case "NotObject":
+            return `Expected a plain object but received ${error.value}`;
+        case "ExtraKeys":
+            return `Unexpected extra keys: ${error.reason.extraKeys.join(", ")}`;
+        case "Props": {
+            const formattedErrors = Object.entries(error.reason.errors)
+                .filter(([, error]) => error !== undefined)
+                .map(([key, error]) => `- ${key}: ${formatTypeError(error)}`)
+                .join("\n");
+            return `Invalid object properties:\n${formattedErrors}`;
+        }
+    }
+});
+export const formatObjectWithRecordError = (formatTypeError) => createTypeErrorFormatter((error) => {
+    switch (error.reason.kind) {
+        case "NotObject":
+            return `Expected an object, but received ${error.value}.`;
+        case "Props":
+            return formatObjectError(formatTypeError)({
+                type: "Object",
+                value: error.value,
+                reason: { kind: "Props", errors: error.reason.errors },
+            });
+        case "IndexKey":
+            return `Invalid index key ${error.reason.key}: ${formatTypeError(error.reason.error)}`;
+        case "IndexValue":
+            return `Invalid value at index key ${error.reason.key}: ${formatTypeError(error.reason.error)}`;
+    }
+});
+export function union(...args) {
+    /**
+     * Good First Issue:
+     *
+     * 1. Optimize for microbenchmarks:
+     *
+     *    - Detect if all arguments are literals and generate a fast-check function.
+     *    - This could significantly improve performance for unions of literals.
+     * 2. Enhance tagged union support:
+     *
+     *    - Detect if all arguments are objects with the same property but different
+     *         literal values (tagged unions).
+     *    - Generate a specialized function to improve validation performance for such
+     *         cases.
+     */
+    /* eslint-disable */
+    const members = args.map((arg) => (isType(arg) ? arg : literal(arg)));
+    const fromUnknown = (value) => {
+        const errors = [];
+        for (const member of members) {
+            const result = member.fromUnknown(value);
+            if (result.ok)
+                return result;
+            errors.push(result.error);
+        }
+        return err({
+            type: "Union",
+            value,
+            errors,
+        });
+    };
+    const to = (value) => {
+        for (const member of members) {
+            if (member.is(value))
+                return member.to(value);
+        }
+        assert(false, "No matching member found in Union Type `to` function");
+    };
+    return {
+        ...createType("Union", {
+            fromUnknown,
+            to,
+            fromParent: fromUnknown,
+            toParent: to,
+        }),
+        members,
+    };
+    /* eslint-enable */
+}
+export const formatUnionError = (formatTypeError) => createTypeErrorFormatter((error) => {
+    const formattedErrors = error.errors
+        .map((e, i) => `  ${i + 1}. ${formatTypeError(e)}`)
+        .join("\n");
+    return `Value ${error.value} does not match any member of the union.\nErrors:\n${formattedErrors}`;
+});
+export const isUnionType = (t) => t.name === "Union" && Array.isArray(t.members);
+/**
+ * Recursive {@link Type}.
+ *
+ * Recursive types can't be inferred, so we must define them using an interface
+ * and `recursive` Type Factory that returns a {@link Type}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * interface Category {
+ *   readonly name: string;
+ *   readonly subcategories: ReadonlyArray<Category>;
+ * }
+ *
+ * interface CategoryInput {
+ *   readonly name: string;
+ *   readonly subcategories: ReadonlyArray<CategoryInput>;
+ * }
+ *
+ * type CategoryError = ObjectError<{
+ *   readonly name: typeof String.Error;
+ *   readonly subcategories: ArrayError<CategoryError>;
+ * }>;
+ *
+ * const Category = recursive(
+ *   (): Type<"Object", Category, CategoryInput, CategoryError> =>
+ *     object({
+ *       name: String,
+ *       subcategories: array(Category),
+ *     }),
+ * );
+ * ```
+ *
+ * @category Base Factories
+ */
+export const recursive = (create) => {
+    let type;
+    return {
+        name: "Recursive",
+        from: (value) => {
+            type ??= create();
+            return type.from(value);
+        },
+        fromUnknown: (value) => {
+            type ??= create();
+            return type.fromUnknown(value);
+        },
+        to: (value) => {
+            type ??= create();
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+            return type.to(value);
+        },
+        fromParent: (value) => {
+            type ??= create();
+            return type.fromParent(value);
+        },
+        toParent: (value) => {
+            type ??= create();
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+            return type.toParent(value);
+        },
+        is: (value) => {
+            type ??= create();
+            return type.is(value);
+        },
+        [EvoluTypeSymbol]: true,
+        getParentType: () => {
+            type ??= create();
+            return type;
+        },
+    };
+};
+/**
+ * `union(null, T)` {@link Type}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const NullOrString = nullOr(String);
+ * NullOrString.from("hello"); // ok("hello")
+ * NullOrString.from(null); // ok(null)
+ * NullOrString.from(42); // err(...)
+ * ```
+ *
+ * @category Base Factories
+ */
+export const nullOr = (type) => union(Null, type);
+/**
+ * `union(undefined, T)` {@link Type}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const UndefinedOrString = undefinedOr(String);
+ * UndefinedOrString.from("world"); // ok("world")
+ * UndefinedOrString.from(undefined); // ok()
+ * UndefinedOrString.from(42); // err(...)
+ * ```
+ *
+ * @category Base Factories
+ */
+export const undefinedOr = (type) => union(Undefined, type);
+/**
+ * `union(undefined, null, T)` {@link Type}.
+ *
+ * Learn more:
+ * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#nullish-coalescing
+ *
+ * ### Example
+ *
+ * ```ts
+ * const NullishOrString = nullishOr(String);
+ * NullishOrString.from("test"); // ok("test")
+ * NullishOrString.from(null); // ok(null)
+ * NullishOrString.from(undefined); // ok()
+ * NullishOrString.from(42); // err(...)
+ * ```
+ *
+ * @category Base Factories
+ */
+export const nullishOr = (type) => union(Undefined, Null, type);
+/**
+ * Tuple {@link Type}.
+ *
+ * Represents a tuple of specific Types.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const NameAndAge = tuple(NonEmptyTrimmedString, PositiveNumber);
+ *
+ * const result = NameAndAge.from(["Alice", 25]); // ok(["Alice", 25])
+ * const error = NameAndAge.from(["Alice", -10]); // err
+ * ```
+ *
+ * @category Base Factories
+ */
+export const tuple = (...elements) => {
+    const fromUnknown = (value) => {
+        if (!Array.isArray(value) || value.length !== elements.length) {
+            return err({
+                type: "Tuple",
+                value,
+                reason: { kind: "InvalidLength", expected: elements.length },
+            });
+        }
+        const result = [];
+        for (let i = 0; i < elements.length; i++) {
+            const elementResult = elements[i].fromUnknown(value[i]);
+            if (!elementResult.ok) {
+                return err({
+                    type: "Tuple",
+                    value,
+                    reason: {
+                        kind: "Element",
+                        index: i,
+                        error: elementResult.error,
+                    },
+                });
+            }
+            result[i] = elementResult.value;
+        }
+        return ok(result);
+    };
+    const to = (value) => value.map((val, index) => elements[index].to(val));
+    const fromParent = (value) => {
+        if (!Array.isArray(value) || value.length !== elements.length) {
+            return err({
+                type: "Tuple",
+                value,
+                reason: { kind: "InvalidLength", expected: elements.length },
+            });
+        }
+        const result = [];
+        for (let i = 0; i < elements.length; i++) {
+            const elementResult = elements[i].fromParent(value[i]);
+            if (!elementResult.ok) {
+                return err({
+                    type: "Tuple",
+                    value,
+                    reason: {
+                        kind: "Element",
+                        index: i,
+                        error: elementResult.error,
+                    },
+                });
+            }
+            result.push(elementResult.value);
+        }
+        return ok(result);
+    };
+    const toParent = (value) => value.map((val, index) => elements[index].toParent(val));
+    return {
+        ...createType("Tuple", {
+            fromUnknown,
+            to,
+            fromParent,
+            toParent,
+        }),
+        elements,
+    };
+};
+export const formatTupleError = (formatTypeError) => createTypeErrorFormatter((error) => {
+    switch (error.reason.kind) {
+        case "InvalidLength":
+            return `Expected a tuple of length ${error.reason.expected}, but received ${error.value}.`;
+        case "Element":
+            return `Invalid element at index ${error.reason.index}:\n  ${formatTypeError(error.reason.error)}`;
+    }
+});
+/**
+ * 64-bit signed integer.
+ *
+ * `Int64` represents a `BigInt` constrained to a 64-bit signed integer range,
+ * which is useful for platforms that do not support the `bigint` type, such as
+ * SQLite.
+ *
+ * Because SQLite lacks a dedicated `bigint` type, it may return `number` or
+ * 'Int64` depending on the stored value or even a wrong value if a platform
+ * wrapper does not support it. A workaround for SQLite is to insert 'Int64`
+ * serialized as a string (SQLite will convert it to int) and manually cast the
+ * result to a string in SQL query and then to `Int64` in JS.
+ *
+ * https://www.sqlite.org/c3ref/int64.html
+ *
+ * @category Number
+ */
+export const Int64 = brand("Int64", BigInt, (value) => value >= -9223372036854775808n && value <= 9223372036854775807n
+    ? ok(value)
+    : err({ type: "Int64", value }));
+export const formatInt64Error = createTypeErrorFormatter((error) => `The value ${error.value} is not a valid 64-bit signed integer (Int64).`);
+export const BigIntFromString = transform(String, BigInt, (value) => trySync(() => globalThis.BigInt(value), () => ({ type: "BigIntFromString", value })), (value) => value.toString());
+export const formatBigIntFromStringError = createTypeErrorFormatter((error) => `The value ${error.value} could not be converted to a BigInt.`);
+/**
+ * Stringified {@link Int64}.
+ *
+ * @category Number
+ */
+export const Int64String = brand("Int64", String, (value) => {
+    const bigint = BigIntFromString.fromParent(value);
+    if (bigint.ok) {
+        const int64 = Int64.fromParent(globalThis.BigInt(value));
+        if (int64.ok)
+            return ok(value);
+    }
+    return err({ type: "Int64String", value });
+});
+export const formatInt64StringError = createTypeErrorFormatter((error) => `The value ${error.value} is not a valid Int64 string.`);
+/**
+ * JSON-compatible value: string, {@link FiniteNumber}, boolean, null,
+ * {@link JsonArray}, or {@link JsonObject}.
+ *
+ * @category Base Types
+ */
+export const JsonValue = recursive(() => union(String, FiniteNumber, Boolean, Null, JsonArray, JsonObject));
+/**
+ * JSON-compatible array of {@link JsonValue} elements.
+ *
+ * @category Array
+ */
+export const JsonArray = array(JsonValue);
+/**
+ * JSON-compatible object with string keys and {@link JsonValue} values.
+ *
+ * @category Object
+ */
+export const JsonObject = record(String, JsonValue);
+/**
+ * Transform Type that parses a JSON into a {@link JsonValue} and serializes a
+ * JsonValue back into a JSON string.
+ *
+ * ### Example
+ *
+ * ```ts
+ * JsonValueFromString.from(`{"key":"value"}`); // -> ok({ key: "value" })
+ * JsonValueFromString.to({ key: "value" }); // -> '{"key":"value"}'
+ * ```
+ *
+ * @category String
+ */
+export const JsonValueFromString = transform(String, JsonValue, (value) => trySync(() => JSON.parse(value), (error) => ({
+    type: `JsonValueFromString`,
+    value,
+    message: globalThis.String(error),
+})), (value) => JSON.stringify(value));
+export const formatJsonValueFromStringError = createTypeErrorFormatter((error) => `Invalid JSONValue: ${error.value}. Error: ${error.message}`);
+/**
+ * JSON-string {@link Type}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const result = Json.from('{"key":"value"}'); // -> ok('{"key":"value"}')
+ * const error = Json.from("invalid json"); // -> err({ type: "Json", value: "invalid json", message: "Unexpected token i in JSON at position 0" })
+ * ```
+ *
+ * @category String
+ */
+export const Json = brand("Json", String, (value) => {
+    const result = JsonValueFromString.fromParent(value);
+    if (!result.ok)
+        return err({
+            type: "Json",
+            value,
+            message: result.error.message,
+        });
+    return ok(value);
+});
+export const formatJsonError = createTypeErrorFormatter((error) => `Invalid JSON: ${error.value}. Error: ${error.message}`);
+/**
+ * Optional {@link Type}.
+ *
+ * Marks a `Type` as **optional**, meaning:
+ *
+ * - If the value is **present**, it must match the given `Type`.
+ * - If the value is **absent**, it is **not included** in the final object.
+ *
+ * This is different from {@link undefinedOr}, which allows explicit `undefined`
+ * but **still requires the key to exist**.
+ *
+ * ### Example:
+ *
+ * ```ts
+ * const Todo = object({
+ *   id: TodoId,
+ *   title: NonEmptyString1000,
+ *   isCompleted: optional(SqliteBoolean),
+ * });
+ * ```
+ */
+export const optional = (type) => ({
+    ...createType("Optional", {
+        fromUnknown: type.fromUnknown,
+        to: type.to,
+        fromParent: type.fromParent,
+        toParent: type.toParent,
+    }),
+    parent: type,
+});
+/** Determines if a given type is an {@link OptionalType}. */
+export const isOptionalType = (x) => typeof x === "object" && x != null && "name" in x && x.name === "Optional";
+/**
+ * Creates a partial object type where all properties are optional.
+ *
+ * This is useful when you want to validate an object in which none of the keys
+ * are required, but if they are present they must conform to their
+ * corresponding Types.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const PartialUser = partial({
+ *   name: NonEmptyString,
+ *   age: PositiveNumber,
+ * });
+ *
+ * // Valid: an empty object is accepted
+ * PartialUser.from({});
+ *
+ * // Valid: when provided, the properties must validate correctly
+ * PartialUser.from({ name: "Alice" });
+ *
+ * // Invalid: if a property is present but fails validation it returns an error
+ * PartialUser.from({ age: -5 });
+ * ```
+ *
+ * @category Object
+ */
+export const partial = (props) => {
+    const optionalProps = {};
+    for (const key in props) {
+        if (Object.prototype.hasOwnProperty.call(props, key)) {
+            optionalProps[key] = optional(props[key]);
+        }
+    }
+    return object(optionalProps);
+};
+/**
+ * Converts each “nullable” property (a union that includes {@link Null}) into an
+ * {@link optional} property. This means consumers can omit the property
+ * entirely, or set it to `null`, or set it to the non-null member of the
+ * union.
+ *
+ * @category Object
+ */
+export const nullableToOptional = (props) => {
+    const transformedProps = {};
+    for (const key in props) {
+        const type = props[key];
+        if (isUnionType(type)) {
+            const hasNull = type.members.some((m) => m === Null);
+            if (hasNull) {
+                transformedProps[key] = optional(type);
+                continue;
+            }
+        }
+        transformedProps[key] = type;
+    }
+    return object(transformedProps);
+};
+/**
+ * Create a new `object` {@link Type} by omitting some keys.
+ *
+ * @category Object
+ */
+export function omit(objectType, ...keys) {
+    const newProps = {};
+    for (const key in objectType.props) {
+        if (!keys.includes(key)) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+            newProps[key] = objectType.props[key];
+        }
+    }
+    return object(newProps);
+}
+/**
+ * Creates a transform Type that serializes a given `Type` into a branded JSON
+ * string. The transformation is reversible, ensuring that we can safely parse
+ * it back.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const Person = object({
+ *   name: NonEmptyString50,
+ *   age: FiniteNumber,
+ * });
+ * type Person = typeof Person.Type;
+ *
+ * const PersonJson = json(Person, "PersonJson");
+ * // string & Brand<"PersonJson">
+ * type PersonJson = typeof PersonJson.Type;
+ *
+ * // Person -> string & Brand<"PersonJson">
+ * const personJson = PersonJson.from({ name: "Alice", age: 30 });
+ * expect(personJson).toEqual(ok('{"name":"Alice","age":30}'));
+ *
+ * // string & Brand<"PersonJson"> -> Person
+ * const person = PersonJson.to(personJson);
+ *
+ * // serialize/parse any JSON value
+ * const AnyJson = json(JsonValue, "AnyJson");
+ * ```
+ */
+export const json = (type, name) => {
+    const BrandedJsonString = brand(name, String, (value) => {
+        const jsonValue = JsonValueFromString.fromParent(value);
+        if (!jsonValue.ok)
+            return jsonValue;
+        const parsed = type.fromUnknown(jsonValue.value);
+        if (!parsed.ok)
+            return parsed;
+        return ok(value);
+    });
+    return transform(type, BrandedJsonString, (value) => ok(JSON.stringify(value)), 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    (value) => JSON.parse(value));
+};
+/**
+ * Creates a unified error formatter that handles both Evolu Type's built-in
+ * {@link TypeErrors} and custom errors. It also lets us override the default
+ * formatting for specific errors.
+ *
+ * If you prefer not to reuse any built-in error formatters, you can write your
+ * own `formatTypeError` function from scratch.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * const formatError = createFormatTypeError();
+ * console.log(formatError({ type: "String", value: 42 }));
+ * // "A value 42 is not a string."
+ * ```
+ *
+ * A custom `formatTypeError` function:
+ *
+ * ```ts
+ * type AppErrors =
+ *   | ValidMutationSizeError
+ *   | StringError
+ *   | MinLengthError
+ *   | MaxLengthError
+ *   | NullError
+ *   | IdError
+ *   | TrimmedError
+ *   | MnemonicError
+ *   | LiteralError
+ *   // Composite errors
+ *   | ObjectError<Record<string, AppErrors>>
+ *   | UnionError<AppErrors>;
+ *
+ * const formatTypeError: TypeErrorFormatter<AppErrors> = (error) => {
+ *   // In the real code, we would use the createTypeErrorFormatter helper
+ *   // that safely stringifies error value.
+ *   switch (error.type) {
+ *     case "Id":
+ *       return `Invalid Id on table: ${error.table}.`;
+ *     case "MaxLength":
+ *       return `Max length is ${error.max}.`;
+ *     case "MinLength":
+ *       return `Min length is ${error.min}.`;
+ *     case "Mnemonic":
+ *       return `Invalid mnemonic: ${String(error.value)}`;
+ *     case "Null":
+ *       return `Not null`;
+ *     case "String":
+ *       // We can reuse existing formatter.
+ *       return formatStringError(error);
+ *     case "Trimmed":
+ *       return "Value is not trimmed.";
+ *     case "ValidMutationSize":
+ *       return "A developer made an error, this should not happen.";
+ *     case "Literal":
+ *       return formatLiteralError(error);
+ *     // Composite Types
+ *     case "Union":
+ *       return `Union errors: ${error.errors.map(formatTypeError).join(", ")}`;
+ *     case "Object": {
+ *       if (
+ *         error.reason.kind === "ExtraKeys" ||
+ *         error.reason.kind === "NotObject"
+ *       )
+ *         return "A developer made an error, this should not happen.";
+ *       const firstError = Object.values(error.reason.errors).find(
+ *         (e) => e !== undefined,
+ *       )!;
+ *       return formatTypeError(firstError);
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @category Utilities
+ */
+export const createFormatTypeError = (extraFormatter) => {
+    const formatTypeError = (error) => {
+        const extraMessage = extraFormatter?.(error);
+        if (extraMessage != null)
+            return extraMessage;
+        error = error;
+        switch (error.type) {
+            case "String":
+                return formatStringError(error);
+            case "Number":
+                return formatNumberError(error);
+            case "BigInt":
+                return formatBigIntError(error);
+            case "Boolean":
+                return formatBooleanError(error);
+            case "Undefined":
+                return formatUndefinedError(error);
+            case "Null":
+                return formatNullError(error);
+            case "Function":
+                return formatFunctionError(error);
+            case "Uint8Array":
+                return formatUint8ArrayError(error);
+            case "InstanceOf":
+                return formatInstanceOfError(error);
+            case "EvoluType":
+                return formatIsTypeError(error);
+            case "CurrencyCode":
+                return formatCurrencyCodeError(error);
+            case "DateIsoString":
+                return formatDateIsoStringError(error);
+            case "Trimmed":
+                return formatTrimmedError(error);
+            case "MinLength":
+                return formatMinLengthError(error);
+            case "MaxLength":
+                return formatMaxLengthError(error);
+            case "Length":
+                return formatLengthError(error);
+            case "Mnemonic":
+                return formatMnemonicError(error);
+            case "Regex":
+                return formatRegexError(error);
+            case "Id":
+                return formatIdError(error);
+            case "Positive":
+                return formatPositiveError(error);
+            case "Negative":
+                return formatNegativeError(error);
+            case "NonPositive":
+                return formatNonPositiveError(error);
+            case "NonNegative":
+                return formatNonNegativeError(error);
+            case "Int":
+                return formatIntError(error);
+            case "GreaterThan":
+                return formatGreaterThanError(error);
+            case "LessThan":
+                return formatLessThanError(error);
+            case "GreaterThanOrEqualTo":
+                return formatGreaterThanOrEqualToError(error);
+            case "LessThanOrEqualTo":
+                return formatLessThanOrEqualToError(error);
+            case "NonNaN":
+                return formatNonNaNError(error);
+            case "Finite":
+                return formatFiniteError(error);
+            case "MultipleOf":
+                return formatMultipleOfError(error);
+            case "Between":
+                return formatBetweenError(error);
+            case "Literal":
+                return formatLiteralError(error);
+            case "Int64":
+                return formatInt64Error(error);
+            case "BigIntFromString":
+                return formatBigIntFromStringError(error);
+            case "Int64String":
+                return formatInt64StringError(error);
+            case "JsonValueFromString":
+                return formatJsonValueFromStringError(error);
+            case "Json":
+                return formatJsonError(error);
+            // Composite Types
+            case "SimplePassword":
+                return formatSimplePasswordError(formatTypeError)(error);
+            case "Array":
+                return formatArrayError(formatTypeError)(error);
+            case "Record":
+                return formatRecordError(formatTypeError)(error);
+            case "Object":
+                return formatObjectError(formatTypeError)(error);
+            case "ObjectWithRecord":
+                return formatObjectWithRecordError(formatTypeError)(error);
+            case "Union":
+                return formatUnionError(formatTypeError)(error);
+            case "Tuple":
+                return formatTupleError(formatTypeError)(error);
+        }
+    };
+    return formatTypeError;
+};