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 |
|---|---|---|
|
const |
The valibot schema. Composable. |
|
interface |
The validated shape. |
|
const |
|
|
interface |
The same shape under its own name. |
|
const |
|
|
interface |
Only with a |
|
const |
Only with a |
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 |
|---|---|---|
|
const |
A frozen object mapping member name to value. |
|
type |
The union of that object’s values. |
|
const |
|
Per union#
Export |
Kind |
What it is |
|---|---|---|
|
type |
The union of every variant type. |
|
const |
|
|
const |
|
|
interface |
One variant: its tag, and its |
|
const |
That variant’s schema, with the tag pinned to a literal. |
|
const |
That variant’s |
Per route#
Export |
Kind |
What it is |
|---|---|---|
|
interface |
|
|
const |
The route’s |
|
function |
Only with placeholders: builds the URL path from the fields they name. |
|
function |
Calls the route: |
Per model#
Export |
Kind |
What it is |
|---|---|---|
|
const |
Only with |
|
type |
Only with a searchable table: an item of |
|
type |
Only on a struct something refers to: an item of its |
|
type |
Only on a struct with related rows: an item of its |
|
interface |
Only with |
@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 |
|---|---|---|
|
|
a boolean |
|
|
a string |
|
|
a |
|
|
a |
|
|
a number |
|
|
|
|
|
a |
|
|
an |
|
|
a |
|
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>;