TypeScript API reference#

Everything a generated module exports, and what each field type becomes at runtime.

Generated exports#

Per struct#

Export

Kind

What it is

<Name>Schema

const

The valibot schema. Composable.

<Name>

interface

The validated shape.

<Name>

const

{ validate(input: unknown): <Name> }. Throws on failure.

<Name>Shape

interface

The same shape under its own name.

<Struct><Field>Window

const

{ from, to } for a time field that declares a window.

<Name>Summary

interface

Only with a summary: what a listing item’s fields holds, each summary field, and a top_level struct’s key; an embedded struct as its own <Embedded>Summary.

<Name>SummarySchema

const

Only with a summary: the schema decoding it.

The interface and the const share a name deliberately: TypeScript keeps types and values in separate declaration spaces, so <Name> works as both.

Per enum#

Export

Kind

What it is

<Name>

const

A frozen object mapping member name to value.

<Name>

type

The union of that object’s values.

<Name>Schema

const

v.enum of <Name>.

Per union#

Export

Kind

What it is

<Name>

type

The union of every variant type.

<Name>Schema

const

v.variant over every variant schema, keyed on <tagName>.

<Name>

const

{ validate(input: unknown): <Name> }.

<Name><Variant>

interface

One variant: its tag, and its inner_type as value.

<Name><Variant>Schema

const

That variant’s schema, with the tag pinned to a literal.

<Name><Variant>

const

That variant’s validate.

Per route#

Export

Kind

What it is

<Name>

interface

{ handle(request): Promise<Resp<Success, Error>> }; Success is Record<never, never> for a route without a success_response.

<Name>Path

const

The route’s path, placeholders included.

<camelName>Url

function

Only with placeholders: builds the URL path from the fields they name.

<camelName>

function

Calls the route: (request, init?) => Promise<RouteResp<Success, Error>>.

Per model#

Export

Kind

What it is

rest

const

Only with [tool.model.go.rest]: each REST resource’s client, by struct name, and search when a table is searchable. See REST resources.

SearchItem

type

Only with a searchable table: an item of rest.search, a TypedItem per searchable struct.

<Name>ReferencedByItem

type

Only on a struct something refers to: an item of its referencedBy, a TypedItem per referring struct.

<Name>RelatedItem

type

Only on a struct with related rows: an item of its related, a TypedItem of a RelatedItem per related struct.

<Name>Urls

interface

Only with [tool.model.go.rest]: the URLs a row of the struct carries, self and each endpoint it serves. See Following a row’s URLs.

@omniblack/model-runtime#

What generated modules import, see Dependencies. A module imports only the names it uses, and a name it uses only as a type, such as Resp, with import type, so the compiler erases it. The package also exports the metadata types.

export type Resp<S, E> =
    | ({ is_success: true } & S)
    | ({ is_success: false } & E);

export interface RouteStatus {
    readonly status: number;
    readonly is_created: boolean; // 201
    readonly is_accepted: boolean; // 202
    readonly is_no_content: boolean; // 204
}

export type RouteResp<S, E> = Resp<S, E> & RouteStatus;

export function isPlainObject(value: unknown): boolean;

export class ModelMap<K, V> implements Map<K, V> {
    constructor(entries?: Iterable<readonly [K, V]> | null);
    pop(key: K): V | undefined;
    toJSON(): Record<string, V>;
}

export class Ref<T, K> {
    constructor(key: K);
    readonly key: K;
    resolve(init?: RequestInit): Promise<RestResp<T>>;
    toJSON(): K;
}

export function registerIdentityKeyClass(
    cls: abstract new (...args: never) => unknown,
): void;

export function parseZonedDateTime(value: string): Temporal.ZonedDateTime;
export function isZonedDateTime(value: string): boolean;

export class HttpError extends Error {
    readonly status: number;
    readonly body: string;
}

export type RestResp<T> =
    | { is_success: true; value: T; etag: string | null }
    | { is_success: false; problem: Problem };

export interface Problem {
    type?: string;
    title: string;
    status: number;
    detail?: string;
    errors?: FieldError[];
    existing_errors?: FieldError[];
}

export interface ListItem<F = unknown> {
    type?: string;
    fields: F;
    title?: string;
    title_html?: string;
    subtitle?: string;
    subtitle_html?: string;
    url?: string;
    image?: string;
}

export interface RelatedItem<F = unknown> extends ListItem<F> {
    relation: Relation;
}

export type TypedItem<N extends string, I extends ListItem<unknown>> = I & {
    type: N;
};

export class Page<T extends ListItem<unknown> = ListItem> {
    readonly items: readonly T[];
    readonly next: string | null;
    readonly prev: string | null;
}

export type Linked<T, U> = T & { readonly [urls]?: U };
export type UrlsOf<O>; // the U of a Linked O

export class Link<T, O = undefined> {
    readonly href: string;
    toString(): string; // href
    toJSON(): string; // href
}

export class FileLink<F extends string> {
    readonly href: string;
    url(client: BaseClient, field: F, ...steps: string[]): string;
}

export interface DirEntry {
    readonly name: string;
    readonly dir: boolean;
    readonly size: number;
    readonly modified?: Temporal.Instant;
}

export class RootFiles {
    constructor(client: BaseClient, prefix: string);
    url(path?: string): string;
    dirUrl(path?: string): string;
    list(path?: string, init?: CallInit): Promise<RestResp<DirEntry[]>>;
    fetch(path: string, init?: CallInit): Promise<RestResp<Response>>;
}

export class BaseClient {
    get<T, O>(link: Link<T, O>, options?: O, init?: CallInit): Promise<RestResp<T>>;
    urls<O extends object>(obj: O): UrlsOf<O>;
    follow<O extends object, K extends LinkRel<UrlsOf<O>>>(
        obj: O,
        rel: K,
        options?: LinkOptions<UrlsOf<O>[K]>,
        init?: CallInit,
    ): Promise<RestResp<LinkTarget<UrlsOf<O>[K]>>>;
}

