@evolu/common 8.2.0 → 8.3.1

package/dist/src/Type.js

@@ -1,5 +1,429 @@
 /**
- * Runtime types.
+ * ## Intro
+ *
+ * Runtime validation with precise TypeScript types and structured errors.
+ *
+ * Evolu {@link Type} is a pure, synchronous codec for defining semantic domains.
+ * It partially decodes an `Input` into an `Output` and totally encodes every
+ * valid `Output` into a `CanonicalInput`. Types can validate, refine,
+ * transform, and compose without losing the contracts TypeScript can express.
+ *
+ * Decoding failures are explicit {@link Result} values, and their structured
+ * errors preserve the exact error types each Type can return.
+ *
+ * Evolu Type is designed to make correct code the easiest code to write:
+ *
+ * - Predefined constraints add a {@link Brand} to their Output.
+ * - Invalid declarations produce readable {@link CompileTimeError} types when the
+ *   compiler can detect them.
+ * - Evolu Type uses runtime {@link assert | assertions} to detect developer errors
+ *   that TypeScript cannot express, such as excess properties and sparse
+ *   arrays.
+ * - Typed `from` boundaries allow connecting value producers to domain fields
+ *   through their exact TypeScript types, so incompatible contract changes are
+ *   compile-time errors rather than runtime validation errors.
+ * - Lawful codecs compose without creating unencodable values: every valid Output
+ *   has a canonical Input representation and round-trips to the same semantic
+ *   value.
+ * - Type-safe localization infers the required error formatters from selected
+ *   Types, so missing validation messages are compile-time errors.
+ *
+ * Correctness is especially important for local-first data: application authors
+ * cannot inspect or repair a user's data.
+ *
+ * Evolu Type is optimized for small real-world bundles: composed Types share
+ * runtime code, while unused validators and formatters are tree-shaken. It
+ * could be smaller with less descriptive assertion messages, but Evolu favors
+ * actionable diagnostics over micro-optimizing isolated Types.
+ *
+ * Predefined Types use the names of corresponding JavaScript built-ins. When a
+ * Type shadows one, access the JavaScript built-in through `globalThis`, such
+ * as `globalThis.String` or `globalThis.Date`.
+ *
+ * Evolu Type supports [Standard Schema](https://standardschema.dev/) and
+ * requires TypeScript 7+ with `exactOptionalPropertyTypes` enabled.
+ *
+ * ## Examples
+ *
+ * Define a domain object with a custom `Age` Type, then validate unknown input:
+ *
+ * ```ts
+ * import {
+ *   Number,
+ *   NonEmptyTrimmedString100,
+ *   brand,
+ *   finite,
+ *   int,
+ *   lessThan,
+ *   nonNaN,
+ *   nonNegative,
+ *   object,
+ *   type Brand,
+ *   type InferErrors,
+ *   type InferType,
+ * } from "@evolu/common";
+ *
+ * // Age and its parent Types are predefined by Evolu. They are reconstructed
+ * // here to reveal every constraint behind a seemingly simple domain value.
+ * const NonNaNNumber = nonNaN(Number);
+ * const FiniteNumber = finite(NonNaNNumber);
+ * const Int = int(FiniteNumber);
+ * const NonNegativeInt = nonNegative(Int);
+ *
+ * const Age = brand("Age", lessThan(200)(NonNegativeInt));
+ * type Age = typeof Age.Output;
+ *
+ * expectTypeOf<Age>().toEqualTypeOf<
+ *   number &
+ *     Brand<"NonNaN"> &
+ *     Brand<"Finite"> &
+ *     Brand<"Int"> &
+ *     Brand<"NonNegative"> &
+ *     Brand<"LessThan200"> &
+ *     Brand<"Age">
+ * >();
+ *
+ * const User = object({
+ *   name: NonEmptyTrimmedString100,
+ *   age: Age,
+ * });
+ * interface User extends InferType<typeof User> {}
+ *
+ * const value: unknown = { name: "Ada", age: 37 };
+ * const user = User.fromUnknown(value);
+ *
+ * expectOk(user, { name: "Ada", age: 37 });
+ * expectTypeOf(user.value).toExtend<User>();
+ *
+ * const invalidUser = User.fromUnknown({ name: "Ada", age: 37.5 });
+ *
+ * expectErr(invalidUser, {
+ *   type: "Object",
+ *   reason: {
+ *     kind: "Properties",
+ *     errors: {
+ *       age: { type: "Int", value: 37.5 },
+ *     },
+ *   },
+ * });
+ *
+ * // InferErrors includes every structured error User.fromUnknown can return.
+ * expectTypeOf(invalidUser.error).toEqualTypeOf<
+ *   InferErrors<typeof User>
+ * >();
+ * ```
+ *
+ * A Type can format its structured errors into user-facing messages:
+ *
+ * ```ts
+ * import { Age } from "@evolu/common";
+ *
+ * const age = Age.fromUnknown(37.5);
+ *
+ * expectErr(age, { type: "Int", value: 37.5 });
+ * expect(Age.formatError(age.error)).toBe(
+ *   "The value 37.5 must be a safe integer.",
+ * );
+ * ```
+ *
+ * Use {@link localizeTypes} to derive Types with localized messages without
+ * changing validation behavior.
+ *
+ * One of Evolu Type's strongest features is typed `from` boundaries. A value
+ * producer, such as a form input, carries the precise constraints it
+ * guarantees, and TypeScript checks them against the consuming domain field.
+ * Unlike validation from `unknown` or `string`, this checks the contract
+ * between the producer and consumer, not merely whether the current value
+ * passes:
+ *
+ * ```ts
+ * import {
+ *   NonEmptyTrimmedString100,
+ *   NonEmptyTrimmedString1000,
+ *   object,
+ *   trim,
+ *   type MaxLengthError,
+ *   type MinLengthError,
+ *   type Result,
+ *   type TrimmedString,
+ * } from "@evolu/common";
+ *
+ * const Todo = object({ title: NonEmptyTrimmedString100 });
+ *
+ * // This is type-checked: Todo.from expects NonEmptyTrimmedString100.
+ * const title = NonEmptyTrimmedString100.orThrow("Buy milk");
+ * expectOk(Todo.from({ title }), { title });
+ *
+ * // Imagine the UI input component is changed to allow longer titles.
+ * // TypeScript rejects the mismatch, so users never see a save error
+ * // for a title the UI accepts but the domain cannot save.
+ * const longerTitle = NonEmptyTrimmedString1000.orThrow("Buy milk");
+ * // @ts-expect-error MaxLength1000 does not guarantee MaxLength100.
+ * Todo.from({ title: longerTitle });
+ *
+ * // Imagine a UI input component that returns TrimmedString.
+ * // from.parent.parent connects it to the domain field and validates the
+ * // remaining constraints.
+ * const titleFromTrimmingInput: TrimmedString = trim("  Buy milk  ");
+ * const validatedTitle = Todo.props.title.from.parent.parent(
+ *   titleFromTrimmingInput,
+ * );
+ *
+ * // No "not a string" or "not trimmed" errors: the input guarantees both.
+ * expectTypeOf(validatedTitle).toEqualTypeOf<
+ *   Result<
+ *     NonEmptyTrimmedString100,
+ *     MaxLengthError<100> | MinLengthError<1>
+ *   >
+ * >();
+ * expectOk(validatedTitle, "Buy milk");
+ * ```
+ *
+ * Evolu includes dozens of predefined Types and Type factories. Use Types such
+ * as {@link Age}, {@link PositiveInt}, {@link DateIso},
+ * {@link NonEmptyTrimmedString100}, {@link Base64Url}, and {@link Json} directly.
+ * Build domain Types with factories such as {@link brand}, {@link typed},
+ * {@link minLength}, {@link maxLength}, {@link array}, {@link object},
+ * {@link union}, {@link templateLiteral}, {@link transform},
+ * {@link discriminatedUnion}, and {@link json}.
+ *
+ * ## Guarantees
+ *
+ * Evolu Type validates values; it does not defend against adversarial
+ * JavaScript such as malicious Proxies, mutation during validation, throwing
+ * traps, forged built-ins, or code deliberately bypassing TypeScript with `any`
+ * or casts.
+ *
+ * Evolu Type trusts application code and audited dependencies. Untrusted code
+ * can cause harm far beyond validation and must not run in the application.
+ * Defending against it would add complexity without creating a meaningful
+ * security boundary.
+ *
+ * Runtime assertions still detect accidental developer errors that TypeScript
+ * cannot express. They are correctness checks, not defenses against malicious
+ * code.
+ *
+ * ## FAQ
+ *
+ * ### What does a Type represent?
+ *
+ * A Type is a lawful, pure codec for an exact semantic domain:
+ *
+ * ```text
+ * Input           ── partial decode ──▶ Output
+ * CanonicalInput  ◀─── total encode ─── Output
+ *
+ * CanonicalInput ⊆ Input
+ * ```
+ *
+ * Read each line in the direction of its arrowhead. `Input` is the complete
+ * typed decoding boundary, including candidates that validation can reject and
+ * noncanonical representations that decoding can normalize. `Output` is the
+ * validated semantic value. `CanonicalInput` is the statically known subtype of
+ * `Input` returned by the complete `to` operation. It can be wider than the
+ * values actually emitted when a refinement follows an arbitrary transformation
+ * because TypeScript cannot determine which values its encoder returns for the
+ * narrowed Output. `fromUnknown` and the `from` operations decode; `to`
+ * encodes.
+ *
+ * A lawful Type round-trips every Output:
+ *
+ * ```text
+ * fromUnknown(to(output)) ≈ ok(output)
+ * ```
+ *
+ * Encoding can canonicalize a valid Input:
+ *
+ * ```text
+ * "0042" ──decode──▶ 42 ──encode──▶ "42"
+ * ```
+ *
+ * Once canonicalized, repeating the decode-encode cycle must preserve that
+ * representation:
+ *
+ * ```text
+ * "42" ──decode──▶ 42 ──encode──▶ "42"
+ * ```
+ *
+ * Here `decode` means running the complete decoding pipeline, as `fromUnknown`
+ * does, and `≈` means equality appropriate for the semantic domain. Validation
+ * refinements, {@link ArrayType | Array Types}, and
+ * {@link ObjectType | Object Types} preserve these laws when their contained
+ * Types do. A {@link union} additionally requires compatible dispatch: it
+ * encodes through the first member matching the Output and decodes through the
+ * first member accepting the Input. Member ordering is lawful only when those
+ * choices agree semantically. Encoded representations can overlap even when
+ * member Output types are disjoint.
+ *
+ * When encoding returns a refined value unchanged, the refinement can narrow
+ * `CanonicalInput` without changing its JavaScript representation. For example,
+ * {@link FiniteNumber} has `number` as its Input, while its Output and
+ * CanonicalInput are `FiniteNumber`: decoding can reject non-finite number
+ * candidates, and encoding only receives validated finite Outputs. A
+ * transformation can change the representation entirely. For
+ * {@link Int64FromInt64String}, Input is `string`, Output is `Int64`, and
+ * CanonicalInput is `Int64String`. Structural Type factories derive their
+ * CanonicalInput recursively from their contained Types.
+ *
+ * ### Why is to total?
+ *
+ * Suppose a Type accepts only strings containing decimal digits and decodes
+ * them to JavaScript numbers. Parsing `"42"` is possible, but the Type cannot
+ * lawfully declare its Output as `number`:
+ *
+ * ```text
+ * digits-only string ──partial decode──▶ number
+ * digits-only string ◀─── total encode ── number  // impossible
+ * ```
+ *
+ * `number` also contains negative and fractional numbers, `NaN`, positive and
+ * negative infinity, and `-0`. None of those values has a digits-only
+ * representation, so `to` could not encode every valid Output.
+ *
+ * One lawful design narrows the Output to the exact representable domain:
+ *
+ * ```text
+ * digits-only string ──partial decode──▶ NonNegativeSafeInteger
+ * digits-only string ◀─── total encode ── NonNegativeSafeInteger
+ *
+ * "0042" ──decode──▶ 42 ──encode──▶ "42"
+ * ```
+ *
+ * Another lawful design keeps `number` as the Output but expands the Input
+ * representation to include a canonical string for every number, including
+ * `"NaN"`, `"Infinity"`, `"-Infinity"`, and `"-0"`, as well as negative and
+ * fractional numbers.
+ *
+ * The same principle applies when converting between two representations. Give
+ * each representation its own Type with the same exact Output. For example, a
+ * string representation and a number representation can both decode to the
+ * shared `SafeInteger` domain:
+ *
+ * ```text
+ * string ──partial decode──▶ SafeInteger
+ * string ◀─── total encode ── SafeInteger
+ *
+ * number ──partial decode──▶ SafeInteger
+ * number ◀─── total encode ── SafeInteger
+ * ```
+ *
+ * Conversion decodes the source representation, then total-encodes the shared
+ * Output into the target representation. If no lossless shared domain exists,
+ * the operation is a partial conversion, migration, or policy decision and
+ * should be an explicit function returning Result, not a Type transformation.
+ *
+ * ### Why can a typed operation throw?
+ *
+ * TypeScript proves structural assignability, but it cannot describe every
+ * runtime invariant. For example, it cannot express whether an object property
+ * is own, enumerable, or a data property. It also permits a wider object with
+ * excess properties where a narrower object type is expected.
+ *
+ * `fromUnknown` treats such invalid external values as input data and returns a
+ * typed error. Typed boundaries instead assert the domain promised by their
+ * parameter type. If application code claims an accessor-backed object or an
+ * object with excess properties is an Object Output, the assertion throws
+ * because the application contract is broken. `orThrow` and `orNull` preserve
+ * the assertion at their typed `Input` boundary, then apply {@link getOrThrow}
+ * or {@link getOrNull} only to validation failures returned by the remaining
+ * pipeline.
+ *
+ * Consequently, structural representation errors such as sparse Arrays,
+ * accessors, and excess properties normally do not enter user-facing validation
+ * in typed application flows. They violate the producer's declared contract and
+ * throw as developer errors. At a genuinely unknown boundary, such as a
+ * schema-authoring tool, import, or external protocol, the same issues are
+ * legitimate typed validation errors and their formatter messages are useful.
+ *
+ * This distinction applies to data failures. Any Type operation, including
+ * `fromUnknown`, can throw when trusted Type-declaration code, such as a
+ * successful transformation callback, violates its declared contract.
+ *
+ * Materialize accessor values into plain data, remove properties the Type does
+ * not represent, or use a different Type. Silently discarding excess data would
+ * make the code constructing it dead while appearing to encode it successfully.
+ * One exact Object policy also keeps Output membership independent of parsing
+ * configuration. Exact structural policies also keep Output membership
+ * independent of whether a transformation happens to allocate a new value.
+ * Evolu Type therefore does not invoke accessors, discard excess properties, or
+ * make `to` fallible. This keeps `to` total for every legitimate Output and
+ * lets transformations compose without an encoding-error channel.
+ *
+ * ### How should values from another realm be handled?
+ *
+ * Values returned by legacy code or another realm can still be uncertain and
+ * should be validated. Realm-neutral Types accept an otherwise legitimate
+ * representation without requiring conversion merely because its JavaScript
+ * built-ins belong to another realm.
+ *
+ * When an application trusts both the producer and its return contract, expose
+ * that contract as an accurate TypeScript type and use the typed value
+ * directly. If the boundary returns `unknown`, validate it instead of bypassing
+ * the boundary with a cast. Use a specialized Type or explicit transformation
+ * when the producer uses a different representation that needs adaptation or
+ * normalization.
+ *
+ * ### Why doesn't Evolu Type extract data from rich objects?
+ *
+ * Some validation libraries parse an object's data projection. An imaginary
+ * validation library can enumerate own enumerable string properties and decode
+ * them into a fresh plain object. That lets a class instance decode as plain
+ * data while its prototype and methods are ignored. The same general policy can
+ * treat a `Date` or `Map` as an empty Record and can invoke enumerable getters.
+ * This is a coherent but intentionally forgiving normalization model.
+ *
+ * Evolu Type validates exactly the runtime representation defined by each Type;
+ * it does not implicitly project one representation into another. The
+ * predefined {@link Object} defines an open plain-object representation with
+ * unknown values, {@link object} defines a closed plain-object representation,
+ * and {@link record} defines a plain-dictionary representation whose complete
+ * set of own properties are its entries. Their realm-neutral plain-object rule
+ * accepts a `null` prototype or an immediate root prototype whose own prototype
+ * is `null`; ordinary class instances and deeper prototype chains are rejected.
+ * Every property must be an enumerable data property; inherited members are not
+ * entries, while accessors and hidden properties are invalid instead of being
+ * invoked or ignored. {@link array} similarly defines a dense sequence whose
+ * only own properties are `length` and its indexed data properties;
+ * {@link tuple} applies the same representation rules with a fixed length and a
+ * distinct Type for each position. Only an explicit {@link transform} changes
+ * the representation. Consequently, `is` tests exact Output membership and `to`
+ * stays total for valid Outputs.
+ *
+ * ### Why is JsonValue stricter than JSON.stringify?
+ *
+ * `JSON.stringify` is a forgiving data projection. It can invoke `toJSON` and
+ * accessors, discard object properties, replace unsupported array elements and
+ * non-finite numbers with `null`, and normalize `-0` to `0`. Those rules are
+ * useful for ordinary serialization, but they do not preserve an exact value.
+ *
+ * {@link JsonValue} instead defines data that is already represented as data.
+ * Invalid runtime behavior and values are rejected rather than interpreted or
+ * silently discarded. Its encoder is total and stack-safe for every valid
+ * Output, and {@link JsonValueFromJson} preserves the semantic value when it is
+ * encoded and decoded, including JavaScript's distinction between `-0` and `0`.
+ * Use an explicit transformation before this boundary when a projection or
+ * other normalization is desired.
+ *
+ * ### Why are Types pure and synchronous?
+ *
+ * A Type describes data meaning, not work. Time, I/O, dependencies, external
+ * state, authorization, and other contextual decisions belong in a {@link Task}.
+ * Use a Type to decode the data required by that work, then pass the decoded
+ * value to a Task. A pure synchronous conversion that can fail can be an
+ * ordinary function returning Result.
+ *
+ * Keeping those responsibilities separate prevents Evolu Type from becoming a
+ * hidden application workflow. It also keeps validation deterministic,
+ * dependency-free, immediately composable, and straightforward to test.
+ *
+ * ### What if only decoding is needed?
+ *
+ * Use `fromUnknown` for unknown data. For typed application data, call `from`
+ * at the boundary its input type proves, or use `orThrow` or `orNull` for a
+ * flat conversion from `Input`. The canonical `to` encoder still keeps the Type
+ * lawful and composable with transformations and structural Types. A genuinely
+ * irreversible operation is a separate function or Task, not a Type
+ * transformation.
  *
  * @module
  */
