@evolu/common 8.1.0 → 8.3.0

package/dist/src/Type.js

@@ -1,5 +1,328 @@
 /**
- * Runtime types.
+ * ## Intro
+ *
+ * Runtime validation with precise TypeScript types and structured errors.
+ *
+ * Evolu {@link Type} is a pure, synchronous codec for defining semantic domains.
+ * It partially decodes an `Input` into an `Output` and totally encodes every
+ * valid `Output` into a `CanonicalInput`. Types can validate, refine,
+ * transform, and compose without losing the contracts TypeScript can express.
+ *
+ * ```ts
+ * import {
+ *   NonEmptyTrimmedString100,
+ *   PositiveInt,
+ *   object,
+ *   type InferType,
+ * } from "@evolu/common";
+ *
+ * const User = object({
+ *   name: NonEmptyTrimmedString100,
+ *   age: PositiveInt,
+ * });
+ * interface User extends InferType<typeof User> {}
+ *
+ * const value: unknown = { name: "Ada", age: 37 };
+ * const user = User.fromUnknown(value);
+ *
+ * expectOk(user, { name: "Ada", age: 37 });
+ * expectTypeOf(user.value).toExtend<User>();
+ * ```
+ *
+ * Decoding failures are explicit {@link Result} values. Error formatters are
+ * separate from validation, so structured errors remain exhaustively typed and
+ * can be localized without changing the Type.
+ *
+ * Evolu Type is designed to make correct code the easiest code to write:
+ *
+ * - {@link Brand} carries every refinement constraint into TypeScript.
+ * - Invalid declarations produce readable {@link CompileTimeError} types when the
+ *   compiler can detect them; runtime assertions enforce construction contracts
+ *   it cannot prove.
+ * - Typed `from` boundaries allow connecting value producers to domain fields
+ *   through their exact TypeScript types, so incompatible contract changes are
+ *   compile-time errors rather than runtime validation errors.
+ * - Lawful codecs compose without creating unencodable values: every valid
+ *   Output has a canonical Input representation and round-trips to the same
+ *   semantic value.
+ * - Type-safe localization infers the required error formatters from selected
+ *   Types, so missing validation messages are compile-time errors.
+ *
+ * Correctness is especially important for local-first data: application authors
+ * cannot inspect or repair a user's data on a server. Type declarations reject
+ * invalid data at system boundaries, then preserve those guarantees wherever
+ * the data travels.
+ *
+ * Evolu Type supports [Standard Schema](https://standardschema.dev/) while
+ * preserving each Type's exact Input and Output. Its implementation is
+ * optimized for small bundles, but keeps actionable assertion messages as a
+ * deliberate developer-experience tradeoff.
+ *
+ * Evolu Type requires TypeScript 7 or newer and `exactOptionalPropertyTypes`.
+ * Predefined Types use the names of corresponding JavaScript built-ins. When
+ * one shadows a built-in, access the built-in through `globalThis`, such as
+ * `globalThis.String` or `globalThis.Date`.
+ *
+ * ## Boundaries
+ *
+ * `fromUnknown` validates untyped input through the complete pipeline. `from`
+ * and its `.parent` operations assert their declared boundary, then return only
+ * errors from the remaining stages. `orThrow` and `orNull` reuse the deepest
+ * `from` operation accepting `Input`, while `to` asserts its Output boundary. A
+ * failed assertion is a developer error; its cause preserves the exact
+ * structured Output validation error.
+ *
+ * Prefer the most precise typed boundary available. A value is not unknown
+ * merely because it originated outside the application: forms, components, and
+ * other producers often expose a `string` or a branded value that can connect
+ * directly to a matching `from` boundary. Reserve `fromUnknown` for values
+ * whose TypeScript type is genuinely `unknown`. `is` means exact membership in
+ * the Output domain, not merely that an encoded Input can be decoded.
+ *
+ * Typed boundaries also connect producer and domain constraints at compile
+ * time. Suppose a form and its domain field both use
+ * {@link NonEmptyTrimmedString100}. If the form is later relaxed to
+ * {@link NonEmptyTrimmedString1000}, the domain Type will still reject longer
+ * values, so invalid data cannot be stored. But a boundary accepting only
+ * `unknown` or `string` cannot reveal that the producer contract changed. The
+ * application still compiles, and users discover the incompatibility only when
+ * a valid form value fails to save.
+ *
+ * Passing the precise branded value to `from` makes that incompatibility a
+ * compile-time error. The developer must preserve the original form limit or
+ * introduce a new field for the wider domain instead of shipping a broken form.
+ *
+ * A weaker producer is sometimes intentional. In that case, a matching
+ * `.parent` boundary validates only the constraints the producer does not
+ * already guarantee, while preserving its existing guarantees in the type.
+ *
+ * ## FAQ
+ *
+ * ### What does a Type represent?
+ *
+ * A Type is a lawful, pure codec for an exact semantic domain:
+ *
+ * ```text
+ * Input           ── partial decode ──▶ Output
+ * CanonicalInput  ◀─── total encode ─── Output
+ *
+ * CanonicalInput ⊆ Input
+ * ```
+ *
+ * Read each line in the direction of its arrowhead. `Input` is the complete
+ * typed decoding boundary, including candidates that validation can reject and
+ * noncanonical representations that decoding can normalize. `Output` is the
+ * validated semantic value. `CanonicalInput` is the statically known subtype of
+ * `Input` returned by the complete `to` operation. It can be wider than the
+ * values actually emitted when a refinement follows an arbitrary transformation
+ * because TypeScript cannot determine which values its encoder returns for the
+ * narrowed Output. `fromUnknown` and the `from` operations decode; `to`
+ * encodes.
+ *
+ * A lawful Type round-trips every Output:
+ *
+ * ```text
+ * fromUnknown(to(output)) ≈ ok(output)
+ * ```
+ *
+ * Encoding can canonicalize a valid Input:
+ *
+ * ```text
+ * "0042" ──decode──▶ 42 ──encode──▶ "42"
+ * ```
+ *
+ * Once canonicalized, repeating the decode-encode cycle must preserve that
+ * representation:
+ *
+ * ```text
+ * "42" ──decode──▶ 42 ──encode──▶ "42"
+ * ```
+ *
+ * Here `decode` means running the complete decoding pipeline, as `fromUnknown`
+ * does, and `≈` means equality appropriate for the semantic domain. Validation
+ * refinements, {@link ArrayType | Array Types}, and
+ * {@link ObjectType | Object Types} preserve these laws when their contained
+ * Types do. A {@link union} additionally requires compatible dispatch: it
+ * encodes through the first member matching the Output and decodes through the
+ * first member accepting the Input. Member ordering is lawful only when those
+ * choices agree semantically. Encoded representations can overlap even when
+ * member Output types are disjoint.
+ *
+ * When encoding returns a refined value unchanged, the refinement can narrow
+ * `CanonicalInput` without changing its JavaScript representation. For example,
+ * {@link FiniteNumber} has `number` as its Input, while its Output and
+ * CanonicalInput are `FiniteNumber`: decoding can reject non-finite number
+ * candidates, and encoding only receives validated finite Outputs. A
+ * transformation can change the representation entirely. For
+ * {@link Int64FromInt64String}, Input is `string`, Output is `Int64`, and
+ * CanonicalInput is `Int64String`. Structural Type factories derive their
+ * CanonicalInput recursively from their contained Types.
+ *
+ * ### Why is to total?
+ *
+ * Suppose a Type accepts only strings containing decimal digits and decodes
+ * them to JavaScript numbers. Parsing `"42"` is possible, but the Type cannot
+ * lawfully declare its Output as `number`:
+ *
+ * ```text
+ * digits-only string ──partial decode──▶ number
+ * digits-only string ◀─── total encode ── number  // impossible
+ * ```
+ *
+ * `number` also contains negative and fractional numbers, `NaN`, positive and
+ * negative infinity, and `-0`. None of those values has a digits-only
+ * representation, so `to` could not encode every valid Output.
+ *
+ * One lawful design narrows the Output to the exact representable domain:
+ *
+ * ```text
+ * digits-only string ──partial decode──▶ NonNegativeSafeInteger
+ * digits-only string ◀─── total encode ── NonNegativeSafeInteger
+ *
+ * "0042" ──decode──▶ 42 ──encode──▶ "42"
+ * ```
+ *
+ * Another lawful design keeps `number` as the Output but expands the Input
+ * representation to include a canonical string for every number, including
+ * `"NaN"`, `"Infinity"`, `"-Infinity"`, and `"-0"`, as well as negative and
+ * fractional numbers.
+ *
+ * The same principle applies when converting between two representations. Give
+ * each representation its own Type with the same exact Output. For example, a
+ * string representation and a number representation can both decode to the
+ * shared `SafeInteger` domain:
+ *
+ * ```text
+ * string ──partial decode──▶ SafeInteger
+ * string ◀─── total encode ── SafeInteger
+ *
+ * number ──partial decode──▶ SafeInteger
+ * number ◀─── total encode ── SafeInteger
+ * ```
+ *
+ * Conversion decodes the source representation, then total-encodes the shared
+ * Output into the target representation. If no lossless shared domain exists,
+ * the operation is a partial conversion, migration, or policy decision and
+ * should be an explicit function returning Result, not a Type transformation.
+ *
+ * ### Why can a typed operation throw?
+ *
+ * TypeScript proves structural assignability, but it cannot describe every
+ * runtime invariant. For example, it cannot express whether an object property
+ * is own, enumerable, or a data property. It also permits a wider object with
+ * excess properties where a narrower object type is expected.
+ *
+ * `fromUnknown` treats such invalid external values as input data and returns a
+ * typed error. Typed boundaries instead assert the domain promised by their
+ * parameter type. If application code claims an accessor-backed object or an
+ * object with excess properties is an Object Output, the assertion throws
+ * because the application contract is broken. `orThrow` and `orNull` preserve
+ * the assertion at their typed `Input` boundary, then apply {@link getOrThrow}
+ * or {@link getOrNull} only to validation failures returned by the remaining
+ * pipeline.
+ *
+ * Consequently, structural representation errors such as sparse Arrays,
+ * accessors, and excess properties normally do not enter user-facing validation
+ * in typed application flows. They violate the producer's declared contract and
+ * throw as developer errors. At a genuinely unknown boundary, such as a
+ * schema-authoring tool, import, or external protocol, the same issues are
+ * legitimate typed validation errors and their formatter messages are useful.
+ *
+ * This distinction applies to data failures. Any Type operation, including
+ * `fromUnknown`, can throw when trusted Type-declaration code, such as a
+ * successful transformation callback, violates its declared contract.
+ *
+ * Materialize accessor values into plain data, remove properties the Type does
+ * not represent, or use a different Type. Silently discarding excess data would
+ * make the code constructing it dead while appearing to encode it successfully.
+ * One exact Object policy also keeps Output membership independent of parsing
+ * configuration. Exact structural policies also keep Output membership
+ * independent of whether a transformation happens to allocate a new value.
+ * Evolu Type therefore does not invoke accessors, discard excess properties, or
+ * make `to` fallible. This keeps `to` total for every legitimate Output and
+ * lets transformations compose without an encoding-error channel.
+ *
+ * ### How should values from another realm be handled?
+ *
+ * Code trust and data validation are separate decisions. Values returned by
+ * trusted legacy code or another realm can still be uncertain and should be
+ * validated. Realm-neutral Types accept an otherwise legitimate representation
+ * without requiring conversion merely because its built-ins belong to another
+ * realm.
+ *
+ * When an application trusts both the producer and its return contract, expose
+ * that contract as an accurate TypeScript type and use the typed value directly.
+ * If the boundary returns `unknown`, validate it instead of bypassing the
+ * boundary with a cast. Use a specialized Type or explicit transformation when
+ * the producer uses a different representation that needs adaptation or
+ * normalization.
+ *
+ * All executing JavaScript remains trusted. Deliberately forged built-ins,
+ * hostile Proxies, throwing traps, or sabotaged executable behavior can throw;
+ * Evolu Type does not selectively contain them or claim to be a security
+ * boundary for untrusted code.
+ *
+ * ### Why doesn't Evolu Type extract data from rich objects?
+ *
+ * Some validation libraries parse an object's data projection. An imaginary
+ * validation library can enumerate own enumerable string properties and decode
+ * them into a fresh plain object. That lets a class instance decode as plain
+ * data while its prototype and methods are ignored. The same general policy can
+ * treat a `Date` or `Map` as an empty Record and can invoke enumerable getters.
+ * This is a coherent but intentionally forgiving normalization model.
+ *
+ * Evolu Type validates exactly the runtime representation defined by each Type;
+ * it does not implicitly project one representation into another. The
+ * predefined {@link Object} defines an open plain-object representation with
+ * unknown values, {@link object} defines a closed plain-object representation,
+ * and {@link record} defines a plain-dictionary representation whose complete
+ * set of own properties are its entries. Their realm-neutral plain-object rule
+ * accepts a `null` prototype or an immediate root prototype whose own prototype
+ * is `null`; ordinary class instances and deeper prototype chains are rejected.
+ * Every property must be an enumerable data property; inherited members are not
+ * entries, while accessors and hidden properties are invalid instead of being
+ * invoked or ignored. {@link array} similarly defines a dense sequence whose
+ * only own properties are `length` and its indexed data properties;
+ * {@link tuple} applies the same representation rules with a fixed length and a
+ * distinct Type for each position. Only an explicit {@link transform} changes
+ * the representation. Consequently, `is` tests exact Output membership and `to`
+ * stays total for valid Outputs.
+ *
+ * ### Why is JsonValue stricter than JSON.stringify?
+ *
+ * `JSON.stringify` is a forgiving data projection. It can invoke `toJSON` and
+ * accessors, discard object properties, replace unsupported array elements and
+ * non-finite numbers with `null`, and normalize `-0` to `0`. Those rules are
+ * useful for ordinary serialization, but they do not preserve an exact value.
+ *
+ * {@link JsonValue} instead defines data that is already represented as data.
+ * Invalid runtime behavior and values are rejected rather than interpreted or
+ * silently discarded. Its encoder is total and stack-safe for every valid
+ * Output, and {@link JsonValueFromJson} preserves the semantic value when it is
+ * encoded and decoded, including JavaScript's distinction between `-0` and `0`.
+ * Use an explicit transformation before this boundary when a projection or
+ * other normalization is desired.
+ *
+ * ### Why are Types pure and synchronous?
+ *
+ * A Type describes data meaning, not work. Time, I/O, dependencies, external
+ * state, authorization, and other contextual decisions belong in a {@link Task}.
+ * Use a Type to decode the data required by that work, then pass the decoded
+ * value to a Task. A pure synchronous conversion that can fail can be an
+ * ordinary function returning Result.
+ *
+ * Keeping those responsibilities separate prevents Evolu Type from becoming a
+ * hidden application workflow. It also keeps validation deterministic,
+ * dependency-free, immediately composable, and straightforward to test.
+ *
+ * ### What if only decoding is needed?
+ *
+ * Use `fromUnknown` for unknown data. For typed application data, call `from`
+ * at the boundary its input type proves, or use `orThrow` or `orNull` for a
+ * flat conversion from `Input`. The canonical `to` encoder still keeps the Type
+ * lawful and composable with transformations and structural Types. A genuinely
+ * irreversible operation is a separate function or Task, not a Type
+ * transformation.
  *
  * @module
  */
