@evolu/common 8.2.0 → 8.3.1

package/dist/src/Type.d.ts

@@ -1,8 +1,3 @@
-/**
- * Runtime types.
- *
- * @module
- */
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { AtLeastTwoReadonlyArray, NonEmptyReadonlyArray } from "./Array.ts";
 import type { Brand } from "./Brand.ts";
@@ -12,359 +7,12 @@ import { type Result } from "./Result.ts";
 import type { TimeDep } from "./Time.ts";
 import { type CompileTimeError, type IsUnion, type Literal, type Simplify, type ValueWithLength, type WidenLiteral } from "./Types.ts";
 /**
- * A runtime representation of a TypeScript type with typed structured errors.
- *
- * Evolu Type reports expected decoding failures through {@link Result} rather
- * than exceptions. It represents both an encoded `Input` and its semantic
- * `Output`, supporting validation, transformation, and canonical encoding.
- *
- * Evolu Type is designed for correctness and developer experience. Correctness
- * is especially important for local-first data: application authors cannot
- * inspect or repair a user's data on a server because they do not have access
- * to it. Type declarations must reject invalid data at system boundaries, then
- * preserve those guarantees wherever the data travels.
- *
- * To make correct code the easiest code to write, Evolu Type preserves as much
- * information as TypeScript can express. Invalid declarations produce readable
- * {@link CompileTimeError} types when the compiler can detect them, while
- * runtime assertions enforce construction contracts it cannot prove. Together,
- * these choices create a pit of success.
- *
- * The implementation is optimized for minimal bundle size. Less descriptive
- * assertion messages could make it even smaller, but Evolu keeps actionable
- * messages as a deliberate tradeoff for developer experience.
- *
- * The main properties of Evolu Type are:
- *
- * - **Result-based error handling** – expected failures are explicit values.
- * - **Typed errors with decoupled formatters** – validation logic stays
- *   independent of user-facing messages, and errors can be handled
- *   exhaustively.
- * - **Type-safe, tree-shakeable localization** – formatter requirements are
- *   inferred from selected Types, while apps bundle exactly the locales they
- *   support so users can change language offline.
- * - **Consistent constraints through {@link Brand}** – every refinement constraint
- *   is represented in the TypeScript type, so an unconstrained parent value
- *   cannot be used where the constrained value is required.
- * - **Typed inputs** – prefer `from` and its `.parent` entry points to connect
- *   precise producer and consumer contracts while preserving typed remaining
- *   errors; reserve `fromUnknown` for genuinely unknown values.
- * - **Lawful codecs** – Types partially decode `Input` to `Output` and totally
- *   encode every legitimate `Output` to `CanonicalInput`, the statically known
- *   subtype of `Input` returned by complete encoding.
- * - **A top-down implementation** – the source is intended to be read from
- *   beginning to end.
- *
- * Evolu Type supports [Standard Schema](https://standardschema.dev/) for
- * interoperability with compatible tools and frameworks while preserving each
- * Type's exact Input and Output.
- *
- * Evolu Type assumes that all executing code, including third-party
- * dependencies, has been audited and is trusted. It validates data contracts
- * under that assumption. Trusting code does not require trusting every value it
- * returns, so uncertain values from legacy code or another realm can still be
- * decoded at an explicit boundary. It does not protect against hostile
- * executable behavior such as sabotaged Proxies or throwing traps; Type
- * validation is not a security boundary for untrusted JavaScript.
- *
- * Type declarations and their callbacks are trusted construction code. Evolu
- * Type leverages that trust for better developer experience and does not try to
- * recover from code that defeats the type system with `any` or casts, including
- * fabricating an `Err` for `Result<_, never>`. Runtime assertions still enforce
- * contracts TypeScript cannot express, and every Type declaration must be
- * tested for its expected successes and failures.
- *
- * `fromUnknown` validates untyped input through the complete pipeline. `from`
- * and its `.parent` operations use their declared boundary to determine which
- * remaining stages can return validation errors, but assert that boundary at
- * runtime. `orThrow` and `orNull` reuse the deepest `from` operation accepting
- * `Input`, while `to` asserts its Output boundary. A failed assertion means
- * application code violated its static contract; it is a developer error, not
- * an expected validation failure. Its message identifies the expected Type and
- * 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 output-side parsing could succeed. A
- * successful `fromUnknown` result always satisfies `is`.
- *
- * Decoding accepts a representation outside the Output domain only when the
- * Type explicitly declares that representation, such as a transformation Input.
- * Structural Types do not implicitly repair another JavaScript representation.
- * In particular, {@link array} and {@link tuple} require dense own data elements,
- * while the predefined {@link Object}, {@link object}, and {@link record} require
- * plain objects with own enumerable data properties. They do not invoke
- * accessors or materialize inherited and non-enumerable properties.
- *
- * TypeScript object types are structural and do not encode JavaScript realm
- * identity. Structural Types therefore accept legitimate representations from
- * other realms. Prototype checks remain when the prototype defines the semantic
- * domain. Plain-object Types accept a `null` prototype or an immediate root
- * prototype whose own prototype is `null`; ordinary class instances and deeper
- * prototype chains are rejected. When Record decoding must construct a
- * normalized value, it uses a `null` prototype so every string key remains
- * ordinary data.
- *
- * Evolu Type requires TypeScript 7 or newer and expects the
- * `exactOptionalPropertyTypes` compiler option to be enabled.
- *
- * Predefined Types intentionally use the names of corresponding JavaScript
- * built-ins because they represent those familiar value categories. If an
- * imported Type shadows a built-in in the same scope, access the built-in
- * through `globalThis`, JavaScript's standard cross-environment global object,
- * such as `globalThis.String` or `globalThis.Date`.
- *
- * ### Example
- *
- * ```ts
- * import { String, type Result } from "@evolu/common";
- *
- * const value: unknown = "hello";
- * const result = String.fromUnknown(value);
- *
- * expectTypeOf(result).toEqualTypeOf<
- *   Result<
- *     string,
- *     {
- *       readonly type: "TypeOf";
- *       readonly expected: "String";
- *       readonly value: unknown;
- *     }
- *   >
- * >();
- * expectOk(result, "hello");
- * ```
- *
- * ## 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.
+ * A runtime representation of a TypeScript type, including its encoded input,
+ * semantic output, structured errors, and canonical encoding.
  *
- * One lawful design narrows the Output to the exact representable domain:
+ * See the {@link @evolu/common!Type | Type overview}.
  *
- * ```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 expected 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, it can
- * cast the boundary API's `unknown` because validation is redundant. Use a
- * specialized Type or explicit transformation when the producer actually 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 an 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.
- *
- * @group Core Types
+ * @group Core
  */
 export interface Type<Name extends TypeName, in out Input, in out Output, Error extends TypeError, in out Parent extends TypeNode | null = null, in out Errors extends TypeError = Error | ([Parent] extends [infer P extends TypeNode] ? InferErrors<P> : never), in out CustomFrom extends CustomFromOperation = never, in out CanonicalInput extends Input = Input, in out IdentityEncoding extends boolean = true> extends TypeNode {
     /** The name identifying this Type node. */
@@ -423,16 +71,42 @@ export interface Type<Name extends TypeName, in out Input, in out Output, Error
     readonly [identityEncodingSymbol]: IdentityEncoding;
     /** The one preceding Type node, or `null` for a root Type. */
     readonly parent: Parent;
-    /** Decodes an unknown value through the complete Type pipeline. */
+    /**
+     * Decodes an unknown value through the complete Type pipeline.
+     *
+     * ### Example
+     *
+     * ```ts
+     * import { PositiveInt } from "@evolu/common";
+     *
+     * const value: unknown = 42;
+     * const result = PositiveInt.fromUnknown(value);
+     *
+     * expectOk(result, 42);
+     * ```
+     */
     readonly fromUnknown: (value: unknown, options?: ValidationOptions) => Result<Output, Errors>;
     /**
      * Formats an error returned by `fromUnknown` or `from` as one human-readable
-     * message. Built-in Types use English; {@link localizeTypes} derives Types
+     * message. Predefined Types use English; {@link localizeTypes} derives Types
      * with localized formatters.
      *
      * Structural errors retain nested errors and their locations in the typed
      * error value. This formatter does not encode paths or enumerate nested
      * errors in its message.
+     *
+     * ### Example
+     *
+     * ```ts
+     * import { String } from "@evolu/common";
+     *
+     * const result = String.fromUnknown(42);
+     *
+     * expectErr(result, { type: "TypeOf", expected: "String", value: 42 });
+     * expect(String.formatError(result.error)).toBe(
+     *   "A value 42 is not a string.",
+     * );
+     * ```
      */
     readonly formatError: TypeErrorFormatter<Errors>;
     /**
@@ -468,6 +142,52 @@ export interface Type<Name extends TypeName, in out Input, in out Output, Error
      * developer error. The Error message identifies the expected boundary Type,
      * and its cause preserves the structured validation error. Only failures
      * introduced after that boundary are returned through `Result`.
+     *
+     * ### Example
+     *
+     * A form already guarantees every constraint on a title, while a new note
+     * input guarantees only trimmed text. The note's parent boundary validates
+     * only the constraints that the form does not guarantee:
+     *
+     * ```ts
+     * import {
+     *   flatMapResult,
+     *   NonEmptyTrimmedString100,
+     *   object,
+     *   TrimmedString,
+     *   type MaxLengthError,
+     *   type MinLengthError,
+     *   type Result,
+     * } from "@evolu/common";
+     *
+     * const Todo = object({
+     *   title: NonEmptyTrimmedString100,
+     *   note: NonEmptyTrimmedString100,
+     * });
+     *
+     * const saveTodo = (
+     *   title: NonEmptyTrimmedString100,
+     *   note: TrimmedString,
+     * ) => {
+     *   // @ts-expect-error TrimmedString does not guarantee a non-empty value
+     *   // with at most 100 characters.
+     *   Todo.from({ title, note });
+     *
+     *   return flatMapResult(
+     *     Todo.props.note.from.parent.parent(note),
+     *     (note) => Todo.from({ title, note }),
+     *   );
+     * };
+     *
+     * const title = NonEmptyTrimmedString100.orThrow("Buy milk");
+     * const note = TrimmedString.orThrow("Remember oat milk");
+     * const result = saveTodo(title, note);
+     *
+     * expectTypeOf(result).toEqualTypeOf<
+     *   Result<typeof Todo.Output, MaxLengthError<100> | MinLengthError<1>>
+     * >();
+     * expectOk(result, { title, note });
+     * ```
      */
     readonly from: [CustomFrom] extends [never] ? [Parent] extends [infer P extends TypeNode] ? FromOperation<Output, Error, P> : TypeOperationFn<"from", Output, Output, never> : CustomFrom;
     /**
@@ -477,6 +197,16 @@ export interface Type<Name extends TypeName, in out Input, in out Output, Error
      * `to` runs the complete encoding pipeline. Its first `.parent` stops at the
      * immediate parent Output, and each additional suffix stops one Type closer
      * to the root. Every entry point accepts this Type's `Output`.
+     *
+     * ### Example
+     *
+     * ```ts
+     * import { Int64, Int64FromInt64String } from "@evolu/common";
+     *
+     * const value = Int64.orThrow(42n);
+     *
+     * expect(Int64FromInt64String.to(value)).toBe("42");
+     * ```
      */
     readonly to: [Parent] extends [infer P extends TypeNode] ? ToOperation<Output, CanonicalInput, P> : (value: Output) => CanonicalInput;
     /**
@@ -506,6 +236,9 @@ export interface Type<Name extends TypeName, in out Input, in out Output, Error
      *
      * // Equivalent because `from.parent` is this Type's deepest `from` operation:
      * const sameValue = getOrThrow(NonEmptyString.from.parent("Evolu"));
+     *
+     * expect(value).toBe("Evolu");
+     * expect(sameValue).toBe(value);
      * ```
      */
     readonly orThrow: TypeOperationFn<"orThrow", Input, Output, never>;
@@ -536,11 +269,19 @@ export interface Type<Name extends TypeName, in out Input, in out Output, Error
      *
      * // Equivalent because `from.parent` is this Type's deepest `from` operation:
      * const sameValue = getOrNull(NonEmptyString.from.parent("Evolu"));
+     *
+     * expect(value).toBe("Evolu");
+     * expect(sameValue).toBe(value);
+     * expect(NonEmptyString.orNull("")).toBeNull();
      * ```
      */
     readonly orNull: TypeOperationFn<"orNull", Input, Output, never>;
 }
-/** @group Core Types */
+/**
+ * A capitalized name identifying a {@link Type} node.
+ *
+ * @group Core
+ */
 export type TypeName = Capitalize<string>;
 /**
  * A plain structured error produced by a {@link Type} operation.
@@ -552,7 +293,7 @@ export type TypeName = Capitalize<string>;
  * only when it intentionally represents the same error contract. Accidental
  * reuse prevents reliable discriminated-union narrowing.
  *
- * @group Core Types
+ * @group Core
  */
 export interface TypeError<Name extends TypeName = TypeName> {
     readonly type: Name;
@@ -567,7 +308,7 @@ interface TransparentTypeError {
  * Structural errors such as Array and Union errors extend {@link TypeError}
  * instead because they locate nested errors rather than own one value.
  *
- * @group Core Types
+ * @group Core
  */
 export interface TypeValueError<Name extends TypeName = TypeName> extends TypeError<Name> {
     readonly value: unknown;
@@ -575,10 +316,15 @@ export interface TypeValueError<Name extends TypeName = TypeName> extends TypeEr
 /**
  * Formats a structured {@link TypeError} as a human-readable message.
  *
- * @group Core Types
+ * @group Core
  */
 export type TypeErrorFormatter<Error extends TypeError> = (error: Error) => string;
-/** @group Core Types */
+/**
+ * The common structural shape of every {@link Type}, with its specific type
+ * parameters erased.
+ *
+ * @group Core
+ */
 export interface TypeNode {
     readonly name: TypeName;
     readonly "~standard": StandardSchemaV1.Props<unknown, unknown>;
@@ -601,7 +347,7 @@ export interface TypeNode {
  * 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.
  *
@@ -621,38 +367,36 @@ export interface TypeNode {
  * >();
  * ```
  *
- * @group Core Types
+ * @group Core
  */
 export declare const assertType: <T extends TypeNode>(type: T, value: unknown) => asserts value is T["Output"];
 /**
- * Localized copies of selected {@link Type} declarations for every locale.
+ * Creates localized copies of selected {@link Type} declarations.
  *
- * 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.
+ * 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.
  *
- * 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 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.
  *
- * The selected Type map, locale map, and each formatter map must be plain
- * objects whose entries are own enumerable string-keyed data properties.
+ * 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.
  *
- * 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 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.
  *
- * 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.
+ * The selected Type map, locale map, and formatter maps must be plain objects
+ * with own enumerable string-keyed data properties.
  *
  * ### Example
  *
@@ -662,7 +406,7 @@ export declare const assertType: <T extends TypeNode>(type: T, value: unknown) =
  *
  * const Label = minLength(1)(String);
  *
- * const TypesByLocale = localizeTypes(
+ * const typesByLocale = localizeTypes(
  *   { Label },
  *   {
  *     cs: {
@@ -672,11 +416,66 @@ export declare const assertType: <T extends TypeNode>(type: T, value: unknown) =
  *   },
  * );
  *
- * 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 declare const localizeTypes: LocalizeTypes;
@@ -762,15 +561,20 @@ declare const identityEncodingSymbol: unique symbol;
  *   age: optional(PositiveInt),
  * });
  * interface User extends InferType<typeof User> {}
+ *
+ * const user = User.orThrow({ name: "Ada", age: 37 });
+ *
+ * expectTypeOf(user).toExtend<User>();
+ * expect(user.name).toBe("Ada");
  * ```
  *
- * @group Type utilities
+ * @group Core
  */
 export type InferType<T extends TypeNode> = T["Output"];
 /**
  * The union of errors a {@link Type} can return from `fromUnknown`.
  *
- * @group Type utilities
+ * @group Core
  */
 export type InferErrors<T extends TypeNode> = T[typeof errorsSymbol];
 type CanonicalInputOf<T extends TypeNode> = T extends TypeNode ? T["CanonicalInput"] : never;
@@ -842,7 +646,7 @@ type TypeOperationFn<Kind extends "from" | "orThrow" | "orNull", Input, Output,
 /**
  * Configures how container {@link Type} operations report errors.
  *
- * @group Core Types
+ * @group Core
  */
 export interface ValidationOptions {
     /** Controls whether container {@link Type} operations return one or all errors. */
@@ -914,10 +718,12 @@ type ConcreteChildTypeNameError = CompileTimeError<"Type", "Name must be one con
  * expectErr(Text.fromUnknown(42), { type: "Text", value: 42 });
  * ```
  *
- * @group Type construction
+ * @group Construction
  */
 export declare function createType<Name extends TypeName, Output, Error extends TypeError>(name: ValidateConcreteTypeName<Name>, fromUnknown: (value: unknown) => Result<Output, Error>, formatError: TypeErrorFormatter<NoInfer<Error>>): Type<Name, Output, Output, Error, null, Error, never, Output>;
+/** Creates an infallible child Type that preserves its parent's Output. */
 export declare function createType<Name extends TypeName, ParentType extends ConcreteTypeNode>(name: ValidateConcreteTypeName<Name>, parent: ValidateParent<ParentType>, fromParent: (value: ParentType["Output"]) => Result<ParentType["Output"], never>): Type<Name, ParentType["Input"], ParentType["Output"], never, ParentType, InferErrors<ParentType>, ChildCustomFrom<ParentType, ParentType["Output"], never>, CanonicalInputForChild<ParentType, ParentType["Output"]>, IdentityEncodingOf<ParentType>>;
+/** Creates a fallible child Type that narrows its parent's Output. */
 export declare function createType<Name extends TypeName, ParentType extends ConcreteTypeNode, Output extends ParentType["Output"], Error extends TypeError<Name>>(name: Name, parent: ValidateBrandParent<Name, ParentType>, fromParent: (value: ParentType["Output"]) => Result<Output, Error>, formatError: [Error] extends [never] ? never : TypeErrorFormatter<NoInfer<Error>>): Type<Name, ParentType["Input"], Output, Error, ParentType, Error | InferErrors<ParentType>, ChildCustomFrom<ParentType, Output, Error>, CanonicalInputForChild<ParentType, Output>, IdentityEncodingOf<ParentType>>;
 /**
  * Transform {@link Type}.
@@ -925,12 +731,19 @@ export declare function createType<Name extends TypeName, ParentType extends Con
  * `from` accepts the semantic Output. `from.parent` converts the parent Output
  * to the output Type Input, then runs the complete output Type pipeline. `to`
  * canonically encodes every output Type value before converting it back through
- * the parent Type. Transformation callbacks are Type construction code. Their
- * successful results are asserted against the declared boundary so a broken
- * callback fails as a developer error rather than becoming a validation error.
- * Like all Type-construction callbacks, they are trusted to follow their
- * declared TypeScript types. A `Result<_, never>` callback is therefore trusted
- * never to return an `Err`.
+ * the parent Type.
+ *
+ * The callbacks must form a lawful codec: decoding `to(output)` must reproduce
+ * the same semantic Output for every valid output value. Encoding may
+ * canonicalize multiple parent representations, but it must be total and must
+ * not lose distinctions present in the Output domain.
+ *
+ * Transformation callbacks are Type construction code. Their successful results
+ * are asserted against the declared boundary so a broken callback fails as a
+ * developer error rather than becoming a validation error. Like all
+ * Type-construction callbacks, they are trusted to follow their declared
+ * TypeScript types. A `Result<_, never>` callback is therefore trusted never to
+ * return an `Err`.
  *
  * Errors from the parent and the forward callback remain unchanged. A forward
  * callback error must use the transformation name as its type. Errors from the
@@ -943,23 +756,30 @@ export declare function createType<Name extends TypeName, ParentType extends Con
  * ### Example
  *
  * ```ts
- * import { Number, String, ok, transform } from "@evolu/common";
+ * import { Boolean, literal, ok, transform, union } from "@evolu/common";
  *
- * const NumberFromString = transform("NumberFromString", String, Number, {
- *   from: (value) => ok(globalThis.Number(value)),
- *   to: globalThis.String,
- * });
+ * const BooleanString = union(literal("false"), literal("true"));
+ * const BooleanFromString = transform(
+ *   "BooleanFromString",
+ *   BooleanString,
+ *   Boolean,
+ *   {
+ *     from: (value) => ok(value === "true"),
+ *     to: (value) => (value ? "true" : "false"),
+ *   },
+ * );
  *
- * expectOk(NumberFromString.from.parent("42"), 42);
- * assert(NumberFromString.to(42) === "42");
+ * expectOk(BooleanFromString.from.parent("true"), true);
+ * expect(BooleanFromString.to(false)).toBe("false");
  * ```
  *
- * @group Type construction
+ * @group Construction
  */
 export declare function transform<Name extends TypeName, ParentType extends ConcreteTypeNode, OutputType extends ConcreteTypeNode, ToOutput extends ParentType["Output"]>(name: ValidateChildTypeName<Name, ParentType>, parent: ValidateParent<ParentType>, output: ValidateOutput<OutputType>, operations: {
     readonly from: (value: ParentType["Output"]) => Result<OutputType["Input"], never>;
     readonly to: (value: CanonicalInputOf<OutputType>) => ToOutput;
 }): TransformType<ParentType, OutputType, Name, never, ToOutput>;
+/** Creates a fallible transformed Type with its own error formatter. */
 export declare function transform<Name extends TypeName, ParentType extends ConcreteTypeNode, OutputType extends ConcreteTypeNode, ToOutput extends ParentType["Output"], FromError extends {
     readonly type: Name;
     readonly outputError?: never;
@@ -967,17 +787,26 @@ export declare function transform<Name extends TypeName, ParentType extends Conc
     readonly from: (value: ParentType["Output"]) => Result<OutputType["Input"], FromError>;
     readonly to: (value: CanonicalInputOf<OutputType>) => ToOutput;
 }, formatError: [FromError] extends [never] ? never : TypeErrorFormatter<NoInfer<FromError>>): TransformType<ParentType, OutputType, Name, FromError, ToOutput>;
-/** @group Type construction */
+/**
+ * The {@link Type} returned by {@link transform}.
+ *
+ * @group Construction
+ */
 export interface TransformType<ParentType extends TypeNode, OutputType extends TypeNode, Name extends TypeName, FromError extends TypeError<Name>, ToOutput extends ParentType["Output"] = ParentType["Output"]> extends Type<Name, ParentType["Input"], OutputType["Output"], TransformError<Name, FromError, TypeFromError<OutputType>>, ParentType, TransformError<Name, FromError, TypeFromError<OutputType>> | InferErrors<ParentType>, ChildCustomFrom<ParentType, OutputType["Output"], TransformError<Name, FromError, TypeFromError<OutputType>>>, CanonicalInputForChild<ParentType, ToOutput>, false> {
     readonly [reflectedTypesSymbol]?: OutputType;
     readonly output: OutputType;
 }
-/** @group Type construction */
+/**
+ * An error produced by {@link transform} while decoding or validating its
+ * output.
+ *
+ * @group Construction
+ */
 export type TransformError<Name extends TypeName, OwnError extends TypeError<Name>, OutputError extends TypeError> = OwnError | ([OutputError] extends [never] ? never : TransformOutputError<Name, OutputError>);
 /**
  * Wraps an error produced by the output {@link Type} of {@link transform}.
  *
- * @group Type construction
+ * @group Construction
  */
 export interface TransformOutputError<Name extends TypeName, OutputError extends TypeError> extends TypeError<Name>, TransparentTypeError {
     /** The error returned by the output Type. */
@@ -990,10 +819,23 @@ type DeepestFromError<Operation> = DeepestFromOperation<Operation> extends (...a
 type TypeFromError<T extends TypeNode> = unknown extends T[typeof customFromSymbol] ? DeepestFromError<TypeFromOperation<T>> : [T[typeof customFromSymbol]] extends [never] ? NonRootErrors<T> : DeepestFromError<T[typeof customFromSymbol]>;
 declare const templateLiteralSyntaxSymbolType: unique symbol;
 declare const templateLiteralSyntaxSymbol: typeof templateLiteralSyntaxSymbolType;
-/** @group Base Types */
+/**
+ * An infallible {@link Type} accepting every value.
+ *
+ * @group Base
+ */
 export declare const Unknown: Type<"Unknown", unknown, unknown, never, null, never, never, unknown, true>;
-/** @group Base Types */
+/**
+ * A {@link Type} rejecting every value.
+ *
+ * @group Base
+ */
 export declare const Never: Type<"Never", never, never, NeverError, null, NeverError, never, never, true>;
+/**
+ * Error returned by {@link Never} for every value.
+ *
+ * @group Base
+ */
 export interface NeverError extends TypeError<"Never"> {
     readonly value: unknown;
 }
@@ -1005,7 +847,11 @@ interface TypeOfOutputByName {
     readonly Symbol: symbol;
     readonly Function: globalThis.Function;
 }
-/** @group Base Types */
+/**
+ * Error returned when `typeof` does not match the expected JavaScript type.
+ *
+ * @group Base
+ */
 export interface TypeOfError<Name extends keyof TypeOfOutputByName> extends TypeError<"TypeOf"> {
     readonly expected: Name;
     readonly value: unknown;
@@ -1033,6 +879,8 @@ export interface TypeOfError<Name extends keyof TypeOfOutputByName> extends Type
  * expectTypeOf<WireValue100>().toEqualTypeOf<
  *   string & Brand<"MaxLength100">
  * >();
+ * expectOk(WireValue100.fromUnknown(""), "");
+ * expectOk(WireValue100.fromUnknown(" value "), " value ");
  * ```
  *
  * @group String
@@ -1107,21 +955,37 @@ export declare const String: Type<"String", string, string, TypeOfError<"String"
  * @group Number
  */
 export declare const Number: Type<"Number", number, number, TypeOfError<"Number">, null, TypeOfError<"Number">, never, number, true>;
-/** @group Base Types */
+/**
+ * A JavaScript bigint {@link Type}.
+ *
+ * @group Base
+ */
 export declare const BigInt: Type<"BigInt", bigint, bigint, TypeOfError<"BigInt">, null, TypeOfError<"BigInt">, never, bigint, true>;
-/** @group Base Types */
+/**
+ * A JavaScript boolean {@link Type}.
+ *
+ * @group Base
+ */
 export declare const Boolean: Type<"Boolean", boolean, boolean, TypeOfError<"Boolean">, null, TypeOfError<"Boolean">, never, boolean, true>;
-/** @group Base Types */
+/**
+ * A JavaScript symbol {@link Type}.
+ *
+ * @group Base
+ */
 export declare const Symbol: Type<"Symbol", symbol, symbol, TypeOfError<"Symbol">, null, TypeOfError<"Symbol">, never, symbol, true>;
-/** @group Base Types */
+/**
+ * A JavaScript function {@link Type}.
+ *
+ * @group Base
+ */
 export declare const Function: Type<"Function", Function, Function, TypeOfError<"Function">, null, TypeOfError<"Function">, never, Function, true>;
 /**
- * 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 declare const EvoluType: Type<"EvoluType", AnyType, AnyType, EvoluTypeError, null, EvoluTypeError, never, AnyType, true>;
 /**
@@ -1134,22 +998,22 @@ export declare const EvoluType: Type<"EvoluType", AnyType, AnyType, EvoluTypeErr
  * the recursive `TypeNode` shape so composing Types does not repeatedly add its
  * compiler cost; {@link EvoluType} bridges that runtime evidence to this type.
  *
- * @group Core Types
+ * @group Core
  */
 export interface AnyType extends TypeNode {
     readonly [concreteTypeSymbol]: true;
 }
 /**
- * Error returned when a value is not an Evolu {@link Type}.
+ * Error returned when {@link EvoluType} rejects a value.
  *
- * @group Core Types
+ * @group Core
  */
 export interface EvoluTypeError extends TypeValueError<"EvoluType"> {
 }
 /**
  * Nominal evidence that a value has one object tag.
  *
- * @group Base Types
+ * @group Base
  */
 export interface ObjectTag<Name extends TypeName> {
     readonly [objectTagSymbol]: Name;
@@ -1157,7 +1021,7 @@ export interface ObjectTag<Name extends TypeName> {
 /**
  * The {@link Type} returned by {@link objectTag}.
  *
- * @group Base Types
+ * @group Base
  */
 export interface ObjectTagType<Name extends TypeName, OutputType extends TypeNode & {
     readonly Output: object;
@@ -1168,7 +1032,7 @@ export interface ObjectTagType<Name extends TypeName, OutputType extends TypeNod
 /**
  * An error returned when an object does not report the expected tag.
  *
- * @group Base Types
+ * @group Base
  */
 export interface ObjectTagError<Expected extends TypeName = TypeName> extends TypeError<"ObjectTag"> {
     readonly expected: Expected;
@@ -1182,22 +1046,34 @@ interface ObjectTagOutputByName {
 /**
  * Realm-neutral {@link Type} trusting an object's reported tag.
  *
- * Predefined built-in tags expose their native Output type under the assumption
- * that trusted code does not forge their tags. They do not verify native
- * internal slots. A custom tag refines the supplied Type and adds nominal
- * evidence to its Output, so only a value validated by the resulting Type is
- * accepted by its typed operations.
+ * Predefined tags for JavaScript built-ins expose their native Output type
+ * under the assumption that trusted code does not forge their tags. They do not
+ * verify native internal slots. A custom tag refines the supplied Type and adds
+ * nominal evidence to its Output, so only a value validated by the resulting
+ * Type is accepted by its typed operations.
+ *
+ * `Object.prototype.toString` recognizes legitimate JavaScript built-ins from
+ * another realm, but any object can customize the result with
+ * `Symbol.toStringTag`. Types returned by this factory therefore classify
+ * trusted values; they are not security boundaries. Passing a forged JavaScript
+ * built-in tag violates the trust assumption of the predefined Type. Primitive
+ * Outputs are rejected at compile time.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { objectTag } from "@evolu/common";
+ *
+ * const DateType = objectTag("Date");
+ * const date = new globalThis.Date("2025-01-01T00:00:00.000Z");
  *
- * `Object.prototype.toString` recognizes legitimate built-ins from another
- * realm, but any object can customize the result with `Symbol.toStringTag`.
- * Types returned by this factory therefore classify trusted values; they are
- * not security boundaries. Passing a forged built-in tag violates the trust
- * assumption of the predefined Type. Primitive Outputs are rejected at compile
- * time.
+ * expectOk(DateType.fromUnknown(date), date);
+ * ```
  *
- * @group Base Types
+ * @group Base
  */
 export declare function objectTag<Name extends keyof ObjectTagOutputByName>(name: ValidateConcreteTypeName<Name>): Type<Name, ObjectTagOutputByName[Name], ObjectTagOutputByName[Name], ObjectTagError<Name>, null, ObjectTagError<Name>, never, ObjectTagOutputByName[Name]>;
+/** Creates an object-tag Type by refining an existing object Type. */
 export declare function objectTag<Name extends TypeName, OutputType extends ConcreteTypeNode & {
     readonly Output: object;
 }>(name: ValidateConcreteTypeName<Name>, outputType: ValidateOutput<OutputType> & ([ChildTypeNameValidationError<"ObjectTag", OutputType>] extends [never] ? unknown : ChildTypeNameValidationError<"ObjectTag", OutputType>)): ObjectTagType<Name, OutputType>;
@@ -1207,7 +1083,7 @@ declare const objectTagSymbol: unique symbol;
  *
  * It trusts the reported object tag and does not verify Date internal slots.
  *
- * @group Base Types
+ * @group Base
  */
 export declare const Date: Type<"Date", Date, Date, ObjectTagError<"Date">, null, ObjectTagError<"Date">, never, Date, true>;
 /**
@@ -1216,7 +1092,7 @@ export declare const Date: Type<"Date", Date, Date, ObjectTagError<"Date">, null
  * It trusts the reported object tag and does not verify Uint8Array internal
  * slots.
  *
- * @group Base Types
+ * @group Base
  */
 export declare const Uint8Array: Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, ObjectTagError<"Uint8Array">, null, ObjectTagError<"Uint8Array">, never, Uint8Array<ArrayBufferLike>, true>;
 /**
@@ -1225,7 +1101,7 @@ export declare const Uint8Array: Type<"Uint8Array", Uint8Array<ArrayBufferLike>,
  * It trusts the reported object tag and does not verify ArrayBuffer internal
  * slots.
  *
- * @group Base Types
+ * @group Base
  */
 export declare const ArrayBuffer: Type<"ArrayBuffer", ArrayBuffer, ArrayBuffer, ObjectTagError<"ArrayBuffer">, null, ObjectTagError<"ArrayBuffer">, never, ArrayBuffer, true>;
 /**
@@ -1256,25 +1132,33 @@ export declare const ArrayBuffer: Type<"ArrayBuffer", ArrayBuffer, ArrayBuffer,
  * assert(!UserInstance.is({ name: "Ada" }));
  * ```
  *
- * @group Base Types
+ * @group Base
  */
 export declare const instanceOf: <Constructor extends InstanceConstructor>(constructor: ValidateInstanceConstructor<Constructor>) => InstanceOfType<Constructor>;
 /**
  * A JavaScript class constructor accepted by {@link instanceOf}.
  *
- * @group Base Types
+ * @group Base
  */
 export type InstanceConstructor<Instance extends object = object> = (abstract new (...args: ReadonlyArray<never>) => Instance) & {
     readonly name: string;
 };
-/** @group Base Types */
+/**
+ * The {@link Type} returned by {@link instanceOf}.
+ *
+ * @group Base
+ */
 export interface InstanceOfType<Constructor extends InstanceConstructor> extends Type<"InstanceOf", InstanceOfOutput<Constructor>, InstanceOfOutput<Constructor>, InstanceOfError, null, InstanceOfError, never, InstanceOfOutput<Constructor>> {
     readonly constructor: Constructor;
 }
 type InstanceOfOutput<Constructor extends InstanceConstructor> = Constructor extends {
     readonly prototype: infer Output extends object;
 } ? Output : InstanceType<Constructor>;
-/** @group Base Types */
+/**
+ * Error returned when a value is not an instance of the expected constructor.
+ *
+ * @group Base
+ */
 export interface InstanceOfError extends TypeValueError<"InstanceOf"> {
     readonly constructorName: string;
 }
@@ -1311,7 +1195,11 @@ type InstanceConstructorCompileTimeError = CompileTimeError<"Type", "Constructor
  * @group Unions
  */
 export declare const literal: <const Expected extends Literal>(expected: ValidateLiteral<Expected>) => LiteralType<Expected>;
-/** @group Unions */
+/**
+ * The {@link Type} returned by {@link literal}.
+ *
+ * @group Unions
+ */
 export interface LiteralType<Expected extends Literal> extends Type<"Literal", WidenLiteral<Expected>, Expected, LiteralError<Expected>, LiteralParent<Expected>, LiteralError<Expected> | LiteralParentErrors<Expected>, never, CanonicalInputSubset<WidenLiteral<Expected>, CanonicalInputForParent<LiteralParent<Expected>, Expected>>, IdentityEncodingForParent<LiteralParent<Expected>>> {
     readonly [templateLiteralSyntaxSymbol]: true;
     readonly expected: Expected;
@@ -1320,14 +1208,26 @@ type LiteralParent<Expected extends Literal> = Expected extends string ? typeof
 type LiteralParentErrors<Expected extends Literal> = LiteralParent<Expected> extends infer Parent extends TypeNode ? InferErrors<Parent> : never;
 type ValidateLiteral<Expected extends Literal> = IsUnion<Expected> extends false ? {} extends Readonly<Record<`${Expected}`, never>> ? LiteralCompileTimeError : Expected : LiteralCompileTimeError;
 type LiteralCompileTimeError = CompileTimeError<"Type", "Expected must be one concrete literal value.">;
-/** @group Unions */
+/**
+ * Error returned when a value does not equal the expected literal.
+ *
+ * @group Unions
+ */
 export interface LiteralError<Expected extends Literal = Literal> extends TypeError<"Literal"> {
     readonly expected: Expected;
     readonly value: unknown;
 }
-/** @group Unions */
+/**
+ * Literal {@link Type} accepting only `undefined`.
+ *
+ * @group Unions
+ */
 export declare const Undefined: LiteralType<undefined>;
-/** @group Unions */
+/**
+ * Literal {@link Type} accepting only `null`.
+ *
+ * @group Unions
+ */
 export declare const Null: LiteralType<null>;
 /**
  * Union {@link Type}.
@@ -1352,7 +1252,10 @@ export declare const Null: LiteralType<null>;
  * within each member.
  *
  * Member order matters when multiple members accept the same value: validation
- * and encoding use the first matching member.
+ * and encoding use the first matching member. When member Inputs overlap,
+ * decoding the value emitted by the first member selected for an Output must
+ * reproduce that semantic Output; otherwise the Union violates the round-trip
+ * law.
  *
  * ### Example
  *
@@ -1389,9 +1292,11 @@ export declare function union<const Expected extends AtLeastTwoReadonlyArray<Lit
 }): UnionType<{
     readonly [Index in keyof Expected]: LiteralType<Expected[Index]>;
 }>;
+/** Creates a Union Type from Type members. */
 export declare function union<const Members extends AtLeastTwoReadonlyArray<TypeNode>>(...members: {
     readonly [Index in keyof Members]: ValidateUnionTypeMember<Members[Index]>;
 }): UnionType<Members>;
+/** Creates a Union Type from Type and literal members. */
 export declare function union<const Members extends AtLeastTwoReadonlyArray<TypeNode | Literal>>(...members: {
     readonly [Index in keyof Members]: ValidateUnionMember<Members[Index]>;
 }): UnionType<NormalizeUnionMembers<Members>>;
@@ -1401,18 +1306,49 @@ export declare function union<const Members extends AtLeastTwoReadonlyArray<Type
  * 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 declare const undefinedOr: <ValueType extends TypeNode>(type: ValidateUnionTypeMember<ValueType>) => UnionType<readonly [ValueType, typeof 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 declare const nullOr: <ValueType extends TypeNode>(type: ValidateUnionTypeMember<ValueType>) => UnionType<readonly [ValueType, typeof 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 declare const nullishOr: <ValueType extends TypeNode>(type: ValidateUnionTypeMember<ValueType>) => UnionType<readonly [ValueType, typeof Null, typeof Undefined]>;
@@ -1424,7 +1360,11 @@ type UnionMemberConcreteTypeError = CompileTimeError<"Type", "Union member must
 type NormalizeUnionMembers<Members extends AtLeastTwoReadonlyArray<TypeNode | Literal>> = {
     readonly [Index in keyof Members]: Members[Index] extends TypeNode ? Members[Index] : Members[Index] extends Literal ? LiteralType<Members[Index]> : never;
 } extends infer Normalized extends AtLeastTwoReadonlyArray<TypeNode> ? Normalized : never;
-/** @group Unions */
+/**
+ * The {@link Type} returned by {@link union}.
+ *
+ * @group Unions
+ */
 export interface UnionType<Members extends AtLeastTwoReadonlyArray<TypeNode>> extends Type<"Union", Members[number]["Input"], Members[number]["Output"], UnionTypeError<Members>, UnionInputParent<Members>, UnionTypeError<Members>, never, CanonicalInputOf<Members[number]>, AllTypesUseIdentityEncoding<Members[number]>> {
     readonly [templateLiteralSyntaxSymbol]: true;
     readonly [reflectedTypesSymbol]?: Members[number];
@@ -1442,9 +1382,17 @@ type UnionInputTypeError<Members extends AtLeastTwoReadonlyArray<TypeNode>, Root
 type RootUnionMembers<Members extends AtLeastTwoReadonlyArray<TypeNode>> = {
     readonly [Index in keyof Members]: RootType<Members[Index]>;
 } extends infer RootMembers extends AtLeastTwoReadonlyArray<TypeNode> ? RootMembers : never;
-/** @group Unions */
+/**
+ * Error returned when every member of a {@link union} rejects an input.
+ *
+ * @group Unions
+ */
 export type UnionError<Error extends TypeError = TypeError, MemberError extends UnionMemberError<Error> = UnionMemberError<Error>> = [Error] extends [never] ? never : UnionErrorValue<Error, MemberError>;
-/** @group Unions */
+/**
+ * An error returned by one {@link union} member and its index.
+ *
+ * @group Unions
+ */
 export interface UnionMemberError<Error extends TypeError, Index extends number = number> {
     readonly index: Index;
     readonly error: Error;
@@ -1472,9 +1420,7 @@ interface UnionErrorValue<Error extends TypeError, MemberError extends UnionMemb
     readonly errors: NonEmptyReadonlyArray<MemberError>;
 }
 /**
- * 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
@@ -1490,10 +1436,10 @@ interface UnionErrorValue<Error extends TypeError, MemberError extends UnionMemb
  * 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.
  *
@@ -1530,10 +1476,9 @@ interface UnionErrorValue<Error extends TypeError, MemberError extends UnionMemb
  *
  * // 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",
@@ -1592,10 +1537,9 @@ interface UnionErrorValue<Error extends TypeError, MemberError extends UnionMemb
  *
  * // 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);
@@ -1645,14 +1589,22 @@ interface UnionErrorValue<Error extends TypeError, MemberError extends UnionMemb
  * @group Template literals
  */
 export declare const templateLiteralParser: <const Parts extends TemplateLiteralParts>(...parts: { readonly [Index in keyof Parts]: ValidateTemplateLiteralPart<Parts[Index]>; } & TemplateLiteralValidation<Parts>) => TemplateLiteralParserType<Parts>;
-/** @group Template literals */
+/**
+ * The parsing {@link Type} returned by {@link templateLiteralParser}.
+ *
+ * @group Template literals
+ */
 export interface TemplateLiteralParserType<Parts extends TemplateLiteralParts> extends Type<"TemplateLiteral", string, TemplateLiteralCaptureTuple<Parts>["Output"], never, TemplateLiteralType<Parts>, InferErrors<TemplateLiteralType<Parts>>, never, TemplateLiteralStringOutput<Parts>, false> {
     readonly [templateLiteralSyntaxSymbol]: true;
     readonly [reflectedTypesSymbol]?: TemplateLiteralCaptureTuple<Parts>;
     readonly output: TemplateLiteralCaptureTuple<Parts>;
     readonly parts: Parts;
 }
-/** @group Template literals */
+/**
+ * The validating string {@link Type} returned by {@link templateLiteral}.
+ *
+ * @group Template literals
+ */
 export interface TemplateLiteralType<Parts extends TemplateLiteralParts> extends Type<"TemplateLiteral", string, TemplateLiteralStringOutput<Parts>, TemplateLiteralParseError<Parts>, typeof String, TypeOfError<"String"> | TemplateLiteralParseError<Parts>, never, TemplateLiteralStringOutput<Parts>, true> {
     readonly [templateLiteralSyntaxSymbol]: true;
     readonly [reflectedTypesSymbol]?: TemplateLiteralCaptureTuple<Parts>;
@@ -1665,8 +1617,8 @@ export interface TemplateLiteralType<Parts extends TemplateLiteralParts> extends
  * 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
  *
@@ -1690,7 +1642,11 @@ export declare const templateLiteral: <const Parts extends TemplateLiteralParts>
 type TemplateLiteralParseError<Parts extends TemplateLiteralParts> = TransformError<"TemplateLiteral", TemplateLiteralIsFrameless<Parts> extends true ? never : TemplateLiteralError, TemplateLiteralCaptureTupleError<Parts>>;
 type TemplateLiteralCaptureTupleError<Parts extends TemplateLiteralParts> = TupleElementsError<TemplateLiteralCaptureFromStringError<TemplateLiteralCaptureTypes<Parts>[number]>>;
 type TemplateLiteralCaptureFromStringError<T extends TypeNode> = T extends TypeNode ? string extends RootType<T>["Output"] ? TypeFromError<T> : InferErrors<T> : never;
-/** @group Template literals */
+/**
+ * Error returned when a string does not match a template literal declaration.
+ *
+ * @group Template literals
+ */
 export interface TemplateLiteralError extends TypeError<"TemplateLiteral"> {
     readonly value: string;
 }
@@ -1780,72 +1736,19 @@ type TemplateLiteralStringWidth<Value extends string, Width extends ReadonlyArra
  * });
  * ```
  *
- * To reuse a Brand constraint with different parent Types, define a
- * {@link BrandFactory}. Brand Factories can then be composed:
- *
- * ```ts
- * import {
- *   String,
- *   brand,
- *   err,
- *   minLength,
- *   ok,
- *   type Brand,
- *   type BrandFactory,
- *   type TypeError,
- * } from "@evolu/common";
- *
- * const trimmed: BrandFactory<"Trimmed", string, TrimmedError> = (
- *   parent,
- * ) =>
- *   brand(
- *     "Trimmed",
- *     parent,
- *     (value) =>
- *       value === value.trim()
- *         ? ok()
- *         : err<TrimmedError>({ type: "Trimmed", value }),
- *     () => "Expected a string without surrounding whitespace.",
- *   );
- *
- * const TrimmedString = trimmed(String);
- * type TrimmedString = typeof TrimmedString.Output;
- *
- * expectTypeOf<TrimmedString>().toEqualTypeOf<string & Brand<"Trimmed">>();
- *
- * const NonEmptyString = minLength(1)(String);
- * type NonEmptyString = typeof NonEmptyString.Output;
- *
- * expectTypeOf<NonEmptyString>().toEqualTypeOf<
- *   string & Brand<"MinLength1">
- * >();
- *
- * const NonEmptyTrimmedString = minLength(1)(TrimmedString);
- * type NonEmptyTrimmedString = typeof NonEmptyTrimmedString.Output;
- *
- * expectTypeOf<NonEmptyTrimmedString>().toEqualTypeOf<
- *   string & Brand<"Trimmed"> & Brand<"MinLength1">
- * >();
- *
- * interface TrimmedError extends TypeError<"Trimmed"> {
- *   readonly value: string;
- * }
- *
- * // Validation from unknown.
- * expectOk(NonEmptyTrimmedString.fromUnknown("Evolu"), "Evolu");
- *
- * // The typed input selects TrimmedString as the validated boundary.
- * expectOk(
- *   NonEmptyTrimmedString.from.parent(TrimmedString.orThrow("Evolu")),
- *   "Evolu",
- * );
- * ```
+ * To reuse and compose a Brand constraint with different parent Types, define a
+ * {@link BrandFactory}.
  *
- * @group Type construction
+ * @group Construction
  */
 export declare function brand<Name extends TypeName, ParentType extends ConcreteTypeNode>(name: ValidateConcreteTypeName<Name>, parent: ValidateParent<ParentType>, validate?: (value: ParentType["Output"]) => Result<void, never>): BrandType<ParentType, Name, never>;
+/** Creates a validated Brand Type with its own error formatter. */
 export declare function brand<Name extends TypeName, ParentType extends ConcreteTypeNode, Error extends TypeError<NoInfer<Name>>>(name: Name, parent: ValidateBrandParent<Name, ParentType>, validate: (value: ParentType["Output"]) => Result<void, Error>, formatError: TypeErrorFormatter<NoInfer<Error>>): BrandType<ParentType, Name, Error>;
-/** @group Type construction */
+/**
+ * The {@link Type} returned by {@link brand}.
+ *
+ * @group Construction
+ */
 export interface BrandType<ParentType extends TypeNode, Name extends TypeName, Error extends TypeError> extends Type<Name, ParentType["Input"], ParentType["Output"] & Brand<Name>, Error, ParentType, Error | InferErrors<ParentType>, ChildCustomFrom<ParentType, ParentType["Output"] & Brand<Name>, Error>, CanonicalInputForChild<ParentType, ParentType["Output"] & Brand<Name>>, IdentityEncodingOf<ParentType>> {
 }
 /**
@@ -1878,17 +1781,37 @@ export interface BrandType<ParentType extends TypeNode, Name extends TypeName, E
  */
 export declare const DateIso: BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "DateIso", DateIsoError>;
 export type DateIso = typeof DateIso.Output;
-/** @group String */
+/**
+ * Error returned when a string is not a canonical {@link DateIso}.
+ *
+ * @group String
+ */
 export interface DateIsoError extends TypeError<"DateIso"> {
     readonly value: string;
 }
 /**
  * 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 declare const DateIsoFromDate: TransformType<Type<"Date", Date, Date, ObjectTagError<"Date">, null, ObjectTagError<"Date">, never, Date, true>, BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "DateIso", DateIsoError>, "DateIsoFromDate", DateIsoFromDateError, Date>;
-/** @group String */
+/**
+ * Error returned when a {@link Date} cannot be represented as {@link DateIso}.
+ *
+ * @group String
+ */
 export interface DateIsoFromDateError extends TypeError<"DateIsoFromDate"> {
     readonly value: globalThis.Date;
 }
@@ -1899,7 +1822,11 @@ export interface DateIsoFromDateError extends TypeError<"DateIsoFromDate"> {
  */
 export declare const Int64: BrandType<Type<"BigInt", bigint, bigint, TypeOfError<"BigInt">, null, TypeOfError<"BigInt">, never, bigint, true>, "Int64", Int64Error>;
 export type Int64 = typeof Int64.Output;
-/** @group Number */
+/**
+ * Error returned when a bigint is outside the signed 64-bit {@link Int64} range.
+ *
+ * @group Number
+ */
 export interface Int64Error extends TypeError<"Int64"> {
     readonly value: bigint;
 }
@@ -1910,7 +1837,12 @@ export interface Int64Error extends TypeError<"Int64"> {
  */
 export declare const UInt64: BrandType<Type<"BigInt", bigint, bigint, TypeOfError<"BigInt">, null, TypeOfError<"BigInt">, never, bigint, true>, "UInt64", UInt64Error>;
 export type UInt64 = typeof UInt64.Output;
-/** @group Number */
+/**
+ * Error returned when a bigint is outside the unsigned 64-bit {@link UInt64}
+ * range.
+ *
+ * @group Number
+ */
 export interface UInt64Error extends TypeError<"UInt64"> {
     readonly value: bigint;
 }
@@ -1966,7 +1898,7 @@ export interface UInt64Error extends TypeError<"UInt64"> {
  * For numeric parameters encoded in a Brand name, use
  * {@link ValidateBrandFactoryNumber}.
  *
- * @group Type construction
+ * @group Construction
  */
 export type BrandFactory<Name extends TypeName, Value, Error extends TypeError<Name>> = <ParentType extends ConcreteTypeNode & {
     readonly Output: Value;
@@ -2031,7 +1963,7 @@ export type BrandFactory<Name extends TypeName, Value, Error extends TypeError<N
  * lessThan(100 - 1)(Number);
  * ```
  *
- * @group Type utilities
+ * @group Construction
  */
 export type ValidateBrandFactoryNumber<Value extends number> = IsUnion<Value> extends false ? {} extends Record<`${Value}`, never> ? Value & Readonly<Record<BrandFactoryNumberError, never>> : Value : Value & Readonly<Record<BrandFactoryNumberError, never>>;
 type BrandFactoryNumberError = CompileTimeError<"Brand Factory", "Parameter must be one concrete numeric literal instead of a widened, union, or branded number.">;
@@ -2062,7 +1994,11 @@ type BrandFactoryNumberError = CompileTimeError<"Brand Factory", "Parameter must
  * @group String
  */
 export declare const capitalized: BrandFactory<"Capitalized", string, CapitalizedError>;
-/** @group String */
+/**
+ * Error returned when {@link capitalized} rejects a string.
+ *
+ * @group String
+ */
 export interface CapitalizedError extends TypeError<"Capitalized"> {
     readonly value: string;
 }
@@ -2076,10 +2012,24 @@ export type CapitalizedString = typeof CapitalizedString.Output;
 /**
  * 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 declare const trimmed: BrandFactory<"Trimmed", string, TrimmedError>;
-/** @group String */
+/**
+ * Error returned when {@link trimmed} rejects a string.
+ *
+ * @group String
+ */
 export interface TrimmedError extends TypeError<"Trimmed"> {
     readonly value: string;
 }
@@ -2099,17 +2049,41 @@ export type TrimmedString = typeof TrimmedString.Output;
 /**
  * Trims a string and returns a {@link TrimmedString}.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { trim } from "@evolu/common";
+ *
+ * expect(trim("  Evolu  ")).toBe("Evolu");
+ * ```
+ *
  * @group String
  */
 export declare const trim: (value: string) => TrimmedString;
 /**
- * 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
  */
 export declare const minLength: <Min extends number>(min: ValidateBrandFactoryNumber<Min>) => BrandFactory<`MinLength${Min}`, ValueWithLength, MinLengthError<Min>>;
-/** @group Collection */
+/**
+ * Error returned when {@link minLength} rejects a value.
+ *
+ * @group Collection
+ */
 export interface MinLengthError<Min extends number = number> extends TypeError<`MinLength${Min}`> {
     readonly value: ValueWithLength;
     readonly min: Min;
@@ -2131,13 +2105,29 @@ export interface MinLengthError<Min extends number = number> extends TypeError<`
 export declare const NonEmptyTrimmedString: BrandType<BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "Trimmed", TrimmedError>, "MinLength1", MinLengthError<1>>;
 export type NonEmptyTrimmedString = typeof NonEmptyTrimmedString.Output;
 /**
- * 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
  */
 export declare const maxLength: <Max extends number>(max: ValidateBrandFactoryNumber<Max>) => BrandFactory<`MaxLength${Max}`, ValueWithLength, MaxLengthError<Max>>;
-/** @group Collection */
+/**
+ * Error returned when {@link maxLength} rejects a value.
+ *
+ * @group Collection
+ */
 export interface MaxLengthError<Max extends number = number> extends TypeError<`MaxLength${Max}`> {
     readonly value: ValueWithLength;
     readonly max: Max;
@@ -2157,13 +2147,29 @@ export type NonEmptyTrimmedString100 = typeof NonEmptyTrimmedString100.Output;
 export declare const NonEmptyTrimmedString1000: BrandType<BrandType<BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "Trimmed", TrimmedError>, "MinLength1", MinLengthError<1>>, "MaxLength1000", MaxLengthError<1000>>;
 export type NonEmptyTrimmedString1000 = typeof NonEmptyTrimmedString1000.Output;
 /**
- * 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
  */
 export declare const length: <Exact extends number>(exact: ValidateBrandFactoryNumber<Exact>) => BrandFactory<`Length${Exact}`, ValueWithLength, LengthError<Exact>>;
-/** @group Collection */
+/**
+ * Error returned when {@link length} rejects a value.
+ *
+ * @group Collection
+ */
 export interface LengthError<Exact extends number = number> extends TypeError<`Length${Exact}`> {
     readonly value: ValueWithLength;
     readonly exact: Exact;
@@ -2197,7 +2203,12 @@ export interface LengthError<Exact extends number = number> extends TypeError<`L
  * @group String
  */
 export declare const regex: <const Name extends TypeName>(name: ValidateConcreteTypeName<Name>, pattern: RegExp) => BrandFactory<Name, string, RegexError<Name>>;
-/** @group String */
+/**
+ * Error returned when a string does not match the regular expression supplied
+ * to {@link regex}.
+ *
+ * @group String
+ */
 export interface RegexError<Name extends TypeName = TypeName> extends TypeError<Name> {
     readonly value: string;
     readonly source: string;
@@ -2217,25 +2228,51 @@ export type UrlSafeString = typeof UrlSafeString.Output;
 /**
  * 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
  */
 export declare const Base64Url: BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "Base64Url", Base64UrlError>;
 export type Base64Url = typeof Base64Url.Output;
-/** @group String */
+/**
+ * Error returned when a string is not valid {@link Base64Url} text.
+ *
+ * @group String
+ */
 export interface Base64UrlError extends TypeError<"Base64Url"> {
     readonly value: 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 declare const uint8ArrayToBase64Url: (bytes: Uint8Array) => Base64Url;
 /**
- * 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
  */
@@ -2247,7 +2284,11 @@ export declare const base64UrlToUint8Array: (value: Base64Url) => Uint8Array;
  */
 export declare const Name: BrandType<BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "UrlSafeString", RegexError<"UrlSafeString">>, "Name", NameError>;
 export type Name = typeof Name.Output;
-/** @group String */
+/**
+ * Error returned when a string is not a valid {@link Name}.
+ *
+ * @group String
+ */
 export interface NameError extends TypeError<"Name"> {
     readonly value: string;
 }
@@ -2271,7 +2312,11 @@ export type SimplePassword = typeof SimplePassword.Output;
  */
 export declare const Mnemonic: BrandType<BrandType<BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "Trimmed", TrimmedError>, "MinLength1", MinLengthError<1>>, "Mnemonic", MnemonicError>;
 export type Mnemonic = typeof Mnemonic.Output;
-/** @group String */
+/**
+ * Error returned when a string is not a valid English BIP39 {@link Mnemonic}.
+ *
+ * @group String
+ */
 export interface MnemonicError extends TypeError<"Mnemonic"> {
     readonly value: string;
 }
@@ -2287,7 +2332,11 @@ export interface MnemonicError extends TypeError<"Mnemonic"> {
  */
 export declare const Id: BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "Id", IdError>;
 export type Id = typeof Id.Output;
-/** @group String */
+/**
+ * Error returned when a string is not a valid {@link Id}.
+ *
+ * @group String
+ */
 export interface IdError extends TypeError<"Id"> {
     readonly value: string;
 }
@@ -2297,6 +2346,22 @@ export interface IdError extends TypeError<"Id"> {
  * 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 declare const createId: <B extends string = never>(deps: RandomBytesDep, ..._validation: IdBrandValidation<B>) => CreatedId<B>;
@@ -2331,20 +2396,64 @@ export declare const createIdFromString: <B extends string = never>(value: strin
  * 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 declare const createIdAsUuidv7: <B extends string = never>(deps: RandomBytesDep & TimeDep, ..._validation: IdBrandValidation<B>) => CreatedId<B>;
 /**
  * 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 declare const id: <Table extends TypeName>(table: ValidateTableName<Table>) => TableId<Table>;
-/** @group String */
+/**
+ * The {@link Type} returned by {@link id} for one table.
+ *
+ * @group String
+ */
 export interface TableId<Table extends TypeName> extends Type<"TableId", string, Id & Brand<Table>, TableIdError<Table>, typeof String, TableIdError<Table> | InferErrors<typeof String>, ChildCustomFrom<typeof String, Id & Brand<Table>, TableIdError<Table>>, CanonicalInputForChild<typeof String, Id & Brand<Table>>, IdentityEncodingOf<typeof String>> {
     readonly table: Table;
 }
-/** @group String */
+/**
+ * Error returned when a string is not a valid {@link Id} for the expected table.
+ *
+ * @group String
+ */
 export interface TableIdError<Table extends TypeName = TypeName> extends TypeError<"TableId"> {
     readonly table: Table;
     readonly value: string;
@@ -2364,11 +2473,47 @@ type ConcreteIdBrandError = CompileTimeError<"Id", "Brand must be one concrete s
  */
 export declare const IdBytes: BrandType<BrandType<Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, ObjectTagError<"Uint8Array">, null, ObjectTagError<"Uint8Array">, never, Uint8Array<ArrayBufferLike>, true>, "Length16", LengthError<16>>, "IdBytes", never>;
 export type IdBytes = typeof IdBytes.Output;
-/** @group String */
+/**
+ * Byte length of an {@link IdBytes} value.
+ *
+ * @group String
+ */
 export declare const idBytesTypeValueLength: NonNegativeInt;
-/** @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 declare const idToIdBytes: (value: Id) => IdBytes;
-/** @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 declare const idBytesToId: (value: IdBytes) => Id;
 /**
  * Decimal string representation of a signed {@link Int64}.
@@ -2377,7 +2522,11 @@ export declare const idBytesToId: (value: IdBytes) => Id;
  */
 export declare const Int64String: BrandType<BrandType<BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "Trimmed", TrimmedError>, "MinLength1", MinLengthError<1>>, "Int64String", Int64StringError>;
 export type Int64String = typeof Int64String.Output;
-/** @group Number */
+/**
+ * Error returned when a string is not a canonical {@link Int64String}.
+ *
+ * @group Number
+ */
 export interface Int64StringError extends TypeError<"Int64String"> {
     readonly value: string;
 }
@@ -2388,16 +2537,43 @@ export interface Int64StringError extends TypeError<"Int64String"> {
  * 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 declare const Int64FromInt64String: TransformType<BrandType<BrandType<BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "Trimmed", TrimmedError>, "MinLength1", MinLengthError<1>>, "Int64String", Int64StringError>, BrandType<Type<"BigInt", bigint, bigint, TypeOfError<"BigInt">, null, TypeOfError<"BigInt">, never, bigint, true>, "Int64", Int64Error>, "Int64FromInt64String", never, string & Brand<"Trimmed"> & Brand<"MinLength1"> & Brand<"Int64String">>;
 /**
  * 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 declare const nonNegative: BrandFactory<"NonNegative", number, NonNegativeError>;
-/** @group Number */
+/**
+ * Error returned when {@link nonNegative} rejects a number.
+ *
+ * @group Number
+ */
 export interface NonNegativeError extends TypeError<"NonNegative"> {
     readonly value: number;
 }
@@ -2411,10 +2587,24 @@ export type NonNegativeNumber = typeof NonNegativeNumber.Output;
 /**
  * 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 declare const positive: BrandFactory<"Positive", number, PositiveError>;
-/** @group Number */
+/**
+ * Error returned when {@link positive} rejects a number.
+ *
+ * @group Number
+ */
 export interface PositiveError extends TypeError<"Positive"> {
     readonly value: number;
 }
@@ -2431,10 +2621,24 @@ export type PositiveNumber = typeof PositiveNumber.Output;
 /**
  * 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 declare const nonPositive: BrandFactory<"NonPositive", number, NonPositiveError>;
-/** @group Number */
+/**
+ * Error returned when {@link nonPositive} rejects a number.
+ *
+ * @group Number
+ */
 export interface NonPositiveError extends TypeError<"NonPositive"> {
     readonly value: number;
 }
@@ -2448,10 +2652,24 @@ export type NonPositiveNumber = typeof NonPositiveNumber.Output;
 /**
  * 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 declare const negative: BrandFactory<"Negative", number, NegativeError>;
-/** @group Number */
+/**
+ * Error returned when {@link negative} rejects a number.
+ *
+ * @group Number
+ */
 export interface NegativeError extends TypeError<"Negative"> {
     readonly value: number;
 }
@@ -2468,10 +2686,24 @@ export type NegativeNumber = typeof NegativeNumber.Output;
 /**
  * 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 declare const nonNaN: BrandFactory<"NonNaN", number, NonNaNError>;
-/** @group Number */
+/**
+ * Error returned when {@link nonNaN} rejects `NaN`.
+ *
+ * @group Number
+ */
 export interface NonNaNError extends TypeError<"NonNaN"> {
     readonly value: number;
 }
@@ -2490,10 +2722,24 @@ export type NonNaNNumber = typeof NonNaNNumber.Output;
 /**
  * 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 declare const finite: BrandFactory<"Finite", number, FiniteError>;
-/** @group Number */
+/**
+ * Error returned when {@link finite} rejects a non-finite number.
+ *
+ * @group Number
+ */
 export interface FiniteError extends TypeError<"Finite"> {
     readonly value: number;
 }
@@ -2541,7 +2787,11 @@ export type PositiveFiniteNumber = typeof PositiveFiniteNumber.Output;
  * @group Number
  */
 export declare const int: BrandFactory<"Int", number, IntError>;
-/** @group Number */
+/**
+ * Error returned when {@link int} rejects a number that is not a safe integer.
+ *
+ * @group Number
+ */
 export interface IntError extends TypeError<"Int"> {
     readonly value: number;
 }
@@ -2607,10 +2857,24 @@ export type NegativeInt = typeof NegativeInt.Output;
 /**
  * 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 declare const greaterThan: <Min extends number>(min: ValidateBrandFactoryNumber<Min>) => BrandFactory<`GreaterThan${Min}`, number, GreaterThanError<Min>>;
-/** @group Number */
+/**
+ * Error returned when {@link greaterThan} rejects a number.
+ *
+ * @group Number
+ */
 export interface GreaterThanError<Min extends number = number> extends TypeError<`GreaterThan${Min}`> {
     readonly value: number;
     readonly min: Min;
@@ -2618,10 +2882,24 @@ export interface GreaterThanError<Min extends number = number> extends TypeError
 /**
  * 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 declare const greaterThanOrEqualTo: <Min extends number>(min: ValidateBrandFactoryNumber<Min>) => BrandFactory<`GreaterThanOrEqualTo${Min}`, number, GreaterThanOrEqualToError<Min>>;
-/** @group Number */
+/**
+ * Error returned when {@link greaterThanOrEqualTo} rejects a number.
+ *
+ * @group Number
+ */
 export interface GreaterThanOrEqualToError<Min extends number = number> extends TypeError<`GreaterThanOrEqualTo${Min}`> {
     readonly value: number;
     readonly min: Min;
@@ -2629,10 +2907,24 @@ export interface GreaterThanOrEqualToError<Min extends number = number> extends
 /**
  * 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 declare const lessThan: <Max extends number>(max: ValidateBrandFactoryNumber<Max>) => BrandFactory<`LessThan${Max}`, number, LessThanError<Max>>;
-/** @group Number */
+/**
+ * Error returned when {@link lessThan} rejects a number.
+ *
+ * @group Number
+ */
 export interface LessThanError<Max extends number = number> extends TypeError<`LessThan${Max}`> {
     readonly value: number;
     readonly max: Max;
@@ -2647,10 +2939,24 @@ export type Age = typeof Age.Output;
 /**
  * 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 declare const lessThanOrEqualTo: <Max extends number>(max: ValidateBrandFactoryNumber<Max>) => BrandFactory<`LessThanOrEqualTo${Max}`, number, LessThanOrEqualToError<Max>>;
-/** @group Number */
+/**
+ * Error returned when {@link lessThanOrEqualTo} rejects a number.
+ *
+ * @group Number
+ */
 export interface LessThanOrEqualToError<Max extends number = number> extends TypeError<`LessThanOrEqualTo${Max}`> {
     readonly value: number;
     readonly max: Max;
@@ -2707,17 +3013,35 @@ export type Ratio = typeof Ratio.Output;
  */
 export declare const DecimalString: BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "DecimalString", DecimalStringError>;
 export type DecimalString = typeof DecimalString.Output;
-/** @group Number */
+/**
+ * Error returned when a string is not a canonical {@link DecimalString}.
+ *
+ * @group Number
+ */
 export interface DecimalStringError extends TypeError<"DecimalString"> {
     readonly value: string;
 }
 /**
  * {@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 declare const nonNegativeDecimalString: BrandFactory<"NonNegativeDecimalString", DecimalString, NonNegativeDecimalStringError>;
-/** @group Number */
+/**
+ * Error returned when {@link nonNegativeDecimalString} rejects a decimal string.
+ *
+ * @group Number
+ */
 export interface NonNegativeDecimalStringError extends TypeError<"NonNegativeDecimalString"> {
     readonly value: string;
 }
@@ -2731,10 +3055,24 @@ export type NonNegativeDecimalString = typeof NonNegativeDecimalString.Output;
 /**
  * {@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 declare const positiveDecimalString: BrandFactory<"PositiveDecimalString", DecimalString, PositiveDecimalStringError>;
-/** @group Number */
+/**
+ * Error returned when {@link positiveDecimalString} rejects a decimal string.
+ *
+ * @group Number
+ */
 export interface PositiveDecimalStringError extends TypeError<"PositiveDecimalString"> {
     readonly value: string;
 }
@@ -2751,10 +3089,24 @@ export type PositiveDecimalString = typeof PositiveDecimalString.Output;
 /**
  * {@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 declare const nonPositiveDecimalString: BrandFactory<"NonPositiveDecimalString", DecimalString, NonPositiveDecimalStringError>;
-/** @group Number */
+/**
+ * Error returned when {@link nonPositiveDecimalString} rejects a decimal string.
+ *
+ * @group Number
+ */
 export interface NonPositiveDecimalStringError extends TypeError<"NonPositiveDecimalString"> {
     readonly value: string;
 }
@@ -2768,10 +3120,24 @@ export type NonPositiveDecimalString = typeof NonPositiveDecimalString.Output;
 /**
  * {@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 declare const negativeDecimalString: BrandFactory<"NegativeDecimalString", DecimalString, NegativeDecimalStringError>;
-/** @group Number */
+/**
+ * Error returned when {@link negativeDecimalString} rejects a decimal string.
+ *
+ * @group Number
+ */
 export interface NegativeDecimalStringError extends TypeError<"NegativeDecimalString"> {
     readonly value: string;
 }
@@ -2818,7 +3184,11 @@ export type NegativeDecimalString = typeof NegativeDecimalString.Output;
  * @group Number
  */
 export declare const multipleOf: <const Divisor extends string>(divisor: ValidateMultipleOfDivisor<Divisor>) => BrandFactory<`MultipleOf${Divisor}`, number, MultipleOfError<Divisor>>;
-/** @group Number */
+/**
+ * Error returned when {@link multipleOf} rejects a number.
+ *
+ * @group Number
+ */
 export interface MultipleOfError<Divisor extends string = string> extends TypeError<`MultipleOf${Divisor}`> {
     readonly value: number;
     readonly divisor: Divisor;
@@ -2834,10 +3204,24 @@ type MultipleOfDivisorError = CompileTimeError<"MultipleOf", 'Divisor must be on
 /**
  * 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 declare const between: <Min extends number, Max extends number>(min: ValidateBrandFactoryNumber<Min>, max: ValidateBrandFactoryNumber<Max>) => BrandFactory<`Between${Min}-${Max}`, number, BetweenError<Min, Max>>;
-/** @group Number */
+/**
+ * Error returned when {@link between} rejects a number.
+ *
+ * @group Number
+ */
 export interface BetweenError<Min extends number = number, Max extends number = number> extends TypeError<`Between${Min}-${Max}`> {
     readonly value: number;
     readonly min: Min;
@@ -2894,7 +3278,11 @@ export interface BetweenError<Min extends number = number, Max extends number =
  * @group Collection
  */
 export declare const array: <ElementType extends ConcreteTypeNode>(element: ValidateElement<ElementType>) => ArrayType<ElementType>;
-/** @group Collection */
+/**
+ * The homogeneous readonly-array {@link Type} returned by {@link array}.
+ *
+ * @group Collection
+ */
 export interface ArrayType<ElementType extends TypeNode> extends Type<"Array", ReadonlyArray<ElementType["Input"]>, ReadonlyArray<ElementType["Output"]>, ArrayNodeError<ElementType>, ArrayParent<ElementType>, ArrayError<InferErrors<ElementType>>, ArrayCustomFrom<ElementType>, ReadonlyArray<CanonicalInputOf<ElementType>>, AllTypesUseIdentityEncoding<ElementType>> {
     readonly [reflectedTypesSymbol]?: ElementType;
     readonly element: ElementType;
@@ -2915,42 +3303,78 @@ type ArrayParent<ElementType extends TypeNode> = [
 type ArrayNodeError<ElementType extends TypeNode> = [
     ElementType["parent"]
 ] extends [TypeNode] ? ArrayElementsError<ElementType["Error"]> : ArrayError<ElementType["Error"]>;
-/** @group Collection */
+/**
+ * Error returned by {@link array} for a non-array value or invalid array items.
+ *
+ * @group Collection
+ */
 export type ArrayError<Error extends TypeError = TypeError> = ArrayNotArrayError | ArrayItemsErrorValue<Error, true>;
-/** @group Collection */
+/**
+ * Error returned when an {@link array} input is not an array.
+ *
+ * @group Collection
+ */
 export interface ArrayNotArrayError extends TypeError<"Array"> {
     readonly reason: {
         readonly kind: "NotArray";
         readonly value: unknown;
     };
 }
-/** @group Collection */
+/**
+ * An {@link array} error containing structural or element issues.
+ *
+ * @group Collection
+ */
 export type ArrayItemsError<Error extends TypeError> = ArrayItemsErrorValue<Error, true>;
-/** @group Collection */
+/**
+ * One structural or element issue found by {@link array}.
+ *
+ * @group Collection
+ */
 export type ArrayIssue<Error extends TypeError> = ArrayStructuralIssue | ArrayElementIssue<Error>;
-/** @group Collection */
+/**
+ * A missing array element.
+ *
+ * @group Collection
+ */
 export interface ArrayHoleIssue {
     readonly kind: "Hole";
     readonly index: number;
 }
-/** @group Collection */
+/**
+ * An array element defined by an accessor instead of a data property.
+ *
+ * @group Collection
+ */
 export interface ArrayAccessorIssue {
     readonly kind: "Accessor";
     readonly index: number;
 }
-/** @group Collection */
+/**
+ * An own array property other than `length` or an indexed element.
+ *
+ * @group Collection
+ */
 export interface ArrayExcessPropertyIssue {
     readonly kind: "ExcessProperty";
     readonly key: string | symbol;
 }
 type ArrayStructuralIssue = ArrayHoleIssue | ArrayAccessorIssue | ArrayExcessPropertyIssue;
-/** @group Collection */
+/**
+ * An invalid array element and its index.
+ *
+ * @group Collection
+ */
 export type ArrayElementIssue<Error extends TypeError> = Error extends TypeError ? {
     readonly kind: "Element";
     readonly index: number;
     readonly error: Error;
 } : never;
-/** @group Collection */
+/**
+ * An {@link array} error containing element errors from a typed boundary.
+ *
+ * @group Collection
+ */
 export type ArrayElementsError<Error extends TypeError> = [Error] extends [
     never
 ] ? never : ArrayItemsErrorValue<Error, false>;
@@ -2968,10 +3392,25 @@ interface ArrayItemsErrorValue<Error extends TypeError, IncludeStructuralIssues
  * 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 declare const set: <ElementType extends ConcreteTypeNode>(element: ValidateElement<ElementType>) => SetType<ElementType>;
-/** @group Collection */
+/**
+ * The homogeneous readonly-set {@link Type} returned by {@link set}.
+ *
+ * @group Collection
+ */
 export interface SetType<ElementType extends TypeNode> extends Type<"Set", ReadonlySet<ElementType["Input"]>, ReadonlySet<ElementType["Output"]>, SetNodeError<ElementType>, SetParent<ElementType>, SetError<InferErrors<ElementType>>, SetCustomFrom<ElementType>, ReadonlySet<CanonicalInputOf<ElementType>>, AllTypesUseIdentityEncoding<ElementType>> {
     readonly [reflectedTypesSymbol]?: ElementType;
     readonly element: ElementType;
@@ -2991,9 +3430,18 @@ type SetParent<ElementType extends TypeNode> = [ElementType["parent"]] extends [
 type SetNodeError<ElementType extends TypeNode> = [
     ElementType["parent"]
 ] extends [TypeNode] ? SetElementsError<ElementType["Error"]> : SetError<ElementType["Error"]>;
-/** @group Collection */
+/**
+ * Error returned by {@link set} for a non-Set value, an invalid Set prototype,
+ * or invalid Set items.
+ *
+ * @group Collection
+ */
 export type SetError<Error extends TypeError = TypeError> = SetNotSetError | SetUnexpectedPrototypeError | SetItemsErrorValue<Error, true>;
-/** @group Collection */
+/**
+ * Error returned when a {@link set} input is not a Set.
+ *
+ * @group Collection
+ */
 export interface SetNotSetError extends TypeError<"Set"> {
     readonly reason: {
         readonly kind: "NotSet";
@@ -3011,21 +3459,37 @@ export interface SetUnexpectedPrototypeError extends TypeError<"Set"> {
         readonly value: ReadonlySet<unknown>;
     };
 }
-/** @group Collection */
+/**
+ * An own property found on a Set value.
+ *
+ * @group Collection
+ */
 export interface SetExcessPropertyIssue {
     readonly kind: "ExcessProperty";
     readonly key: string | symbol;
 }
 type SetStructuralIssue = SetExcessPropertyIssue;
-/** @group Collection */
+/**
+ * An invalid Set element and its iteration index.
+ *
+ * @group Collection
+ */
 export type SetElementIssue<Error extends TypeError> = Error extends TypeError ? {
     readonly kind: "Element";
     readonly index: number;
     readonly error: Error;
 } : never;
-/** @group Collection */
+/**
+ * A {@link set} error containing structural or element issues.
+ *
+ * @group Collection
+ */
 export type SetItemsError<Error extends TypeError> = SetItemsErrorValue<Error, true>;
-/** @group Collection */
+/**
+ * A {@link set} error containing element errors from a typed boundary.
+ *
+ * @group Collection
+ */
 export type SetElementsError<Error extends TypeError> = [Error] extends [never] ? never : SetItemsErrorValue<Error, false>;
 interface SetItemsErrorValue<Error extends TypeError, IncludeStructuralIssues extends boolean> extends TypeError<"Set"> {
     readonly reason: {
@@ -3058,17 +3522,12 @@ interface SetItemsErrorValue<Error extends TypeError, IncludeStructuralIssues ex
  * ### Example
  *
  * ```ts
- * import { Number, String, ok, transform, tuple } from "@evolu/common";
- *
- * const NumberFromString = transform("NumberFromString", String, Number, {
- *   from: (value) => ok(globalThis.Number(value)),
- *   to: globalThis.String,
- * });
+ * import { Int64FromInt64String, String, tuple } from "@evolu/common";
  *
- * const Entry = tuple(String, NumberFromString);
+ * const Entry = tuple(String, Int64FromInt64String);
  *
- * expectOk(Entry.fromUnknown(["count", "1"]), ["count", 1]);
- * expectOk(Entry.from.parent(["count", "1"]), ["count", 1]);
+ * expectOk(Entry.fromUnknown(["count", "1"]), ["count", 1n]);
+ * expectOk(Entry.from.parent(["count", "1"]), ["count", 1n]);
  * ```
  *
  * @group Collection
@@ -3267,7 +3726,7 @@ type PlainObjectError = ObjectError<Readonly<Record<never, never>>, ObjectProper
  * values have their own Types, and {@link instanceOf} when an instance belongs
  * to the domain.
  *
- * @group Base Types
+ * @group Base
  */
 export declare const Object: Type<"Object", Readonly<Record<string, unknown>>, Readonly<Record<string, unknown>>, PlainObjectError, null, PlainObjectError, never, Readonly<Record<string, unknown>>>;
 /**
@@ -3300,20 +3759,13 @@ export declare const Object: Type<"Object", Readonly<Record<string, unknown>>, R
  *
  * ```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.
@@ -3322,7 +3774,7 @@ export declare const Object: Type<"Object", Readonly<Record<string, unknown>>, R
  *   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({
@@ -3334,11 +3786,10 @@ export declare const Object: Type<"Object", Readonly<Record<string, unknown>>, R
  * // 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
@@ -3382,7 +3833,11 @@ export declare const Object: Type<"Object", Readonly<Record<string, unknown>>, R
  * @group Objects
  */
 export declare const record: <KeyType extends ConcreteTypeNode, ValueType extends ConcreteTypeNode>(key: ValidateRecordKeyType<KeyType>, value: ValidateRecordValueType<ValueType>) => RecordType<KeyType, ValueType>;
-/** @group Objects */
+/**
+ * The {@link Type} returned by {@link record}.
+ *
+ * @group Objects
+ */
 export interface RecordType<KeyType extends TypeNode, ValueType extends TypeNode> extends Type<"Record", RecordShape<KeyType, ValueType, "Input">, RecordShape<KeyType, ValueType, "Output">, RecordNodeError<KeyType, ValueType>, RecordParent<KeyType, ValueType>, RecordError<InferErrors<KeyType>, InferErrors<ValueType>, RecordCollisionFor<KeyType>>, never, CanonicalInputSubset<RecordShape<KeyType, ValueType, "Input">, RecordShape<KeyType, ValueType, "CanonicalInput">>, AllTypesUseIdentityEncoding<KeyType | ValueType>> {
     readonly [reflectedTypesSymbol]?: KeyType | ValueType;
     readonly key: KeyType;
@@ -3412,16 +3867,28 @@ type ValidateRecordValueType<T extends ConcreteTypeNode> = IsUnion<T> extends fa
 type RecordKeyConcreteTypeError = CompileTimeError<"Type", "Record key must use one concrete Type node. Pass a Union Type node instead of a union of Type nodes.">;
 type RecordValueConcreteTypeError = CompileTimeError<"Type", "Record value must use one concrete Type node. Pass a Union Type node instead of a union of Type nodes.">;
 type RecordKeyStringTypeError = CompileTimeError<"Type", "Record key Type Input and Output must extend string.">;
-/** @group Objects */
+/**
+ * Error returned while validating a {@link record} and its entries.
+ *
+ * @group Objects
+ */
 export type RecordError<KeyError extends TypeError = TypeError, ValueError extends TypeError = TypeError, Collision extends RecordCollisionIssue = RecordCollisionIssue> = RecordNotRecordError | RecordNotPlainRecordError | RecordEntriesErrorValue<KeyError, ValueError, Collision | RecordAccessorIssue | RecordNonEnumerableIssue>;
-/** @group Objects */
+/**
+ * Error returned when a {@link record} input is not an object.
+ *
+ * @group Objects
+ */
 export interface RecordNotRecordError extends TypeError<"Record"> {
     readonly reason: {
         readonly kind: "NotRecord";
         readonly value: unknown;
     };
 }
-/** @group Objects */
+/**
+ * Error returned when a {@link record} input is not a plain object.
+ *
+ * @group Objects
+ */
 export interface RecordNotPlainRecordError extends TypeError<"Record"> {
     readonly reason: {
         readonly kind: "NotPlainRecord";
@@ -3438,9 +3905,17 @@ export interface RecordNotPlainRecordError extends TypeError<"Record"> {
  * @group Objects
  */
 export type RecordEntriesError<KeyError extends TypeError, ValueError extends TypeError, StructuralIssue extends RecordStructuralIssue = RecordCollisionIssue> = [KeyError | ValueError | StructuralIssue] extends [never] ? never : RecordEntriesErrorValue<KeyError, ValueError, StructuralIssue>;
-/** @group Objects */
+/**
+ * An invalid key, value, or property structure in a {@link record}.
+ *
+ * @group Objects
+ */
 export type RecordIssue<KeyError extends TypeError, ValueError extends TypeError, StructuralIssue extends RecordStructuralIssue = RecordCollisionIssue> = RecordKeyIssue<KeyError> | RecordValueIssue<ValueError> | StructuralIssue;
-/** @group Objects */
+/**
+ * A property-structure issue returned by {@link record}.
+ *
+ * @group Objects
+ */
 export type RecordStructuralIssue = RecordAccessorIssue | RecordCollisionIssue | RecordNonEnumerableIssue;
 /**
  * An accessor property rejected by {@link record}.
@@ -3460,19 +3935,31 @@ export interface RecordNonEnumerableIssue {
     readonly kind: "NonEnumerable";
     readonly key: string | symbol;
 }
-/** @group Objects */
+/**
+ * An invalid key and its source property key in a {@link record}.
+ *
+ * @group Objects
+ */
 export type RecordKeyIssue<Error extends TypeError> = Error extends TypeError ? {
     readonly kind: "Key";
     readonly key: string | symbol;
     readonly error: Error;
 } : never;
-/** @group Objects */
+/**
+ * An invalid value and its property key in a {@link record}.
+ *
+ * @group Objects
+ */
 export type RecordValueIssue<Error extends TypeError> = Error extends TypeError ? {
     readonly kind: "Value";
     readonly key: string | symbol;
     readonly error: Error;
 } : never;
-/** @group Objects */
+/**
+ * Two {@link record} keys that decode to the same output key.
+ *
+ * @group Objects
+ */
 export interface RecordCollisionIssue {
     readonly kind: "Collision";
     readonly key: string | symbol;
@@ -3563,48 +4050,38 @@ type ObjectProperty = ObjectProps[string];
  *
  * ```ts
  * import {
- *   Number,
+ *   Int64FromInt64String,
  *   String,
  *   object,
- *   ok,
- *   transform,
  *   type InferType,
- *   type Result,
  * } from "@evolu/common";
  *
- * const AgeFromString = transform("AgeFromString", String, Number, {
- *   from: (value) => ok(globalThis.Number(value)),
- *   to: globalThis.String,
- * });
- *
  * const User = object({
  *   name: String,
- *   age: AgeFromString,
+ *   loginCount: Int64FromInt64String,
  * });
  * interface User extends InferType<typeof User> {}
  *
  * // Validate an unknown value.
- * const userFromUnknown = User.fromUnknown({ name: "Ada", age: "42" });
+ * const userFromUnknown = User.fromUnknown({
+ *   name: "Ada",
+ *   loginCount: "42",
+ * });
  *
- * expectOk(userFromUnknown, { name: "Ada", age: 42 });
+ * expectOk(userFromUnknown, { name: "Ada", loginCount: 42n });
  *
  * // Validate the object and root property Types.
  * const userInput = User.parent.fromUnknown({
  *   name: "Ada",
- *   age: "42",
+ *   loginCount: "42",
  * });
- * expectOk(userInput, { name: "Ada", age: "42" });
+ * expectOk(userInput, { name: "Ada", loginCount: "42" });
  *
  * // Run the remaining property stages.
- * const userFromInput: Result<
- *   { readonly name: string; readonly age: number },
- *   never
- * > = User.from.parent(userInput.value);
+ * const userFromInput = User.from.parent(userInput.value);
  *
- * expectTypeOf(userFromInput).toEqualTypeOf<
- *   Result<{ readonly name: string; readonly age: number }, never>
- * >();
- * expectOk(userFromInput, { name: "Ada", age: 42 });
+ * expectOk(userFromInput, { name: "Ada", loginCount: 42n });
+ * expectTypeOf(userFromInput.value).toExtend<User>();
  * ```
  *
  * Note that TypeScript does not model an object's runtime prototype. This can
@@ -3652,6 +4129,7 @@ type ObjectProperty = ObjectProps[string];
  * @group Objects
  */
 export declare function object<const Props extends ObjectProps>(props: Props, ...validation: [ObjectValidationError<Props>] extends [never] ? [] : [ValidationFailure<ObjectValidationError<Props>>]): StrictObjectType<Props>;
+/** Creates an Object Type with additional record properties. */
 export declare function object<const Props extends ObjectProps, const Rest extends RecordTypeNode & ConcreteTypeNode>(props: Props, record: Rest, ...validation: [
     ObjectValidationError<Props> | ObjectRecordValidationError<Props, Rest>
 ] extends [never] ? [] : [
@@ -3693,7 +4171,11 @@ type ObjectRecordKeyTypeError = CompileTimeError<"Type", "Object Record key must
 type ObjectRecordInputTypeError = CompileTimeError<"Type", "Every declared property Type Input must extend the Object Record value Type Input.">;
 type ObjectRecordOutputTypeError = CompileTimeError<"Type", "Every declared property Type Output must extend the Object Record value Type Output.">;
 type ObjectRecordCanonicalInputTypeError = CompileTimeError<"Type", "Every declared property Type CanonicalInput must extend the Object Record value Type CanonicalInput.">;
-/** @group Objects */
+/**
+ * The {@link Type} returned by {@link object}.
+ *
+ * @group Objects
+ */
 export type ObjectType<Props extends ObjectProps, Rest extends ObjectRecordTypeNode | undefined = undefined> = Rest extends ObjectRecordTypeNode ? ObjectWithRecordType<Props, Rest> : StrictObjectType<Props>;
 type StrictObjectType<Props extends ObjectProps> = Type<"Object", StrictObjectShape<Props, "Input">, StrictObjectShape<Props, "Output">, [
     StrictObjectParents<Props>
@@ -3791,10 +4273,10 @@ export interface ObjectNotObjectError extends TypeError<"Object"> {
  *
  * Object Types accept a `null` prototype or a prototype whose own prototype is
  * `null`. This includes ordinary and cross-realm plain objects as well as
- * objects created from an immediate root prototype. Arrays, built-in objects,
- * class instances, and objects with deeper custom prototype chains return this
- * error instead of having their prototype or inherited state discarded.
- * `reason.value` is the rejected object.
+ * objects created from an immediate root prototype. Arrays, JavaScript built-in
+ * objects, class instances, and objects with deeper custom prototype chains
+ * return this error instead of having their prototype or inherited state
+ * discarded. `reason.value` is the rejected object.
  *
  * @group Objects
  */
@@ -3883,7 +4365,11 @@ type ObjectRestFromParentError<Rest extends ObjectRecordTypeNode | undefined> =
  * @group Objects
  */
 export declare const partial: <const Props extends ObjectProps>(props: Props, ..._validation: [ObjectValidationError<Props>] extends [never] ? [] : [ValidationFailure<ObjectValidationError<Props>>]) => ObjectType<PartialObjectProps<Props>>;
-/** @group Objects */
+/**
+ * Maps every required object property Type to an optional property.
+ *
+ * @group Objects
+ */
 export type PartialObjectProps<Props extends ObjectProps> = {
     readonly [Key in keyof Props]: Props[Key] extends OptionalProperty<TypeNode> ? Props[Key] : Props[Key] extends TypeNode ? OptionalProperty<Props[Key]> : never;
 };
@@ -3915,13 +4401,29 @@ export type PartialObjectProps<Props extends ObjectProps> = {
  * @group Objects
  */
 export declare const nullableToOptional: <const Props extends ObjectProps>(props: Props, ..._validation: [ObjectValidationError<Props>] extends [never] ? [] : [ValidationFailure<ObjectValidationError<Props>>]) => ObjectType<NullableToOptionalProps<Props>>;
-/** @group Objects */
+/**
+ * Maps object properties whose Union Type includes {@link Null} to optional
+ * properties.
+ *
+ * @group Objects
+ */
 export type NullableToOptionalProps<Props extends ObjectProps> = {
     readonly [Key in keyof Props]: Props[Key] extends OptionalProperty<TypeNode> ? Props[Key] : Props[Key] extends UnionType<infer Members> ? typeof Null extends Members[number] ? OptionalProperty<Props[Key]> : Props[Key] : Props[Key];
 };
 /**
  * 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 declare const omit: <const Props extends ObjectProps, const Keys extends ReadonlyArray<keyof Props>, Rest extends ObjectRecordTypeNode | undefined = undefined>(objectType: ObjectType<Props, Rest>, ...keys: Keys & ([ValidateOmitKeys<Keys>] extends [never] ? unknown : readonly [ValidationFailure<ValidateOmitKeys<Keys>>])) => ObjectType<Omit<Props, Keys[number]>, Rest>;
@@ -3931,10 +4433,10 @@ type ValidateOmitKeys<Keys extends ReadonlyArray<PropertyKey>> = number extends
 type OmitKeysTupleError = CompileTimeError<"Type", "Omitted keys must use one concrete finite tuple.">;
 type OmitKeyConcreteTypeError = CompileTimeError<"Type", "Each omitted key must be one concrete property key.">;
 /**
- * {@link Result} {@link Type} for typed success and error values.
+ * Creates a {@link Type} for {@link Result} values.
  *
  * Use this to validate Results crossing a storage, worker, API, or other
- * serialization boundary. The operation returns an outer validation Result. Its
+ * serialization boundary. `fromUnknown` returns an outer validation Result. Its
  * successful value is the inner domain Result described by `okType` and
  * `errorType`.
  *
@@ -3951,34 +4453,16 @@ type OmitKeyConcreteTypeError = CompileTimeError<"Type", "Each omitted key must
  *
  * const SyncResponse = result(
  *   object({ timestamp: NonNegativeInt }),
- *   typed("SyncError", { message: String }),
+ *   typed("SyncFailed", { message: String }),
  * );
  *
- * const describeResponse = (input: unknown): string => {
- *   const validated = SyncResponse.fromUnknown(input);
- *   if (!validated.ok) return "Invalid response";
- *
- *   const response = validated.value;
- *   return response.ok
- *     ? `Synced at ${response.value.timestamp}`
- *     : response.error.message;
- * };
+ * const validated = SyncResponse.fromUnknown({
+ *   ok: true,
+ *   value: { timestamp: 42 },
+ * });
  *
- * expect(
- *   describeResponse({
- *     ok: true,
- *     value: { timestamp: 42 },
- *   }),
- * ).toBe("Synced at 42");
- * expect(
- *   describeResponse({
- *     ok: false,
- *     error: { type: "SyncError", message: "Offline" },
- *   }),
- * ).toBe("Offline");
- * expect(describeResponse({ ok: true, value: { timestamp: -1 } })).toBe(
- *   "Invalid response",
- * );
+ * expectOk(validated, { ok: true, value: { timestamp: 42 } });
+ * expectOk(validated.value, { timestamp: 42 });
  * ```
  *
  * @group Results
@@ -4010,7 +4494,7 @@ export declare const UnknownResult: DiscriminatedUnionType<"ok", readonly [Stric
 }>]>;
 export type UnknownResult = typeof UnknownResult.Output;
 /**
- * Tagged {@link ObjectType}.
+ * Creates an {@link ObjectType} with a literal `type` property.
  *
  * The discriminator belongs to `typed`, so additional properties cannot declare
  * `type`. The discriminator Input is `string`, inherited from {@link String},
@@ -4022,35 +4506,38 @@ export type UnknownResult = typeof UnknownResult.Output;
  * ### Example
  *
  * ```ts
- * import { String, discriminatedUnion, typed } from "@evolu/common";
+ * import { String, typed } from "@evolu/common";
  *
  * const Pending = typed("Pending", {
  *   label: String,
  * });
  *
- * const Completed = typed("Completed");
- * const Status = discriminatedUnion(Pending, Completed);
- *
- * expectOk(Status.fromUnknown({ type: "Pending", label: "Waiting" }), {
+ * expectOk(Pending.fromUnknown({ type: "Pending", label: "Waiting" }), {
  *   type: "Pending",
  *   label: "Waiting",
  * });
- * expectOk(Status.fromUnknown({ type: "Completed" }), {
- *   type: "Completed",
- * });
  * ```
  *
  * @group Discriminated unions
  */
 export declare function typed<const Tag extends TypeName>(tag: ValidateTypedTag<Tag>): TypedType<Tag>;
+/** Creates a Tagged Object Type with declared properties. */
 export declare function typed<const Tag extends TypeName, const Props extends ObjectProps>(tag: ValidateTypedTag<Tag>, props: Props, ...validation: [TypedValidationError<Props>] extends [never] ? [] : [ValidationFailure<TypedValidationError<Props>>]): TypedType<Tag, Props>;
+/** Creates a Tagged Object Type with additional record properties. */
 export declare function typed<const Tag extends TypeName, const Props extends ObjectProps, const Rest extends RecordTypeNode & ConcreteTypeNode>(tag: ValidateTypedTag<Tag>, props: Props, record: Rest, ...validation: [
     TypedValidationError<Props> | ObjectRecordValidationError<TypedProps<Tag, Props>, Rest>
 ] extends [never] ? [] : [
     ValidationFailure<TypedValidationError<Props> | ObjectRecordValidationError<TypedProps<Tag, Props>, Rest>>
 ]): TypedType<Tag, Props, Rest extends ObjectRecordTypeNode ? Rest : never>;
 /**
- * A structurally tagged value created by {@link typed}.
+ * A TypeScript interface with a literal `type` property.
+ *
+ * Use `Typed` for both domain objects in discriminated unions and plain domain
+ * errors returned by {@link Result}. Name a domain error interface `XError`.
+ * When `X` already describes a failure, use `X` for its `type` discriminant
+ * because `Error` describes the interface's role rather than the runtime error
+ * kind. Keep `Error` when it is needed to make the discriminant unambiguous,
+ * such as `TimeoutError`.
  *
  * Typed unions model mutually exclusive states as separate variants instead of
  * combinations of flags and optional properties. TypeScript narrows a union by
@@ -4061,20 +4548,23 @@ export declare function typed<const Tag extends TypeName, const Props extends Ob
  * ### Example
  *
  * ```ts
- * import { type Typed } from "@evolu/common";
+ * import { err, ok, type Result, type Typed } from "@evolu/common";
  *
- * type Status = Typed<"Pending"> | Typed<"Completed">;
+ * interface User extends Typed<"User"> {
+ *   readonly id: string;
+ * }
  *
- * const getStatusMessage = (status: Status): string => {
- *   switch (status.type) {
- *     case "Pending":
- *       return "Waiting";
- *     case "Completed":
- *       return "Done";
- *   }
- * };
+ * const getUser = (id: string): Result<User, UserNotFoundError> =>
+ *   id === "user-1"
+ *     ? ok({ type: "User", id })
+ *     : err({ type: "UserNotFound", id });
+ *
+ * interface UserNotFoundError extends Typed<"UserNotFound"> {
+ *   readonly id: string;
+ * }
  *
- * expect(getStatusMessage({ type: "Pending" })).toBe("Waiting");
+ * expectOk(getUser("user-1"), { type: "User", id: "user-1" });
+ * expectErr(getUser("missing"), { type: "UserNotFound", id: "missing" });
  * ```
  *
  * @group Discriminated unions
@@ -4085,7 +4575,7 @@ export interface Typed<Tag extends TypeName> {
 /**
  * Extracts members of a {@link Typed} Output union by their `type` literal.
  *
- * The requested name is constrained to the union's actual discriminator values,
+ * The requested tag is constrained to the union's actual discriminator values,
  * so a misspelling is a TypeScript error instead of silently producing
  * `never`.
  *
@@ -4131,7 +4621,8 @@ type ConcreteTypedTagError = CompileTimeError<"Type", "Tag must be one concrete
 type TypedValidationError<Props extends ObjectProps> = "type" extends keyof Props ? TypedTypePropertyError : ObjectValidationError<Props>;
 type TypedTypePropertyError = CompileTimeError<"Type", 'Additional properties must not declare the reserved "type" property.'>;
 /**
- * Producer-result {@link Type} for value, error, or done outcomes.
+ * Creates a {@link Type} for producer Results with value, error, or done
+ * outcomes.
  *
  * The three outcomes are `Ok<Value>`, `Err<Error>`, and `Err<Typed<"Done"> & {
  * done: Done }>`. This keeps normal completion distinct from failure while
@@ -4144,7 +4635,7 @@ type TypedTypePropertyError = CompileTimeError<"Type", 'Additional properties mu
  *
  * const StringNextResult = nextResult(
  *   String,
- *   typed("ProducerError", { message: String }),
+ *   typed("ReadFailed", { message: String }),
  *   String,
  * );
  *
@@ -4168,7 +4659,7 @@ type TypedTypePropertyError = CompileTimeError<"Type", 'Additional properties mu
  * expect(
  *   describeNext({
  *     ok: false,
- *     error: { type: "ProducerError", message: "Offline" },
+ *     error: { type: "ReadFailed", message: "Offline" },
  *   }),
  * ).toBe("Error: Offline");
  * ```
@@ -4200,7 +4691,7 @@ export declare const UnknownNextResult: DiscriminatedUnionType<"ok", readonly [S
 }>]>;
 export type UnknownNextResult = typeof UnknownNextResult.Output;
 /**
- * Discriminated Union {@link Type}.
+ * Discriminated union {@link Type}.
  *
  * With no explicit key, the conventional `type` property created by
  * {@link typed} is used. Pass a key first to discriminate
@@ -4231,6 +4722,34 @@ export type UnknownNextResult = typeof UnknownNextResult.Output;
  * @group Discriminated unions
  */
 export declare function discriminatedUnion<const Members extends DiscriminatedUnionMembers>(...members: Members & DiscriminatedUnionValidation<"type", Members>): DiscriminatedUnionType<"type", Members>;
+/**
+ * Creates a Discriminated Union Type with an explicit discriminator key.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   Number,
+ *   String,
+ *   discriminatedUnion,
+ *   literal,
+ *   object,
+ * } from "@evolu/common";
+ *
+ * const Added = object({ kind: literal("added"), value: String });
+ * const Removed = object({ kind: literal("removed"), id: Number });
+ * const Event = discriminatedUnion("kind", Added, Removed);
+ *
+ * expectOk(Event.fromUnknown({ kind: "added", value: "Evolu" }), {
+ *   kind: "added",
+ *   value: "Evolu",
+ * });
+ * expectOk(Event.fromUnknown({ kind: "removed", id: 1 }), {
+ *   kind: "removed",
+ *   id: 1,
+ * });
+ * ```
+ */
 export declare function discriminatedUnion<const Key extends string, const Members extends DiscriminatedUnionMembers>(key: ValidateDiscriminatedUnionKey<Key>, ...members: Members & DiscriminatedUnionValidation<Key, Members>): DiscriminatedUnionType<Key, Members>;
 /**
  * The routed {@link Type} returned by {@link discriminatedUnion}.
@@ -4353,10 +4872,10 @@ type DiscriminatedUnionMemberConcreteTypeError = CompileTimeError<"Type", "Membe
 type DiscriminatedUnionPropertyError<Key extends string> = CompileTimeError<"Type", `Property "${Key}" must be a required String, Number, BigInt, or Boolean Literal Type in every member.`>;
 type DiscriminatedUnionDuplicateValueError<Key extends string, Expected extends DiscriminatedUnionLiteral> = CompileTimeError<"Type", `Duplicate value "${Expected}" at property "${Key}".`>;
 /**
- * Lazy {@link Type} for recursive definitions.
+ * Creates a lazy {@link Type} for recursive definitions.
  *
- * Lazy defers and caches a Type definition, allowing recursive data such as
- * trees and mutually recursive models.
+ * The definition is evaluated on first use and then cached, allowing recursive
+ * data such as trees and mutually recursive models.
  *
  * A recursive declaration refers to its own variable while that variable is
  * being initialized, so TypeScript cannot infer it reliably. Getter-based
@@ -4376,12 +4895,10 @@ type DiscriminatedUnionDuplicateValueError<Key extends string, Expected extends
  *
  * ```ts
  * import {
- *   Number,
  *   String,
  *   array,
  *   lazy,
  *   object,
- *   optional,
  *   type ArrayError,
  *   type LazyType,
  *   type ObjectError,
@@ -4402,35 +4919,19 @@ type DiscriminatedUnionDuplicateValueError<Key extends string, Expected extends
  *   () => object({ value: String, children: array(Tree) }),
  * );
  *
- * interface Left {
- *   readonly label: string;
- *   readonly right?: Right;
- * }
- *
- * interface Right {
- *   readonly count: number;
- *   readonly left?: Left;
- * }
- *
- * interface LeftError extends ObjectError<{
- *   readonly label: TypeOfError<"String">;
- *   readonly right?: RightError;
- * }> {}
- *
- * interface RightError extends ObjectError<{
- *   readonly count: TypeOfError<"Number">;
- *   readonly left?: LeftError;
- * }> {}
- *
- * const Left: LazyType<Left, Left, never, LeftError, LeftError> = lazy(
- *   () => object({ label: String, right: optional(Right) }),
- * );
+ * const result = Tree.fromUnknown({
+ *   value: "root",
+ *   children: [{ value: "leaf", children: [] }],
+ * });
  *
- * const Right: LazyType<Right, Right, never, RightError, RightError> =
- *   lazy(() => object({ count: Number, left: optional(Left) }));
+ * expectOk(result, {
+ *   value: "root",
+ *   children: [{ value: "leaf", children: [] }],
+ * });
+ * expectTypeOf(result.value).toEqualTypeOf<Tree>();
  * ```
  *
- * @group Recursive Types
+ * @group Recursive
  */
 export declare function lazy<Target extends ConcreteTypeNode>(getType: Thunk<ValidateLazyTarget<Target>>): LazyType<Target["Input"], Target["Output"], TypeFromError<Target>, InferErrors<RootType<Target>>, InferErrors<Target>, CanonicalInputOf<Target>, IdentityEncodingOf<Target>>;
 /**
@@ -4448,7 +4949,7 @@ export declare function lazy<Target extends ConcreteTypeNode>(getType: Thunk<Val
  * recursive declaration finite for TypeScript while preserving structured
  * errors at every boundary.
  *
- * @group Recursive Types
+ * @group Recursive
  */
 export interface LazyType<in out Input, in out Output, in out FromError extends TypeError, in out InputError extends TypeError, in out Errors extends TypeError, in out CanonicalInput extends Input = Input, in out UsesIdentityEncoding extends boolean = true> extends Type<"Lazy", Input, Output, FromError, Type<"Lazy", Input, Input, InputError, null, InputError, never, Input>, Errors, never, CanonicalInput, UsesIdentityEncoding> {
     readonly [lazyTypeSymbol]: true;
@@ -4504,7 +5005,7 @@ export interface JsonObject {
     readonly [key: string]: JsonValue;
 }
 /**
- * One issue found while validating an exact {@link JsonValue}.
+ * One issue found while validating a candidate as an exact {@link JsonValue}.
  *
  * @group JSON
  */
@@ -4542,7 +5043,8 @@ export type JsonValueIssue = {
     readonly ancestorPath: ReadonlyArray<string | number | symbol>;
 };
 /**
- * An error containing one or more issues found in a {@link JsonValue}.
+ * An error containing one or more issues found while validating a candidate as
+ * an exact {@link JsonValue}.
  *
  * @group JSON
  */
@@ -4580,6 +5082,21 @@ export interface JsonError extends TypeError<"Json"> {
 /**
  * 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 declare const JsonValue: JsonValueType;
@@ -4599,7 +5116,7 @@ export declare const JsonObject: JsonObjectType;
  * 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
@@ -4607,88 +5124,100 @@ export declare const JsonObject: JsonObjectType;
 export declare const Json: BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "Json", JsonError>;
 export type Json = typeof Json.Output;
 /**
- * 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 declare const jsonToJsonValue: (value: Json) => JsonValue;
 /**
- * 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 declare const jsonValueToJson: (value: JsonValue) => Json;
 /**
- * {@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 declare const JsonValueFromJson: TransformType<BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "Json", JsonError>, JsonValueType, "JsonValueFromJson", never, string & Brand<"Json">>;
 /**
- * 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 person = Person.orThrow({ name: "Ada", age: 42 });
- * const personJson = personToPersonJson(person);
- * const decodedPerson = personJsonToPerson(personJson);
+ * const user = User.orThrow({ name: "Ada", age: 37 });
+ * const userJson = userToUserJson(user);
  *
- * 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 declare const json: <T extends ConcreteTypeNode, Name extends TypeName>(type: T, name: ValidateChildTypeName<Name, typeof Json>, ..._validation: [JsonTypeValidationError<T>] extends [never] ? [] : [ValidationFailure<JsonTypeValidationError<T>>]) => readonly [jsonType: BrandType<typeof Json, Name, TypeError<Name> & TransparentTypeError & {