@@ -50,7 +474,7 @@ const formatDefaultRuntimeTypeIssue = (issue) => issue.formatError(issue.error);
  * Asserts that a value belongs to a {@link Type} Output domain.
  *
  * Use this for internal invariants, not external input. Validate external input
- * with `Type.fromUnknown` so expected failures remain typed values. A failed
+ * with `Type.fromUnknown` so validation failures remain typed values. A failed
  * assertion uses the Type name for its message and preserves the exact Output
  * validation error as the thrown Error's cause.
  *
@@ -70,7 +494,7 @@ const formatDefaultRuntimeTypeIssue = (issue) => issue.formatError(issue.error);
  * >();
  * ```
  *
- * @group Core Types
+ * @group Core
  */
 export const assertType = (type, value) => {
     // TODO: Make assert prepend "Expected " and accept an optional third cause
@@ -90,34 +514,32 @@ const assertTypeOutput = (name, is, validateOutput, value, options = firstValida
     throw new Error(`Expected ${name}.`, { cause: error });
 };
 /**
- * Localized copies of selected {@link Type} declarations for every locale.
- *
- * Each locale supplies one formatter for every Type that can own a formatted
- * error. Structural Types use their own formatter for structural failures and
- * delegate contained failures to the Type that produced them. A Union owns its
- * complete failure because no member matched. Formatter requirements are
- * inferred recursively from structured errors, including mutually recursive
- * Lazy error interfaces.
- *
- * Parents and Types exposed through public reflection are localized recursively
- * through one shared cache. Lazy definitions stay opaque and are not evaluated;
- * their declared error types provide the formatter requirements instead.
- *
- * The selected Type map, locale map, and each formatter map must be plain
- * objects whose entries are own enumerable string-keyed data properties.
- *
- * All localized Types for one locale share the same formatter set. The result
- * preserves the selected names and exact TypeScript types under every locale
- * key, making one localized set easy to provide through dependency injection or
- * application context. Canonical Types remain unchanged.
- *
- * Localization is scoped to the Types an app imports instead of a package-wide
- * translation registry. Ordinary static imports give bundlers an explicit
- * dependency graph from those Types to their formatters, so unrelated Type and
- * localization code can be removed. An app supplies all locales it supports in
- * the same self-contained bundle, allowing users to change language without a
- * network connection. Different localized Type sets can coexist on one page or
- * in separate dependency-injection scopes.
+ * Creates localized copies of selected {@link Type} declarations.
+ *
+ * Pass the Types used together in one localization scope and formatter maps
+ * keyed by locale. TypeScript infers every formatter required by the selected
+ * Types, including errors from nested structural Types and recursive Lazy
+ * Types. Every locale must provide the complete inferred formatter set; missing
+ * and unrelated formatters are compile-time errors.
+ *
+ * The result preserves the locale names, selected Type names, and exact
+ * TypeScript types. A localized Type validates exactly like its source Type;
+ * only its human-readable `formatError` and Standard Schema messages change.
+ * The source Types remain unchanged.
+ *
+ * Parents and reflected child Types are localized with the same formatter set.
+ * Structural Types retain error paths and delegate nested messages to the Type
+ * that produced them. Different localized Type sets can coexist in separate
+ * application or dependency-injection scopes.
+ *
+ * Localization is scoped to the selected Types instead of a package-wide
+ * translation registry. Static imports give bundlers an explicit dependency
+ * graph, so unrelated Types, locales, and formatters can be removed. Bundling
+ * every locale an app supports also allows language changes without a network
+ * connection.
+ *
+ * The selected Type map, locale map, and formatter maps must be plain objects
+ * with own enumerable string-keyed data properties.
  *
  * ### Example
  *
@@ -127,7 +549,7 @@ const assertTypeOutput = (name, is, validateOutput, value, options = firstValida
  *
  * const Label = minLength(1)(String);
  *
- * const TypesByLocale = localizeTypes(
+ * const typesByLocale = localizeTypes(
  *   { Label },
  *   {
  *     cs: {
@@ -137,11 +559,66 @@ const assertTypeOutput = (name, is, validateOutput, value, options = firstValida
  *   },
  * );
  *
- * expectTypeOf<typeof TypesByLocale.cs.Label>().toEqualTypeOf<
+ * expectTypeOf<typeof typesByLocale.cs.Label>().toEqualTypeOf<
  *   typeof Label
  * >();
+ *
+ * const result = typesByLocale.cs.Label.fromUnknown("");
+ * expectErr(result, { type: "MinLength1", min: 1, value: "" });
+ * expect(typesByLocale.cs.Label.formatError(result.error)).toBe(
+ *   "Text nesmí být prázdný.",
+ * );
  * ```
  *
