@evolu/common 8.3.0 → 8.3.2

package/src/Type.ts

@@ -8,17 +8,84 @@
  * valid `Output` into a `CanonicalInput`. Types can validate, refine,
  * transform, and compose without losing the contracts TypeScript can express.
  *
+ * Decoding failures are explicit {@link Result} values, and their structured
+ * errors preserve the exact error types each Type can return.
+ *
+ * Evolu Type is designed to make correct code the easiest code to write:
+ *
+ * - Predefined constraints add a {@link Brand} to their Output.
+ * - Invalid declarations produce readable {@link CompileTimeError} types when the
+ *   compiler can detect them.
+ * - Evolu Type uses runtime {@link assert | assertions} to detect developer errors
+ *   that TypeScript cannot express, such as excess properties and sparse
+ *   arrays.
+ * - Typed `from` boundaries allow connecting value producers to domain fields
+ *   through their exact TypeScript types, so incompatible contract changes are
+ *   compile-time errors rather than runtime validation errors.
+ * - Lawful codecs compose without creating unencodable values: every valid Output
+ *   has a canonical Input representation and round-trips to the same semantic
+ *   value.
+ * - Type-safe localization infers the required error formatters from selected
+ *   Types, so missing validation messages are compile-time errors.
+ *
+ * Correctness is especially important for local-first data: application authors
+ * cannot inspect or repair a user's data.
+ *
+ * Evolu Type is optimized for small real-world bundles: composed Types share
+ * runtime code, while unused validators and formatters are tree-shaken. It
+ * could be smaller with less descriptive assertion messages, but Evolu favors
+ * actionable diagnostics over micro-optimizing isolated Types.
+ *
+ * Predefined Types use the names of corresponding JavaScript built-ins. When a
+ * Type shadows one, access the JavaScript built-in through `globalThis`, such
+ * as `globalThis.String` or `globalThis.Date`.
+ *
+ * Evolu Type supports [Standard Schema](https://standardschema.dev/) and
+ * requires TypeScript 7+ with `exactOptionalPropertyTypes` enabled.
+ *
+ * ## Examples
+ *
+ * Define a domain object with a custom `Age` Type, then validate unknown input:
+ *
  * ```ts
  * import {
+ *   Number,
  *   NonEmptyTrimmedString100,
- *   PositiveInt,
+ *   brand,
+ *   finite,
+ *   int,
+ *   lessThan,
+ *   nonNaN,
+ *   nonNegative,
  *   object,
+ *   type Brand,
+ *   type InferErrors,
  *   type InferType,
  * } from "@evolu/common";
  *
+ * // Age and its parent Types are predefined by Evolu. They are reconstructed
+ * // here to reveal every constraint behind a seemingly simple domain value.
+ * const NonNaNNumber = nonNaN(Number);
+ * const FiniteNumber = finite(NonNaNNumber);
+ * const Int = int(FiniteNumber);
+ * const NonNegativeInt = nonNegative(Int);
+ *
+ * const Age = brand("Age", lessThan(200)(NonNegativeInt));
+ * type Age = typeof Age.Output;
+ *
+ * expectTypeOf<Age>().toEqualTypeOf<
+ *   number &
+ *     Brand<"NonNaN"> &
+ *     Brand<"Finite"> &
+ *     Brand<"Int"> &
+ *     Brand<"NonNegative"> &
+ *     Brand<"LessThan200"> &
+ *     Brand<"Age">
+ * >();
+ *
  * const User = object({
  *   name: NonEmptyTrimmedString100,
- *   age: PositiveInt,
+ *   age: Age,
  * });
  * interface User extends InferType<typeof User> {}
  *
@@ -27,74 +94,114 @@
  *
  * expectOk(user, { name: "Ada", age: 37 });
  * expectTypeOf(user.value).toExtend<User>();
+ *
+ * const invalidUser = User.fromUnknown({ name: "Ada", age: 37.5 });
+ *
+ * expectErr(invalidUser, {
+ *   type: "Object",
+ *   reason: {
+ *     kind: "Properties",
+ *     errors: {
+ *       age: { type: "Int", value: 37.5 },
+ *     },
+ *   },
+ * });
+ *
+ * // InferErrors includes every structured error User.fromUnknown can return.
+ * expectTypeOf(invalidUser.error).toEqualTypeOf<
+ *   InferErrors<typeof User>
+ * >();
  * ```
  *
- * 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.
+ * A Type can format its structured errors into user-facing messages:
  *
- * Evolu Type is designed to make correct code the easiest code to write:
+ * ```ts
+ * import { Age } from "@evolu/common";
  *
- * - {@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.
+ * const age = Age.fromUnknown(37.5);
  *
- * 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.
+ * expectErr(age, { type: "Int", value: 37.5 });
+ * expect(Age.formatError(age.error)).toBe(
+ *   "The value 37.5 must be a safe integer.",
+ * );
+ * ```
+ *
+ * Use {@link localizeTypes} to derive Types with localized messages without
+ * changing validation behavior.
+ *
+ * One of Evolu Type's strongest features is typed `from` boundaries. A value
+ * producer, such as a form input, carries the precise constraints it
+ * guarantees, and TypeScript checks them against the consuming domain field.
+ * Unlike validation from `unknown` or `string`, this checks the contract
+ * between the producer and consumer, not merely whether the current value
+ * passes:
+ *
+ * ```ts
+ * import {
+ *   NonEmptyTrimmedString100,
+ *   NonEmptyTrimmedString1000,
+ *   object,
+ *   trim,
+ *   type MaxLengthError,
+ *   type MinLengthError,
+ *   type Result,
+ *   type TrimmedString,
+ * } from "@evolu/common";
+ *
+ * const Todo = object({ title: NonEmptyTrimmedString100 });
+ *
+ * // This is type-checked: Todo.from expects NonEmptyTrimmedString100.
+ * const title = NonEmptyTrimmedString100.orThrow("Buy milk");
+ * expectOk(Todo.from({ title }), { title });
+ *
+ * // Imagine the UI input component is changed to allow longer titles.
+ * // TypeScript rejects the mismatch, so users never see a save error
+ * // for a title the UI accepts but the domain cannot save.
+ * const longerTitle = NonEmptyTrimmedString1000.orThrow("Buy milk");
+ * // @ts-expect-error MaxLength1000 does not guarantee MaxLength100.
+ * Todo.from({ title: longerTitle });
+ *
+ * // Imagine a UI input component that returns TrimmedString.
+ * // from.parent.parent connects it to the domain field and validates the
+ * // remaining constraints.
+ * const titleFromTrimmingInput: TrimmedString = trim("  Buy milk  ");
+ * const validatedTitle = Todo.props.title.from.parent.parent(
+ *   titleFromTrimmingInput,
+ * );
+ *
+ * // No "not a string" or "not trimmed" errors: the input guarantees both.
+ * expectTypeOf(validatedTitle).toEqualTypeOf<
+ *   Result<
+ *     NonEmptyTrimmedString100,
+ *     MaxLengthError<100> | MinLengthError<1>
+ *   >
+ * >();
+ * expectOk(validatedTitle, "Buy milk");
+ * ```
+ *
+ * Evolu includes dozens of predefined Types and Type factories. Use Types such
+ * as {@link Age}, {@link PositiveInt}, {@link DateIso},
+ * {@link NonEmptyTrimmedString100}, {@link Base64Url}, and {@link Json} directly.
+ * Build domain Types with factories such as {@link brand}, {@link typed},
+ * {@link minLength}, {@link maxLength}, {@link array}, {@link object},
+ * {@link union}, {@link templateLiteral}, {@link transform},
+ * {@link discriminatedUnion}, and {@link json}.
+ *
+ * ## Guarantees
+ *
+ * Evolu Type validates values; it does not defend against adversarial
+ * JavaScript such as malicious Proxies, mutation during validation, throwing
+ * traps, forged built-ins, or code deliberately bypassing TypeScript with `any`
+ * or casts.
+ *
+ * Evolu Type trusts application code and audited dependencies. Untrusted code
+ * can cause harm far beyond validation and must not run in the application.
+ * Defending against it would add complexity without creating a meaningful
+ * security boundary.
+ *
+ * Runtime assertions still detect accidental developer errors that TypeScript
+ * cannot express. They are correctness checks, not defenses against malicious
+ * code.
  *
  * ## FAQ
  *
@@ -244,24 +351,18 @@
  *
  * ### 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.
+ * Values returned by legacy code or another realm can still be uncertain and
+ * should be validated. Realm-neutral Types accept an otherwise legitimate
+ * representation without requiring conversion merely because its JavaScript
+ * built-ins belong to another realm.
  *
  * When an application trusts both the producer and its return contract, expose
- * that contract as an accurate TypeScript type and use the typed value directly.
- * If the boundary returns `unknown`, validate it instead of bypassing the
- * boundary with a cast. Use a specialized Type or explicit transformation when
- * the producer uses a different representation that needs adaptation or
+ * 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
@@ -485,7 +586,7 @@ export interface Type<
 
   /**
    * Formats an error returned by `fromUnknown` or `from` as one human-readable
-   * message. Built-in Types use English; {@link localizeTypes} derives Types
+   * message. Predefined Types use English; {@link localizeTypes} derives Types
    * with localized formatters.
    *
    * Structural errors retain nested errors and their locations in the typed
@@ -723,7 +824,7 @@ interface TransparentTypeError {
  *
  * @group Core
  */
-// Built-in errors intentionally repeat narrower `value` properties. Making
+// Predefined errors intentionally repeat narrower `value` properties. Making
 // `value` generic here and sharing this base regresses `pnpm bench:type`.
 export interface TypeValueError<
   Name extends TypeName = TypeName,
@@ -938,8 +1039,8 @@ const assertTypeOutput = <Error extends TypeError>(
  * 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.
+ * Types. Every locale must provide the complete inferred formatter set; missing
+ * and unrelated formatters are compile-time errors.
  *
  * The result preserves the locale names, selected Type names, and exact
  * TypeScript types. A localized Type validates exactly like its source Type;
@@ -991,8 +1092,8 @@ const assertTypeOutput = <Error extends TypeError>(
  *
  * ### Supported locales
  *
- * English is built in; use {@link Type} directly for its default formatters.
- * The following additional locales are available:
+ * English is built in; use {@link Type} directly for its default formatters. The
+ * following additional locales are available:
  *
  * - Arabic (`ar`)
  * - Bengali (`bn`)
@@ -2029,9 +2130,9 @@ const createChildType = <
  * canonicalize multiple parent representations, but it must be total and must
  * not lose distinctions present in the Output domain.
  *
- * Transformation callbacks are Type construction code. Their successful
- * results are asserted against the declared boundary so a broken callback fails
- * as a developer error rather than becoming a validation error. Like all
+ * Transformation callbacks are Type construction code. Their successful results
+ * are asserted against the declared boundary so a broken callback fails as a
+ * developer error rather than becoming a validation error. Like all
  * Type-construction callbacks, they are trusted to follow their declared
  * TypeScript types. A `Result<_, never>` callback is therefore trusted never to
  * return an `Err`.
@@ -2047,13 +2148,7 @@ const createChildType = <
  * ### Example
  *
  * ```ts
- * import {
- *   Boolean,
- *   literal,
- *   ok,
- *   transform,
- *   union,
- * } from "@evolu/common";
+ * import { Boolean, literal, ok, transform, union } from "@evolu/common";
  *
  * const BooleanString = union(literal("false"), literal("true"));
  * const BooleanFromString = transform(
@@ -2815,18 +2910,18 @@ interface ObjectTagOutputByName {
 /**
  * Realm-neutral {@link Type} trusting an object's reported tag.
  *
- * Predefined built-in tags expose their native Output type under the assumption
- * that trusted code does not forge their tags. They do not verify native
- * internal slots. A custom tag refines the supplied Type and adds nominal
- * evidence to its Output, so only a value validated by the resulting Type is
- * accepted by its typed operations.
+ * Predefined tags for JavaScript built-ins expose their native Output type
+ * under the assumption that trusted code does not forge their tags. They do not
+ * verify native internal slots. A custom tag refines the supplied Type and adds
+ * nominal evidence to its Output, so only a value validated by the resulting
+ * Type is accepted by its typed operations.
  *
- * `Object.prototype.toString` recognizes legitimate built-ins from another
- * realm, but any object can customize the result with `Symbol.toStringTag`.
- * Types returned by this factory therefore classify trusted values; they are
- * not security boundaries. Passing a forged built-in tag violates the trust
- * assumption of the predefined Type. Primitive Outputs are rejected at compile
- * time.
+ * `Object.prototype.toString` recognizes legitimate JavaScript built-ins from
+ * another realm, but any object can customize the result with
+ * `Symbol.toStringTag`. Types returned by this factory therefore classify
+ * trusted values; they are not security boundaries. Passing a forged JavaScript
+ * built-in tag violates the trust assumption of the predefined Type. Primitive
+ * Outputs are rejected at compile time.
  *
  * ### Example
  *
@@ -5331,8 +5426,8 @@ const base64UrlStringToUint8Array = (value: string): Uint8Array => {
 /**
  * Base64Url text without padding.
  *
- * Encode bytes with {@link uint8ArrayToBase64Url} and decode them with
- * {@link base64UrlToUint8Array}.
+ * Convert bytes to Base64Url with {@link uint8ArrayToBase64Url} and convert
+ * Base64Url to bytes with {@link base64UrlToUint8Array}.
  *
  * @group String
  */
@@ -5361,7 +5456,7 @@ export interface Base64UrlError extends TypeError<"Base64Url"> {
 }
 
 /**
- * Encodes bytes as {@link Base64Url}.
+ * Converts bytes to {@link Base64Url}.
  *
  * ### Example
  *
@@ -5379,7 +5474,7 @@ export const uint8ArrayToBase64Url = (bytes: Uint8Array): Base64Url =>
   uint8ArrayToBase64UrlString(bytes) as Base64Url;
 
 /**
- * Decodes {@link Base64Url} as bytes.
+ * Converts {@link Base64Url} to bytes.
  *
  * ### Example
  *
@@ -5823,7 +5918,9 @@ export interface Int64StringError extends TypeError<"Int64String"> {
  * const result = Int64FromInt64String.fromUnknown("9223372036854775807");
  *
  * expectOk(result, 9223372036854775807n);
- * expect(Int64FromInt64String.to(result.value)).toBe("9223372036854775807");
+ * expect(Int64FromInt64String.to(result.value)).toBe(
+ *   "9223372036854775807",
+ * );
  * ```
  *
  * @group Number
@@ -8467,7 +8564,7 @@ type PlainObjectError = ObjectError<
  *
  * @group Base
  */
-export const Object: Type<
+const _Object: Type<
   "Object",
   Readonly<Record<string, unknown>>,
   Readonly<Record<string, unknown>>,
@@ -8588,6 +8685,13 @@ export const Object: Type<
   }) as TypeErrorFormatter<TypeError>),
 );
 
