@evolu/common 6.0.1-preview.2 → 6.0.1-preview.20

package/dist/src/Type.d.ts

@@ -1,77 +1,179 @@
 /**
- * 🧩 Validation, Parsing, and Transformation
+ * 🧩 Type-safe runtime types
  *
- * ## Intro
+ * Evolu {@link Type} is like a type guard that returns typed errors (via
+ * {@link Result}) instead of throwing. We either get a safely typed value or a
+ * precise, composable error value telling us exactly why validation failed.
  *
- * You probably know [Zod](https://zod.dev). Evolu has {@link Type}.
+ * Why another validation library?
  *
- * Evolu Type exists because no existing validation/parsing/transformation
- * library fully met our needs:
+ * - **Result-based error handling** – no exceptions for normal control flow.
+ * - **Typed errors with decoupled formatters** – validation logic ≠ user
+ *   messages.
+ * - **Consistent constraints via {@link Brand}** – every constraint becomes part
+ *   of the type.
+ * - **No user-land chaining DSL** – designed with the upcoming ES pipe operator
+ *   in mind.
+ * - **Selective validation** – parent validations are skipped when already proved
+ *   by typing.
+ * - **Simple, top-down implementation** – readable source code from top to bottom
+ *   with no hidden magic; just plain functions and composition.
  *
- * - **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.
+ * ### Base Types Quick Start
  *
- * **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.
+ * ```ts
+ * // Validate unknown values
+ * const value: unknown = "hello";
+ * const stringResult = String.fromUnknown(value);
+ * if (!stringResult.ok) {
+ *   // console.error(formatStringError(stringResult.error));
+ *   return stringResult; // inside a function returning Result<string, _>
+ * }
+ * // Safe branch: value is now string
+ * const upper = stringResult.value.toUpperCase();
+ *
+ * // Type guard style
+ * if (String.is(value)) {
+ *   // narrowed to string
+ * }
+ *
+ * // Composing: arrays & objects
+ * const Numbers = array(Number); // ReadonlyArray<number>
+ * const Point = object({ x: Number, y: Number });
+ *
+ * Numbers.from([1, 2, 3]); // ok
+ * Point.from({ x: 1, y: 2 }); // ok
+ * Point.from({ x: 1, y: "2" }); // err -> nested Number error
+ * ```
+ *
+ * ### Branding Basics
+ *
+ * Branding adds semantic meaning & constraints while preserving the runtime
+ * shape:
+ *
+ * ```ts
+ * const CurrencyCode = brand("CurrencyCode", String, (value) =>
+ *   /^[A-Z]{3}$/.test(value)
+ *     ? ok(value)
+ *     : err<CurrencyCodeError>({ type: "CurrencyCode", value }),
+ * );
+ * type CurrencyCode = typeof CurrencyCode.Type; // string & Brand<"CurrencyCode">
+ *
+ * interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}
  *
- * - Evolu `Type` is:
+ * const formatCurrencyCodeError =
+ *   createTypeErrorFormatter<CurrencyCodeError>(
+ *     (error) => `Invalid currency code: ${error.value}`,
+ *   );
  *
- * - 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.
+ * const r = CurrencyCode.from("USD"); // ok("USD")
+ * const e = CurrencyCode.from("usd"); // err(...)
+ * ```
  *
- * 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:
+ * See also reusable brand factories like `minLength`, `maxLength`, `trimmed`,
+ * `positive`, `between`, etc.
  *
- * `Unknown` -> `String` -> `TrimmedString` -> `NonEmptyTrimmedString100`
+ * ### Objects & Optional Fields
  *
- * For `NonEmptyTrimmedString100`, the parent Type is `TrimmedString`. For
- * `TrimmedString`, the parent Type is `String`.
+ * ```ts
+ * const User = object({
+ *   name: NonEmptyTrimmedString100,
+ *   age: optional(PositiveInt),
+ * });
+ * type User = typeof User.Type;
  *
- * 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.
+ * User.from({ name: "Alice" }); // ok
+ * User.from({ name: "Alice", age: -1 }); // err(PositiveInt)
+ * ```
  *
- * Speaking of `fromParent` and `toParent`, those functions exist to bypass
- * parent Types when we can rely on TypeScript types.
+ * ### Deriving JSON String 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")`.
+ * ```ts
+ * const Person = object({
+ *   name: NonEmptyString50,
+ *   // Did you know that JSON.stringify converts NaN (a number) into null?
+ *   // To prevent this, use FiniteNumber.
+ *   age: FiniteNumber,
+ * });
+ * type Person = typeof Person.Type;
+ *
+ * const [PersonJson, personToPersonJson, personJsonToPerson] = json(
+ *   Person,
+ *   "PersonJson",
+ * );
+ * // string & Brand<"PersonJson">
+ * type PersonJson = typeof PersonJson.Type;
+ *
+ * const person = Person.orThrow({
+ *   name: "Alice",
+ *   age: 30,
+ * });
+ *
+ * const personJson = personToPersonJson(person);
+ * expect(personJsonToPerson(personJson)).toEqual(person);
+ * ```
+ *
+ * ### Error Formatting
+ *
+ * Evolu separates validation logic from human-readable messages. There are two
+ * layers:
+ *
+ * 1. Per-type formatters (e.g. `formatStringError`) – simple, focused, already
+ *    used earlier in the quick start example.
+ * 2. A unified formatter via `createFormatTypeError` – composes all built-in and
+ *    custom errors (including nested composite types) and lets us override
+ *    selected messages.
+ *
+ * #### 1. Per-Type Formatter (recap)
+ *
+ * ```ts
+ * const r = String.fromUnknown(42);
+ * if (!r.ok) console.error(formatStringError(r.error));
+ * ```
+ *
+ * #### 2. Unified Formatter with Overrides
+ *
+ * ```ts
+ * // Override only what we care about; fall back to built-ins for the rest.
+ * const formatTypeError = createFormatTypeError((error) => {
+ *   if (error.type === "MinLength") return `Min length is ${error.min}`;
+ * });
+ *
+ * const User = object({ name: NonEmptyTrimmedString100 });
+ * const resultUser = User.from({ name: "" });
+ * if (!resultUser.ok) console.error(formatTypeError(resultUser.error));
+ *
+ * const badPoint = object({ x: Number, y: Number }).from({
+ *   x: 1,
+ *   y: "foo",
+ * });
+ * if (!badPoint.ok) console.error(formatTypeError(badPoint.error));
+ * ```
+ *
+ * The unified formatter walks nested structures (object / array / record /
+ * tuple / union) and applies overrides only where specified, greatly reducing
+ * boilerplate when formatting complex validation errors.
  *
  * ### Tip
  *
  * If necessary, write `globalThis.String` instead of `String` to avoid naming
- * clashes with Base Types.
+ * clashes with native types.
  *
- * ### Design Decision:
+ * ### Design Decision: No Bidirectional Transformations
  *
- * 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.
+ * Evolu Type intentionally does not support bidirectional transformations. It
+ * previously did, but supporting that while keeping typed error fidelity added
+ * complexity that hurt readability & reliability. Most persistence pipelines
+ * (e.g. SQLite) already require explicit mapping of query results, so implicit
+ * reverse transforms would not buy much. We may revisit this if we can design a
+ * minimal, 100% safe API that preserves simplicity.
  *
  * @module
  */
