API reference › @evolu/common › Type

Runtime validation with precise TypeScript types and structured errors.

Evolu 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.

Decoding failures are explicit 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 Brand to their Output, or narrow it to a TypeScript type such as Capitalize<string>.
• Invalid declarations produce readable CompileTimeError types when the compiler can detect them.
• Evolu Type uses runtime assertions to detect bugs that TypeScript cannot prevent, 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 and requires TypeScript 7+ with exactOptionalPropertyTypes enabled.

Examples

Define a domain object with a custom Age Type, then validate unknown input:

import {
  assertEqual,
  Data,
  assertErr,
  assertOk,
  assertType,
  Number,
  NonEmptyTrimmedString100,
  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;

assertType<
  Age,
  number &
    Brand<"NonNaN"> &
    Brand<"Finite"> &
    Brand<"Int"> &
    Brand<"NonNegative"> &
    Brand<"LessThan200"> &
    Brand<"Age">
>();

const User = object({
  name: NonEmptyTrimmedString100,
  age: Age,
});
interface User extends InferType<typeof User> {}

const value: unknown = { name: "Ada", age: 37 };
const user = User.fromUnknown(value);

assertOk(user, { name: "Ada", age: 37 });
assertType<typeof user.value, typeof User.Output>();

const invalidUser = User.fromUnknown({ name: "Ada", age: 37.5 });

assertErr(invalidUser);
// InferErrors includes every structured error User.fromUnknown can return.
assertType<typeof invalidUser.error, InferErrors<typeof User>>();
assertType(Data, invalidUser.error);
assertEqual(invalidUser.error, {
  type: "Object",
  reason: {
    kind: "Properties",
    errors: {
      age: { type: "Int", value: 37.5 },
    },
  },
});

A Type can format its structured errors into user-facing messages:

import { assertEqual, assertType, Data, assertErr, Age } from "@evolu/common";

const age = Age.fromUnknown(37.5);

assertErr(age);
assertType(Data, age.error);
assertEqual(age.error, { type: "Int", value: 37.5 });
assertEqual(
  Age.formatError(age.error),
  "The value 37.5 must be a safe integer.",
);

Use 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:

import {
  assertOk,
  assertType,
  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");
assertOk(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.
assertType<
  typeof validatedTitle,
  Result<NonEmptyTrimmedString100, MaxLengthError<100> | MinLengthError<1>>
>();
assertOk(validatedTitle, "Buy milk");

Evolu includes dozens of predefined Types and Type factories. Use Types such as Age, PositiveInt, DateIso, Email, Uuid, NonEmptyTrimmedString100, Base64Url, and Json directly. Build domain Types with factories such as brand, typed, minLength, maxLength, array, object, union, templateLiteral, transform, discriminatedUnion, and 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 bugs that TypeScript cannot prevent. They are correctness checks, not defenses against malicious code.

Evolu does not support subclassing native JavaScript objects. Such subclasses can be classified as their reported built-in representation, but their behavior is unspecified.

FAQ

What does a Type represent?

A Type is a lawful, pure codec for an exact semantic domain:

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:

fromUnknown(to(output)) ≈ ok(output)

Encoding can canonicalize a valid Input:

"0042" ──decode──▶ 42 ──encode──▶ "42"

Once canonicalized, repeating the decode-encode cycle must preserve that representation:

"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, Array Types, and Object Types preserve these laws when their contained Types do. A 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, 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 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:

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:

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:

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. After that boundary, orThrow throws returned validation errors with a formatted message and the original error as cause, while orNull maps them to null.

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 therefore throw instead of becoming validation 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?

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 normalization.

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 Object defines an open plain-object representation with unknown values, object defines a closed plain-object representation, and record defines a plain-dictionary representation whose complete set of own properties are its entries. Their realm-neutral plain-object rule uses isPlainObject: it accepts a null prototype or an immediate root prototype with own hasOwnProperty and isPrototypeOf properties. A custom root prototype with the same shape can therefore be classified as plain; other custom prototypes and class instances are rejected. This heuristic assumes trusted JavaScript and is not a security boundary. 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. array similarly defines a dense sequence whose only own properties are length and its indexed data properties; tuple applies the same representation rules with a fixed length and a distinct Type for each position. Only an explicit 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.

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 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 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.

Core

Construction

Base

String

Number

Collection

Objects

Unions

Template literals

Discriminated unions

Results

Recursive

JSON

Localization