+// Avoid a local `Object` binding because Babel's CommonJS transform injects
+// `Object.defineProperty` before it is initialized:
+// https://github.com/babel/babel/issues/16943
+// https://github.com/react/metro/issues/1331
+// https://github.com/expo/expo/issues/31167
+export { _Object as Object };
+
 const isPlainObject = (value: object): boolean => {
   const prototype: unknown = globalThis.Object.getPrototypeOf(value);
   return (
@@ -10280,10 +10384,10 @@ export interface ObjectNotObjectError extends TypeError<"Object"> {
  *
  * Object Types accept a `null` prototype or a prototype whose own prototype is
  * `null`. This includes ordinary and cross-realm plain objects as well as
- * objects created from an immediate root prototype. Arrays, built-in objects,
- * class instances, and objects with deeper custom prototype chains return this
- * error instead of having their prototype or inherited state discarded.
- * `reason.value` is the rejected object.
+ * objects created from an immediate root prototype. Arrays, JavaScript built-in
+ * objects, class instances, and objects with deeper custom prototype chains
+ * return this error instead of having their prototype or inherited state
+ * discarded. `reason.value` is the rejected object.
  *
  * @group Objects
  */
@@ -10634,8 +10738,8 @@ type OmitKeyConcreteTypeError = CompileTimeError<
  * Creates a {@link Type} for {@link Result} values.
  *
  * Use this to validate Results crossing a storage, worker, API, or other
- * serialization boundary. `fromUnknown` returns an outer validation Result.
- * Its successful value is the inner domain Result described by `okType` and
+ * serialization boundary. `fromUnknown` returns an outer validation Result. Its
+ * successful value is the inner domain Result described by `okType` and
  * `errorType`.
  *
  * ### Example
@@ -10844,7 +10948,8 @@ export interface Typed<Tag extends TypeName> {
  * Extracts members of a {@link Typed} Output union by their `type` literal.
  *
  * The requested tag is constrained to the union's actual discriminator values,
- * so a misspelling is a TypeScript error instead of silently producing `never`.
+ * so a misspelling is a TypeScript error instead of silently producing
+ * `never`.
  *
  * ### Example
  *
@@ -12517,7 +12622,7 @@ export const JsonObject = /*#__PURE__*/ record(
  * A {@link String} Brand proving that its exact text parses to {@link JsonValue}.
  *
  * The Brand preserves whitespace, property order, and number spelling. Convert
- * it totally to {@link JsonValue} through {@link JsonValueFromJson} or
+ * it to {@link JsonValue} through {@link JsonValueFromJson} or
  * {@link jsonToJsonValue}.
  *
  * @group JSON
@@ -12536,7 +12641,7 @@ export const Json = /*#__PURE__*/ brand(
 export type Json = typeof Json.Output;
 
 /**
- * Totally parses proven {@link Json} text into an exact {@link JsonValue}.
+ * Converts proven {@link Json} text to an exact {@link JsonValue}.
  *
  * ### Example
  *
@@ -12553,7 +12658,7 @@ export type Json = typeof Json.Output;
 export const jsonToJsonValue = (value: Json): JsonValue => parseJson(value);
 
 /**
- * Totally encodes an exact {@link JsonValue} as canonical {@link Json} text.
+ * Converts an exact {@link JsonValue} to canonical {@link Json} text.
  *
  * ### Example
  *
@@ -12600,67 +12705,48 @@ export const JsonValueFromJson = /*#__PURE__*/ transform(
 );
 
 /**
- * Branded {@link Json} Type and total conversions for another Type.
- *
- * Use this factory when a domain value must be stored as JSON text while its
- * exact Type remains visible to TypeScript, such as a JSON column in an Evolu
- * Schema. The returned tuple contains the branded Json Type, an encoder from
- * the supplied Type's Output to Json, and a decoder from Json back to that
- * Output.
- *
- * The supplied Type's `CanonicalInput` must be JSON-compatible. The encoder
- * first uses the Type's canonical `to` operation, then encodes that
- * representation as canonical Json. Runtime representation constraints
- * TypeScript cannot prove, such as dense Arrays and enumerable data properties,
- * are asserted as developer errors.
- *
- * The branded Json Type is the validation boundary for unknown JSON text. It
- * grants its {@link Brand} only when the text is valid Json and decoding it
- * through the supplied Type succeeds. The supplied Type is responsible for
- * preserving semantic Outputs across canonical JSON encoding and decoding. This
- * law cannot be checked generically because Types do not define semantic
- * equality. Before granting the Brand, the encoder asserts the weaker runtime
- * guarantee that the final Json successfully decodes through the supplied Type.
- * Failed decodability therefore throws as a developer error.
- *
- * Consequently, the two typed conversions return their values directly without
- * exposing a validation {@link Result}: an Output satisfying the JSON
- * representation contract of a correctly declared Type can always be encoded,
- * and the branded Json proves decoding will succeed. Decoding still runs the
- * Type pipeline because transformations may need to construct different Output
- * values.
+ * Branded {@link Json} Type and conversions for another {@link Type}.
+ *
+ * Use this when a value must be stored as JSON text, such as in a JSON column
+ * in an Evolu Schema. It returns a branded Json Type and functions for
+ * converting the supplied Type's Output to and from that branded JSON
+ * representation.
  *
  * ### Example
  *
  * ```ts
  * import {
  *   Age,
+ *   NonEmptyTrimmedString100,
  *   json,
  *   object,
- *   String,
  *   type Brand,
- *   type InferType,
- *   type Json,
  * } from "@evolu/common";
  *
- * const Person = object({ name: String, age: Age });
- * interface Person extends InferType<typeof Person> {}
+ * const User = object({
+ *   name: NonEmptyTrimmedString100,
+ *   age: Age,
+ * });
  *
- * const [PersonJson, personToPersonJson, personJsonToPerson] = json(
- *   Person,
- *   "PersonJson",
+ * const [UserJson, userToUserJson, userJsonToUser] = json(
+ *   User,
+ *   "UserJson",
  * );
- * type PersonJson = typeof PersonJson.Output;
- *
- * expectTypeOf<PersonJson>().toEqualTypeOf<Json & Brand<"PersonJson">>();
  *
- * const person = Person.orThrow({ name: "Ada", age: 42 });
- * const personJson = personToPersonJson(person);
- * const decodedPerson = personJsonToPerson(personJson);
+ * const user = User.orThrow({ name: "Ada", age: 37 });
+ * const userJson = userToUserJson(user);
  *
- * expect(decodedPerson).toEqual(person);
+ * expectTypeOf(userJson).toEqualTypeOf<
+ *   string & Brand<"Json"> & Brand<"UserJson">
+ * >();
+ * expect(userJson).toBe('{"name":"Ada","age":37}');
+ * expect(userJsonToUser(userJson)).toEqual(user);
  * ```
  *
+ * The supplied Type must have a JSON-compatible `CanonicalInput`. The branded
+ * Json Type accepts only valid JSON text whose parsed value can be decoded by
+ * the supplied Type.
+ *
  * @group JSON
  */
 export const json = <T extends ConcreteTypeNode, Name extends TypeName>(