-import { NanoIdLibDep } from "./NanoId.js";
-import { Ok, Result } from "./Result.js";
-import type { Brand, Literal, Simplify, WidenLiteral } from "./Types.js";
+import type { Brand } from "./Brand.js";
+import { type RandomBytesDep } from "./Crypto.js";
+import { Result } from "./Result.js";
+import type { Literal, Simplify, WidenLiteral } from "./Types.js";
 export interface Type<Name extends TypeName, 
 /** The type this Type resolves to. */
 T, 
@@ -93,38 +195,58 @@ ParentError extends TypeError = Error> {
      */
     readonly from: (value: Input) => Result<T, ParentError | Error>;
     /**
-     * Creates `T` from an unknown value.
+     * Creates `T` from an `Input` value, throwing an error if validation fails.
      *
-     * This is useful when a value is unknown.
-     */
-    readonly fromUnknown: (value: unknown) => Result<T, ParentError | Error>;
-    /**
-     * The opposite of `from` and `fromUnknown`.
+     * This is a convenience method that combines `from` with `getOrThrow`.
      *
-     * This is useful to transform `T` back to its `Input` representation.
+     * **When to use:**
      *
-     * For `refine`, it only removes the brand. For `transform`, it changes value.
-     */
-    readonly to: (value: T) => Input;
-    /**
-     * Creates `T` from `Parent` type.
+     * - Configuration values that are guaranteed to be valid (e.g., hardcoded
+     *   constants)
+     * - Application startup where failure should crash the program
+     * - Test code with known valid inputs
+     * - Converting from trusted sources where validation failure indicates a
+     *   programming error
      *
-     * This function skips parent Types validations/transformations when we have
-     * already partially validated/transformed value.
+     * **When NOT to use:**
      *
-     * For example, `TrimString.from` checks whether a value is a string and trims
-     * it. If we only want to trim a string, we can use `fromParent`.
+     * - User input validation - use `from` and handle errors gracefully
+     * - Data from external APIs or files - use `from` for proper error handling
+     * - Library code that should return Results rather than throw
      *
      * ### Example
      *
      * ```ts
-     * // string & Brand<"Trimmed">
-     * const value = TrimString.fromParent("a ").value; // as efficient as foo.trim()
+     * // ✅ Good: Known valid constant
+     * const maxRetries = PositiveInt.orThrow(3);
+     *
+     * // ✅ Good: App configuration that should crash on invalid values
+     * const appName = SimpleName.orThrow("MyApp");
+     *
+     * // ❌ Avoid: User input (use `from` instead)
+     * const userAge = PositiveInt.orThrow(userInput); // Could crash!
+     *
+     * // ✅ Better: Handle user input gracefully
+     * const ageResult = PositiveInt.from(userInput);
+     * if (!ageResult.ok) {
+     *   // Handle validation error
+     * }
      * ```
      */
+    readonly orThrow: (value: Input) => T;
+    /**
+     * Creates `T` from an unknown value.
+     *
+     * This is useful when a value is unknown.
+     */
+    readonly fromUnknown: (value: unknown) => Result<T, ParentError | Error>;
+    /**
+     * Creates `T` from `Parent` type.
+     *
+     * This function skips parent Types validations when we have already partially
+     * validated value.
+     */
     readonly fromParent: (value: Parent) => Result<T, Error>;
-    /** The opposite of `fromParent`. */
-    readonly toParent: (value: T) => Parent;
     /**
      * A **type guard** that checks whether an unknown value satisfies the
      * {@link Type}.
@@ -230,12 +352,47 @@ export interface TypeErrorWithReason<Name extends TypeName = TypeName, Reason ex
     readonly reason: Reason;
 }
 export type AnyType = Type<any, any, any, any, any, any>;
+/**
+ * Extracts the name from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferName<A extends AnyType> = A extends Type<infer Name, any, any, any, any, any> ? Name : never;
+/**
+ * Extracts the type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferType<A extends AnyType> = A extends Type<any, infer T, any, any, any, any> ? T : never;
+/**
+ * Extracts the input type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferInput<A extends AnyType> = A extends Type<any, any, infer Input, any, any, any> ? Input : never;
+/**
+ * Extracts the specific error type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferError<A extends AnyType> = A extends Type<any, any, any, infer Error, any, any> ? Error : never;
+/**
+ * Extracts the parent type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferParent<A extends AnyType> = A extends Type<any, any, any, any, infer Parent, any> ? Parent : never;
+/**
+ * Extracts the parent error type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferParentError<A extends AnyType> = A extends Type<any, any, any, any, any, infer ParentError> ? ParentError : never;
+/**
+ * Extracts all error types (Error | ParentError) from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferErrors<T extends AnyType> = T extends Type<any, any, any, infer Error, any, infer ParentError> ? Error | ParentError : never;
 declare const EvoluTypeSymbol: unique symbol;
 /**
@@ -268,12 +425,6 @@ export type TypeErrorFormatter<Error extends TypeError> = (error: Error) => stri
  * 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
  *
@@ -410,7 +561,7 @@ export declare const formatIsTypeError: TypeErrorFormatter<EvoluTypeError>;
  * The `brand` Type Factory takes the name of a new {@link Brand}, a parent Type
  * to be branded, and the optional `refine` function for additional constraint.
  *
- * If the `refine` function is omited, TODO:
+ * The `refine` function can be omitted if we only want to add a brand.
  *
  * ### Examples
  *
@@ -489,7 +640,7 @@ export declare const formatIsTypeError: TypeErrorFormatter<EvoluTypeError>;
  *   confirmPassword: SimplePassword,
  * });
  *
- * const ValidForm = brand("Valid", Form, (value) => {
+ * const ValidForm = brand("ValidForm", Form, (value) => {
  *   if (value.password !== value.confirmPassword)
  *     return err<ValidFormError>({
  *       type: "ValidForm",
@@ -567,17 +718,19 @@ export declare const formatCurrencyCodeError: TypeErrorFormatter<CurrencyCodeErr
  * ### Example
  *
  * ```ts
- * const result = DateIsoString.from("2023-01-01T12:00:00.000Z"); // ok
- * const error = DateIsoString.from("10000-01-01T00:00:00.000Z"); // err
+ * const result = DateIso.from("2023-01-01T12:00:00.000Z"); // ok
+ * const error = DateIso.from("10000-01-01T00:00:00.000Z"); // err
  * ```
  *
  * @category String
  */
-export declare const DateIsoString: BrandType<Type<"String", string, string, StringError, string, StringError>, "DateIso", DateIsoStringError, StringError>;
-export type DateIsoString = typeof DateIsoString.Type;
-export interface DateIsoStringError extends TypeError<"DateIsoString"> {
+export declare const DateIso: BrandType<Type<"String", string, string, StringError, string, StringError>, "DateIso", DateIsoError, StringError>;
+export type DateIso = typeof DateIso.Type;
+export interface DateIsoError extends TypeError<"DateIso"> {
 }
-export declare const formatDateIsoStringError: TypeErrorFormatter<DateIsoStringError>;
+export declare const formatDateIsoError: TypeErrorFormatter<DateIsoError>;
+export declare const dateToDateIso: (value: Date) => Result<DateIso, DateIsoError>;
+export declare const dateIsoToDate: (value: DateIso) => Date;
 /**
  * Helper type for Type Factory that creates a branded Type.
  *
@@ -600,18 +753,12 @@ export type BrandFactory<Name extends TypeName, Input, RefineError extends TypeE
 /**
  * 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.
+ * This Type Factory validates whether a string has no leading or trailing
+ * whitespaces.
  *
- * ### Examples
+ * ### Example
  *
  * ```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;
@@ -623,33 +770,6 @@ export declare const trimmed: BrandFactory<"Trimmed", string, TrimmedError>;
 export interface TrimmedError extends TypeError<"Trimmed"> {
 }
 export declare const formatTrimmedError: TypeErrorFormatter<TrimmedError>;
-export type TransformBrandFactory<Name extends TypeName, Input, TransformError extends TypeError = never> = <PName extends TypeName, P extends Input, PInput, PParent, PError extends TypeError = never, PParentError extends TypeError = never>(parent: Type<PName, P, PInput, PError, PParent, PParentError>) => TransformType<Type<PName, P, PInput, PError, PParent, PParentError>, BrandType<Type<PName, P, PInput, PError, PParent, PParentError>, Name, never, PError | PParentError>, TransformError>;
-/**
- * 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 declare const trim: TransformBrandFactory<"Trimmed", string>;
 /**
  * Trimmed string
  *
@@ -660,6 +780,7 @@ export declare const trim: TransformBrandFactory<"Trimmed", string>;
  */
 export declare const TrimmedString: BrandType<Type<"String", string, string, StringError, string, StringError>, "Trimmed", TrimmedError, StringError>;
 export type TrimmedString = typeof TrimmedString.Type;
+export declare const trim: (value: string) => TrimmedString;
 /**
  * Minimum length.
  *
@@ -782,9 +903,9 @@ export interface RegexError<Name extends TypeName = TypeName> extends TypeError<
 }
 export declare const formatRegexError: TypeErrorFormatter<RegexError<Capitalize<string>>>;
 /**
- * URL-safe Base64 string.
+ * URL-safe string.
  *
- * A `Base64Url` string uses a limited alphabet that is URL-safe:
+ * A `UrlSafeString` uses a limited alphabet that is safe for URLs:
  *
  * - Uppercase letters (`A-Z`)
  * - Lowercase letters (`a-z`)
@@ -792,31 +913,47 @@ export declare const formatRegexError: TypeErrorFormatter<RegexError<Capitalize<
  * - Dash (`-`)
  * - Underscore (`_`)
  *
+ * This is the same character set used by Base64Url encoding, but this type does
+ * not validate that the string is actually Base64Url-encoded data.
+ *
  * ### Example
  *
  * ```ts
- * const result = Base64Url.from("abc123_-");
+ * const result = UrlSafeString.from("abc123_-");
  * if (result.ok) {
- *   console.log("Valid Base64Url string:", result.value);
+ *   console.log("Valid URL-safe string:", result.value);
  * } else {
- *   console.error("Invalid Base64Url string:", result.error);
+ *   console.error("Invalid URL-safe string:", result.error);
  * }
  * ```
  *
  * @category String
  */
-export declare const Base64Url: BrandType<Type<"String", string, string, StringError, string, StringError>, "Base64Url", RegexError<"Base64Url">, StringError>;
-export type Base64Url = typeof Base64Url.Type;
-export type Base64UrlError = typeof Base64Url.Error;
+export declare const UrlSafeString: BrandType<Type<"String", string, string, StringError, string, StringError>, "UrlSafeString", RegexError<"UrlSafeString">, StringError>;
+export type UrlSafeString = typeof UrlSafeString.Type;
+export type UrlSafeStringError = typeof UrlSafeString.Error;
 /**
- * Simple alphanumeric string for naming.
+ * Base64Url without padding.
  *
- * A `SimpleName` string uses a limited, safe alphabet for naming purposes:
+ * Encode with {@link uint8ArrayToBase64Url}, decode with
+ * {@link base64UrlToUint8Array}.
  *
- * - Uppercase letters (`A-Z`)
- * - Lowercase letters (`a-z`)
- * - Digits (`0-9`)
- * - Dash (`-`)
+ * @category String
+ */
+export declare const Base64Url: BrandType<Type<"String", string, string, StringError, string, StringError>, "Base64Url", Base64UrlError, StringError>;
+export type Base64Url = typeof Base64Url.Type;
+export interface Base64UrlError extends TypeError<"Base64Url"> {
+}
+export declare const formatBase64UrlError: TypeErrorFormatter<Base64UrlError>;
+/** Encodes a Uint8Array to a {@link Base64Url} string. */
+export declare const uint8ArrayToBase64Url: (bytes: Uint8Array) => Base64Url;
+/** Decodes a {@link Base64Url} string to a Uint8Array. */
+export declare const base64UrlToUint8Array: (str: Base64Url) => Uint8Array;
+/**
+ * Simple alphanumeric string for naming in file systems, URLs, and identifiers.
+ *
+ * Uses the same safe alphabet as {@link UrlSafeString} (letters, digits, `-`,
+ * `_`). See `UrlSafeString` for details.
  *
  * The string must be between 1 and 42 characters.
  *
@@ -833,17 +970,10 @@ export type Base64UrlError = typeof Base64Url.Error;
  *
  * @category String
  */
-export declare const SimpleName: BrandType<Type<"String", string, string, StringError, string, StringError>, "SimpleName", RegexError<"SimpleName">, StringError>;
+export declare const SimpleName: BrandType<BrandType<Type<"String", string, string, StringError, string, StringError>, "UrlSafeString", RegexError<"UrlSafeString">, StringError>, "SimpleName", SimpleNameError, StringError | RegexError<"UrlSafeString">>;
 export type SimpleName = typeof SimpleName.Type;
-export type SimpleNameError = typeof SimpleName.Error;
-/**
- * Default NanoId.
- *
- * @category String
- */
-export declare const NanoId: BrandType<Type<"String", string, string, StringError, string, StringError>, "NanoId", RegexError<"NanoId">, StringError>;
-export type NanoId = typeof NanoId.Type;
-export type NanoIdError = typeof NanoId.Error;
+export interface SimpleNameError extends TypeError<"SimpleName"> {
+}
 /**
  * Trimmed string between 8 and 64 characters, branded as `SimplePassword`.
  *
@@ -854,16 +984,37 @@ export type SimplePassword = typeof SimplePassword.Type;
 export type SimplePasswordError = typeof SimplePassword.Error;
 export declare const formatSimplePasswordError: (formatTypeError: TypeErrorFormatter<StringError | MinLengthError<8> | MaxLengthError<64> | TrimmedError>) => TypeErrorFormatter<SimplePasswordError>;
 /**
- * `Id` {@link Type}.
+ * Globally unique identifier.
+ *
+ * **Evolu Id** is 16 random bytes from a cryptographically secure random
+ * generator, encoded as 22-character Base64Url string. This provides strong
+ * collision resistance for distributed ID generation.
+ *
+ * ### Design Rationale
+ *
+ * Why Evolu Id over alternatives:
  *
- * Represents a unique identifier with exactly 21 characters, using NanoID's
- * standard format (`A-Za-z0-9_-`).
+ * - **NanoID**: No standard binary serialization format, and uses only ~126 bits
+ *   of entropy (21 characters from 64-symbol alphabet) compared to Evolu Id's
+ *   128 bits.
+ * - **UUID (v4)**: String format is 36 characters (with hyphens) compared to
+ *   Evolu Id's 22 characters. While UUIDs can be stored as 16 bytes, their
+ *   standard string representation is verbose.
+ * - **UUID v7**: Includes timestamp in the ID, which leaks information about when
+ *   data was created. This is a privacy concern for local-first applications
+ *   where creation time must remain private.
+ *
+ * Evolu Id provides 128 bits of entropy, compact string representation (22
+ * characters), standard and native string serialization (Base64Url), and no
+ * privacy leaks.
  *
  * @category String
  */
-export declare const Id: BrandType<Type<"String", string, string, StringError, string, StringError>, "Id", RegexError<"Id">, StringError>;
+export declare const Id: BrandType<Type<"String", string, string, StringError, string, StringError>, "Id", IdError, StringError>;
 export type Id = typeof Id.Type;
-export declare const idTypeValueLength = 21;
+export interface IdError extends TypeError<"Id"> {
+}
+export declare const formatIdError: TypeErrorFormatter<IdError>;
 /**
  * Creates an {@link Id}.
  *
@@ -872,11 +1023,48 @@ export declare const idTypeValueLength = 21;
  * ```ts
  * // string & Brand<"Id">
  * const id = createId(deps);
+ *
+ * // string & Brand<"Id"> & Brand<"Todo">
+ * const todoId = createId<"Todo">(deps);
  * ```
  */
-export declare const createId: (deps: NanoIdLibDep) => Id;
+export declare const createId: <B extends string = never>(deps: RandomBytesDep) => [B] extends [never] ? Id : Id & Brand<B>;
 /**
- * Type Factory to create branded {@link Id} Type for a specific table.
+ * Creates an {@link Id} from a string using SHA-256.
+ *
+ * When integrating with external systems that use different ID formats, use
+ * this function to convert external IDs into valid Evolu IDs.
+ *
+ * In Evolu's CRDT, the ID serves as the unique identifier for conflict
+ * resolution across distributed clients. When multiple clients create records
+ * with the same external identifier, they must resolve to the same Evolu ID to
+ * ensure data consistency.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Both clients will generate the same ID
+ * const id1 = createIdFromString("user-api-123");
+ * const id2 = createIdFromString("user-api-123");
+ * console.log(id1 === id2); // true
+ *
+ * upsert("todo", {
+ *   id: createIdFromString("external-todo-456"),
+ *   title: "Synced from external system",
+ * });
+ * ```
+ *
+ * **Important**: This transformation is one-way. We cannot recover the original
+ * external string from the generated {@link Id}. If we need to preserve the
+ * original external ID, store it in a separate column.
+ *
+ * @category String
+ */
+export declare const createIdFromString: <B extends string = never>(value: string) => [B] extends [never] ? Id : Id & Brand<B>;
+/**
+ * Creates a branded {@link Id} Type for a table's primary key.
+ *
+ * The table name becomes an additional brand for type safety.
  *
  * ### Example
  *
@@ -888,14 +1076,20 @@ export declare const createId: (deps: NanoIdLibDep) => Id;
  *
  * @category String
  */
-export declare const id: <Table extends TypeName>(table: Table) => IdType<Table>;
-export interface IdType<Table extends TypeName> extends Type<"Id", string & Brand<"Id"> & Brand<Table>, string, IdError<Table>, string, StringError> {
+export declare const id: <Table extends TypeName>(table: Table) => TableId<Table>;
+export interface TableId<Table extends TypeName> extends Type<"Id", string & Brand<"Id"> & Brand<Table>, string, TableIdError<Table>, string, StringError> {
     table: Table;
 }
-export interface IdError<Table extends TypeName = TypeName> extends TypeError<"Id"> {
+export interface TableIdError<Table extends TypeName = TypeName> extends TypeError<"TableId"> {
     readonly table: Table;
 }
-export declare const formatIdError: TypeErrorFormatter<IdError<Capitalize<string>>>;
+export declare const formatTableIdError: TypeErrorFormatter<TableIdError<Capitalize<string>>>;
+/** Binary representation of an {@link Id}. */
+export declare const IdBytes: BrandType<BrandType<Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, Uint8ArrayError, Uint8Array<ArrayBufferLike>, Uint8ArrayError>, "Length16", LengthError<16>, Uint8ArrayError>, "IdBytes", BrandWithoutRefineError<"IdBytes", LengthError<16> | Uint8ArrayError>, never>;
+export type IdBytes = typeof IdBytes.Type;
+export declare const idBytesTypeValueLength: NonNegativeInt;
+export declare const idToIdBytes: (id: Id) => IdBytes;
+export declare const idBytesToId: (idBytes: IdBytes) => Id;
 /**
  * Positive number.
  *
@@ -963,7 +1157,7 @@ export declare const formatNonNegativeError: TypeErrorFormatter<NonNegativeError
 export declare const NonNegativeNumber: BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "NonNegative", NonNegativeError, NumberError>;
 export type NonNegativeNumber = typeof NonNegativeNumber.Type;
 /** @category Number */
-export declare const PositiveNumber: BrandType<Type<"Brand", number & Brand<"NonNegative">, number, NonNegativeError, number, NumberError>, "Positive", PositiveError, NumberError | NonNegativeError>;
+export declare const PositiveNumber: BrandType<Type<"Brand", number & Brand<"NonNegative">, number, NonNegativeError, number, NumberError>, "Positive", PositiveError, NonNegativeError | NumberError>;
 export type PositiveNumber = typeof PositiveNumber.Type;
 /** @category Number */
 export declare const NonPositiveNumber: BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "NonPositive", NonPositiveError, NumberError>;
@@ -994,16 +1188,18 @@ export declare const formatIntError: TypeErrorFormatter<IntError>;
 export declare const Int: BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Int", IntError, NumberError>;
 export type Int = typeof Int.Type;
 /** @category Number */
-export declare const NonNegativeInt: BrandType<Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>, "NonNegative", NonNegativeError, NumberError | IntError>;
+export declare const NonNegativeInt: BrandType<Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>, "NonNegative", NonNegativeError, IntError | NumberError>;
 export type NonNegativeInt = typeof NonNegativeInt.Type;
 /** @category Number */
-export declare const PositiveInt: BrandType<Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, NonNegativeError, number & Brand<"Int">, NumberError | IntError>, "Positive", PositiveError, NumberError | NonNegativeError | IntError>;
+export declare const PositiveInt: BrandType<Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, NonNegativeError, number & Brand<"Int">, IntError | NumberError>, "Positive", PositiveError, NonNegativeError | IntError | NumberError>;
 export type PositiveInt = typeof PositiveInt.Type;
+/** Maximum safe positive integer value for practically infinite operations. */
+export declare const maxPositiveInt: number & Brand<"Int"> & Brand<"NonNegative"> & Brand<"Positive">;
 /** @category Number */
-export declare const NonPositiveInt: BrandType<Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>, "NonPositive", NonPositiveError, NumberError | IntError>;
+export declare const NonPositiveInt: BrandType<Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>, "NonPositive", NonPositiveError, IntError | NumberError>;
 export type NonPositiveInt = typeof NonPositiveInt.Type;
 /** @category Number */
-export declare const NegativeInt: BrandType<Type<"Brand", number & Brand<"Int"> & Brand<"NonPositive">, number, NonPositiveError, number & Brand<"Int">, NumberError | IntError>, "Negative", NegativeError, NumberError | NonPositiveError | IntError>;
+export declare const NegativeInt: BrandType<Type<"Brand", number & Brand<"Int"> & Brand<"NonPositive">, number, NonPositiveError, number & Brand<"Int">, IntError | NumberError>, "Negative", NegativeError, IntError | NumberError | NonPositiveError>;
 export type NegativeInt = typeof NegativeInt.Type;
 /**
  * Number greater than a specified value.
@@ -1110,9 +1306,6 @@ export interface BetweenError<Min extends number = number, Max extends number =
     readonly max: Max;
 }
 export declare const formatBetweenError: TypeErrorFormatter<BetweenError<number, number>>;
-/** @category Number */
-export declare const Between1And10: BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Between1-10", BetweenError<1, 10>, NumberError>;
-export type Between1And10 = typeof Between1And10.Type;
 /**
  * Literal {@link Type}.
  *
@@ -1138,67 +1331,6 @@ export interface LiteralError<T extends Literal = Literal> extends TypeError<"Li
     readonly expected: T;
 }
 export declare const formatLiteralError: TypeErrorFormatter<LiteralError<Literal>>;
-/**
- * {@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 declare const transform: <FromType extends AnyType, ToType extends AnyType, TransformError extends TypeError = never>(fromType: FromType, toType: ToType, fromParent: (parentValue: InferType<FromType>) => Result<InferType<ToType>, TransformError>, toParent: (value: InferType<ToType>) => InferType<FromType>) => TransformType<FromType, ToType, TransformError>;
-/**
- * TransformType extends {@link Type} with additional `fromType` and `toType`
- * properties for reflection.
- */
-export interface TransformType<FromType extends AnyType, ToType extends AnyType, TransformError extends TypeError = never> extends Type<"Transform", InferType<ToType>, InferInput<FromType>, TransformError, InferType<FromType>, InferErrors<FromType>> {
-    readonly fromType: FromType;
-    readonly toType: ToType;
-    readonly fromParent: (value: InferType<FromType>) => [TransformError] extends [never] ? Ok<InferType<ToType>> : Result<InferType<ToType>, TransformError>;
-}
-/**
- * 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 declare const TrimString: TransformType<Type<"String", string, string, StringError, string, StringError>, BrandType<Type<"String", string, string, StringError, string, StringError>, "Trimmed", never, StringError>, never>;
-/**
- * Transforms a {@link Date} into a {@link DateIsoString} string and vice versa.
- *
- * ### Example
- *
- * TODO:
- *
- * @category String
- */
-export declare const DateIso: TransformType<InstanceOfType<DateConstructor>, BrandType<Type<"String", string, string, StringError, string, StringError>, "DateIso", DateIsoStringError, StringError>, DateIsoStringError>;
-/**
- * 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 declare const NumberFromString: TransformType<BrandType<Type<"Brand", string & Brand<"Trimmed">, string, TrimmedError, string, StringError>, "MinLength1", MinLengthError<1>, StringError | TrimmedError>, BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Finite", FiniteError, NumberError>, NumberFromStringError>;
-export interface NumberFromStringError extends TypeError<"NumberFromString"> {
-}
-export declare const formatNumberFromStringError: TypeErrorFormatter<NumberFromStringError>;
 /**
  * Array of a specific {@link Type}.
  *
@@ -1656,16 +1788,12 @@ export type Int64 = typeof Int64.Type;
 export interface Int64Error extends TypeError<"Int64"> {
 }
 export declare const formatInt64Error: TypeErrorFormatter<Int64Error>;
-export declare const BigIntFromString: TransformType<Type<"String", string, string, StringError, string, StringError>, Type<"BigInt", bigint, bigint, BigIntError, bigint, BigIntError>, BigIntFromStringError>;
-export interface BigIntFromStringError extends TypeError<"BigIntFromString"> {
-}
-export declare const formatBigIntFromStringError: TypeErrorFormatter<BigIntFromStringError>;
 /**
  * Stringified {@link Int64}.
  *
- * @category Number
+ * @category String
  */
-export declare const Int64String: BrandType<Type<"String", string, string, StringError, string, StringError>, "Int64", Int64StringError, StringError>;
+export declare const Int64String: BrandType<BrandType<Type<"Brand", string & Brand<"Trimmed">, string, TrimmedError, string, StringError>, "MinLength1", MinLengthError<1>, StringError | TrimmedError>, "Int64", Int64StringError, StringError | TrimmedError | MinLengthError<1>>;
 export type Int64String = typeof Int64String.Type;
 export interface Int64StringError extends TypeError<"Int64String"> {
 }
@@ -1700,42 +1828,63 @@ export declare const JsonArray: ArrayType<RecursiveType<UnionType<[Type<"String"
  * @category Object
  */
 export declare const JsonObject: RecordType<"String", string, string, StringError, string, StringError, RecursiveType<UnionType<[Type<"String", string, string, StringError, string, StringError>, BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Finite", FiniteError, NumberError>, Type<"Boolean", boolean, boolean, BooleanError, boolean, BooleanError>, Type<"Null", null, null, NullError, null, NullError>, ArrayType<Type<"Recursive", JsonValue, JsonValueInput, JsonValueError, JsonValueInput, JsonValueError>>, RecordType<"String", string, string, StringError, string, StringError, Type<"Recursive", JsonValue, JsonValueInput, JsonValueError, JsonValueInput, JsonValueError>>]>>>;
+export declare const parseJson: (value: string) => Result<JsonValue, JsonError>;
 /**
- * Transform Type that parses a JSON into a {@link JsonValue} and serializes a
- * JsonValue back into a JSON string.
+ * JSON-string {@link Type}.
  *
  * ### Example
  *
  * ```ts
- * JsonValueFromString.from(`{"key":"value"}`); // -> ok({ key: "value" })
- * JsonValueFromString.to({ key: "value" }); // -> '{"key":"value"}'
+ * const result = Json.from('{"key":"value"}'); // ok
+ * const error = Json.from("invalid json"); // err
  * ```
  *
  * @category String
  */
-export declare const JsonValueFromString: TransformType<Type<"String", string, string, StringError, string, StringError>, RecursiveType<UnionType<[Type<"String", string, string, StringError, string, StringError>, BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Finite", FiniteError, NumberError>, Type<"Boolean", boolean, boolean, BooleanError, boolean, BooleanError>, Type<"Null", null, null, NullError, null, NullError>, ArrayType<Type<"Recursive", JsonValue, JsonValueInput, JsonValueError, JsonValueInput, JsonValueError>>, RecordType<"String", string, string, StringError, string, StringError, Type<"Recursive", JsonValue, JsonValueInput, JsonValueError, JsonValueInput, JsonValueError>>]>>, JsonValueFromStringError>;
-export interface JsonValueFromStringError extends TypeError<"JsonValueFromString"> {
+export declare const Json: BrandType<Type<"String", string, string, StringError, string, StringError>, "Json", JsonError, StringError>;
+export type Json = typeof Json.Type;
+export interface JsonError extends TypeError<"Json"> {
     readonly message: string;
 }
-export declare const formatJsonValueFromStringError: TypeErrorFormatter<JsonValueFromStringError>;
+export declare const formatJsonError: TypeErrorFormatter<JsonError>;
+export declare const jsonValueToJson: (value: JsonValue) => Json;
+export declare const jsonToJsonValue: (value: Json) => JsonValue;
 /**
- * JSON-string {@link Type}.
+ * Creates a branded JSON string {@link Type} and type-safe conversion functions
+ * for a given Type.
+ *
+ * This factory creates:
+ *
+ * 1. A branded string Type that validates JSON parsing and structural conformity
+ * 2. A serialization function (Type → branded JSON string)
+ * 3. A parsing function (branded JSON string → Type, skipping validation)
+ *
+ * Optimized for Evolu's SQLite workflow where we store typed JSON strings and
+ * need type-safe conversions without double parsing.
  *
  * ### 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" })
- * ```
+ * const Person = object({
+ *   name: NonEmptyString100,
+ *   age: FiniteNumber,
+ * });
+ * type Person = typeof Person.Type;
  *
- * @category String
+ * const [PersonJson, personToPersonJson, personJsonToPerson] = json(
+ *   Person,
+ *   "PersonJson",
+ * );
+ * // string & Brand<"PersonJson">
+ * type PersonJson = typeof PersonJson.Type;
+ *
+ * // Usage:
+ * const person: Person = { name: "Alice", age: 30 };
+ * const jsonString = personToPersonJson(person); // PersonJson
+ * const backToPerson = personJsonToPerson(jsonString); // Person
+ * ```
  */
-export declare const Json: BrandType<Type<"String", string, string, StringError, string, StringError>, "Json", JsonError, StringError>;
-export type Json = typeof Json.Type;
-export interface JsonError extends TypeError<"Json"> {
-    readonly message: string;
-}
-export declare const formatJsonError: TypeErrorFormatter<JsonError>;
+export declare const json: <T extends AnyType, Name extends TypeName>(type: T, name: Name) => [BrandType<typeof String, Name, JsonError | InferErrors<T>, StringError>, (value: InferType<T>) => InferType<BrandType<typeof String, Name, JsonError | InferErrors<T>, StringError>>, (value: InferType<BrandType<typeof String, Name, JsonError | InferErrors<T>, StringError>>) => InferType<T>];
 /**
  * Optional {@link Type}.
  *
@@ -1766,7 +1915,7 @@ export declare const isOptionalType: (x: unknown) => x is OptionalType<any>;
 /**
  * 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
+ * This is useful when we 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.
  *
@@ -1812,36 +1961,18 @@ export type NullTypeInMembers<Members extends [AnyType, ...Array<AnyType>]> = Me
  * @category Object
  */
 export declare function omit<T extends ObjectType<any>, Keys extends keyof T["props"]>(objectType: T, ...keys: ReadonlyArray<Keys>): ObjectType<Omit<T["props"], Keys>>;
+export declare const maxMutationSize = 655360;
 /**
- * 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");
- * ```
+ * Evolu has to limit the maximum mutation size. Otherwise, sync couldn't use
+ * the `maxProtocolMessageRangesSize`. The max size is 640KB in bytes, measured
+ * via MessagePack. Evolu Protocol DbChange will be smaller thanks to various
+ * optimizations.
  */
-export declare const json: <T extends AnyType, Name extends TypeName>(type: T, name: Name) => TransformType<T, BrandType<typeof String, Name, JsonValueFromStringError | T["Errors"], StringError>>;
+export declare const validMutationSize: <T extends AnyType>(type: T) => BrandType<T, "ValidMutationSize", ValidMutationSizeError, InferErrors<T>>;
+export interface ValidMutationSizeError extends TypeError<"ValidMutationSize"> {
+}
+export declare const formatValidMutationSizeError: TypeErrorFormatter<ValidMutationSizeError>;
+export type ValidMutationSize<Props extends Record<string, AnyType>> = BrandType<ObjectType<Props>, "ValidMutationSize", ValidMutationSizeError, InferErrors<ObjectType<Props>>>;
 /**
  * Union of all `TypeError`s defined in the `Type.ts` file, including base type
  * errors (e.g., `StringError`, `NumberError`), composite type errors
@@ -1855,72 +1986,76 @@ export declare const json: <T extends AnyType, Name extends TypeName>(type: T, n
  *
  * @category Utilities
  */
-export type TypeErrors<ExtraErrors extends TypeError = never> = StringError | NumberError | BigIntError | BooleanError | UndefinedError | NullError | FunctionError | Uint8ArrayError | InstanceOfError | EvoluTypeError | CurrencyCodeError | DateIsoStringError | TrimmedError | MinLengthError | MaxLengthError | LengthError | MnemonicError | RegexError | NanoIdError | SimplePasswordError | IdError | PositiveError | NegativeError | NonPositiveError | NonNegativeError | IntError | GreaterThanError | LessThanError | GreaterThanOrEqualToError | LessThanOrEqualToError | NonNaNError | FiniteError | MultipleOfError | BetweenError | LiteralError | Int64Error | BigIntFromStringError | Int64StringError | JsonValueFromStringError | JsonError | ExtraErrors | ArrayError<TypeErrors<ExtraErrors>> | RecordError<TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>> | ObjectError<Record<string, TypeErrors<ExtraErrors>>> | ObjectWithRecordError<Record<string, TypeErrors<ExtraErrors>>, TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>> | UnionError<TypeErrors<ExtraErrors>> | TupleError<TypeErrors<ExtraErrors>>;
+export type TypeErrors<ExtraErrors extends TypeError = never> = StringError | NumberError | BigIntError | BooleanError | UndefinedError | NullError | FunctionError | Uint8ArrayError | InstanceOfError | EvoluTypeError | CurrencyCodeError | DateIsoError | TrimmedError | MinLengthError | MaxLengthError | LengthError | MnemonicError | RegexError | SimplePasswordError | IdError | TableIdError | PositiveError | NegativeError | NonPositiveError | NonNegativeError | IntError | GreaterThanError | LessThanError | GreaterThanOrEqualToError | LessThanOrEqualToError | NonNaNError | FiniteError | MultipleOfError | BetweenError | LiteralError | Int64Error | Int64StringError | JsonError | ValidMutationSizeError | ExtraErrors | ArrayError<TypeErrors<ExtraErrors>> | RecordError<TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>> | ObjectError<Record<string, TypeErrors<ExtraErrors>>> | ObjectWithRecordError<Record<string, TypeErrors<ExtraErrors>>, TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>> | UnionError<TypeErrors<ExtraErrors>> | TupleError<TypeErrors<ExtraErrors>>;
 /**
- * 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.
+ * Formats Evolu Type errors into user-friendly messages.
  *
- * If you prefer not to reuse any built-in error formatters, you can write your
- * own `formatTypeError` function from scratch.
+ * Evolu Type typed errors ensure every error type must have a formatter.
+ * TypeScript enforces this at compile-time, preventing unhandled validation
+ * errors from reaching users.
  *
- * ### Examples
+ * The `createFormatTypeError` function handles both built-in {@link TypeErrors}
+ * and custom errors, and lets us override default formatting for specific
+ * errors.
+ *
+ * ### Example
  *
  * ```ts
- * const formatError = createFormatTypeError();
- * console.log(formatError({ type: "String", value: 42 }));
- * // "A value 42 is not a string."
+ * const formatTypeError = createFormatTypeError<
+ *   MinLengthError | MaxLengthError
+ * >((error): string => {
+ *   switch (error.type) {
+ *     case "MinLength":
+ *       return `Text must be at least ${error.min} character${error.min === 1 ? "" : "s"} long`;
+ *     case "MaxLength":
+ *       return `Text is too long (maximum ${error.max} characters)`;
+ *   }
+ * });
  * ```
  *
- * A custom `formatTypeError` function:
+ * Alternatively, write a custom formatter from scratch without using
+ * `createFormatTypeError`. This gives us full control over error formatting:
  *
  * ```ts
- * type AppErrors =
- *   | ValidMutationSizeError
+ * const Person = object({
+ *   name: NonEmptyTrimmedString100,
+ *   age: optional(PositiveInt),
+ * });
+ *
+ * // Define only the errors actually used by Person Type
+ * type PersonErrors =
  *   | StringError
- *   | MinLengthError
  *   | MaxLengthError
- *   | NullError
- *   | IdError
+ *   | MinLengthError
  *   | 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.
+ *   | PositiveError
+ *   | NonNegativeError
+ *   | IntError
+ *   | NumberError
+ *   | ObjectError<Record<string, PersonErrors>>;
+ *
+ * const formatTypeError: TypeErrorFormatter<PersonErrors> = (error) => {
  *   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 "Number":
+ *       return "Must be a number";
+ *     case "MinLength":
+ *       return `Must be at least ${error.min} characters`;
+ *     case "MaxLength":
+ *       return `Cannot exceed ${error.max} characters`;
  *     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(", ")}`;
+ *       return "Cannot have leading or trailing spaces";
+ *     case "Positive":
+ *       return "Must be a positive number";
+ *     case "NonNegative":
+ *       return "Must be zero or positive";
+ *     case "Int":
+ *       return "Must be an integer";
  *     case "Object": {
- *       if (
- *         error.reason.kind === "ExtraKeys" ||
- *         error.reason.kind === "NotObject"
- *       )
- *         return "A developer made an error, this should not happen.";
+ *       if (error.reason.kind === "NotObject") return "Must be an object";
+ *       if (error.reason.kind === "ExtraKeys")
+ *         return "Contains unexpected fields";
  *       const firstError = Object.values(error.reason.errors).find(
  *         (e) => e !== undefined,
  *       )!;