@@ -50,7 +373,7 @@ const formatDefaultRuntimeTypeIssue = (issue) => issue.formatError(issue.error);
  * Asserts that a value belongs to a {@link Type} Output domain.
  *
  * Use this for internal invariants, not external input. Validate external input
- * with `Type.fromUnknown` so expected failures remain typed values. A failed
+ * with `Type.fromUnknown` so validation failures remain typed values. A failed
  * assertion uses the Type name for its message and preserves the exact Output
  * validation error as the thrown Error's cause.
  *
@@ -70,7 +393,7 @@ const formatDefaultRuntimeTypeIssue = (issue) => issue.formatError(issue.error);
  * >();
  * ```
  *
- * @group Core Types
+ * @group Core
  */
 export const assertType = (type, value) => {
     // TODO: Make assert prepend "Expected " and accept an optional third cause
@@ -90,34 +413,32 @@ const assertTypeOutput = (name, is, validateOutput, value, options = firstValida
     throw new Error(`Expected ${name}.`, { cause: error });
 };
 /**
- * Creates localized copies of selected {@link Type | Types} 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
  *
@@ -127,7 +448,7 @@ const assertTypeOutput = (name, is, validateOutput, value, options = firstValida
  *
  * const Label = minLength(1)(String);
  *
- * const TypesByLocale = localizeTypes(
+ * const typesByLocale = localizeTypes(
  *   { Label },
  *   {
  *     cs: {
@@ -137,11 +458,66 @@ const assertTypeOutput = (name, is, validateOutput, value, options = firstValida
  *   },
  * );
  *
- * expectTypeOf<typeof TypesByLocale.cs.Label>().toEqualTypeOf<
+ * expectTypeOf<typeof typesByLocale.cs.Label>().toEqualTypeOf<
  *   typeof Label
  * >();
+ *
+ * const result = typesByLocale.cs.Label.fromUnknown("");
+ * expectErr(result, { type: "MinLength1", min: 1, value: "" });
+ * expect(typesByLocale.cs.Label.formatError(result.error)).toBe(
+ *   "Text nesmí být prázdný.",
+ * );
  * ```
  *
