@evolu/common 8.2.0 → 8.3.0

package/dist/src/Type.js

@@ -1,5 +1,328 @@
 /**
- * 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.
+ *
+ * ```ts
+ * import {
+ *   NonEmptyTrimmedString100,
+ *   PositiveInt,
+ *   object,
+ *   type InferType,
+ * } from "@evolu/common";
+ *
+ * const User = object({
+ *   name: NonEmptyTrimmedString100,
+ *   age: PositiveInt,
+ * });
+ * 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>();
+ * ```
+ *
+ * Decoding failures are explicit {@link Result} values. Error formatters are
+ * separate from validation, so structured errors remain exhaustively typed and
+ * can be localized without changing the Type.
+ *
+ * Evolu Type is designed to make correct code the easiest code to write:
+ *
+ * - {@link Brand} carries every refinement constraint into TypeScript.
+ * - Invalid declarations produce readable {@link CompileTimeError} types when the
+ *   compiler can detect them; runtime assertions enforce construction contracts
+ *   it cannot prove.
+ * - 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 on a server. Type declarations reject
+ * invalid data at system boundaries, then preserve those guarantees wherever
+ * the data travels.
+ *
+ * Evolu Type supports [Standard Schema](https://standardschema.dev/) while
+ * preserving each Type's exact Input and Output. Its implementation is
+ * optimized for small bundles, but keeps actionable assertion messages as a
+ * deliberate developer-experience tradeoff.
+ *
+ * Evolu Type requires TypeScript 7 or newer and `exactOptionalPropertyTypes`.
+ * Predefined Types use the names of corresponding JavaScript built-ins. When
+ * one shadows a built-in, access the built-in through `globalThis`, such as
+ * `globalThis.String` or `globalThis.Date`.
+ *
+ * ## Boundaries
+ *
+ * `fromUnknown` validates untyped input through the complete pipeline. `from`
+ * and its `.parent` operations assert their declared boundary, then return only
+ * errors from the remaining stages. `orThrow` and `orNull` reuse the deepest
+ * `from` operation accepting `Input`, while `to` asserts its Output boundary. A
+ * failed assertion is a developer error; its cause preserves the exact
+ * structured Output validation error.
+ *
+ * Prefer the most precise typed boundary available. A value is not unknown
+ * merely because it originated outside the application: forms, components, and
+ * other producers often expose a `string` or a branded value that can connect
+ * directly to a matching `from` boundary. Reserve `fromUnknown` for values
+ * whose TypeScript type is genuinely `unknown`. `is` means exact membership in
+ * the Output domain, not merely that an encoded Input can be decoded.
+ *
+ * Typed boundaries also connect producer and domain constraints at compile
+ * time. Suppose a form and its domain field both use
+ * {@link NonEmptyTrimmedString100}. If the form is later relaxed to
+ * {@link NonEmptyTrimmedString1000}, the domain Type will still reject longer
+ * values, so invalid data cannot be stored. But a boundary accepting only
+ * `unknown` or `string` cannot reveal that the producer contract changed. The
+ * application still compiles, and users discover the incompatibility only when
+ * a valid form value fails to save.
+ *
+ * Passing the precise branded value to `from` makes that incompatibility a
+ * compile-time error. The developer must preserve the original form limit or
+ * introduce a new field for the wider domain instead of shipping a broken form.
+ *
+ * A weaker producer is sometimes intentional. In that case, a matching
+ * `.parent` boundary validates only the constraints the producer does not
+ * already guarantee, while preserving its existing guarantees in the type.
+ *
+ * ## 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?
+ *
+ * Code trust and data validation are separate decisions. Values returned by
+ * trusted 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 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.
+ *
+ * All executing JavaScript remains trusted. Deliberately forged built-ins,
+ * hostile Proxies, throwing traps, or sabotaged executable behavior can throw;
+ * Evolu Type does not selectively contain them or claim to be a security
+ * boundary for untrusted code.
+ *
+ * ### 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 +373,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 +393,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 +413,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 +448,7 @@ const assertTypeOutput = (name, is, validateOutput, value, options = firstValida
  *
  * const Label = minLength(1)(String);
  *
- * const TypesByLocale = localizeTypes(
+ * const typesByLocale = localizeTypes(
  *   { Label },
  *   {
  *     cs: {
@@ -137,11 +458,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 +811,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 +852,8 @@ const createTypeOfType = (name) => {
  * expectTypeOf<WireValue100>().toEqualTypeOf<
  *   string & Brand<"MaxLength100">
  * >();
+ * expectOk(WireValue100.fromUnknown(""), "");
+ * expectOk(WireValue100.fromUnknown(" value "), " value ");
  * ```
  *
  * @group String
@@ -542,36 +928,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 +982,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 +991,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 +1000,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 +1031,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 +1092,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 +1111,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 +1129,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 +1153,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 +1203,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 +1219,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 +1259,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 +1320,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 +1425,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 +1475,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 +1497,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 +1637,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 +1712,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 +1742,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 +1793,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 +1829,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
@@ -1454,12 +1955,34 @@ export const Base64Url = /*#__PURE__*/ brand("Base64Url", String, (value) => {
 /**
  * Encodes bytes as {@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.
  *
+ * ### 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
  */
 export const base64UrlToUint8Array = (value) => base64UrlStringToUint8Array(value);
@@ -1489,7 +2012,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 +2032,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 +2082,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 +2120,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 +2151,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 +2217,17 @@ 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 +2237,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 +2259,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 +2284,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 +2306,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 +2331,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 +2360,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 +2476,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 +2497,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 +2522,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 +2550,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 +2624,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 +2652,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 +2682,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 +2710,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 +2813,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 +2924,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 +2931,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 +3031,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 +3115,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 +3130,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 +3207,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 +3219,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 +3292,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 +3356,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 +3373,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 +3423,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 +3503,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 +3518,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 +3530,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 +3597,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 +3922,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 +4192,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 +4355,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 +4650,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 +4664,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 +4756,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 = 
@@ -3970,21 +4803,52 @@ export const Json = /*#__PURE__*/ brand("Json", String, (value) => {
 /**
  * Totally parses proven {@link Json} text into 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.
  *
+ * ### 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, {