API reference / @evolu/common / Type / LiteralType

Interface: LiteralType<T>

Defined in: packages/common/src/Type.ts:2263

Evolu Type is like a type guard that returns typed errors (via Result) instead of throwing. We either get a safely typed value or a composable typed error telling us exactly why validation failed.

Why another validation library?

• Result-based error handling – no exceptions for normal control flow.
• Typed errors with decoupled formatters – validation logic ≠ user messages.
• Consistent constraints via Brand – every constraint becomes part of the type.
• Skippable validation – parent validations can be skipped when already proved by types.
• Simple, top-down implementation – readable source code from top to bottom.
• No user-land chaining DSL – prepared for TC39 Hack pipes.

A distinctive feature of Evolu Type compared to other validation libraries is that it returns typed errors rather than string messages. This allows TypeScript to enforce that all validation errors are handled by type checking, significantly improving the developer experience.

Evolu Type supports Standard Schema for interoperability with 40+ validation-compatible tools and frameworks.

Base Types Quick Start

// Validate unknown values
const value: unknown = "hello";
const stringResult = String.fromUnknown(value);
if (!stringResult.ok) {
  // console.error(formatStringError(stringResult.error));
  return stringResult; // inside a function returning Result<string, _>
}
// Safe branch: value is now string
const upper = stringResult.value.toUpperCase();

// Type guard style
if (String.is(value)) {
  // narrowed to string
}

// Composing: arrays & objects
const Numbers = array(Number); // ReadonlyArray<number>
const Point = object({ x: Number, y: Number });

Numbers.from([1, 2, 3]); // ok
Point.from({ x: 1, y: 2 }); // ok
Point.from({ x: 1, y: "2" }); // err -> nested Number error

Branding Basics

Branding adds semantic meaning & constraints while preserving the runtime shape:

const CurrencyCode = brand("CurrencyCode", String, (value) =>
  /^[A-Z]{3}$/.test(value)
    ? ok(value)
    : err<CurrencyCodeError>({ type: "CurrencyCode", value }),
);
type CurrencyCode = typeof CurrencyCode.Type; // string & Brand<"CurrencyCode">

interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}

const formatCurrencyCodeError = createTypeErrorFormatter<CurrencyCodeError>(
  (error) => `Invalid currency code: ${error.value}`,
);

const r = CurrencyCode.from("USD"); // ok("USD")
const e = CurrencyCode.from("usd"); // err(...)

See also reusable brand factories like minLength, maxLength, trimmed, positive, between, etc.

Objects & Optional Fields

const User = object({
  name: NonEmptyTrimmedString100,
  age: optional(PositiveInt),
});
type User = typeof User.Type;

User.from({ name: "Alice" }); // ok
User.from({ name: "Alice", age: -1 }); // err(PositiveInt)

Deriving JSON String Types

const Person = object({
  name: NonEmptyString50,
  // Did you know that JSON.stringify converts NaN (a number) into null?
  // To prevent this, use FiniteNumber.
  age: FiniteNumber,
});
type Person = typeof Person.Type;

const [PersonJson, personToPersonJson, personJsonToPerson] = json(
  Person,
  "PersonJson",
);
// string & Brand<"PersonJson">
type PersonJson = typeof PersonJson.Type;

const person = Person.orThrow({
  name: "Alice",
  age: 30,
});

const personJson = personToPersonJson(person);
expect(personJsonToPerson(personJson)).toEqual(person);

Error Formatting

Evolu separates validation logic from human-readable messages. There are two layers:

1. Per-type formatters (e.g. formatStringError) – simple, focused, already used earlier in the quick start example.
2. A unified formatter via createFormatTypeError – composes all built-in and custom errors (including nested composite types) and lets us override selected messages.

1. Per-Type Formatter (recap)

const r = String.fromUnknown(42);
if (!r.ok) console.error(formatStringError(r.error));

2. Unified Formatter with Overrides

// Override only what we care about; fall back to built-ins for the rest.
const formatTypeError = createFormatTypeError((error) => {
  if (error.type === "MinLength") return `Min length is ${error.min}`;
});

const User = object({ name: NonEmptyTrimmedString100 });
const resultUser = User.from({ name: "" });
if (!resultUser.ok) console.error(formatTypeError(resultUser.error));

const badPoint = object({ x: Number, y: Number }).from({
  x: 1,
  y: "foo",
});
if (!badPoint.ok) console.error(formatTypeError(badPoint.error));

The unified formatter walks nested structures (object / array / record / tuple / union) and applies overrides only where specified, greatly reducing boilerplate when formatting complex validation errors.

Tip

If necessary, write globalThis.String instead of String to avoid naming clashes with native types.

Design Decision: No Bidirectional Transformations

Evolu Type intentionally does not support bidirectional transformations. It previously did, but supporting that while keeping typed error fidelity added complexity that hurt readability & reliability. Most persistence pipelines (e.g. SQLite) already require explicit mapping of query results, so implicit reverse transforms would not buy much. We may revisit this if we can design a minimal, 100% safe API that preserves simplicity.

Prepared for TC39 Hack Pipes

Take a look how SimplePassword is defined:

export const SimplePassword = brand(
  "SimplePassword",
  minLength(8)(maxLength(64)(TrimmedString)),
);

Nested functions are often OK (if not, make a helper) and read well, but with TC39 Hack pipes it would be clearer:

// TrimmedString
//   |> minLength(8)(%)
//   |> maxLength(64)(%)
//   |> brand("SimplePassword", %)

Note minLength and maxLength are curried because they are factories.

Extends

• Type<"Literal", T, WidenLiteral<T>, LiteralError<T>>

Type Parameters

Properties