+ * ### Supported locales
+ *
+ * English is built in; use {@link Type} directly for its default formatters. The
+ * following additional locales are available:
+ *
+ * - Arabic (`ar`)
+ * - Bengali (`bn`)
+ * - Catalan (`ca`)
+ * - Chinese, Simplified (`zhCN`)
+ * - Chinese, Traditional (`zhTW`)
+ * - Croatian (`hr`)
+ * - Czech (`cs`)
+ * - Danish (`da`)
+ * - Dutch (`nl`)
+ * - Filipino (`fil`)
+ * - Finnish (`fi`)
+ * - French (`fr`)
+ * - German (`de`)
+ * - Greek (`el`)
+ * - Hebrew (`he`)
+ * - Hindi (`hi`)
+ * - Hungarian (`hu`)
+ * - Indonesian (`id`)
+ * - Italian (`it`)
+ * - Japanese (`ja`)
+ * - Korean (`ko`)
+ * - Malay (`ms`)
+ * - Malayalam (`ml`)
+ * - Marathi (`mr`)
+ * - Norwegian Bokmål (`nb`)
+ * - Persian (`fa`)
+ * - Polish (`pl`)
+ * - Portuguese (`pt`)
+ * - Portuguese, Brazilian (`ptBR`)
+ * - Punjabi (`pa`)
+ * - Romanian (`ro`)
+ * - Slovak (`sk`)
+ * - Slovenian (`sl`)
+ * - Spanish (`es`)
+ * - Swahili (`sw`)
+ * - Swedish (`sv`)
+ * - Tamil (`ta`)
+ * - Telugu (`te`)
+ * - Thai (`th`)
+ * - Turkish (`tr`)
+ * - Ukrainian (`uk`)
+ * - Urdu (`ur`)
+ * - Vietnamese (`vi`)
+ *
  * @group Localization
  */
 export const localizeTypes = ((typesByName, formatErrorByTypeByLocale) => {
@@ -435,9 +912,17 @@ const addRuntimeAssertions = (name, is, validateOutput, parent, operation) => {
     }
     return asserted;
 };
-/** @group Base Types */
+/**
+ * An infallible {@link Type} accepting every value.
+ *
+ * @group Base
+ */
 export const Unknown = /*#__PURE__*/ createRootType("Unknown", ok, identity);
-/** @group Base Types */
+/**
+ * A {@link Type} rejecting every value.
+ *
+ * @group Base
+ */
 export const Never = /*#__PURE__*/ createRootType("Never", (value) => err({ type: "Never", value }), (error) => `A value ${safelyStringifyUnknownValue(error.value)} is not valid for type Never.`);
 const createTypeOfType = (name) => {
     const typeOf = name.toLowerCase();
@@ -468,6 +953,8 @@ const createTypeOfType = (name) => {
  * expectTypeOf<WireValue100>().toEqualTypeOf<
  *   string & Brand<"MaxLength100">
  * >();
+ * expectOk(WireValue100.fromUnknown(""), "");
+ * expectOk(WireValue100.fromUnknown(" value "), " value ");
  * ```
  *
  * @group String
@@ -542,36 +1029,52 @@ export const String = /*#__PURE__*/ createTypeOfType("String");
  * @group Number
  */
 export const Number = /*#__PURE__*/ createTypeOfType("Number");
-/** @group Base Types */
+/**
+ * A JavaScript bigint {@link Type}.
+ *
+ * @group Base
+ */
 export const BigInt = /*#__PURE__*/ createTypeOfType("BigInt");
-/** @group Base Types */
+/**
+ * A JavaScript boolean {@link Type}.
+ *
+ * @group Base
+ */
 export const Boolean = /*#__PURE__*/ createTypeOfType("Boolean");
-/** @group Base Types */
+/**
+ * A JavaScript symbol {@link Type}.
+ *
+ * @group Base
+ */
 export const Symbol = /*#__PURE__*/ createTypeOfType("Symbol");
-/** @group Base Types */
+/**
+ * A JavaScript function {@link Type}.
+ *
+ * @group Base
+ */
 export const Function = /*#__PURE__*/ createTypeOfType("Function");
 /**
- * An Evolu {@link Type} validating other Evolu Types.
+ * A {@link Type} validating Evolu Type declarations.
  *
  * This is useful when a Type itself crosses an unknown boundary or must be
  * asserted with {@link assertType}.
  *
- * @group Core Types
+ * @group Core
  */
 export const EvoluType = /*#__PURE__*/ createType("EvoluType", (value) => isInstance("Type")(value)
     ? ok(value)
     : err({ type: "EvoluType", value }), (error) => `A value ${safelyStringifyUnknownValue(error.value)} is not an Evolu Type.`);
 export function objectTag(name, outputType) {
+    const formatError = (error) => `A value ${safelyStringifyUnknownValue(error.value)} does not have the expected object tag ${safelyStringifyUnknownValue(error.expected)}.`;
     if (outputType === undefined) {
         return createRootType(name, (value) => hasObjectTag(value, name)
             ? ok(value)
-            : err({ type: "ObjectTag", expected: name, value }), formatObjectTagError);
+            : err({ type: "ObjectTag", expected: name, value }), formatError);
     }
     return globalThis.Object.assign(createChildType("ObjectTag", outputType, (value) => hasObjectTag(value, name)
         ? ok(value)
-        : err({ type: "ObjectTag", expected: name, value }), formatObjectTagError), { expected: name });
+        : err({ type: "ObjectTag", expected: name, value }), formatError), { expected: name });
 }
-const formatObjectTagError = (error) => `A value ${safelyStringifyUnknownValue(error.value)} does not have the object tag ${safelyStringifyUnknownValue(error.expected)}.`;
 const hasObjectTag = (value, expected) => value !== null &&
     (typeof value === "object" || typeof value === "function") &&
     globalThis.Object.prototype.toString.call(value) === `[object ${expected}]`;
@@ -580,7 +1083,7 @@ const hasObjectTag = (value, expected) => value !== null &&
  *
  * It trusts the reported object tag and does not verify Date internal slots.
  *
- * @group Base Types
+ * @group Base
  */
 export const Date = /*#__PURE__*/ objectTag("Date");
 /**
@@ -589,7 +1092,7 @@ export const Date = /*#__PURE__*/ objectTag("Date");
  * It trusts the reported object tag and does not verify Uint8Array internal
  * slots.
  *
- * @group Base Types
+ * @group Base
  */
 export const Uint8Array = /*#__PURE__*/ objectTag("Uint8Array");
 /**
@@ -598,7 +1101,7 @@ export const Uint8Array = /*#__PURE__*/ objectTag("Uint8Array");
  * It trusts the reported object tag and does not verify ArrayBuffer internal
  * slots.
  *
- * @group Base Types
+ * @group Base
  */
 export const ArrayBuffer = /*#__PURE__*/ objectTag("ArrayBuffer");
 /**
@@ -629,7 +1132,7 @@ export const ArrayBuffer = /*#__PURE__*/ objectTag("ArrayBuffer");
  * assert(!UserInstance.is({ name: "Ada" }));
  * ```
  *
- * @group Base Types
+ * @group Base
  */
 export const instanceOf = (constructor) => {
     const concreteConstructor = constructor;
@@ -690,9 +1193,17 @@ export const literal = (expected) => {
         [templateLiteralSyntaxSymbol]: true,
     });
 };
-/** @group Unions */
+/**
+ * Literal {@link Type} accepting only `undefined`.
+ *
+ * @group Unions
+ */
 export const Undefined = /*#__PURE__*/ literal(undefined);
-/** @group Unions */
+/**
+ * Literal {@link Type} accepting only `null`.
+ *
+ * @group Unions
+ */
 export const Null = /*#__PURE__*/ literal(null);
 export function union(...typesOrLiterals) {
     const members = typesOrLiterals.map((typeOrLiteral) => typeOrLiteral !== null && typeof typeOrLiteral === "object"
@@ -701,7 +1212,7 @@ export function union(...typesOrLiterals) {
     const inputMembers = members.map(getTerminalRuntimeNode);
     const inputFrom = createUnionValidation(inputMembers, (member, value, options) => member.fromUnknown(value, options));
     const inputValidateOutput = createUnionValidation(inputMembers, (member, value, options) => member[outputValidationSymbol](value, options));
-    const defaultFormatter = formatUnionError;
+    const defaultFormatter = (() => "A value does not match any allowed variant.");
     const getTypeIssues = (error) => singleRuntimeTypeIssue("Union", error, defaultFormatter);
     const input = createTypeNode("Union", null, inputFrom, (value) => inputMembers.some((member) => member.is(value)), inputValidateOutput, ok, identity, getTypeIssues);
     const fromUnknown = createUnionValidation(members, (member, value, options) => member.fromUnknown(value, options));
@@ -719,7 +1230,6 @@ export function union(...typesOrLiterals) {
     };
     return createTypeNode("Union", input, fromUnknown, (value) => members.some((member) => member.is(value)), validateOutput, from, to, getTypeIssues, { members, [templateLiteralSyntaxSymbol]: true });
 }
-const formatUnionError = () => "A value does not match any union member.";
 const createUnionValidation = (members, validateMember) => (value, options = firstValidationOptions) => {
     let errors;
     for (let index = 0; index < members.length; index++) {
@@ -744,18 +1254,49 @@ const createUnionValidation = (members, validateMember) => (value, options = fir
  * This does not make an object property optional. It changes only the values
  * accepted when the property is present.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { String, undefinedOr } from "@evolu/common";
+ *
+ * const StringOrUndefined = undefinedOr(String);
+ *
+ * expectOk(StringOrUndefined.fromUnknown(undefined), undefined);
+ * ```
+ *
  * @group Unions
  */
 export const undefinedOr = (type) => union(type, Undefined);
 /**
  * Union {@link Type} containing the supplied Type and `null`.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { String, nullOr } from "@evolu/common";
+ *
+ * const NullableString = nullOr(String);
+ *
+ * expectOk(NullableString.fromUnknown(null), null);
+ * ```
+ *
  * @group Unions
  */
 export const nullOr = (type) => union(type, Null);
 /**
  * Union {@link Type} containing the supplied Type, `null`, and `undefined`.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { String, nullishOr } from "@evolu/common";
+ *
+ * const NullishString = nullishOr(String);
+ *
+ * expectOk(NullishString.fromUnknown(undefined), undefined);
+ * expectOk(NullishString.fromUnknown(null), null);
+ * ```
+ *
  * @group Unions
  */
 export const nullishOr = (type) => union(type, Null, Undefined);
@@ -763,9 +1304,7 @@ const isRuntimeUnionTypeNode = (type) => type.name === "Union" &&
     "members" in type &&
     globalThis.Array.isArray(type.members);
 /**
- * Template literal {@link Type} for validation and parsing.
- *
- * Parses and creates structured strings.
+ * Template literal {@link Type} that parses canonical strings into Tuples.
  *
  * Accepts the same template parts as {@link templateLiteral}: fixed string
  * literals and Types canonically encoded as strings. Instead of keeping Output
@@ -781,10 +1320,10 @@ const isRuntimeUnionTypeNode = (type) => type.name === "Union" &&
  * reversibility and keeps capture boundaries unambiguous. Different capture
  * Tuples must never encode to the same string. The parser provides predictable
  * parsing without pathological backtracking and decodes each capture once, so
- * adversarial input cannot trigger exponential parser work. Fixed-width captures
- * may be adjacent, but only one variable-width capture is allowed. Declarations
- * that could join UTF-16 surrogate halves across parts are rejected during
- * construction.
+ * adversarial input cannot trigger exponential parser work. Fixed-width
+ * captures may be adjacent, but only one variable-width capture is allowed.
+ * Declarations that could join UTF-16 surrogate halves across parts are
+ * rejected during construction.
  *
  * Keep capture unions reasonably small to avoid excessive compiler work.
  *
@@ -821,10 +1360,9 @@ const isRuntimeUnionTypeNode = (type) => type.name === "Union" &&
  *
  * // Parse an unknown string into structured data.
  * const result = SupportedLocale.fromUnknown("cs-CZ");
- * assert(result.ok);
+ * expectOk(result, ["cs", "CZ"]);
  * const locale = result.value;
  * expectTypeOf(locale).toEqualTypeOf<SupportedLocale>();
- * expect(locale).toEqual(["cs", "CZ"]);
  * expectErr(SupportedLocale.fromUnknown("cs/CZ"), {
  *   type: "TemplateLiteral",
  *   value: "cs/CZ",
@@ -883,10 +1421,9 @@ const isRuntimeUnionTypeNode = (type) => type.name === "Union" &&
  *
  * // Decode the string into structured data.
  * const result = ItemId.fromUnknown("item-42");
- * assert(result.ok);
+ * expectOk(result, [42n]);
  * const itemId = result.value;
  * expectTypeOf(itemId).toEqualTypeOf<ItemId>();
- * expect(itemId).toEqual([42n]);
  *
  * // Encode the structured data into its canonical string.
  * const itemIdLiteral = ItemId.to(itemId);
@@ -989,7 +1526,7 @@ const createTemplateLiteralParserType = (templateParts) => {
         if ("outputError" in error) {
             return runtimeOutput[getRuntimeTypeIssuesSymbol](error.outputError, mode);
         }
-        return singleRuntimeTypeIssue("TemplateLiteral", error, formatTemplateLiteralError);
+        return singleRuntimeTypeIssue("TemplateLiteral", error, ((error) => `The value ${safelyStringifyUnknownValue(error.value)} does not match the template literal.`));
     };
     const canonicalStringFromUnknown = (value, options = firstValidationOptions) => {
         const stringResult = String.fromUnknown(value, options);
@@ -1039,8 +1576,8 @@ const createTemplateLiteralParserType = (templateParts) => {
  * Creates a canonical string Type from fixed strings and string-encoded Types.
  *
  * Use this factory when Output should remain a string. Switch to
- * {@link templateLiteralParser} when the individual Type parts should be
- * decoded into a Tuple.
+ * {@link templateLiteralParser} when the individual Type parts should be decoded
+ * into a Tuple.
  *
  * ### Example
  *
@@ -1061,7 +1598,6 @@ const createTemplateLiteralParserType = (templateParts) => {
  * @group Template literals
  */
 export const templateLiteral = (...parts) => createTemplateLiteralParserType(parts).parent;
-const formatTemplateLiteralError = (error) => `The value ${safelyStringifyUnknownValue(error.value)} does not match the template literal.`;
 const compileTemplateLiteralParser = (parts) => {
     let framing = emptyTemplateLiteralFraming;
     let fixedPartsWidth = 0;
@@ -1202,6 +1738,18 @@ export const DateIso = /*#__PURE__*/ brand("DateIso", String, (value) => value.l
 /**
  * Safely transforms a {@link Date} into a canonical {@link DateIso}.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { DateIsoFromDate } from "@evolu/common";
+ *
+ * const date = new globalThis.Date("2025-01-01T12:00:00.000Z");
+ * const result = DateIsoFromDate.fromUnknown(date);
+ *
+ * expectOk(result, "2025-01-01T12:00:00.000Z");
+ * expect(DateIsoFromDate.to(result.value)).toEqual(date);
+ * ```
+ *
  * @group String
  */
 export const DateIsoFromDate = /*#__PURE__*/ transform("DateIsoFromDate", Date, DateIso, {
@@ -1265,6 +1813,16 @@ export const CapitalizedString = /*#__PURE__*/ capitalized(String);
 /**
  * String {@link Brand} without surrounding whitespace.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { String, trimmed } from "@evolu/common";
+ *
+ * const Trimmed = trimmed(String);
+ *
+ * expectOk(Trimmed.fromUnknown("Evolu"), "Evolu");
+ * ```
+ *
  * @group String
  */
 export const trimmed = (parent) => brand("Trimmed", parent, (value) => value === value.trim()
@@ -1285,11 +1843,31 @@ export const TrimmedString = /*#__PURE__*/ trimmed(String);
 /**
  * Trims a string and returns a {@link TrimmedString}.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { trim } from "@evolu/common";
+ *
+ * expect(trim("  Evolu  ")).toBe("Evolu");
+ * ```
+ *
  * @group String
  */
 export const trim = (value) => value.trim();
 /**
- * Minimum-length {@link Brand} requiring a value to have at least `min` items.
+ * Minimum-length {@link Brand} for values whose `length` is at least `min`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { String, array, minLength } from "@evolu/common";
+ *
+ * const AtLeastThreeCharacters = minLength(3)(String);
+ * const AtLeastTwoItems = minLength(2)(array(String));
+ *
+ * expectOk(AtLeastThreeCharacters.fromUnknown("abc"), "abc");
+ * expectOk(AtLeastTwoItems.fromUnknown(["a", "b"]), ["a", "b"]);
+ * ```
  *
  * @group String
  * @group Collection
@@ -1316,7 +1894,19 @@ export const minLength = (min) => (parent) => {
  */
 export const NonEmptyTrimmedString = /*#__PURE__*/ minLength(1)(TrimmedString);
 /**
- * Maximum-length {@link Brand} requiring a value to have at most `max` items.
+ * Maximum-length {@link Brand} for values whose `length` is at most `max`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { String, array, maxLength } from "@evolu/common";
+ *
+ * const AtMostThreeCharacters = maxLength(3)(String);
+ * const AtMostTwoItems = maxLength(2)(array(String));
+ *
+ * expectOk(AtMostThreeCharacters.fromUnknown("abc"), "abc");
+ * expectOk(AtMostTwoItems.fromUnknown(["a", "b"]), ["a", "b"]);
+ * ```
  *
  * @group String
  * @group Collection
@@ -1340,7 +1930,19 @@ export const NonEmptyTrimmedString100 = /*#__PURE__*/ maxLength(100)(NonEmptyTri
  */
 export const NonEmptyTrimmedString1000 = /*#__PURE__*/ maxLength(1000)(NonEmptyTrimmedString);
 /**
- * Exact-length {@link Brand} requiring a value to have exactly `exact` items.
+ * Exact-length {@link Brand} for values whose `length` equals `exact`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { String, array, length } from "@evolu/common";
+ *
+ * const ThreeCharacters = length(3)(String);
+ * const TwoItems = length(2)(array(String));
+ *
+ * expectOk(ThreeCharacters.fromUnknown("abc"), "abc");
+ * expectOk(TwoItems.fromUnknown(["a", "b"]), ["a", "b"]);
+ * ```
  *
  * @group String
  * @group Collection
@@ -1440,8 +2042,8 @@ const base64UrlStringToUint8Array = (value) => {
 /**
  * Base64Url text without padding.
  *
- * Encode bytes with {@link uint8ArrayToBase64Url} and decode them with
- * {@link base64UrlToUint8Array}.
+ * Convert bytes to Base64Url with {@link uint8ArrayToBase64Url} and convert
+ * Base64Url to bytes with {@link base64UrlToUint8Array}.
  *
  * @group String
  */
@@ -1452,13 +2054,35 @@ export const Base64Url = /*#__PURE__*/ brand("Base64Url", String, (value) => {
         : err({ type: "Base64Url", value });
 }, (error) => `The value ${safelyStringifyUnknownValue(error.value)} is not a valid Base64Url string.`);
 /**
- * Encodes bytes as {@link Base64Url}.
+ * Converts bytes to {@link Base64Url}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { uint8ArrayToBase64Url } from "@evolu/common";
+ *
+ * expect(uint8ArrayToBase64Url(new Uint8Array([0, 1, 2, 255]))).toBe(
+ *   "AAEC_w",
+ * );
+ * ```
  *
  * @group String
  */
 export const uint8ArrayToBase64Url = (bytes) => uint8ArrayToBase64UrlString(bytes);
 /**
- * Decodes {@link Base64Url} as bytes.
+ * Converts {@link Base64Url} to bytes.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { Base64Url, base64UrlToUint8Array } from "@evolu/common";
+ *
+ * const value = Base64Url.orThrow("AAEC_w");
+ *
+ * expect(base64UrlToUint8Array(value)).toEqual(
+ *   new Uint8Array([0, 1, 2, 255]),
+ * );
+ * ```
  *
  * @group String
  */
@@ -1489,7 +2113,7 @@ export const SimplePassword = /*#__PURE__*/ brand("SimplePassword",
  */
 export const Mnemonic = /*#__PURE__*/ brand("Mnemonic", NonEmptyTrimmedString, (value) => bip39.validateMnemonic(value, wordlist)
     ? ok()
-    : err({ type: "Mnemonic", value }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} is not a valid BIP39 mnemonic.`);
+    : err({ type: "Mnemonic", value }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} is not a valid English BIP39 mnemonic.`);
 /**
  * Evolu Id: 16 bytes encoded as a 22-character {@link Base64Url}.
  *
@@ -1509,6 +2133,22 @@ export const Id = /*#__PURE__*/ brand("Id", String, (value) => value.length ===
  * This is the recommended default because it does not encode creation time.
  * Pass a Brand name when the returned Id belongs to one domain entity.
  *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   Id,
+ *   createId,
+ *   createRandomBytes,
+ *   type Brand,
+ * } from "@evolu/common";
+ *
+ * const userId = createId<"User">({ randomBytes: createRandomBytes() });
+ *
+ * expect(Id.is(userId)).toBe(true);
+ * expectTypeOf(userId).toEqualTypeOf<Id & Brand<"User">>();
+ * ```
+ *
  * @group String
  */
 export const createId = (deps, ..._validation) => uint8ArrayToBase64Url(deps.randomBytes.create(16));
@@ -1543,6 +2183,26 @@ export const createIdFromString = (value, ..._validation) => idBytesToId(sha256(
  * logs, URLs, and exports. Prefer {@link createId} unless that tradeoff is
  * deliberate.
  *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   createIdAsUuidv7,
+ *   createRandomBytes,
+ *   createTime,
+ *   idToIdBytes,
+ * } from "@evolu/common";
+ *
+ * const value = createIdAsUuidv7({
+ *   randomBytes: createRandomBytes(),
+ *   time: createTime(),
+ * });
+ * const bytes = idToIdBytes(value);
+ *
+ * expect(bytes[6] >> 4).toBe(0x7);
+ * expect(bytes[8] & 0xc0).toBe(0x80);
+ * ```
+ *
  * @group String
  */
 export const createIdAsUuidv7 = (deps, ..._validation) => {
@@ -1561,6 +2221,22 @@ export const createIdAsUuidv7 = (deps, ..._validation) => {
 /**
  * Table-specific {@link Id} Type.
  *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   createIdFromString,
+ *   id,
+ *   type Brand,
+ *   type Id,
+ * } from "@evolu/common";
+ *
+ * const TodoId = id("Todo");
+ * const todoId = TodoId.orThrow(createIdFromString("todo"));
+ *
+ * expectTypeOf(todoId).toEqualTypeOf<Id & Brand<"Todo">>();
+ * ```
+ *
  * @group String
  */
 export const id = (table) => {
@@ -1576,11 +2252,47 @@ export const id = (table) => {
  */
 export const IdBytes = /*#__PURE__*/ brand("IdBytes", 
 /*#__PURE__*/ length(16)(Uint8Array));
-/** @group String */
+/**
+ * Byte length of an {@link IdBytes} value.
+ *
+ * @group String
+ */
 export const idBytesTypeValueLength = 16;
-/** @group String */
+/**
+ * Converts an {@link Id} to {@link IdBytes}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { createIdFromString, idToIdBytes } from "@evolu/common";
+ *
+ * const bytes = idToIdBytes(createIdFromString("todo"));
+ *
+ * expect(bytes).toHaveLength(16);
+ * ```
+ *
+ * @group String
+ */
 export const idToIdBytes = (value) => base64UrlToUint8Array(value);
-/** @group String */
+/**
+ * Converts {@link IdBytes} to an {@link Id}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   createIdFromString,
+ *   idBytesToId,
+ *   idToIdBytes,
+ * } from "@evolu/common";
+ *
+ * const value = createIdFromString("todo");
+ *
+ * expect(idBytesToId(idToIdBytes(value))).toBe(value);
+ * ```
+ *
+ * @group String
+ */
 export const idBytesToId = (value) => uint8ArrayToBase64Url(value);
 /**
  * Decimal string representation of a signed {@link Int64}.
@@ -1606,6 +2318,19 @@ export const Int64String = /*#__PURE__*/ brand("Int64String", NonEmptyTrimmedStr
  * text, including SQLite queries that cast INTEGER values to TEXT to avoid a
  * lossy JavaScript number conversion.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Int64FromInt64String } from "@evolu/common";
+ *
+ * const result = Int64FromInt64String.fromUnknown("9223372036854775807");
+ *
+ * expectOk(result, 9223372036854775807n);
+ * expect(Int64FromInt64String.to(result.value)).toBe(
+ *   "9223372036854775807",
+ * );
+ * ```
+ *
  * @group Number
  */
 export const Int64FromInt64String = /*#__PURE__*/ transform("Int64FromInt64String", Int64String, Int64, {
@@ -1615,6 +2340,16 @@ export const Int64FromInt64String = /*#__PURE__*/ transform("Int64FromInt64Strin
 /**
  * Number {@link Brand} requiring a value greater than or equal to zero.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Number, nonNegative } from "@evolu/common";
+ *
+ * const NonNegative = nonNegative(Number);
+ *
+ * expectOk(NonNegative.fromUnknown(0), 0);
+ * ```
+ *
  * @group Number
  */
 export const nonNegative = (parent) => brand("NonNegative", parent, (value) => value >= 0 ? ok() : err({ type: "NonNegative", value }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be non-negative (>= 0).`);
@@ -1627,6 +2362,16 @@ export const NonNegativeNumber = /*#__PURE__*/ nonNegative(Number);
 /**
  * Number {@link Brand} requiring a value greater than zero.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Number, positive } from "@evolu/common";
+ *
+ * const Positive = positive(Number);
+ *
+ * expectOk(Positive.fromUnknown(1), 1);
+ * ```
+ *
  * @group Number
  */
 export const positive = (parent) => brand("Positive", parent, (value) => value > 0 ? ok() : err({ type: "Positive", value }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be positive (> 0).`);
@@ -1642,6 +2387,16 @@ export const PositiveNumber = /*#__PURE__*/ positive(NonNegativeNumber);
 /**
  * Number {@link Brand} requiring a value less than or equal to zero.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Number, nonPositive } from "@evolu/common";
+ *
+ * const NonPositive = nonPositive(Number);
+ *
+ * expectOk(NonPositive.fromUnknown(0), 0);
+ * ```
+ *
  * @group Number
  */
 export const nonPositive = (parent) => brand("NonPositive", parent, (value) => value <= 0 ? ok() : err({ type: "NonPositive", value }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be non-positive (<= 0).`);
@@ -1654,6 +2409,16 @@ export const NonPositiveNumber = /*#__PURE__*/ nonPositive(Number);
 /**
  * Number {@link Brand} requiring a value less than zero.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Number, negative } from "@evolu/common";
+ *
+ * const Negative = negative(Number);
+ *
+ * expectOk(Negative.fromUnknown(-1), -1);
+ * ```
+ *
  * @group Number
  */
 export const negative = (parent) => brand("Negative", parent, (value) => value < 0 ? ok() : err({ type: "Negative", value }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be negative (< 0).`);
@@ -1669,6 +2434,16 @@ export const NegativeNumber = /*#__PURE__*/ negative(NonPositiveNumber);
 /**
  * Number {@link Brand} requiring a value other than `NaN`.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Number, nonNaN } from "@evolu/common";
+ *
+ * const NonNaN = nonNaN(Number);
+ *
+ * expectOk(NonNaN.fromUnknown(Infinity), Infinity);
+ * ```
+ *
  * @group Number
  */
 export const nonNaN = (parent) => brand("NonNaN", parent, (value) => globalThis.Number.isNaN(value)
@@ -1688,6 +2463,16 @@ export const NonNaNNumber = /*#__PURE__*/ nonNaN(Number);
 /**
  * Number {@link Brand} requiring a finite value.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Number, finite } from "@evolu/common";
+ *
+ * const Finite = finite(Number);
+ *
+ * expectOk(Finite.fromUnknown(42), 42);
+ * ```
+ *
  * @group Number
  */
 export const finite = (parent) => brand("Finite", parent, (value) => globalThis.Number.isFinite(value)
@@ -1794,6 +2579,16 @@ export const NegativeInt = /*#__PURE__*/ negative(NonPositiveInt);
 /**
  * Number {@link Brand} requiring a value greater than `min`.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Number, greaterThan } from "@evolu/common";
+ *
+ * const GreaterThanTen = greaterThan(10)(Number);
+ *
+ * expectOk(GreaterThanTen.fromUnknown(11), 11);
+ * ```
+ *
  * @group Number
  */
 export const greaterThan = (min) => (parent) => {
@@ -1805,6 +2600,16 @@ export const greaterThan = (min) => (parent) => {
 /**
  * Number {@link Brand} requiring a value greater than or equal to `min`.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Number, greaterThanOrEqualTo } from "@evolu/common";
+ *
+ * const AtLeastTen = greaterThanOrEqualTo(10)(Number);
+ *
+ * expectOk(AtLeastTen.fromUnknown(10), 10);
+ * ```
+ *
  * @group Number
  */
 export const greaterThanOrEqualTo = (min) => (parent) => {
@@ -1820,6 +2625,16 @@ export const greaterThanOrEqualTo = (min) => (parent) => {
 /**
  * Number {@link Brand} requiring a value less than `max`.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Number, lessThan } from "@evolu/common";
+ *
+ * const LessThanTen = lessThan(10)(Number);
+ *
+ * expectOk(LessThanTen.fromUnknown(9), 9);
+ * ```
+ *
  * @group Number
  */
 export const lessThan = (max) => (parent) => {
@@ -1838,6 +2653,16 @@ export const Age = /*#__PURE__*/ brand("Age",
 /**
  * Number {@link Brand} requiring a value less than or equal to `max`.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Number, lessThanOrEqualTo } from "@evolu/common";
+ *
+ * const AtMostTen = lessThanOrEqualTo(10)(Number);
+ *
+ * expectOk(AtMostTen.fromUnknown(10), 10);
+ * ```
+ *
  * @group Number
  */
 export const lessThanOrEqualTo = (max) => (parent) => {
@@ -1902,6 +2727,16 @@ export const DecimalString = /*#__PURE__*/ brand("DecimalString", String, (value
 /**
  * {@link DecimalString} Brand requiring a value greater than or equal to zero.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { DecimalString, nonNegativeDecimalString } from "@evolu/common";
+ *
+ * const NonNegative = nonNegativeDecimalString(DecimalString);
+ *
+ * expectOk(NonNegative.fromUnknown("0.5"), "0.5");
+ * ```
+ *
  * @group Number
  */
 export const nonNegativeDecimalString = (parent) => brand("NonNegativeDecimalString", parent, (value) => value[0] !== "-"
@@ -1920,6 +2755,16 @@ export const NonNegativeDecimalString =
 /**
  * {@link DecimalString} Brand requiring a value greater than zero.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { DecimalString, positiveDecimalString } from "@evolu/common";
+ *
+ * const Positive = positiveDecimalString(DecimalString);
+ *
+ * expectOk(Positive.fromUnknown("0.5"), "0.5");
+ * ```
+ *
  * @group Number
  */
 export const positiveDecimalString = (parent) => brand("PositiveDecimalString", parent, (value) => value !== "0" && value[0] !== "-"
@@ -1940,6 +2785,16 @@ export const PositiveDecimalString = /*#__PURE__*/ positiveDecimalString(NonNega
 /**
  * {@link DecimalString} Brand requiring a value less than or equal to zero.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { DecimalString, nonPositiveDecimalString } from "@evolu/common";
+ *
+ * const NonPositive = nonPositiveDecimalString(DecimalString);
+ *
+ * expectOk(NonPositive.fromUnknown("-0.5"), "-0.5");
+ * ```
+ *
  * @group Number
  */
 export const nonPositiveDecimalString = (parent) => brand("NonPositiveDecimalString", parent, (value) => value === "0" || value[0] === "-"
@@ -1958,6 +2813,16 @@ export const NonPositiveDecimalString =
 /**
  * {@link DecimalString} Brand requiring a value less than zero.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { DecimalString, negativeDecimalString } from "@evolu/common";
+ *
+ * const Negative = negativeDecimalString(DecimalString);
+ *
+ * expectOk(Negative.fromUnknown("-0.5"), "-0.5");
+ * ```
+ *
  * @group Number
  */
 export const negativeDecimalString = (parent) => brand("NegativeDecimalString", parent, (value) => value[0] === "-"
@@ -2051,6 +2916,16 @@ const decimalStringToParts = (value) => {
 /**
  * Number {@link Brand} requiring a value within an inclusive range.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Number, between } from "@evolu/common";
+ *
+ * const Percentage = between(0, 100)(Number);
+ *
+ * expectOk(Percentage.fromUnknown(75), 75);
+ * ```
+ *
  * @group Number
  */
 export const between = (min, max) => (parent) => {
@@ -2152,20 +3027,6 @@ const isArrayCollection = (value, isElement) => {
     }
     return true;
 };
-const formatArrayError = (error) => {
-    if (error.reason.kind === "NotArray") {
-        return `A value ${safelyStringifyUnknownValue(error.reason.value)} is not an array.`;
-    }
-    const issue = error.reason.issues[0];
-    switch (issue.kind) {
-        case "Hole":
-            return `An array element at index ${issue.index} is missing.`;
-        case "Accessor":
-            return `An array element at index ${issue.index} must be a data property.`;
-        case "ExcessProperty":
-            return "An excess Array property is not allowed. Remove it or use a different Type.";
-    }
-};
 const arrayRuntimeConfig = {
     name: "Array",
     typeByElement: arrayTypeByElement,
@@ -2173,7 +3034,22 @@ const arrayRuntimeConfig = {
     validateItems: (value, validateElement, options) => validateArrayItems(value, validateElement, options, false),
     encode: encodeArrayCollection,
     is: isArrayCollection,
-    formatError: formatArrayError,
+    formatError: ((error) => {
+        if (error.reason.kind === "NotArray") {
+            return `A value ${safelyStringifyUnknownValue(error.reason.value)} is not an array.`;
+        }
+        const issue = error.reason.issues[0];
+        switch (issue.kind) {
+            case "Hole":
+                return `An array element at index ${issue.index} is missing.`;
+            case "Accessor":
+                return `An array element at index ${issue.index} must be a data property.`;
+            case "ExcessProperty":
+                return "An excess Array property is not allowed. Remove it or use a different Type.";
+            case "Element":
+                return `An array element at index ${issue.index} is invalid.`;
+        }
+    }),
 };
 const validateArrayItems = (value, validate, options, checkStructure) => validateIndexedArrayItems("Array", value, validate, options, checkStructure);
 // Array and Tuple share their structural and element validation traversal.
@@ -2258,6 +3134,17 @@ const copyArrayPrefix = (value, endIndex) => {
  * iteration order. Classification uses the realm-neutral object tag and
  * prototype structure under Evolu Type's trusted JavaScript policy.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { String, set } from "@evolu/common";
+ *
+ * const Tags = set(String);
+ * const tags = new Set(["local-first", "offline"]);
+ *
+ * expectOk(Tags.fromUnknown(tags), tags);
+ * ```
+ *
  * @group Collection
  */
 export const set = (element) => createHomogeneousCollectionType(element, setRuntimeConfig);
@@ -2331,16 +3218,6 @@ const isSetCollection = (value, isElement) => {
     }
     return true;
 };
-const formatSetError = (error) => {
-    if (error.reason.kind === "NotSet") {
-        return `A value ${safelyStringifyUnknownValue(error.reason.value)} is not a Set.`;
-    }
-    if (error.reason.kind === "UnexpectedPrototype") {
-        return "The value is a Set subclass, but a Set Output must be a direct Set.";
-    }
-    const issue = error.reason.issues[0];
-    return `An excess Set property ${safelyStringifyUnknownValue(issue.key)} is not allowed.`;
-};
 const hasDirectSetPrototype = (value) => {
     const prototype = globalThis.Object.getPrototypeOf(value);
     if (prototype === null)
@@ -2356,7 +3233,19 @@ const setRuntimeConfig = {
     validateItems: (value, validateElement, options) => validateSetItems(value, validateElement, options, false),
     encode: encodeSetCollection,
     is: isSetCollection,
-    formatError: formatSetError,
+    formatError: ((error) => {
+        if (error.reason.kind === "NotSet")
+            return `A value ${safelyStringifyUnknownValue(error.reason.value)} is not a Set.`;
+        if (error.reason.kind === "UnexpectedPrototype")
+            return "The value is an instance of a Set subclass, but a Set Output must be a direct Set instance.";
+        const issue = error.reason.issues[0];
+        switch (issue.kind) {
+            case "ExcessProperty":
+                return `An excess Set property ${safelyStringifyUnknownValue(issue.key)} is not allowed.`;
+            case "Element":
+                return `A Set element at index ${issue.index} is invalid.`;
+        }
+    }),
 };
 const validateSetItems = (value, validate, options, checkStructure) => {
     let issues;
@@ -2421,12 +3310,10 @@ const createTupleType = (typeElements) => {
     const fromUnknown = (value, options = firstValidationOptions) => validate(value, (element, item, elementOptions) => element.fromUnknown(item, elementOptions), options);
     const validateOutput = (value, options = firstValidationOptions) => validate(value, (element, item, elementOptions) => element[outputValidationSymbol](item, elementOptions), options);
     const formatError = (error) => {
-        if (error.reason.kind === "NotArray") {
+        if (error.reason.kind === "NotArray")
             return `A value ${safelyStringifyUnknownValue(error.reason.value)} is not a tuple.`;
-        }
-        if (error.reason.kind === "InvalidLength") {
+        if (error.reason.kind === "InvalidLength")
             return `A Tuple must contain exactly ${error.reason.expected} elements, but the value contains ${error.reason.actual}.`;
-        }
         const issue = error.reason.issues[0];
         switch (issue.kind) {
             case "Hole":
@@ -2435,6 +3322,8 @@ const createTupleType = (typeElements) => {
                 return `A Tuple element at index ${issue.index} must be a data property.`;
             case "ExcessProperty":
                 return "An excess Tuple property is not allowed. Remove it or use a different Type.";
+            case "Element":
+                return `A Tuple element at index ${issue.index} is invalid.`;
         }
     };
     const rootElements = typeElements.map(getTerminalRuntimeNode);
@@ -2506,16 +3395,14 @@ export const Digit1To6 = /*#__PURE__*/ union("1", "2", "3", "4", "5", "6");
  */
 export const Digit1To23 = /*#__PURE__*/ union(Digit1To9, 
 /*#__PURE__*/ templateLiteral("1", Digit), 
-/*#__PURE__*/ templateLiteral("2", 
-/*#__PURE__*/ union("0", "1", "2", "3")));
+/*#__PURE__*/ templateLiteral("2", /*#__PURE__*/ union("0", "1", "2", "3")));
 /**
  * Decimal string from `"1"` to `"51"`.
  *
  * @group String
  */
 export const Digit1To51 = /*#__PURE__*/ union(Digit1To9, 
-/*#__PURE__*/ templateLiteral(
-/*#__PURE__*/ union("1", "2", "3", "4"), Digit), 
+/*#__PURE__*/ templateLiteral(/*#__PURE__*/ union("1", "2", "3", "4"), Digit), 
 /*#__PURE__*/ templateLiteral("5", /*#__PURE__*/ union("0", "1")));
 /**
  * Decimal string from `"1"` to `"99"`.
@@ -2572,21 +3459,9 @@ const createObjectRuntimeTypeIssues = (defaultFormatter, props, recordType) => (
         return recordType[getRuntimeTypeIssuesSymbol](propertyError, mode);
     });
 };
-const formatPlainObjectError = (error) => {
-    if (error.reason.kind !== "Properties") {
-        return formatPlainObjectRootError(error.reason);
-    }
-    const key = Reflect.ownKeys(error.reason.errors).at(0);
-    assertNonNullable(key);
-    const propertyError = error.reason.errors[key];
-    assertNonNullable(propertyError);
-    if (propertyError.type === "ObjectPropertyAccess") {
-        return propertyError.reason === "Accessor"
-            ? "An Object property must be a data property. Materialize accessor values into plain data before using this Type or use a different Type."
-            : "An Object property must be enumerable. Make it enumerable or use a different Type.";
-    }
-    return "An Object property key must be a string. Remove it or use a different Type.";
-};
+const formatPlainObjectRootError = (reason) => reason.kind === "NotObject"
+    ? `A value ${safelyStringifyUnknownValue(reason.value)} is not an object.`
+    : "The value is an object, but an Object Output must be a plain object or have a null prototype.";
 /**
  * A {@link Type} for readonly plain objects with unknown property values.
  *
@@ -2601,7 +3476,7 @@ const formatPlainObjectError = (error) => {
  * values have their own Types, and {@link instanceOf} when an instance belongs
  * to the domain.
  *
- * @group Base Types
+ * @group Base
  */
 export const Object = /*#__PURE__*/ createRootType("Object", (value, options = firstValidationOptions) => {
     if (value === null || typeof value !== "object") {
@@ -2651,15 +3526,56 @@ export const Object = /*#__PURE__*/ createRootType("Object", (value, options = f
             type: "Object",
             reason: { kind: "Properties", errors },
         });
-}, formatPlainObjectError, 
-/*#__PURE__*/ createObjectRuntimeTypeIssues(formatPlainObjectError));
+}, (error) => {
+    if (error.reason.kind !== "Properties")
+        return formatPlainObjectRootError(error.reason);
+    const key = Reflect.ownKeys(error.reason.errors).at(0);
+    assertNonNullable(key);
+    const propertyError = error.reason.errors[key];
+    assertNonNullable(propertyError);
+    if (propertyError.type === "ObjectPropertyAccess") {
+        switch (propertyError.reason) {
+            case "Accessor":
+                return "An Object property must be a data property. Materialize accessor values into plain data before using this Type or use a different Type.";
+            case "NonEnumerable":
+                return "An Object property must be enumerable. Make it enumerable or use a different Type.";
+        }
+    }
+    if (propertyError.type === "ObjectMissingProperty")
+        return `The required property ${safelyStringifyUnknownValue(key)} is missing.`;
+    if (typeof key === "symbol")
+        return "An Object property key must be a string. Remove the symbol property or use a different Type.";
+    if (propertyError.type === "ObjectExcessProperty")
+        return `The property ${safelyStringifyUnknownValue(key)} is not allowed. Remove it or use a different Type.`;
+    return `The property ${safelyStringifyUnknownValue(key)} is invalid.`;
+}, 
+/*#__PURE__*/ createObjectRuntimeTypeIssues(((error) => {
+    if (error.reason.kind !== "Properties")
+        return formatPlainObjectRootError(error.reason);
+    const key = Reflect.ownKeys(error.reason.errors).at(0);
+    assertNonNullable(key);
+    const propertyError = error.reason.errors[key];
+    assertNonNullable(propertyError);
+    if (propertyError.type === "ObjectPropertyAccess") {
+        switch (propertyError.reason) {
+            case "Accessor":
+                return "An Object property must be a data property. Materialize accessor values into plain data before using this Type or use a different Type.";
+            case "NonEnumerable":
+                return "An Object property must be enumerable. Make it enumerable or use a different Type.";
+        }
+    }
+    if (propertyError.type === "ObjectMissingProperty")
+        return `The required property ${safelyStringifyUnknownValue(key)} is missing.`;
+    if (typeof key === "symbol")
+        return "An Object property key must be a string. Remove the symbol property or use a different Type.";
+    if (propertyError.type === "ObjectExcessProperty")
+        return `The property ${safelyStringifyUnknownValue(key)} is not allowed. Remove it or use a different Type.`;
+    return `The property ${safelyStringifyUnknownValue(key)} is invalid.`;
+})));
 const isPlainObject = (value) => {
     const prototype = globalThis.Object.getPrototypeOf(value);
     return (prototype === null || globalThis.Object.getPrototypeOf(prototype) === null);
 };
-const formatPlainObjectRootError = (reason) => reason.kind === "NotObject"
-    ? `A value ${safelyStringifyUnknownValue(reason.value)} is not an object.`
-    : "The value is an object, but an Object Output must be a plain object or have a null prototype.";
 /**
  * Record {@link Type}.
  *
@@ -2690,20 +3606,13 @@ const formatPlainObjectRootError = (reason) => reason.kind === "NotObject"
  *
  * ```ts
  * import {
- *   Number,
+ *   Int64FromInt64String,
  *   String,
- *   ok,
  *   record,
- *   transform,
- *   type Result,
+ *   type Int64,
  * } from "@evolu/common";
  *
- * const ScoreFromString = transform("ScoreFromString", String, Number, {
- *   from: (value) => ok(globalThis.Number(value)),
- *   to: globalThis.String,
- * });
- *
- * const ScoresByUser = record(String, ScoreFromString);
+ * const ScoresByUser = record(String, Int64FromInt64String);
  * type ScoresByUser = typeof ScoresByUser.Output;
  *
  * // Validate an unknown value.
@@ -2712,7 +3621,7 @@ const formatPlainObjectRootError = (reason) => reason.kind === "NotObject"
  *   grace: "20",
  * });
  *
- * expectOk(scoresFromUnknown, { ada: 10, grace: 20 });
+ * expectOk(scoresFromUnknown, { ada: 10n, grace: 20n });
  *
  * // Validate keys and values with their root Types.
  * const scoresInput = ScoresByUser.parent.fromUnknown({
@@ -2724,11 +3633,10 @@ const formatPlainObjectRootError = (reason) => reason.kind === "NotObject"
  * // Run the remaining key and value stages.
  * const scoresFromInput = ScoresByUser.from.parent(scoresInput.value);
  *
- * expectTypeOf(scoresFromInput).toEqualTypeOf<
- *   Result<Readonly<Partial<Record<string, number>>>, never>
+ * expectOk(scoresFromInput, { ada: 10n, grace: 20n });
+ * expectTypeOf(scoresFromInput.value).toEqualTypeOf<
+ *   Readonly<Partial<Record<string, Int64>>>
  * >();
- *
- * expectOk(scoresFromInput, { ada: 10, grace: 20 });
  * ```
  *
  * Note that TypeScript does not model an object's runtime prototype. This can
@@ -2792,18 +3700,20 @@ export const record = (key, value) => {
     const fromUnknown = (input, options = firstValidationOptions) => validate(input, typeKey.fromUnknown, typeValue.fromUnknown, options);
     const validateOutput = (input, options = firstValidationOptions) => validate(input, typeKey[outputValidationSymbol], typeValue[outputValidationSymbol], options);
     const formatError = (error) => {
-        if (error.reason.kind === "NotRecord") {
-            return `A value ${safelyStringifyUnknownValue(error.reason.value)} is not a record.`;
-        }
-        if (error.reason.kind === "NotPlainRecord") {
+        if (error.reason.kind === "NotRecord")
+            return `A value ${safelyStringifyUnknownValue(error.reason.value)} is not a Record.`;
+        if (error.reason.kind === "NotPlainRecord")
             return "The value is an object, but a Record Output must be a plain object or have a null prototype.";
-        }
         const issue = error.reason.issues[0];
         switch (issue.kind) {
+            case "Key":
+                return `Property key ${safelyStringifyUnknownValue(issue.key)} is invalid.`;
+            case "Value":
+                return `The value of property ${safelyStringifyUnknownValue(issue.key)} is invalid.`;
             case "Accessor":
-                return `A record property ${safelyStringifyUnknownValue(issue.key)} must be a data property.`;
+                return `A Record property ${safelyStringifyUnknownValue(issue.key)} must be a data property.`;
             case "NonEnumerable":
-                return `A record property ${safelyStringifyUnknownValue(issue.key)} must be enumerable.`;
+                return `A Record property ${safelyStringifyUnknownValue(issue.key)} must be enumerable.`;
             case "Collision":
                 return `Record keys ${safelyStringifyUnknownValue(issue.previousKey)} and ${safelyStringifyUnknownValue(issue.key)} decode to the same key ${safelyStringifyUnknownValue(issue.outputKey)}.`;
         }
@@ -3115,25 +4025,27 @@ const createObjectType = (props, recordType) => {
     const fromUnknown = (value, options = firstValidationOptions) => validate(value, options, false);
     const validateOutput = (value, options = firstValidationOptions) => validate(value, options, true);
     const formatError = (error) => {
-        if (error.reason.kind !== "Properties") {
+        if (error.reason.kind !== "Properties")
             return formatPlainObjectRootError(error.reason);
-        }
         const key = Reflect.ownKeys(error.reason.errors).at(0);
         assertNonNullable(key);
         const propertyError = error.reason.errors[key];
+        assertNonNullable(propertyError);
         if (propertyError.type === "ObjectPropertyAccess") {
             switch (propertyError.reason) {
                 case "Accessor":
                     return "An Object property must be a data property. Materialize accessor values into plain data before using this Type or use a different Type.";
                 case "NonEnumerable":
-                    return "An Object property must be enumerable.";
+                    return "An Object property must be enumerable. Make it enumerable or use a different Type.";
             }
         }
-        if (typeof key === "string" &&
-            globalThis.Object.hasOwn(runtimeProps, key)) {
-            return "A required property is missing.";
-        }
-        return "An excess property is not allowed. Remove it or use a different Type.";
+        if (propertyError.type === "ObjectMissingProperty")
+            return `The required property ${safelyStringifyUnknownValue(key)} is missing.`;
+        if (typeof key === "symbol")
+            return "An Object property key must be a string. Remove the symbol property or use a different Type.";
+        if (propertyError.type === "ObjectExcessProperty")
+            return `The property ${safelyStringifyUnknownValue(key)} is not allowed. Remove it or use a different Type.`;
+        return `The property ${safelyStringifyUnknownValue(key)} is invalid.`;
     };
     const rootProps = createMutableRecord();
     let hasNonRootType = false;
@@ -3383,6 +4295,17 @@ export const nullableToOptional = (props, ..._validation) => {
 /**
  * Object {@link Type} without the selected declared properties.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { String, object, omit } from "@evolu/common";
+ *
+ * const User = object({ name: String, password: String });
+ * const PublicUser = omit(User, "password");
+ *
+ * expectOk(PublicUser.fromUnknown({ name: "Ada" }), { name: "Ada" });
+ * ```
+ *
  * @group Objects
  */
 export const omit = (objectType, ...keys) => {
@@ -3535,22 +4458,21 @@ export function discriminatedUnion(...keyOrMembers) {
     };
     const route = (value) => membersByDiscriminator.get(Reflect.get(value, key));
     const formatError = (error) => {
-        const reason = error.reason;
-        switch (reason.kind) {
+        switch (error.reason.kind) {
             case "Object":
-                return formatPlainObjectRootError(reason.error.reason);
+                return formatPlainObjectRootError(error.reason.error.reason);
             case "PropertyAccess": {
-                const property = `The discriminator property ${safelyStringifyUnknownValue(reason.key)}`;
-                if (reason.reason === "Accessor") {
+                const property = `The discriminator property ${safelyStringifyUnknownValue(error.reason.key)}`;
+                if (error.reason.reason === "Accessor")
                     return `${property} must be a data property.`;
-                }
-                if (reason.reason === "Inherited") {
+                if (error.reason.reason === "Inherited")
                     return `${property} must be an own property.`;
-                }
                 return `${property} must be enumerable.`;
             }
             case "Discriminator":
-                return `The discriminator property ${safelyStringifyUnknownValue(reason.key)} has an unexpected value ${safelyStringifyUnknownValue(reason.value)}.`;
+                return `The discriminator property ${safelyStringifyUnknownValue(error.reason.key)} has an unexpected value ${safelyStringifyUnknownValue(error.reason.value)}.`;
+            case "Member":
+                return `The selected variant ${safelyStringifyUnknownValue(error.reason.discriminator)} is invalid.`;
         }
     };
     const defaultFormatter = formatError;
@@ -3831,29 +4753,6 @@ const validateJsonValue = (value, options = firstValidationOptions) => {
             },
         });
 };
-const formatJsonValueError = (error) => {
-    const issue = error.reason.issues[0];
-    switch (issue.kind) {
-        case "InvalidType":
-            return `A value ${safelyStringifyUnknownValue(issue.value)} is not a JSON value.`;
-        case "NonFiniteNumber":
-            return "A JSON number must be finite.";
-        case "UnexpectedPrototype":
-            return "The value is an object, but a JsonValue Object must be a plain object or have a null prototype.";
-        case "Accessor":
-            return "A JSON property must be a data property. Materialize accessor values into plain data before using this Type or use a different Type.";
-        case "NonEnumerable":
-            return "A JSON Object property must be enumerable. Remove it or use a different Type.";
-        case "SymbolProperty":
-            return "A JSON Object property key must be a string. Remove the symbol property or use a different Type.";
-        case "Hole":
-            return "A JSON Array element is missing.";
-        case "ExcessProperty":
-            return "An excess JSON Array property is not allowed. Remove it or use a different Type.";
-        case "CircularReference":
-            return "A JsonValue must not contain circular references.";
-    }
-};
 const getJsonValueRuntimeTypeIssues = (error, mode) => {
     const jsonValueError = error;
     const issues = mode === "first"
@@ -3868,7 +4767,29 @@ const getJsonValueRuntimeTypeIssues = (error, mode) => {
                 reason: { kind: "Issues", issues: [issue] },
             },
         path: issue.path,
-        formatError: formatJsonValueError,
+        formatError: ((error) => {
+            const issue = error.reason.issues[0];
+            switch (issue.kind) {
+                case "InvalidType":
+                    return `A value ${safelyStringifyUnknownValue(issue.value)} is not a JSON value.`;
+                case "NonFiniteNumber":
+                    return "A JSON number must be finite.";
+                case "UnexpectedPrototype":
+                    return "The value is an object, but a JsonValue object must be a plain object or have a null prototype.";
+                case "Accessor":
+                    return "A JSON property must be a data property. Materialize accessor values into plain data before using this Type or use a different Type.";
+                case "NonEnumerable":
+                    return "A JSON object property must be enumerable. Remove it or use a different Type.";
+                case "SymbolProperty":
+                    return "A JSON object property key must be a string. Remove the symbol property or use a different Type.";
+                case "Hole":
+                    return "A JSON array element is missing.";
+                case "ExcessProperty":
+                    return "An excess JSON array property is not allowed. Remove it or use a different Type.";
+                case "CircularReference":
+                    return "A JsonValue must not contain circular references.";
+            }
+        }),
     }));
 };
 const parseJson = (value) => globalThis.JSON.parse(value);
@@ -3938,6 +4859,21 @@ const stringifyJsonValue = (value) => {
 /**
  * Exact root Type for {@link JsonValue} data trees.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { JsonValue, type JsonValueInput } from "@evolu/common";
+ *
+ * const input: JsonValueInput = {
+ *   name: "Ada",
+ *   scores: [10, 20],
+ * };
+ * const result = JsonValue.fromUnknown(input);
+ *
+ * expectOk(result, input);
+ * expectTypeOf(result.value).toEqualTypeOf<JsonValue>();
+ * ```
+ *
  * @group JSON
  */
 export const JsonValue = 
@@ -3958,7 +4894,7 @@ export const JsonObject = /*#__PURE__*/ record(String, JsonValue);
  * A {@link String} Brand proving that its exact text parses to {@link JsonValue}.
  *
  * The Brand preserves whitespace, property order, and number spelling. Convert
- * it totally to {@link JsonValue} through {@link JsonValueFromJson} or
+ * it to {@link JsonValue} through {@link JsonValueFromJson} or
  * {@link jsonToJsonValue}.
  *
  * @group JSON
@@ -3968,23 +4904,54 @@ export const Json = /*#__PURE__*/ brand("Json", String, (value) => {
     return result.ok ? ok() : result;
 }, (error) => `The value ${safelyStringifyUnknownValue(error.value)} cannot be parsed into a JsonValue.`);
 /**
- * Totally parses proven {@link Json} text into an exact {@link JsonValue}.
+ * Converts proven {@link Json} text to an exact {@link JsonValue}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { Json, jsonToJsonValue } from "@evolu/common";
+ *
+ * const value = jsonToJsonValue(Json.orThrow('{"name":"Ada"}'));
+ *
+ * expect(value).toEqual({ name: "Ada" });
+ * ```
  *
  * @group JSON
  */
 export const jsonToJsonValue = (value) => parseJson(value);
 /**
- * Totally encodes an exact {@link JsonValue} as canonical {@link Json} text.
+ * Converts an exact {@link JsonValue} to canonical {@link Json} text.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { jsonValueToJson, type JsonValue } from "@evolu/common";
+ *
+ * const value: JsonValue = { name: "Ada" };
+ *
+ * expect(jsonValueToJson(value)).toBe('{"name":"Ada"}');
+ * ```
  *
  * @group JSON
  */
 export const jsonValueToJson = (value) => stringifyJsonValue(JsonValue.to(value));
 /**
- * {@link Json} to {@link JsonValue} transformation.
+ * Transformation {@link Type} that parses {@link Json} into {@link JsonValue}.
  *
  * Decoding unknown input first validates the Json Brand. Starting from the
  * typed Json parent is infallible. Encoding canonicalizes JSON text.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { JsonValueFromJson } from "@evolu/common";
+ *
+ * const result = JsonValueFromJson.fromUnknown('{ "name": "Ada" }');
+ *
+ * expectOk(result, { name: "Ada" });
+ * expect(JsonValueFromJson.to(result.value)).toBe('{"name":"Ada"}');
+ * ```
+ *
  * @group JSON
  */
 export const JsonValueFromJson = /*#__PURE__*/ transform("JsonValueFromJson", Json, JsonValue, {
@@ -3992,67 +4959,48 @@ export const JsonValueFromJson = /*#__PURE__*/ transform("JsonValueFromJson", Js
     to: stringifyJsonValue,
 });
 /**
- * Branded {@link Json} Type and total conversions for another Type.
- *
- * Use this factory when a domain value must be stored as JSON text while its
- * exact Type remains visible to TypeScript, such as a JSON column in an Evolu
- * Schema. The returned tuple contains the branded Json Type, an encoder from
- * the supplied Type's Output to Json, and a decoder from Json back to that
- * Output.
- *
- * The supplied Type's `CanonicalInput` must be JSON-compatible. The encoder
- * first uses the Type's canonical `to` operation, then encodes that
- * representation as canonical Json. Runtime representation constraints
- * TypeScript cannot prove, such as dense Arrays and enumerable data properties,
- * are asserted as developer errors.
- *
- * The branded Json Type is the validation boundary for unknown JSON text. It
- * grants its {@link Brand} only when the text is valid Json and decoding it
- * through the supplied Type succeeds. The supplied Type is responsible for
- * preserving semantic Outputs across canonical JSON encoding and decoding. This
- * law cannot be checked generically because Types do not define semantic
- * equality. Before granting the Brand, the encoder asserts the weaker runtime
- * guarantee that the final Json successfully decodes through the supplied Type.
- * Failed decodability therefore throws as a developer error.
- *
- * Consequently, the two typed conversions return their values directly without
- * exposing a validation {@link Result}: an Output satisfying the JSON
- * representation contract of a correctly declared Type can always be encoded,
- * and the branded Json proves decoding will succeed. Decoding still runs the
- * Type pipeline because transformations may need to construct different Output
- * values.
+ * Branded {@link Json} Type and conversions for another {@link Type}.
+ *
+ * Use this when a value must be stored as JSON text, such as in a JSON column
+ * in an Evolu Schema. It returns a branded Json Type and functions for
+ * converting the supplied Type's Output to and from that branded JSON
+ * representation.
  *
  * ### Example
  *
  * ```ts
  * import {
  *   Age,
+ *   NonEmptyTrimmedString100,
  *   json,
  *   object,
- *   String,
  *   type Brand,
- *   type InferType,
- *   type Json,
  * } from "@evolu/common";
  *
- * const Person = object({ name: String, age: Age });
- * interface Person extends InferType<typeof Person> {}
+ * const User = object({
+ *   name: NonEmptyTrimmedString100,
+ *   age: Age,
+ * });
  *
- * const [PersonJson, personToPersonJson, personJsonToPerson] = json(
- *   Person,
- *   "PersonJson",
+ * const [UserJson, userToUserJson, userJsonToUser] = json(
+ *   User,
+ *   "UserJson",
  * );
- * type PersonJson = typeof PersonJson.Output;
  *
- * expectTypeOf<PersonJson>().toEqualTypeOf<Json & Brand<"PersonJson">>();
+ * const user = User.orThrow({ name: "Ada", age: 37 });
+ * const userJson = userToUserJson(user);
  *
- * const person = Person.orThrow({ name: "Ada", age: 42 });
- * const personJson = personToPersonJson(person);
- * const decodedPerson = personJsonToPerson(personJson);
- *
- * expect(decodedPerson).toEqual(person);
+ * expectTypeOf(userJson).toEqualTypeOf<
+ *   string & Brand<"Json"> & Brand<"UserJson">
+ * >();
+ * expect(userJson).toBe('{"name":"Ada","age":37}');
+ * expect(userJsonToUser(userJson)).toEqual(user);
  * ```
  *
+ * The supplied Type must have a JSON-compatible `CanonicalInput`. The branded
+ * Json Type accepts only valid JSON text whose parsed value can be decoded by
+ * the supplied Type.
+ *
  * @group JSON
  */
 export const json = (type, name, ..._validation) => {