+ * ### Supported locales
+ *
+ * English is built in; use {@link Type} directly for its default formatters.
+ * The following additional locales are available:
+ *
+ * - Arabic (`ar`)
+ * - Bengali (`bn`)
+ * - Catalan (`ca`)
+ * - Chinese, Simplified (`zhCN`)
+ * - Chinese, Traditional (`zhTW`)
+ * - Croatian (`hr`)
+ * - Czech (`cs`)
+ * - Danish (`da`)
+ * - Dutch (`nl`)
+ * - Filipino (`fil`)
+ * - Finnish (`fi`)
+ * - French (`fr`)
+ * - German (`de`)
+ * - Greek (`el`)
+ * - Hebrew (`he`)
+ * - Hindi (`hi`)
+ * - Hungarian (`hu`)
+ * - Indonesian (`id`)
+ * - Italian (`it`)
+ * - Japanese (`ja`)
+ * - Korean (`ko`)
+ * - Malay (`ms`)
+ * - Malayalam (`ml`)
+ * - Marathi (`mr`)
+ * - Norwegian Bokmål (`nb`)
+ * - Persian (`fa`)
+ * - Polish (`pl`)
+ * - Portuguese (`pt`)
+ * - Portuguese, Brazilian (`ptBR`)
+ * - Punjabi (`pa`)
+ * - Romanian (`ro`)
+ * - Slovak (`sk`)
+ * - Slovenian (`sl`)
+ * - Spanish (`es`)
+ * - Swahili (`sw`)
+ * - Swedish (`sv`)
+ * - Tamil (`ta`)
+ * - Telugu (`te`)
+ * - Thai (`th`)
+ * - Turkish (`tr`)
+ * - Ukrainian (`uk`)
+ * - Urdu (`ur`)
+ * - Vietnamese (`vi`)
+ *
  * @group Localization
  */
 export const localizeTypes = ((typesByName, formatErrorByTypeByLocale) => {
@@ -341,6 +717,8 @@ const encoderSymbol =
 /*#__PURE__*/ globalThis.Symbol();
 const fromSymbol = 
 /*#__PURE__*/ globalThis.Symbol();
+const templateLiteralSyntaxSymbol = 
+/*#__PURE__*/ globalThis.Symbol();
 const mapRuntimeResult = (operation, map) => (value, options = firstValidationOptions) => map(operation(value, options), options);
 // `map` must return a fresh operation because this function can attach `.parent`.
 const mapRuntimeOperations = (operation, map) => {
@@ -433,9 +811,17 @@ const addRuntimeAssertions = (name, is, validateOutput, parent, operation) => {
     }
     return asserted;
 };
-/** @group Base Types */
+/**
+ * An infallible {@link Type} accepting every value.
+ *
+ * @group Base
+ */
 export const Unknown = /*#__PURE__*/ createRootType("Unknown", ok, identity);
-/** @group Base Types */
+/**
+ * A {@link Type} rejecting every value.
+ *
+ * @group Base
+ */
 export const Never = /*#__PURE__*/ createRootType("Never", (value) => err({ type: "Never", value }), (error) => `A value ${safelyStringifyUnknownValue(error.value)} is not valid for type Never.`);
 const createTypeOfType = (name) => {
     const typeOf = name.toLowerCase();
@@ -466,6 +852,8 @@ const createTypeOfType = (name) => {
  * expectTypeOf<WireValue100>().toEqualTypeOf<
  *   string & Brand<"MaxLength100">
  * >();
+ * expectOk(WireValue100.fromUnknown(""), "");
+ * expectOk(WireValue100.fromUnknown(" value "), " value ");
  * ```
  *
  * @group String
@@ -540,36 +928,52 @@ export const String = /*#__PURE__*/ createTypeOfType("String");
  * @group Number
  */
 export const Number = /*#__PURE__*/ createTypeOfType("Number");
-/** @group Base Types */
+/**
+ * A JavaScript bigint {@link Type}.
+ *
+ * @group Base
+ */
 export const BigInt = /*#__PURE__*/ createTypeOfType("BigInt");
-/** @group Base Types */
+/**
+ * A JavaScript boolean {@link Type}.
+ *
+ * @group Base
+ */
 export const Boolean = /*#__PURE__*/ createTypeOfType("Boolean");
-/** @group Base Types */
+/**
+ * A JavaScript symbol {@link Type}.
+ *
+ * @group Base
+ */
 export const Symbol = /*#__PURE__*/ createTypeOfType("Symbol");
-/** @group Base Types */
+/**
+ * A JavaScript function {@link Type}.
+ *
+ * @group Base
+ */
 export const Function = /*#__PURE__*/ createTypeOfType("Function");
 /**
- * An Evolu {@link Type} validating other Evolu Types.
+ * A {@link Type} validating Evolu Type declarations.
  *
  * This is useful when a Type itself crosses an unknown boundary or must be
  * asserted with {@link assertType}.
  *
- * @group Core Types
+ * @group Core
  */
 export const EvoluType = /*#__PURE__*/ createType("EvoluType", (value) => isInstance("Type")(value)
     ? ok(value)
     : err({ type: "EvoluType", value }), (error) => `A value ${safelyStringifyUnknownValue(error.value)} is not an Evolu Type.`);
 export function objectTag(name, outputType) {
+    const formatError = (error) => `A value ${safelyStringifyUnknownValue(error.value)} does not have the expected object tag ${safelyStringifyUnknownValue(error.expected)}.`;
     if (outputType === undefined) {
         return createRootType(name, (value) => hasObjectTag(value, name)
             ? ok(value)
-            : err({ type: "ObjectTag", expected: name, value }), formatObjectTagError);
+            : err({ type: "ObjectTag", expected: name, value }), formatError);
     }
     return globalThis.Object.assign(createChildType("ObjectTag", outputType, (value) => hasObjectTag(value, name)
         ? ok(value)
-        : err({ type: "ObjectTag", expected: name, value }), formatObjectTagError), { expected: name });
+        : err({ type: "ObjectTag", expected: name, value }), formatError), { expected: name });
 }
-const formatObjectTagError = (error) => `A value ${safelyStringifyUnknownValue(error.value)} does not have the object tag ${safelyStringifyUnknownValue(error.expected)}.`;
 const hasObjectTag = (value, expected) => value !== null &&
     (typeof value === "object" || typeof value === "function") &&
     globalThis.Object.prototype.toString.call(value) === `[object ${expected}]`;
@@ -578,7 +982,7 @@ const hasObjectTag = (value, expected) => value !== null &&
  *
  * It trusts the reported object tag and does not verify Date internal slots.
  *
- * @group Base Types
+ * @group Base
  */
 export const Date = /*#__PURE__*/ objectTag("Date");
 /**
@@ -587,7 +991,7 @@ export const Date = /*#__PURE__*/ objectTag("Date");
  * It trusts the reported object tag and does not verify Uint8Array internal
  * slots.
  *
- * @group Base Types
+ * @group Base
  */
 export const Uint8Array = /*#__PURE__*/ objectTag("Uint8Array");
 /**
@@ -596,11 +1000,11 @@ export const Uint8Array = /*#__PURE__*/ objectTag("Uint8Array");
  * It trusts the reported object tag and does not verify ArrayBuffer internal
  * slots.
  *
- * @group Base Types
+ * @group Base
  */
 export const ArrayBuffer = /*#__PURE__*/ objectTag("ArrayBuffer");
 /**
- * Creates a {@link Type} for instances of one constructor.
+ * Instance {@link Type} for one constructor.
  *
  * Membership uses the intrinsic prototype chain, so subclasses are accepted,
  * equivalent constructors from other realms are rejected, and custom
@@ -627,7 +1031,7 @@ export const ArrayBuffer = /*#__PURE__*/ objectTag("ArrayBuffer");
  * assert(!UserInstance.is({ name: "Ada" }));
  * ```
  *
- * @group Base Types
+ * @group Base
  */
 export const instanceOf = (constructor) => {
     const concreteConstructor = constructor;
@@ -644,6 +1048,26 @@ export const instanceOf = (constructor) => {
  * primitive through `from.parent`. The expected value must have one exact
  * literal type. Validation uses `===`, so `-0` matches `0`.
  *
+ * In {@link templateLiteralParser}, use a string Literal Type when the literal
+ * should be decoded into the Output Tuple. Use a raw string when it should only
+ * frame the canonical string.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { literal } from "@evolu/common";
+ *
+ * const Ready = literal("ready");
+ *
+ * expectTypeOf<typeof Ready.Output>().toEqualTypeOf<"ready">();
+ * expectOk(Ready.fromUnknown("ready"), "ready");
+ * expectErr(Ready.fromUnknown("pending"), {
+ *   type: "Literal",
+ *   expected: "ready",
+ *   value: "pending",
+ * });
+ * ```
+ *
  * @group Unions
  */
 export const literal = (expected) => {
@@ -663,11 +1087,22 @@ export const literal = (expected) => {
     const formatError = (error) => `The value ${safelyStringifyUnknownValue(error.value)} is not strictly equal to the expected literal: ${globalThis.String(error.expected)}.`;
     return globalThis.Object.assign(parent
         ? createChildType("Literal", parent, validate, formatError)
-        : createRootType("Literal", validate, formatError), { expected: literalExpected });
+        : createRootType("Literal", validate, formatError), {
+        expected: literalExpected,
+        [templateLiteralSyntaxSymbol]: true,
+    });
 };
-/** @group Unions */
+/**
+ * Literal {@link Type} accepting only `undefined`.
+ *
+ * @group Unions
+ */
 export const Undefined = /*#__PURE__*/ literal(undefined);
-/** @group Unions */
+/**
+ * Literal {@link Type} accepting only `null`.
+ *
+ * @group Unions
+ */
 export const Null = /*#__PURE__*/ literal(null);
 export function union(...typesOrLiterals) {
     const members = typesOrLiterals.map((typeOrLiteral) => typeOrLiteral !== null && typeof typeOrLiteral === "object"
@@ -676,7 +1111,7 @@ export function union(...typesOrLiterals) {
     const inputMembers = members.map(getTerminalRuntimeNode);
     const inputFrom = createUnionValidation(inputMembers, (member, value, options) => member.fromUnknown(value, options));
     const inputValidateOutput = createUnionValidation(inputMembers, (member, value, options) => member[outputValidationSymbol](value, options));
-    const defaultFormatter = formatUnionError;
+    const defaultFormatter = (() => "A value does not match any allowed variant.");
     const getTypeIssues = (error) => singleRuntimeTypeIssue("Union", error, defaultFormatter);
     const input = createTypeNode("Union", null, inputFrom, (value) => inputMembers.some((member) => member.is(value)), inputValidateOutput, ok, identity, getTypeIssues);
     const fromUnknown = createUnionValidation(members, (member, value, options) => member.fromUnknown(value, options));
@@ -692,9 +1127,8 @@ export function union(...typesOrLiterals) {
         assertNonNullable(member);
         return member[encoderSymbol](value);
     };
-    return createTypeNode("Union", input, fromUnknown, (value) => members.some((member) => member.is(value)), validateOutput, from, to, getTypeIssues, { members });
+    return createTypeNode("Union", input, fromUnknown, (value) => members.some((member) => member.is(value)), validateOutput, from, to, getTypeIssues, { members, [templateLiteralSyntaxSymbol]: true });
 }
-const formatUnionError = () => "A value does not match any union member.";
 const createUnionValidation = (members, validateMember) => (value, options = firstValidationOptions) => {
     let errors;
     for (let index = 0; index < members.length; index++) {
@@ -714,22 +1148,53 @@ const createUnionValidation = (members, validateMember) => (value, options = fir
     });
 };
 /**
- * Shorthand for passing a {@link Type} and `undefined` to {@link union}.
+ * Union {@link Type} containing the supplied Type and `undefined`.
  *
  * This does not make an object property optional. It changes only the values
  * accepted when the property is present.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { String, undefinedOr } from "@evolu/common";
+ *
+ * const StringOrUndefined = undefinedOr(String);
+ *
+ * expectOk(StringOrUndefined.fromUnknown(undefined), undefined);
+ * ```
+ *
  * @group Unions
  */
 export const undefinedOr = (type) => union(type, Undefined);
 /**
- * Shorthand for passing a {@link Type} and `null` to {@link union}.
+ * Union {@link Type} containing the supplied Type and `null`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { String, nullOr } from "@evolu/common";
+ *
+ * const NullableString = nullOr(String);
+ *
+ * expectOk(NullableString.fromUnknown(null), null);
+ * ```
  *
  * @group Unions
  */
 export const nullOr = (type) => union(type, Null);
 /**
- * Shorthand for passing a {@link Type}, `null`, and `undefined` to {@link union}.
+ * 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
  */
@@ -737,6 +1202,402 @@ export const nullishOr = (type) => union(type, Null, Undefined);
 const isRuntimeUnionTypeNode = (type) => type.name === "Union" &&
     "members" in type &&
     globalThis.Array.isArray(type.members);
+/**
+ * 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
+ * as a string, fixed literals define the framing and Output is a readonly Tuple
+ * of the decoded Type parts. `to` encodes that Tuple back into the canonical
+ * string represented by the parent Type. At least one Type part is required.
+ *
+ * When every capture uses identity encoding, the parent Output is the exact
+ * TypeScript template literal type. A transforming capture makes it nominal;
+ * create such strings with `to` or validate them with the parent Type.
+ *
+ * Deterministic framing is a core correctness guarantee. It preserves
+ * 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.
+ *
+ * Keep capture unions reasonably small to avoid excessive compiler work.
+ *
+ * TypeScript template literal types can describe a fixed number of digit
+ * positions, but not an arbitrarily long sequence of digits. Such grammars use
+ * branded Types such as {@link DecimalString}; `templateLiteralParser` preserves
+ * that exactness by requiring a validated branded capture when encoding.
+ *
+ * ### Example
+ *
+ * A template literal Type defines both a canonical string representation and
+ * the structured data decoded from it:
+ *
+ * ```ts
+ * import { templateLiteralParser, union } from "@evolu/common";
+ *
+ * const Language = union("en", "cs");
+ * const Region = union("US", "CZ");
+ *
+ * // Define a Type for "en-US" | "en-CZ" | "cs-US" | "cs-CZ".
+ * const SupportedLocale = templateLiteralParser(Language, "-", Region);
+ *
+ * // Output is the decoded language and region.
+ * type SupportedLocale = typeof SupportedLocale.Output;
+ * expectTypeOf<SupportedLocale>().toEqualTypeOf<
+ *   readonly ["en" | "cs", "US" | "CZ"]
+ * >();
+ *
+ * // The parent Output is the canonical locale string.
+ * type SupportedLocaleLiteral = typeof SupportedLocale.parent.Output;
+ * expectTypeOf<SupportedLocaleLiteral>().toEqualTypeOf<
+ *   "en-US" | "en-CZ" | "cs-US" | "cs-CZ"
+ * >();
+ *
+ * // Parse an unknown string into structured data.
+ * const result = SupportedLocale.fromUnknown("cs-CZ");
+ * expectOk(result, ["cs", "CZ"]);
+ * const locale = result.value;
+ * expectTypeOf(locale).toEqualTypeOf<SupportedLocale>();
+ * expectErr(SupportedLocale.fromUnknown("cs/CZ"), {
+ *   type: "TemplateLiteral",
+ *   value: "cs/CZ",
+ * });
+ *
+ * // Encode structured data into its canonical string.
+ * const localeLiteral = SupportedLocale.to(locale);
+ * expectTypeOf(localeLiteral).toEqualTypeOf<SupportedLocaleLiteral>();
+ * expect(localeLiteral).toBe("cs-CZ");
+ *
+ * // Validate a string configuration value.
+ * const configValue: unknown = "cs-CZ";
+ * assert(SupportedLocale.parent.is(configValue));
+ * expectTypeOf(configValue).toEqualTypeOf<SupportedLocaleLiteral>();
+ * expect(SupportedLocale.parent.is("fr-CZ")).toBe(false);
+ * ```
+ *
+ * `SupportedLocale` is structured data for application code.
+ * `SupportedLocaleLiteral` is its canonical representation for configuration
+ * and other APIs that require a string, such as URL parameters, environment
+ * variables, and storage keys.
+ *
+ * Use branded captures for strings that TypeScript template literal types
+ * cannot express exactly, such as arbitrary-length canonical decimals:
+ *
+ * ```ts
+ * import {
+ *   NonNegativeDecimalString,
+ *   templateLiteralParser,
+ * } from "@evolu/common";
+ *
+ * const DecimalText = templateLiteralParser(
+ *   "decimal:",
+ *   NonNegativeDecimalString,
+ * );
+ *
+ * // DecimalText.to requires a validated NonNegativeDecimalString.
+ * const zero = NonNegativeDecimalString.orThrow("0");
+ *
+ * expectOk(DecimalText.fromUnknown("decimal:0"), [zero]);
+ * expect(DecimalText.to([zero])).toBe("decimal:0");
+ * ```
+ *
+ * Capture Types (the Type arguments passed to `templateLiteralParser`) can use
+ * transformations to decode substrings into non-string data:
+ *
+ * ```ts
+ * import {
+ *   Int64FromInt64String,
+ *   templateLiteralParser,
+ * } from "@evolu/common";
+ *
+ * const ItemId = templateLiteralParser("item-", Int64FromInt64String);
+ * type ItemId = typeof ItemId.Output;
+ * type ItemIdLiteral = typeof ItemId.parent.Output;
+ *
+ * // Decode the string into structured data.
+ * const result = ItemId.fromUnknown("item-42");
+ * expectOk(result, [42n]);
+ * const itemId = result.value;
+ * expectTypeOf(itemId).toEqualTypeOf<ItemId>();
+ *
+ * // Encode the structured data into its canonical string.
+ * const itemIdLiteral = ItemId.to(itemId);
+ * expectTypeOf(itemIdLiteral).toEqualTypeOf<ItemIdLiteral>();
+ * expect(itemIdLiteral).toBe("item-42");
+ *
+ * // TypeScript cannot prove from the literal alone that "42" is a valid Int64 encoding.
+ * // @ts-expect-error Validate it with ItemId.parent or create it with ItemId.to.
+ * const invalidItemIdLiteral: ItemIdLiteral = "item-42";
+ * ```
+ *
+ * Fixed-width captures can be adjacent:
+ *
+ * ```ts
+ * import { templateLiteralParser, union } from "@evolu/common";
+ *
+ * const Digit = union("0", "1", "2", "3", "4", "5", "6", "7", "8", "9");
+ * const TwoDigits = templateLiteralParser(Digit, Digit);
+ * type TwoDigits = typeof TwoDigits.Output;
+ * type TwoDigitsLiteral = typeof TwoDigits.parent.Output;
+ *
+ * const twoDigits: TwoDigits = ["4", "2"];
+ * const twoDigitsLiteral: TwoDigitsLiteral = "42";
+ * // @ts-expect-error TwoDigitsLiteral requires exactly two digits.
+ * const threeDigitsLiteral: TwoDigitsLiteral = "123";
+ *
+ * expectOk(TwoDigits.from.parent(twoDigitsLiteral), twoDigits);
+ * expect(TwoDigits.to(twoDigits)).toBe(twoDigitsLiteral);
+ * ```
+ *
+ * TypeScript rejects multiple variable-width captures because their encoded
+ * boundaries would be ambiguous:
+ *
+ * ```ts
+ * import { String, templateLiteralParser } from "@evolu/common";
+ *
+ * // @ts-expect-error At most one Type capture can have a variable-width string representation.
+ * templateLiteralParser(String, ":", String);
+ * ```
+ *
+ * This restriction keeps encoding reversible: different capture Tuples must
+ * never produce the same string. A delimiter alone is not enough because it can
+ * also occur inside a capture. Some formats could provide stronger guarantees,
+ * such as captures that exclude a delimiter; support for those can be added
+ * when concrete use cases justify the additional framing rules.
+ *
+ * @group Template literals
+ */
+export const templateLiteralParser = (...parts) => createTemplateLiteralParserType(parts);
+const createTemplateLiteralParserType = (templateParts) => {
+    const captureTypes = templateParts.filter((part) => typeof part !== "string");
+    const runtimeCaptureTypes = captureTypes;
+    const output = tuple(...captureTypes);
+    const runtimeOutput = output;
+    const reflection = {
+        output,
+        parts: templateParts,
+        [templateLiteralSyntaxSymbol]: true,
+    };
+    const parse = compileTemplateLiteralParser(templateParts);
+    const decodeString = (value, options = firstValidationOptions) => {
+        const parseResult = parse(value);
+        if (!parseResult.ok)
+            return parseResult;
+        const outputResult = validateTupleItems(parseResult.value, runtimeCaptureTypes, (capture, value, captureOptions) => capture.fromUnknown(value, captureOptions), options, false);
+        return (outputResult.ok
+            ? outputResult
+            : err({
+                type: "TemplateLiteral",
+                outputError: outputResult.error,
+            }));
+    };
+    const encodeCaptures = (captures) => {
+        const encodedCaptures = runtimeOutput[encoderSymbol](captures);
+        let value = "";
+        let captureIndex = 0;
+        for (const part of templateParts) {
+            value +=
+                typeof part === "string" ? part : encodedCaptures[captureIndex++];
+        }
+        return value;
+    };
+    const canonicalizeString = (value, options) => {
+        const result = decodeString(value, options);
+        return result.ok ? ok(encodeCaptures(result.value)) : result;
+    };
+    const validateCanonicalString = (value, options = firstValidationOptions) => {
+        const stringResult = String.fromUnknown(value, options);
+        if (!stringResult.ok)
+            return stringResult;
+        const result = canonicalizeString(stringResult.value, options);
+        if (!result.ok || result.value === stringResult.value)
+            return result;
+        return err({ type: "TemplateLiteral", value: stringResult.value });
+    };
+    const getTypeIssues = (error, mode) => {
+        if (error.type !== "TemplateLiteral") {
+            return String[getRuntimeTypeIssuesSymbol](error, mode);
+        }
+        if ("outputError" in error) {
+            return runtimeOutput[getRuntimeTypeIssuesSymbol](error.outputError, mode);
+        }
+        return singleRuntimeTypeIssue("TemplateLiteral", error, ((error) => `The value ${safelyStringifyUnknownValue(error.value)} does not match the template literal.`));
+    };
+    const canonicalStringFromUnknown = (value, options = firstValidationOptions) => {
+        const stringResult = String.fromUnknown(value, options);
+        return stringResult.ok
+            ? canonicalizeString(stringResult.value, options)
+            : stringResult;
+    };
+    const canonicalStringFrom = createFromOperation((value, options = firstValidationOptions) => canonicalizeString(value, options));
+    const stringType = createTypeNode("TemplateLiteral", String, canonicalStringFromUnknown, (value) => validateCanonicalString(value, firstValidationOptions).ok, validateCanonicalString, canonicalStringFrom, identity, getTypeIssues, reflection);
+    const fromUnknown = (value, options = firstValidationOptions) => {
+        const stringResult = String.fromUnknown(value, options);
+        if (!stringResult.ok)
+            return stringResult;
+        // The internal parser has one broad signature, but a statically frameless
+        // declaration cannot return its framing error.
+        return decodeString(stringResult.value, options);
+    };
+    const fromCanonicalString = (value, options = firstValidationOptions) => {
+        String.from(value);
+        const result = decodeString(value, options);
+        if (!result.ok || encodeCaptures(result.value) !== value) {
+            throw new Error("Expected TemplateLiteral.", {
+                cause: result.ok
+                    ? {
+                        type: "TemplateLiteral",
+                        value,
+                    }
+                    : result.error,
+            });
+        }
+        return result;
+    };
+    const fromString = (value, options = firstValidationOptions) => {
+        String.from(value);
+        return decodeString(value, options);
+    };
+    fromCanonicalString.parent = fromString;
+    const from = createFromOperation(fromCanonicalString);
+    const type = createTypeNode("TemplateLiteral", stringType, fromUnknown, runtimeOutput.is, runtimeOutput[outputValidationSymbol], from, encodeCaptures, getTypeIssues, reflection);
+    type.from.parent =
+        fromCanonicalString;
+    return type;
+};
+/**
+ * Template literal {@link Type} for validation.
+ *
+ * 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.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { templateLiteral, union } from "@evolu/common";
+ *
+ * const Language = union("en", "cs");
+ * const Region = union("US", "CZ");
+ * const Locale = templateLiteral(Language, "-", Region);
+ *
+ * expectTypeOf<typeof Locale.Output>().toEqualTypeOf<
+ *   "en-US" | "en-CZ" | "cs-US" | "cs-CZ"
+ * >();
+ * expectOk(Locale.fromUnknown("cs-CZ"), "cs-CZ");
+ * expect(Locale.is("fr-CZ")).toBe(false);
+ * ```
+ *
+ * @group Template literals
+ */
+export const templateLiteral = (...parts) => createTemplateLiteralParserType(parts).parent;
+const compileTemplateLiteralParser = (parts) => {
+    let framing = emptyTemplateLiteralFraming;
+    let fixedPartsWidth = 0;
+    const compiledParts = parts.map((part) => {
+        const partFraming = getTemplateLiteralPartFraming(part);
+        framing = concatenateTemplateLiteralFraming(framing, partFraming);
+        fixedPartsWidth += partFraming.width ?? 0;
+        return [part, partFraming.width];
+    });
+    return (input) => {
+        const inputCodePoints = globalThis.Array.from(input);
+        const variableWidth = inputCodePoints.length - fixedPartsWidth;
+        if (variableWidth < 0) {
+            return err({ type: "TemplateLiteral", value: input });
+        }
+        const captures = [];
+        let position = 0;
+        for (const [part, width] of compiledParts) {
+            const partWidth = width ?? variableWidth;
+            const value = inputCodePoints
+                .slice(position, position + partWidth)
+                .join("");
+            if (typeof part === "string") {
+                if (value !== part) {
+                    return err({ type: "TemplateLiteral", value: input });
+                }
+            }
+            else {
+                captures.push(value);
+            }
+            position += partWidth;
+        }
+        return position === inputCodePoints.length
+            ? ok(captures)
+            : err({ type: "TemplateLiteral", value: input });
+    };
+};
+const emptyTemplateLiteralFraming = {
+    width: 0,
+    canBeEmpty: true,
+    canStartWithLowSurrogate: false,
+    canEndWithHighSurrogate: false,
+};
+const unknownTemplateLiteralFraming = {
+    width: null,
+    canBeEmpty: true,
+    canStartWithLowSurrogate: true,
+    canEndWithHighSurrogate: true,
+};
+const concatenateTemplateLiteralFraming = (left, right) => {
+    assert(!(left.canEndWithHighSurrogate && right.canStartWithLowSurrogate), "A TemplateLiteral cannot form a Unicode surrogate pair across part boundaries.");
+    return {
+        width: left.width !== null && right.width !== null
+            ? left.width + right.width
+            : null,
+        canBeEmpty: left.canBeEmpty && right.canBeEmpty,
+        canStartWithLowSurrogate: left.canStartWithLowSurrogate ||
+            (left.canBeEmpty && right.canStartWithLowSurrogate),
+        canEndWithHighSurrogate: right.canEndWithHighSurrogate ||
+            (right.canBeEmpty && left.canEndWithHighSurrogate),
+    };
+};
+const getStringTemplateLiteralFraming = (value) => {
+    const firstCodeUnit = value.charCodeAt(0);
+    const lastCodeUnit = value.charCodeAt(value.length - 1);
+    return {
+        width: globalThis.Array.from(value).length,
+        canBeEmpty: value.length === 0,
+        canStartWithLowSurrogate: firstCodeUnit >= 0xdc00 && firstCodeUnit <= 0xdfff,
+        canEndWithHighSurrogate: lastCodeUnit >= 0xd800 && lastCodeUnit <= 0xdbff,
+    };
+};
+const getTemplateLiteralPartFraming = (part) => {
+    if (typeof part === "string")
+        return getStringTemplateLiteralFraming(part);
+    const type = part;
+    if (type[templateLiteralSyntaxSymbol] === true) {
+        if (type.name === "Literal") {
+            return getStringTemplateLiteralFraming(type.expected);
+        }
+        if (type.name === "Union") {
+            const memberFramings = type.members.map(getTemplateLiteralPartFraming);
+            const width = memberFramings[0].width;
+            return {
+                width: width !== null &&
+                    memberFramings.every((framing) => framing.width === width)
+                    ? width
+                    : null,
+                canBeEmpty: memberFramings.some((framing) => framing.canBeEmpty),
+                canStartWithLowSurrogate: memberFramings.some((framing) => framing.canStartWithLowSurrogate),
+                canEndWithHighSurrogate: memberFramings.some((framing) => framing.canEndWithHighSurrogate),
+            };
+        }
+        if (type.name === "TemplateLiteral") {
+            return type.parts.reduce((framing, part) => concatenateTemplateLiteralFraming(framing, getTemplateLiteralPartFraming(part)), emptyTemplateLiteralFraming);
+        }
+    }
+    if (type.parent === null)
+        return unknownTemplateLiteralFraming;
+    return getTemplateLiteralPartFraming(type.parent);
+};
 export function brand(name, parent, validate, formatError) {
     return createChildType(name, parent, validate
         ? (value) => flatMapResult(validate(value), () => ok(value))
@@ -776,6 +1637,18 @@ export const DateIso = /*#__PURE__*/ brand("DateIso", String, (value) => value.l
 /**
  * Safely transforms a {@link Date} into a canonical {@link DateIso}.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { DateIsoFromDate } from "@evolu/common";
+ *
+ * const date = new globalThis.Date("2025-01-01T12:00:00.000Z");
+ * const result = DateIsoFromDate.fromUnknown(date);
+ *
+ * expectOk(result, "2025-01-01T12:00:00.000Z");
+ * expect(DateIsoFromDate.to(result.value)).toEqual(date);
+ * ```
+ *
  * @group String
  */
 export const DateIsoFromDate = /*#__PURE__*/ transform("DateIsoFromDate", Date, DateIso, {
@@ -837,7 +1710,17 @@ export const capitalized = (parent) => brand("Capitalized", parent, (value) => {
  */
 export const CapitalizedString = /*#__PURE__*/ capitalized(String);
 /**
- * Adds a {@link Brand} requiring a string without surrounding whitespace.
+ * 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
  */
@@ -859,11 +1742,31 @@ export const TrimmedString = /*#__PURE__*/ trimmed(String);
 /**
  * Trims a string and returns a {@link TrimmedString}.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { trim } from "@evolu/common";
+ *
+ * expect(trim("  Evolu  ")).toBe("Evolu");
+ * ```
+ *
  * @group String
  */
 export const trim = (value) => value.trim();
 /**
- * Adds a {@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
@@ -890,7 +1793,19 @@ export const minLength = (min) => (parent) => {
  */
 export const NonEmptyTrimmedString = /*#__PURE__*/ minLength(1)(TrimmedString);
 /**
- * Adds a {@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
@@ -914,7 +1829,19 @@ export const NonEmptyTrimmedString100 = /*#__PURE__*/ maxLength(100)(NonEmptyTri
  */
 export const NonEmptyTrimmedString1000 = /*#__PURE__*/ maxLength(1000)(NonEmptyTrimmedString);
 /**
- * Adds a {@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
@@ -926,7 +1853,7 @@ export const length = (exact) => (parent) => {
         : err({ type: name, value, exact }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} does not have the required length of ${error.exact}.`);
 };
 /**
- * Creates a string {@link Brand} that must match a regular expression.
+ * String {@link Brand} constrained by a regular expression.
  *
  * ### Example
  *
@@ -1028,12 +1955,34 @@ export const Base64Url = /*#__PURE__*/ brand("Base64Url", String, (value) => {
 /**
  * Encodes bytes as {@link Base64Url}.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { uint8ArrayToBase64Url } from "@evolu/common";
+ *
+ * expect(uint8ArrayToBase64Url(new Uint8Array([0, 1, 2, 255]))).toBe(
+ *   "AAEC_w",
+ * );
+ * ```
+ *
  * @group String
  */
 export const uint8ArrayToBase64Url = (bytes) => uint8ArrayToBase64UrlString(bytes);
 /**
  * Decodes {@link Base64Url} as bytes.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Base64Url, base64UrlToUint8Array } from "@evolu/common";
+ *
+ * const value = Base64Url.orThrow("AAEC_w");
+ *
+ * expect(base64UrlToUint8Array(value)).toEqual(
+ *   new Uint8Array([0, 1, 2, 255]),
+ * );
+ * ```
+ *
  * @group String
  */
 export const base64UrlToUint8Array = (value) => base64UrlStringToUint8Array(value);
@@ -1063,7 +2012,7 @@ export const SimplePassword = /*#__PURE__*/ brand("SimplePassword",
  */
 export const Mnemonic = /*#__PURE__*/ brand("Mnemonic", NonEmptyTrimmedString, (value) => bip39.validateMnemonic(value, wordlist)
     ? ok()
-    : err({ type: "Mnemonic", value }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} is not a valid BIP39 mnemonic.`);
+    : err({ type: "Mnemonic", value }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} is not a valid English BIP39 mnemonic.`);
 /**
  * Evolu Id: 16 bytes encoded as a 22-character {@link Base64Url}.
  *
@@ -1083,6 +2032,22 @@ export const Id = /*#__PURE__*/ brand("Id", String, (value) => value.length ===
  * This is the recommended default because it does not encode creation time.
  * Pass a Brand name when the returned Id belongs to one domain entity.
  *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   Id,
+ *   createId,
+ *   createRandomBytes,
+ *   type Brand,
+ * } from "@evolu/common";
+ *
+ * const userId = createId<"User">({ randomBytes: createRandomBytes() });
+ *
+ * expect(Id.is(userId)).toBe(true);
+ * expectTypeOf(userId).toEqualTypeOf<Id & Brand<"User">>();
+ * ```
+ *
  * @group String
  */
 export const createId = (deps, ..._validation) => uint8ArrayToBase64Url(deps.randomBytes.create(16));
@@ -1117,6 +2082,26 @@ export const createIdFromString = (value, ..._validation) => idBytesToId(sha256(
  * logs, URLs, and exports. Prefer {@link createId} unless that tradeoff is
  * deliberate.
  *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   createIdAsUuidv7,
+ *   createRandomBytes,
+ *   createTime,
+ *   idToIdBytes,
+ * } from "@evolu/common";
+ *
+ * const value = createIdAsUuidv7({
+ *   randomBytes: createRandomBytes(),
+ *   time: createTime(),
+ * });
+ * const bytes = idToIdBytes(value);
+ *
+ * expect(bytes[6] >> 4).toBe(0x7);
+ * expect(bytes[8] & 0xc0).toBe(0x80);
+ * ```
+ *
  * @group String
  */
 export const createIdAsUuidv7 = (deps, ..._validation) => {
@@ -1133,7 +2118,23 @@ export const createIdAsUuidv7 = (deps, ..._validation) => {
     return uint8ArrayToBase64Url(bytes);
 };
 /**
- * A table-specific {@link Id} Type.
+ * 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
  */
@@ -1150,11 +2151,47 @@ export const id = (table) => {
  */
 export const IdBytes = /*#__PURE__*/ brand("IdBytes", 
 /*#__PURE__*/ length(16)(Uint8Array));
-/** @group String */
+/**
+ * Byte length of an {@link IdBytes} value.
+ *
+ * @group String
+ */
 export const idBytesTypeValueLength = 16;
-/** @group String */
+/**
+ * Converts an {@link Id} to {@link IdBytes}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { createIdFromString, idToIdBytes } from "@evolu/common";
+ *
+ * const bytes = idToIdBytes(createIdFromString("todo"));
+ *
+ * expect(bytes).toHaveLength(16);
+ * ```
+ *
+ * @group String
+ */
 export const idToIdBytes = (value) => base64UrlToUint8Array(value);
-/** @group String */
+/**
+ * Converts {@link IdBytes} to an {@link Id}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   createIdFromString,
+ *   idBytesToId,
+ *   idToIdBytes,
+ * } from "@evolu/common";
+ *
+ * const value = createIdFromString("todo");
+ *
+ * expect(idBytesToId(idToIdBytes(value))).toBe(value);
+ * ```
+ *
+ * @group String
+ */
 export const idBytesToId = (value) => uint8ArrayToBase64Url(value);
 /**
  * Decimal string representation of a signed {@link Int64}.
@@ -1180,6 +2217,17 @@ export const Int64String = /*#__PURE__*/ brand("Int64String", NonEmptyTrimmedStr
  * text, including SQLite queries that cast INTEGER values to TEXT to avoid a
  * lossy JavaScript number conversion.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Int64FromInt64String } from "@evolu/common";
+ *
+ * const result = Int64FromInt64String.fromUnknown("9223372036854775807");
+ *
+ * expectOk(result, 9223372036854775807n);
+ * expect(Int64FromInt64String.to(result.value)).toBe("9223372036854775807");
+ * ```
+ *
  * @group Number
  */
 export const Int64FromInt64String = /*#__PURE__*/ transform("Int64FromInt64String", Int64String, Int64, {
@@ -1187,7 +2235,17 @@ export const Int64FromInt64String = /*#__PURE__*/ transform("Int64FromInt64Strin
     to: (value) => globalThis.String(value),
 });
 /**
- * Adds a {@link Brand} requiring a number greater than or equal to zero.
+ * 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
  */
@@ -1199,7 +2257,17 @@ export const nonNegative = (parent) => brand("NonNegative", parent, (value) => v
  */
 export const NonNegativeNumber = /*#__PURE__*/ nonNegative(Number);
 /**
- * Adds a {@link Brand} requiring a number greater than zero.
+ * 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
  */
@@ -1214,7 +2282,17 @@ export const positive = (parent) => brand("Positive", parent, (value) => value >
  */
 export const PositiveNumber = /*#__PURE__*/ positive(NonNegativeNumber);
 /**
- * Adds a {@link Brand} requiring a number less than or equal to zero.
+ * 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
  */
@@ -1226,7 +2304,17 @@ export const nonPositive = (parent) => brand("NonPositive", parent, (value) => v
  */
 export const NonPositiveNumber = /*#__PURE__*/ nonPositive(Number);
 /**
- * Adds a {@link Brand} requiring a number less than zero.
+ * 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
  */
@@ -1241,7 +2329,17 @@ export const negative = (parent) => brand("Negative", parent, (value) => value <
  */
 export const NegativeNumber = /*#__PURE__*/ negative(NonPositiveNumber);
 /**
- * Adds a {@link Brand} requiring a number other than `NaN`.
+ * 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
  */
@@ -1260,7 +2358,17 @@ export const nonNaN = (parent) => brand("NonNaN", parent, (value) => globalThis.
  */
 export const NonNaNNumber = /*#__PURE__*/ nonNaN(Number);
 /**
- * Adds a {@link Brand} requiring a finite number.
+ * Number {@link Brand} requiring a finite value.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { Number, finite } from "@evolu/common";
+ *
+ * const Finite = finite(Number);
+ *
+ * expectOk(Finite.fromUnknown(42), 42);
+ * ```
  *
  * @group Number
  */
@@ -1366,7 +2474,17 @@ export const NonPositiveInt = /*#__PURE__*/ nonPositive(Int);
  */
 export const NegativeInt = /*#__PURE__*/ negative(NonPositiveInt);
 /**
- * Adds a {@link Brand} requiring a number greater than `min`.
+ * 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
  */
@@ -1377,7 +2495,17 @@ export const greaterThan = (min) => (parent) => {
         : err({ type: name, value, min }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be greater than ${error.min}.`);
 };
 /**
- * Adds a {@link Brand} requiring a number greater than or equal to `min`.
+ * 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
  */
@@ -1392,7 +2520,17 @@ export const greaterThanOrEqualTo = (min) => (parent) => {
         }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be greater than or equal to ${error.min}.`);
 };
 /**
- * Adds a {@link Brand} requiring a number less than `max`.
+ * 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
  */
@@ -1410,7 +2548,17 @@ export const lessThan = (max) => (parent) => {
 export const Age = /*#__PURE__*/ brand("Age", 
 /*#__PURE__*/ lessThan(200)(NonNegativeInt));
 /**
- * Adds a {@link Brand} requiring a number less than or equal to `max`.
+ * 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
  */
@@ -1430,46 +2578,167 @@ export const lessThanOrEqualTo = (max) => (parent) => {
 export const Ratio = /*#__PURE__*/ brand("Ratio", 
 /*#__PURE__*/ lessThanOrEqualTo(1)(NonNegativeFiniteNumber));
 /**
- * Canonical string representation of a positive base-10 decimal value.
+ * Canonical string representation of a signed base-10 decimal value.
  *
  * Use this Type when a decimal value must remain exact instead of being
  * converted to an IEEE-754 number. Equivalent values have one accepted
- * representation, so leading zeroes, trailing fractional zeroes, signs, and
- * exponent notation are rejected.
+ * representation, so leading zeroes, trailing fractional zeroes, `-0`, plus
+ * signs, and exponent notation are rejected.
  *
  * The decoded value remains a string. Arithmetic requires an explicit decimal
  * or fixed-point representation.
  *
+ * TypeScript template literal types can describe a fixed number of digit
+ * positions, but not the arbitrarily long integer and fractional parts accepted
+ * here. `DecimalString` therefore uses a {@link Brand} so its TypeScript type
+ * does not accept strings that have not been validated.
+ *
+ * Use these predefined Types or their corresponding factories to add sign
+ * constraints to compatible decimal string Types:
+ *
+ * - {@link NonNegativeDecimalString} / {@link nonNegativeDecimalString}
+ * - {@link PositiveDecimalString} / {@link positiveDecimalString}
+ * - {@link NonPositiveDecimalString} / {@link nonPositiveDecimalString}
+ * - {@link NegativeDecimalString} / {@link negativeDecimalString}
+ *
  * ### Example
  *
  * ```ts
- * import { PositiveDecimalString } from "@evolu/common";
+ * import { DecimalString } from "@evolu/common";
  *
- * expectOk(PositiveDecimalString.fromUnknown("0.3"), "0.3");
- * expectOk(PositiveDecimalString.fromUnknown("25"), "25");
- * expectOk(PositiveDecimalString.fromUnknown("10.01"), "10.01");
+ * expectOk(DecimalString.fromUnknown("-10.25"), "-10.25");
+ * expectOk(DecimalString.fromUnknown("0"), "0");
+ * expectOk(DecimalString.fromUnknown("10.25"), "10.25");
  *
- * expectErr(PositiveDecimalString.fromUnknown("0"), {
- *   type: "PositiveDecimalString",
- *   value: "0",
- * });
- * expectErr(PositiveDecimalString.fromUnknown("0.30"), {
- *   type: "PositiveDecimalString",
- *   value: "0.30",
+ * expectErr(DecimalString.fromUnknown("10.250"), {
+ *   type: "DecimalString",
+ *   value: "10.250",
  * });
  * ```
  *
  * @group Number
  */
-export const PositiveDecimalString = /*#__PURE__*/ brand("PositiveDecimalString", String, (value) => /^(?:[1-9]\d*|(?:0|[1-9]\d*)\.\d*[1-9])$/.test(value)
+export const DecimalString = /*#__PURE__*/ brand("DecimalString", String, (value) => /^(?:0|-?(?:[1-9]\d*|(?:0|[1-9]\d*)\.\d*[1-9]))$/.test(value)
+    ? ok()
+    : err({ type: "DecimalString", value }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be a canonical decimal 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 const nonNegativeDecimalString = (parent) => brand("NonNegativeDecimalString", parent, (value) => value[0] !== "-"
+    ? ok()
+    : err({
+        type: "NonNegativeDecimalString",
+        value,
+    }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be a non-negative decimal string.`);
+/**
+ * Non-negative {@link DecimalString}.
+ *
+ * @group Number
+ */
+export const NonNegativeDecimalString = 
+/*#__PURE__*/ nonNegativeDecimalString(DecimalString);
+/**
+ * {@link DecimalString} Brand requiring a value greater than zero.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { DecimalString, positiveDecimalString } from "@evolu/common";
+ *
+ * const Positive = positiveDecimalString(DecimalString);
+ *
+ * expectOk(Positive.fromUnknown("0.5"), "0.5");
+ * ```
+ *
+ * @group Number
+ */
+export const positiveDecimalString = (parent) => brand("PositiveDecimalString", parent, (value) => value !== "0" && value[0] !== "-"
     ? ok()
     : err({
         type: "PositiveDecimalString",
         value,
-    }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be a canonical positive decimal string.`);
+    }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be a positive decimal string.`);
 /**
- * Adds a {@link Brand} requiring a number to be a multiple of an exact decimal
- * `divisor`.
+ * Positive {@link DecimalString}.
+ *
+ * Also satisfies {@link NonNegativeDecimalString}, so it can be used wherever a
+ * non-negative decimal string is required.
+ *
+ * @group Number
+ */
+export const PositiveDecimalString = /*#__PURE__*/ positiveDecimalString(NonNegativeDecimalString);
+/**
+ * {@link DecimalString} Brand requiring a value less than or equal to zero.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { DecimalString, nonPositiveDecimalString } from "@evolu/common";
+ *
+ * const NonPositive = nonPositiveDecimalString(DecimalString);
+ *
+ * expectOk(NonPositive.fromUnknown("-0.5"), "-0.5");
+ * ```
+ *
+ * @group Number
+ */
+export const nonPositiveDecimalString = (parent) => brand("NonPositiveDecimalString", parent, (value) => value === "0" || value[0] === "-"
+    ? ok()
+    : err({
+        type: "NonPositiveDecimalString",
+        value,
+    }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be a non-positive decimal string.`);
+/**
+ * Non-positive {@link DecimalString}.
+ *
+ * @group Number
+ */
+export const NonPositiveDecimalString = 
+/*#__PURE__*/ nonPositiveDecimalString(DecimalString);
+/**
+ * {@link DecimalString} Brand requiring a value less than zero.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { DecimalString, negativeDecimalString } from "@evolu/common";
+ *
+ * const Negative = negativeDecimalString(DecimalString);
+ *
+ * expectOk(Negative.fromUnknown("-0.5"), "-0.5");
+ * ```
+ *
+ * @group Number
+ */
+export const negativeDecimalString = (parent) => brand("NegativeDecimalString", parent, (value) => value[0] === "-"
+    ? ok()
+    : err({
+        type: "NegativeDecimalString",
+        value,
+    }), (error) => `The value ${safelyStringifyUnknownValue(error.value)} must be a negative decimal string.`);
+/**
+ * Negative {@link DecimalString}.
+ *
+ * Also satisfies {@link NonPositiveDecimalString}, so it can be used wherever a
+ * non-positive decimal string is required.
+ *
+ * @group Number
+ */
+export const NegativeDecimalString = /*#__PURE__*/ negativeDecimalString(NonPositiveDecimalString);
+/**
+ * Number {@link Brand} requiring an exact decimal multiple of `divisor`.
  *
  * The divisor must be one canonical positive decimal string literal because its
  * exact value is encoded in the resulting Brand name. The declaration is
@@ -1542,7 +2811,17 @@ const decimalStringToParts = (value) => {
     return { coefficient, exponent };
 };
 /**
- * Adds a {@link Brand} requiring a number to be within an inclusive range.
+ * 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
  */
@@ -1645,20 +2924,6 @@ const isArrayCollection = (value, isElement) => {
     }
     return true;
 };
-const formatArrayError = (error) => {
-    if (error.reason.kind === "NotArray") {
-        return `A value ${safelyStringifyUnknownValue(error.reason.value)} is not an array.`;
-    }
-    const issue = error.reason.issues[0];
-    switch (issue.kind) {
-        case "Hole":
-            return `An array element at index ${issue.index} is missing.`;
-        case "Accessor":
-            return `An array element at index ${issue.index} must be a data property.`;
-        case "ExcessProperty":
-            return "An excess Array property is not allowed. Remove it or use a different Type.";
-    }
-};
 const arrayRuntimeConfig = {
     name: "Array",
     typeByElement: arrayTypeByElement,
@@ -1666,7 +2931,22 @@ const arrayRuntimeConfig = {
     validateItems: (value, validateElement, options) => validateArrayItems(value, validateElement, options, false),
     encode: encodeArrayCollection,
     is: isArrayCollection,
-    formatError: formatArrayError,
+    formatError: ((error) => {
+        if (error.reason.kind === "NotArray") {
+            return `A value ${safelyStringifyUnknownValue(error.reason.value)} is not an array.`;
+        }
+        const issue = error.reason.issues[0];
+        switch (issue.kind) {
+            case "Hole":
+                return `An array element at index ${issue.index} is missing.`;
+            case "Accessor":
+                return `An array element at index ${issue.index} must be a data property.`;
+            case "ExcessProperty":
+                return "An excess Array property is not allowed. Remove it or use a different Type.";
+            case "Element":
+                return `An array element at index ${issue.index} is invalid.`;
+        }
+    }),
 };
 const validateArrayItems = (value, validate, options, checkStructure) => validateIndexedArrayItems("Array", value, validate, options, checkStructure);
 // Array and Tuple share their structural and element validation traversal.
@@ -1751,6 +3031,17 @@ const copyArrayPrefix = (value, endIndex) => {
  * iteration order. Classification uses the realm-neutral object tag and
  * prototype structure under Evolu Type's trusted JavaScript policy.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { String, set } from "@evolu/common";
+ *
+ * const Tags = set(String);
+ * const tags = new Set(["local-first", "offline"]);
+ *
+ * expectOk(Tags.fromUnknown(tags), tags);
+ * ```
+ *
  * @group Collection
  */
 export const set = (element) => createHomogeneousCollectionType(element, setRuntimeConfig);
@@ -1824,16 +3115,6 @@ const isSetCollection = (value, isElement) => {
     }
     return true;
 };
-const formatSetError = (error) => {
-    if (error.reason.kind === "NotSet") {
-        return `A value ${safelyStringifyUnknownValue(error.reason.value)} is not a Set.`;
-    }
-    if (error.reason.kind === "UnexpectedPrototype") {
-        return "The value is a Set subclass, but a Set Output must be a direct Set.";
-    }
-    const issue = error.reason.issues[0];
-    return `An excess Set property ${safelyStringifyUnknownValue(issue.key)} is not allowed.`;
-};
 const hasDirectSetPrototype = (value) => {
     const prototype = globalThis.Object.getPrototypeOf(value);
     if (prototype === null)
@@ -1849,7 +3130,19 @@ const setRuntimeConfig = {
     validateItems: (value, validateElement, options) => validateSetItems(value, validateElement, options, false),
     encode: encodeSetCollection,
     is: isSetCollection,
-    formatError: formatSetError,
+    formatError: ((error) => {
+        if (error.reason.kind === "NotSet")
+            return `A value ${safelyStringifyUnknownValue(error.reason.value)} is not a Set.`;
+        if (error.reason.kind === "UnexpectedPrototype")
+            return "The value is an instance of a Set subclass, but a Set Output must be a direct Set instance.";
+        const issue = error.reason.issues[0];
+        switch (issue.kind) {
+            case "ExcessProperty":
+                return `An excess Set property ${safelyStringifyUnknownValue(issue.key)} is not allowed.`;
+            case "Element":
+                return `A Set element at index ${issue.index} is invalid.`;
+        }
+    }),
 };
 const validateSetItems = (value, validate, options, checkStructure) => {
     let issues;
@@ -1914,12 +3207,10 @@ const createTupleType = (typeElements) => {
     const fromUnknown = (value, options = firstValidationOptions) => validate(value, (element, item, elementOptions) => element.fromUnknown(item, elementOptions), options);
     const validateOutput = (value, options = firstValidationOptions) => validate(value, (element, item, elementOptions) => element[outputValidationSymbol](item, elementOptions), options);
     const formatError = (error) => {
-        if (error.reason.kind === "NotArray") {
+        if (error.reason.kind === "NotArray")
             return `A value ${safelyStringifyUnknownValue(error.reason.value)} is not a tuple.`;
-        }
-        if (error.reason.kind === "InvalidLength") {
+        if (error.reason.kind === "InvalidLength")
             return `A Tuple must contain exactly ${error.reason.expected} elements, but the value contains ${error.reason.actual}.`;
-        }
         const issue = error.reason.issues[0];
         switch (issue.kind) {
             case "Hole":
@@ -1928,6 +3219,8 @@ const createTupleType = (typeElements) => {
                 return `A Tuple element at index ${issue.index} must be a data property.`;
             case "ExcessProperty":
                 return "An excess Tuple property is not allowed. Remove it or use a different Type.";
+            case "Element":
+                return `A Tuple element at index ${issue.index} is invalid.`;
         }
     };
     const rootElements = typeElements.map(getTerminalRuntimeNode);
@@ -1974,6 +3267,55 @@ const createTupleType = (typeElements) => {
     return createTypeNode("Tuple", parent, fromUnknown, is, validateOutput, from, to, getTypeIssues, { elements: typeElements });
 };
 const validateTupleItems = (value, elements, validate, options, checkStructure) => validateIndexedArrayItems("Tuple", value, (value, elementOptions, index) => validate(elements[index], value, elementOptions, index), options, checkStructure);
+/**
+ * Decimal digit from `"0"` to `"9"`.
+ *
+ * @group String
+ */
+export const Digit = /*#__PURE__*/ union("0", "1", "2", "3", "4", "5", "6", "7", "8", "9");
+/**
+ * Decimal digit from `"1"` to `"9"`.
+ *
+ * @group String
+ */
+export const Digit1To9 = /*#__PURE__*/ union("1", "2", "3", "4", "5", "6", "7", "8", "9");
+/**
+ * Decimal string from `"1"` to `"6"`.
+ *
+ * @group String
+ */
+export const Digit1To6 = /*#__PURE__*/ union("1", "2", "3", "4", "5", "6");
+/**
+ * Decimal string from `"1"` to `"23"`.
+ *
+ * @group String
+ */
+export const Digit1To23 = /*#__PURE__*/ union(Digit1To9, 
+/*#__PURE__*/ templateLiteral("1", Digit), 
+/*#__PURE__*/ templateLiteral("2", /*#__PURE__*/ union("0", "1", "2", "3")));
+/**
+ * Decimal string from `"1"` to `"51"`.
+ *
+ * @group String
+ */
+export const Digit1To51 = /*#__PURE__*/ union(Digit1To9, 
+/*#__PURE__*/ templateLiteral(/*#__PURE__*/ union("1", "2", "3", "4"), Digit), 
+/*#__PURE__*/ templateLiteral("5", /*#__PURE__*/ union("0", "1")));
+/**
+ * Decimal string from `"1"` to `"99"`.
+ *
+ * @group String
+ */
+export const Digit1To99 = /*#__PURE__*/ union(Digit1To9, 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit));
+/**
+ * Decimal string from `"1"` to `"59"`.
+ *
+ * @group String
+ */
+export const Digit1To59 = /*#__PURE__*/ union(Digit1To9, 
+/*#__PURE__*/ templateLiteral(
+/*#__PURE__*/ union("1", "2", "3", "4", "5"), Digit));
 const createObjectRuntimeTypeIssues = (defaultFormatter, props, recordType) => (error, mode) => {
     const objectError = error;
     if (objectError.reason.kind !== "Properties") {
@@ -2014,21 +3356,9 @@ const createObjectRuntimeTypeIssues = (defaultFormatter, props, recordType) => (
         return recordType[getRuntimeTypeIssuesSymbol](propertyError, mode);
     });
 };
-const formatPlainObjectError = (error) => {
-    if (error.reason.kind !== "Properties") {
-        return formatPlainObjectRootError(error.reason);
-    }
-    const key = Reflect.ownKeys(error.reason.errors).at(0);
-    assertNonNullable(key);
-    const propertyError = error.reason.errors[key];
-    assertNonNullable(propertyError);
-    if (propertyError.type === "ObjectPropertyAccess") {
-        return propertyError.reason === "Accessor"
-            ? "An Object property must be a data property. Materialize accessor values into plain data before using this Type or use a different Type."
-            : "An Object property must be enumerable. Make it enumerable or use a different Type.";
-    }
-    return "An Object property key must be a string. Remove it or use a different Type.";
-};
+const formatPlainObjectRootError = (reason) => reason.kind === "NotObject"
+    ? `A value ${safelyStringifyUnknownValue(reason.value)} is not an object.`
+    : "The value is an object, but an Object Output must be a plain object or have a null prototype.";
 /**
  * A {@link Type} for readonly plain objects with unknown property values.
  *
@@ -2043,7 +3373,7 @@ const formatPlainObjectError = (error) => {
  * values have their own Types, and {@link instanceOf} when an instance belongs
  * to the domain.
  *
- * @group Base Types
+ * @group Base
  */
 export const Object = /*#__PURE__*/ createRootType("Object", (value, options = firstValidationOptions) => {
     if (value === null || typeof value !== "object") {
@@ -2093,15 +3423,56 @@ export const Object = /*#__PURE__*/ createRootType("Object", (value, options = f
             type: "Object",
             reason: { kind: "Properties", errors },
         });
-}, formatPlainObjectError, 
-/*#__PURE__*/ createObjectRuntimeTypeIssues(formatPlainObjectError));
+}, (error) => {
+    if (error.reason.kind !== "Properties")
+        return formatPlainObjectRootError(error.reason);
+    const key = Reflect.ownKeys(error.reason.errors).at(0);
+    assertNonNullable(key);
+    const propertyError = error.reason.errors[key];
+    assertNonNullable(propertyError);
+    if (propertyError.type === "ObjectPropertyAccess") {
+        switch (propertyError.reason) {
+            case "Accessor":
+                return "An Object property must be a data property. Materialize accessor values into plain data before using this Type or use a different Type.";
+            case "NonEnumerable":
+                return "An Object property must be enumerable. Make it enumerable or use a different Type.";
+        }
+    }
+    if (propertyError.type === "ObjectMissingProperty")
+        return `The required property ${safelyStringifyUnknownValue(key)} is missing.`;
+    if (typeof key === "symbol")
+        return "An Object property key must be a string. Remove the symbol property or use a different Type.";
+    if (propertyError.type === "ObjectExcessProperty")
+        return `The property ${safelyStringifyUnknownValue(key)} is not allowed. Remove it or use a different Type.`;
+    return `The property ${safelyStringifyUnknownValue(key)} is invalid.`;
+}, 
+/*#__PURE__*/ createObjectRuntimeTypeIssues(((error) => {
+    if (error.reason.kind !== "Properties")
+        return formatPlainObjectRootError(error.reason);
+    const key = Reflect.ownKeys(error.reason.errors).at(0);
+    assertNonNullable(key);
+    const propertyError = error.reason.errors[key];
+    assertNonNullable(propertyError);
+    if (propertyError.type === "ObjectPropertyAccess") {
+        switch (propertyError.reason) {
+            case "Accessor":
+                return "An Object property must be a data property. Materialize accessor values into plain data before using this Type or use a different Type.";
+            case "NonEnumerable":
+                return "An Object property must be enumerable. Make it enumerable or use a different Type.";
+        }
+    }
+    if (propertyError.type === "ObjectMissingProperty")
+        return `The required property ${safelyStringifyUnknownValue(key)} is missing.`;
+    if (typeof key === "symbol")
+        return "An Object property key must be a string. Remove the symbol property or use a different Type.";
+    if (propertyError.type === "ObjectExcessProperty")
+        return `The property ${safelyStringifyUnknownValue(key)} is not allowed. Remove it or use a different Type.`;
+    return `The property ${safelyStringifyUnknownValue(key)} is invalid.`;
+})));
 const isPlainObject = (value) => {
     const prototype = globalThis.Object.getPrototypeOf(value);
     return (prototype === null || globalThis.Object.getPrototypeOf(prototype) === null);
 };
-const formatPlainObjectRootError = (reason) => reason.kind === "NotObject"
-    ? `A value ${safelyStringifyUnknownValue(reason.value)} is not an object.`
-    : "The value is an object, but an Object Output must be a plain object or have a null prototype.";
 /**
  * Record {@link Type}.
  *
@@ -2132,20 +3503,13 @@ const formatPlainObjectRootError = (reason) => reason.kind === "NotObject"
  *
  * ```ts
  * import {
- *   Number,
+ *   Int64FromInt64String,
  *   String,
- *   ok,
  *   record,
- *   transform,
- *   type Result,
+ *   type Int64,
  * } from "@evolu/common";
  *
- * const ScoreFromString = transform("ScoreFromString", String, Number, {
- *   from: (value) => ok(globalThis.Number(value)),
- *   to: globalThis.String,
- * });
- *
- * const ScoresByUser = record(String, ScoreFromString);
+ * const ScoresByUser = record(String, Int64FromInt64String);
  * type ScoresByUser = typeof ScoresByUser.Output;
  *
  * // Validate an unknown value.
@@ -2154,7 +3518,7 @@ const formatPlainObjectRootError = (reason) => reason.kind === "NotObject"
  *   grace: "20",
  * });
  *
- * expectOk(scoresFromUnknown, { ada: 10, grace: 20 });
+ * expectOk(scoresFromUnknown, { ada: 10n, grace: 20n });
  *
  * // Validate keys and values with their root Types.
  * const scoresInput = ScoresByUser.parent.fromUnknown({
@@ -2166,11 +3530,10 @@ const formatPlainObjectRootError = (reason) => reason.kind === "NotObject"
  * // Run the remaining key and value stages.
  * const scoresFromInput = ScoresByUser.from.parent(scoresInput.value);
  *
- * expectTypeOf(scoresFromInput).toEqualTypeOf<
- *   Result<Readonly<Partial<Record<string, number>>>, never>
+ * expectOk(scoresFromInput, { ada: 10n, grace: 20n });
+ * expectTypeOf(scoresFromInput.value).toEqualTypeOf<
+ *   Readonly<Partial<Record<string, Int64>>>
  * >();
- *
- * expectOk(scoresFromInput, { ada: 10, grace: 20 });
  * ```
  *
  * Note that TypeScript does not model an object's runtime prototype. This can
@@ -2234,18 +3597,20 @@ export const record = (key, value) => {
     const fromUnknown = (input, options = firstValidationOptions) => validate(input, typeKey.fromUnknown, typeValue.fromUnknown, options);
     const validateOutput = (input, options = firstValidationOptions) => validate(input, typeKey[outputValidationSymbol], typeValue[outputValidationSymbol], options);
     const formatError = (error) => {
-        if (error.reason.kind === "NotRecord") {
-            return `A value ${safelyStringifyUnknownValue(error.reason.value)} is not a record.`;
-        }
-        if (error.reason.kind === "NotPlainRecord") {
+        if (error.reason.kind === "NotRecord")
+            return `A value ${safelyStringifyUnknownValue(error.reason.value)} is not a Record.`;
+        if (error.reason.kind === "NotPlainRecord")
             return "The value is an object, but a Record Output must be a plain object or have a null prototype.";
-        }
         const issue = error.reason.issues[0];
         switch (issue.kind) {
+            case "Key":
+                return `Property key ${safelyStringifyUnknownValue(issue.key)} is invalid.`;
+            case "Value":
+                return `The value of property ${safelyStringifyUnknownValue(issue.key)} is invalid.`;
             case "Accessor":
-                return `A record property ${safelyStringifyUnknownValue(issue.key)} must be a data property.`;
+                return `A Record property ${safelyStringifyUnknownValue(issue.key)} must be a data property.`;
             case "NonEnumerable":
-                return `A record property ${safelyStringifyUnknownValue(issue.key)} must be enumerable.`;
+                return `A Record property ${safelyStringifyUnknownValue(issue.key)} must be enumerable.`;
             case "Collision":
                 return `Record keys ${safelyStringifyUnknownValue(issue.previousKey)} and ${safelyStringifyUnknownValue(issue.key)} decode to the same key ${safelyStringifyUnknownValue(issue.outputKey)}.`;
         }
@@ -2557,25 +3922,27 @@ const createObjectType = (props, recordType) => {
     const fromUnknown = (value, options = firstValidationOptions) => validate(value, options, false);
     const validateOutput = (value, options = firstValidationOptions) => validate(value, options, true);
     const formatError = (error) => {
-        if (error.reason.kind !== "Properties") {
+        if (error.reason.kind !== "Properties")
             return formatPlainObjectRootError(error.reason);
-        }
         const key = Reflect.ownKeys(error.reason.errors).at(0);
         assertNonNullable(key);
         const propertyError = error.reason.errors[key];
+        assertNonNullable(propertyError);
         if (propertyError.type === "ObjectPropertyAccess") {
             switch (propertyError.reason) {
                 case "Accessor":
                     return "An Object property must be a data property. Materialize accessor values into plain data before using this Type or use a different Type.";
                 case "NonEnumerable":
-                    return "An Object property must be enumerable.";
+                    return "An Object property must be enumerable. Make it enumerable or use a different Type.";
             }
         }
-        if (typeof key === "string" &&
-            globalThis.Object.hasOwn(runtimeProps, key)) {
-            return "A required property is missing.";
-        }
-        return "An excess property is not allowed. Remove it or use a different Type.";
+        if (propertyError.type === "ObjectMissingProperty")
+            return `The required property ${safelyStringifyUnknownValue(key)} is missing.`;
+        if (typeof key === "symbol")
+            return "An Object property key must be a string. Remove the symbol property or use a different Type.";
+        if (propertyError.type === "ObjectExcessProperty")
+            return `The property ${safelyStringifyUnknownValue(key)} is not allowed. Remove it or use a different Type.`;
+        return `The property ${safelyStringifyUnknownValue(key)} is invalid.`;
     };
     const rootProps = createMutableRecord();
     let hasNonRootType = false;
@@ -2746,7 +4113,7 @@ const createRecordPropertyError = (issue) => ({
     reason: { kind: "Entries", issues: [issue] },
 });
 /**
- * Creates an {@link object} Type with every property optional.
+ * Object {@link Type} with every property optional.
  *
  * No property is required, but every present property must still satisfy its
  * Type.
@@ -2777,7 +4144,8 @@ export const partial = (props, ..._validation) => {
     return createObjectType(partialProps);
 };
 /**
- * Makes every property whose Union Type includes {@link Null} optional.
+ * Object {@link Type} making every property whose Union Type includes
+ * {@link Null} optional.
  *
  * The property retains its original Union Type, so consumers may omit it, set
  * it to `null`, or provide any other member of that Union. Properties without
@@ -2822,7 +4190,18 @@ export const nullableToOptional = (props, ..._validation) => {
     return createObjectType(optionalProps);
 };
 /**
- * Creates an {@link object} Type without the selected declared properties.
+ * 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
  */
@@ -2976,22 +4355,21 @@ export function discriminatedUnion(...keyOrMembers) {
     };
     const route = (value) => membersByDiscriminator.get(Reflect.get(value, key));
     const formatError = (error) => {
-        const reason = error.reason;
-        switch (reason.kind) {
+        switch (error.reason.kind) {
             case "Object":
-                return formatPlainObjectRootError(reason.error.reason);
+                return formatPlainObjectRootError(error.reason.error.reason);
             case "PropertyAccess": {
-                const property = `The discriminator property ${safelyStringifyUnknownValue(reason.key)}`;
-                if (reason.reason === "Accessor") {
+                const property = `The discriminator property ${safelyStringifyUnknownValue(error.reason.key)}`;
+                if (error.reason.reason === "Accessor")
                     return `${property} must be a data property.`;
-                }
-                if (reason.reason === "Inherited") {
+                if (error.reason.reason === "Inherited")
                     return `${property} must be an own property.`;
-                }
                 return `${property} must be enumerable.`;
             }
             case "Discriminator":
-                return `The discriminator property ${safelyStringifyUnknownValue(reason.key)} has an unexpected value ${safelyStringifyUnknownValue(reason.value)}.`;
+                return `The discriminator property ${safelyStringifyUnknownValue(error.reason.key)} has an unexpected value ${safelyStringifyUnknownValue(error.reason.value)}.`;
+            case "Member":
+                return `The selected variant ${safelyStringifyUnknownValue(error.reason.discriminator)} is invalid.`;
         }
     };
     const defaultFormatter = formatError;
@@ -3272,29 +4650,6 @@ const validateJsonValue = (value, options = firstValidationOptions) => {
             },
         });
 };
-const formatJsonValueError = (error) => {
-    const issue = error.reason.issues[0];
-    switch (issue.kind) {
-        case "InvalidType":
-            return `A value ${safelyStringifyUnknownValue(issue.value)} is not a JSON value.`;
-        case "NonFiniteNumber":
-            return "A JSON number must be finite.";
-        case "UnexpectedPrototype":
-            return "The value is an object, but a JsonValue Object must be a plain object or have a null prototype.";
-        case "Accessor":
-            return "A JSON property must be a data property. Materialize accessor values into plain data before using this Type or use a different Type.";
-        case "NonEnumerable":
-            return "A JSON Object property must be enumerable. Remove it or use a different Type.";
-        case "SymbolProperty":
-            return "A JSON Object property key must be a string. Remove the symbol property or use a different Type.";
-        case "Hole":
-            return "A JSON Array element is missing.";
-        case "ExcessProperty":
-            return "An excess JSON Array property is not allowed. Remove it or use a different Type.";
-        case "CircularReference":
-            return "A JsonValue must not contain circular references.";
-    }
-};
 const getJsonValueRuntimeTypeIssues = (error, mode) => {
     const jsonValueError = error;
     const issues = mode === "first"
@@ -3309,7 +4664,29 @@ const getJsonValueRuntimeTypeIssues = (error, mode) => {
                 reason: { kind: "Issues", issues: [issue] },
             },
         path: issue.path,
-        formatError: formatJsonValueError,
+        formatError: ((error) => {
+            const issue = error.reason.issues[0];
+            switch (issue.kind) {
+                case "InvalidType":
+                    return `A value ${safelyStringifyUnknownValue(issue.value)} is not a JSON value.`;
+                case "NonFiniteNumber":
+                    return "A JSON number must be finite.";
+                case "UnexpectedPrototype":
+                    return "The value is an object, but a JsonValue object must be a plain object or have a null prototype.";
+                case "Accessor":
+                    return "A JSON property must be a data property. Materialize accessor values into plain data before using this Type or use a different Type.";
+                case "NonEnumerable":
+                    return "A JSON object property must be enumerable. Remove it or use a different Type.";
+                case "SymbolProperty":
+                    return "A JSON object property key must be a string. Remove the symbol property or use a different Type.";
+                case "Hole":
+                    return "A JSON array element is missing.";
+                case "ExcessProperty":
+                    return "An excess JSON array property is not allowed. Remove it or use a different Type.";
+                case "CircularReference":
+                    return "A JsonValue must not contain circular references.";
+            }
+        }),
     }));
 };
 const parseJson = (value) => globalThis.JSON.parse(value);
@@ -3379,6 +4756,21 @@ const stringifyJsonValue = (value) => {
 /**
  * Exact root Type for {@link JsonValue} data trees.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { JsonValue, type JsonValueInput } from "@evolu/common";
+ *
+ * const input: JsonValueInput = {
+ *   name: "Ada",
+ *   scores: [10, 20],
+ * };
+ * const result = JsonValue.fromUnknown(input);
+ *
+ * expectOk(result, input);
+ * expectTypeOf(result.value).toEqualTypeOf<JsonValue>();
+ * ```
+ *
  * @group JSON
  */
 export const JsonValue = 
@@ -3411,21 +4803,52 @@ export const Json = /*#__PURE__*/ brand("Json", String, (value) => {
 /**
  * Totally parses proven {@link Json} text into an exact {@link JsonValue}.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { Json, jsonToJsonValue } from "@evolu/common";
+ *
+ * const value = jsonToJsonValue(Json.orThrow('{"name":"Ada"}'));
+ *
+ * expect(value).toEqual({ name: "Ada" });
+ * ```
+ *
  * @group JSON
  */
 export const jsonToJsonValue = (value) => parseJson(value);
 /**
  * Totally encodes an exact {@link JsonValue} as canonical {@link Json} text.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { jsonValueToJson, type JsonValue } from "@evolu/common";
+ *
+ * const value: JsonValue = { name: "Ada" };
+ *
+ * expect(jsonValueToJson(value)).toBe('{"name":"Ada"}');
+ * ```
+ *
  * @group JSON
  */
 export const jsonValueToJson = (value) => stringifyJsonValue(JsonValue.to(value));
 /**
- * {@link Json} to {@link JsonValue} transformation.
+ * Transformation {@link Type} that parses {@link Json} into {@link JsonValue}.
  *
  * Decoding unknown input first validates the Json Brand. Starting from the
  * typed Json parent is infallible. Encoding canonicalizes JSON text.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { JsonValueFromJson } from "@evolu/common";
+ *
+ * const result = JsonValueFromJson.fromUnknown('{ "name": "Ada" }');
+ *
+ * expectOk(result, { name: "Ada" });
+ * expect(JsonValueFromJson.to(result.value)).toBe('{"name":"Ada"}');
+ * ```
+ *
  * @group JSON
  */
 export const JsonValueFromJson = /*#__PURE__*/ transform("JsonValueFromJson", Json, JsonValue, {
@@ -3433,7 +4856,7 @@ export const JsonValueFromJson = /*#__PURE__*/ transform("JsonValueFromJson", Js
     to: stringifyJsonValue,
 });
 /**
- * Creates a branded {@link Json} Type and total conversions for another Type.
+ * 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