@evolu/common 8.3.0 → 8.3.1

package/dist/src/Type.js

@@ -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
@@ -418,8 +519,8 @@ const assertTypeOutput = (name, is, validateOutput, value, options = firstValida
  * 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;
@@ -471,8 +572,8 @@ const assertTypeOutput = (name, is, validateOutput, value, options = firstValida
  *
  * ### 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`)
@@ -1941,8 +2042,8 @@ const base64UrlStringToUint8Array = (value) => {
 /**
  * Base64Url text without padding.
  *
- * Encode bytes with {@link uint8ArrayToBase64Url} and decode them with
- * {@link base64UrlToUint8Array}.
+ * Convert bytes to Base64Url with {@link uint8ArrayToBase64Url} and convert
+ * Base64Url to bytes with {@link base64UrlToUint8Array}.
  *
  * @group String
  */
@@ -1953,7 +2054,7 @@ export const Base64Url = /*#__PURE__*/ brand("Base64Url", String, (value) => {
         : err({ type: "Base64Url", value });
 }, (error) => `The value ${safelyStringifyUnknownValue(error.value)} is not a valid Base64Url string.`);
 /**
- * Encodes bytes as {@link Base64Url}.
+ * Converts bytes to {@link Base64Url}.
  *
  * ### Example
  *
@@ -1969,7 +2070,7 @@ export const Base64Url = /*#__PURE__*/ brand("Base64Url", String, (value) => {
  */
 export const uint8ArrayToBase64Url = (bytes) => uint8ArrayToBase64UrlString(bytes);
 /**
- * Decodes {@link Base64Url} as bytes.
+ * Converts {@link Base64Url} to bytes.
  *
  * ### Example
  *
@@ -2225,7 +2326,9 @@ export const Int64String = /*#__PURE__*/ brand("Int64String", NonEmptyTrimmedStr
  * const result = Int64FromInt64String.fromUnknown("9223372036854775807");
  *
  * expectOk(result, 9223372036854775807n);
- * expect(Int64FromInt64String.to(result.value)).toBe("9223372036854775807");
+ * expect(Int64FromInt64String.to(result.value)).toBe(
+ *   "9223372036854775807",
+ * );
  * ```
  *
  * @group Number
@@ -4791,7 +4894,7 @@ export const JsonObject = /*#__PURE__*/ record(String, JsonValue);
  * A {@link String} Brand proving that its exact text parses to {@link JsonValue}.
  *
  * The Brand preserves whitespace, property order, and number spelling. Convert
- * it totally to {@link JsonValue} through {@link JsonValueFromJson} or
+ * it to {@link JsonValue} through {@link JsonValueFromJson} or
  * {@link jsonToJsonValue}.
  *
  * @group JSON
@@ -4801,7 +4904,7 @@ export const Json = /*#__PURE__*/ brand("Json", String, (value) => {
     return result.ok ? ok() : result;
 }, (error) => `The value ${safelyStringifyUnknownValue(error.value)} cannot be parsed into a JsonValue.`);
 /**
- * Totally parses proven {@link Json} text into an exact {@link JsonValue}.
+ * Converts proven {@link Json} text to an exact {@link JsonValue}.
  *
  * ### Example
  *
@@ -4817,7 +4920,7 @@ export const Json = /*#__PURE__*/ brand("Json", String, (value) => {
  */
 export const jsonToJsonValue = (value) => parseJson(value);
 /**
- * Totally encodes an exact {@link JsonValue} as canonical {@link Json} text.
+ * Converts an exact {@link JsonValue} to canonical {@link Json} text.
  *
  * ### Example
  *
@@ -4856,67 +4959,48 @@ export const JsonValueFromJson = /*#__PURE__*/ transform("JsonValueFromJson", Js
     to: stringifyJsonValue,
 });
 /**
- * Branded {@link Json} Type and total conversions for another Type.
- *
- * Use this factory when a domain value must be stored as JSON text while its
- * exact Type remains visible to TypeScript, such as a JSON column in an Evolu
- * Schema. The returned tuple contains the branded Json Type, an encoder from
- * the supplied Type's Output to Json, and a decoder from Json back to that
- * Output.
- *
- * The supplied Type's `CanonicalInput` must be JSON-compatible. The encoder
- * first uses the Type's canonical `to` operation, then encodes that
- * representation as canonical Json. Runtime representation constraints
- * TypeScript cannot prove, such as dense Arrays and enumerable data properties,
- * are asserted as developer errors.
- *
- * The branded Json Type is the validation boundary for unknown JSON text. It
- * grants its {@link Brand} only when the text is valid Json and decoding it
- * through the supplied Type succeeds. The supplied Type is responsible for
- * preserving semantic Outputs across canonical JSON encoding and decoding. This
- * law cannot be checked generically because Types do not define semantic
- * equality. Before granting the Brand, the encoder asserts the weaker runtime
- * guarantee that the final Json successfully decodes through the supplied Type.
- * Failed decodability therefore throws as a developer error.
- *
- * Consequently, the two typed conversions return their values directly without
- * exposing a validation {@link Result}: an Output satisfying the JSON
- * representation contract of a correctly declared Type can always be encoded,
- * and the branded Json proves decoding will succeed. Decoding still runs the
- * Type pipeline because transformations may need to construct different Output
- * values.
+ * Branded {@link Json} Type and conversions for another {@link Type}.
+ *
+ * Use this when a value must be stored as JSON text, such as in a JSON column
+ * in an Evolu Schema. It returns a branded Json Type and functions for
+ * converting the supplied Type's Output to and from that branded JSON
+ * representation.
  *
  * ### Example
  *
  * ```ts
  * import {
  *   Age,
+ *   NonEmptyTrimmedString100,
  *   json,
  *   object,
- *   String,
  *   type Brand,
- *   type InferType,
- *   type Json,
  * } from "@evolu/common";
  *
- * const Person = object({ name: String, age: Age });
- * interface Person extends InferType<typeof Person> {}
+ * const User = object({
+ *   name: NonEmptyTrimmedString100,
+ *   age: Age,
+ * });
  *
- * const [PersonJson, personToPersonJson, personJsonToPerson] = json(
- *   Person,
- *   "PersonJson",
+ * const [UserJson, userToUserJson, userJsonToUser] = json(
+ *   User,
+ *   "UserJson",
  * );
- * type PersonJson = typeof PersonJson.Output;
- *
- * expectTypeOf<PersonJson>().toEqualTypeOf<Json & Brand<"PersonJson">>();
  *
- * const 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 = (type, name, ..._validation) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/common",
-  "version": "8.3.0",
+  "version": "8.3.1",
   "description": "TypeScript library and local-first platform",
   "keywords": [
     "evolu",