export type MergePatch<T> = { [K in keyof T]?: T[K] | null };

export function toWireJson(value: unknown): string;
export function fromWireJson(text: string): unknown;

HttpError is what a generated call throws for a response it cannot read as the endpoint’s. RestResp, Problem, Page and MergePatch are the types a REST resource’s methods take and give. A ListItem’s fields is its struct’s <Name>Summary, or, for a struct without a summary, an object of its key fields; a listing of several structs’ rows is a union of TypedItems, which type narrows. A Problem is RFC 9457 problem details: errors are the body’s field errors, and existing_errors those the stored row already had, when an update was refused for adding errors of its own.

A row or listing item the client decoded is a Linked one, carrying the URLs the server sent for it, a generated <Name>Urls, under a symbol only the runtime reads. BaseClient.urls reads them, throwing a TypeError for an object that carries none, and BaseClient.follow fetches one by name. A Link is a URL the server sent and how to decode what it names, which BaseClient.get fetches. A FileLink builds the URL of a file below a row. An absolute URL, as the server sends under a public URL, is fetched as it is, ignoring the client’s base. See Following a row’s URLs.

A RootFiles is a root endpoint on a client’s server, and a DirEntry one entry of the directory listing it reads.

toWireJson and fromWireJson are the model’s JSON wire form: JSON.stringify() and JSON.parse(), but for writing a bigint as a bare number, and reading an integer too large for a number as a bigint.

isPlainObject is true only for genuine plain objects — object literals and Object.create(null). Class instances such as Map, Set, Array, and Decimal are rejected even when they expose no own enumerable keys, which is why a bare v.strictObject cannot be trusted to exclude them. The map schemas use it to tell an object literal from something that merely looks like one.

ModelMap is the value a map field holds. It has the whole Map API, and compares keys by their value, not by identity: two Decimal keys, or two Temporal.PlainDate keys, are the same key when they hold the same value, so 1.0 and 1 are one key. Two Temporal.ZonedDateTime keys are the same key when they are the same instant, even written in different zones, and two Refs when their keys are. Like a Map, it keeps the order its keys were first set in; setting an existing key keeps its position. pop removes a key and returns its value. toJSON writes it as an object keyed by each key’s text, in that order, so JSON.stringify() encodes it. A Map would encode as {}. It is not a Map instance, so check for it with instanceof ModelMap. Every generated module shares the one class, so a ModelMap built for one model is accepted by another’s map schemas.

Ref is the base of the <Target>Ref class a ref field holds: its target’s primary key, as key. It is written back out as the bare key. Its own resolve rejects; a generated <Target>Ref whose struct the server serves a REST resource of overrides it (see References).

A ModelMap keys an object by its text, so two equal Decimals are one key. registerIdentityKeyClass exempts a class with one object per value, whose instances are then keyed by identity. A generated module registers libnerd_font’s Glyph when it imports it. Registering a class twice is harmless.

parseZonedDateTime reads a datetime’s text, RFC 9557: 2026-10-06T21:00:00-04:00[America/New_York]. It also reads a plain RFC 3339 timestamp, taking Z as the zone UTC and a numeric offset as a zone fixed at it. It throws a RangeError for a timestamp with no offset, an unknown zone, an offset the zone does not have at that instant, or a critical (!) annotation other than the zone. It reads exactly what go-runtime’s ZonedTime and Python’s model.zoned_datetime read, but for a bare offset with seconds, which Temporal has no zone for. isZonedDateTime is true when it would succeed. A datetime schema checks with one and converts with the other.

@omniblack/model-runtime/svelte#

What a Svelte module imports in place of the plain runtime’s names. It needs svelte 5, an optional peer dependency of the package.

export class ModelMap<K, V> extends PlainModelMap<K, V> {}

ModelMap holds its entries in a SvelteMap, so reading it in an effect or a $derived tracks what was read, and set, delete and clear notify. It extends the plain ModelMap, so it compares, orders and encodes its keys as that one does, and every map schema accepts it.

Runtime types#

What a validated value actually holds:

Model type

TypeScript type

Runtime value

boolean

boolean

a boolean

string, path

string

a string

integer

bigint

a BigInt

decimal

Decimal

a Decimal from decimal.js

estimate

number

a number

time

string

"HH:MM:SS"

datetime

Temporal.ZonedDateTime

a Temporal.ZonedDateTime, assumed global

list

Array<T>

an Array

map

ModelMap<K, V>

a ModelMap, even when a Map or a plain object went in

model

the referenced type

that type’s validated shape

Optional fields are ?:. A list or map field that stands in for emptiness is also ?:, and its validated value is [] or an empty ModelMap rather than null.

Working with the schemas#

The generated validate is v.parse with the schema already chosen. Anything else valibot offers works on the same schema: v.safeParse for a failure as a value, v.object and v.array to compose it into a larger shape, v.pipe with v.check to add a constraint of your own.

import * as v from "valibot";
import { ProductSchema } from "./catalog.mjs";

// A failure as a value, not an exception.
const result = v.safeParse(ProductSchema, input);

// The model's type, composed into a larger one.
const PageSchema = v.object({
    items: v.array(ProductSchema),
    cursor: v.optional(v.string()),
});

// The model's constraints, plus one of your own.
const InStock = v.pipe(
    ProductSchema,
    v.check((p) => p.tags.includes("in-stock"), "must be in stock"),
);

Inferring the type back out of a composed schema is valibot’s job, with v.InferOutput:

type Page = v.InferOutput<typeof PageSchema>;