Model metadata#

The types module also describes the model itself: each struct’s fields with their types, constraints and schemas, each enum’s values, each union’s variants, and each route’s method and path. Use it to build something from the model at runtime, such as a form, a table, or an admin screen, instead of writing it out for each type.

A struct’s const#

Each struct’s const, the one holding validate, carries its metadata. Its fields hold each field by name, in the order the YAML declares them, leaving out a field no request may read. A field has its type and constraints as the YAML spells them, keys staying snake_case, and its valibot schema:

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

Object.keys(Product.fields);
// ["sku", "name", "price", "tags"]

Product.fields.sku;
// { type: "string", name: "sku", display: "SKU", desc: "...",
//   required: true, guaranteed: true, primary_key: true, min_length: 1,
//   schema: ... }

v.safeParse(Product.fields.sku.schema, "");
// { success: false, ... }

A field’s Type names its TypeScript type, the type of the value its schema gives. It is there for the compiler only, and is undefined at runtime, so read it with typeof. A field that is not guaranteed may be null or undefined, unless it is a list or map, which is read as empty when missing:

let price: typeof Product.fields.price.Type;
// Decimal
let tags: typeof Product.fields.tags.Type;
// Array<string>, even though tags is not guaranteed

A field’s required and guaranteed answer two questions. required is the YAML’s: a write must supply the field. guaranteed is whether a response always holds it. They differ only for a required field that sets a read perm, which a response leaves out for a request without the perm: it is required and not guaranteed. A field’s schema reads responses, so it does not reject that field when it is missing, and a form checks required itself. A foreign model is one this model only reads, so its fields’ required is their guaranteed, and its structs have no writeOnly.

A field’s schema checks that field alone, as the struct’s schema would. Use it to check one input of a form as it is edited. The struct’s schema is built from these, so the two cannot disagree. The exception is a url field whose base is another field: its own schema leaves it a string, because only the struct as a whole knows that field’s value.

A member left unset in the YAML is left out of its entry, not written as null. That covers an optional constraint such as max_length, or a struct’s root_type or summary. Members that say how one language binds a type, xml and a route’s go, are left out too. The const also holds the struct’s meta values, as meta and top_level_meta.

The perms of a struct a row reaches are its perms, and a route’s is its perm, each resolved and left out when it declares none. A field’s are its perms, left out when it requires nothing more. They hold read, create, and update, each a list of the field’s guards: its own perm and that of the struct it embeds, all of which a request must pass. They are for checking in the client, to grey out what a user may not do; the server still enforces them.

Fields a response never holds#

fields is what a response may hold, so a field whose read is false is not there, and a form has nothing to label it with. A struct’s writeOnly lists those a request may create or update, by name, in the order the YAML declares them, and is left out when there are none:

Object.keys(Vendor.fields);
// ["id", "name"]

Vendor.writeOnly.api_key;
// { type: "secret", name: "api_key", display: "API Key", desc: "...",
//   required: false, guaranteed: false, primary_key: false, perms: ... }

An entry is a field’s metadata without its schema or Type, as schemas read responses and no response holds it. Its required says whether a write must supply it, and its perms what writing it takes.

A create form is fields plus writeOnly. An edit form is the same, and reads a row’s $present for the writeOnly names, to show whether saving would replace anything.

The model constant#

The module exports model. Its types hold each top-level type by name. A struct’s entry is its const. An enum’s, a union’s, or a route’s is its description, told apart by type:

import { model, Product } from "./catalog.mjs";

model.types.Product === Product; // true
model.types.Direction.values.map((value) => value.name);
// ["ltr", "rtl"]

model is declared as const, and checked with satisfies against the metadata types’ Model, so the compiler knows the exact shape of every entry: model.types.Product.fields.sku.type is "string", not string. TypeName is the union of the model’s type names.

Types#

@omniblack/model-runtime, the package generated code imports (see Dependencies), exports the types model satisfies, so code can take any model’s metadata, not only this one’s:

Type

Describes

Model

A model: types, its top-level types by name.

TopLevelType

Struct | Enum | Union | Route, told apart by type.

Struct

name, display, desc, fields by name, writeOnly by name, top_level, root_type, summary.

Summary

The names of its fields, its title and subtitle templates, and the name of its image field.

Enum, EnumValue

tag_type, and each value’s name, value, display, desc.

Union, Variant

tag_name, tag_type, file, and each variant’s tag and inner_type.

Route

method, path, whether it is a merge_patch route, and the names of its request and error_response types, and of its success_response type if it has one.

Field

One of the Types plus name, display, desc, required, guaranteed, primary_key, queryable, unique, schema, and the type-only Type member.

WriteOnlyField

One of the Types plus the same members, less schema and Type.

Type

One interface per field type, StringType, ListType, and so on, told apart by type. Each has that type’s parameters: a list’s values, a string’s min_length.

Narrowing on type gives a field type’s own parameters, its schema, and its Type:

import * as v from "valibot";
import type { Field } from "@omniblack/model-runtime";

function maxLength(field: Field): number | undefined {
    switch (field.type) {
        case "string":
        case "list":
        case "map":
            return field.max_length;
        default:
            return undefined;
    }
}

function readCount(field: Field, text: string): bigint | undefined {
    if (field.type === "integer" && field.guaranteed) {
        // field.schema takes string | number | bigint and gives bigint.
        return v.parse(field.schema, text);
    }
    return undefined;
}

The schema of a field that is not guaranteed also takes null and undefined, and may give them back. Checking guaranteed, as above, narrows that away. required does not.

A field type’s schema is typed by what any field of that type takes and gives, so a type with parameters leaves them unknown: a list’s schema gives unknown[], a map’s ModelMap<unknown, unknown>, a ref’s Ref<unknown, unknown>, and a model field’s unknown. A field read straight from a struct’s const, as in Product.fields.tags.schema, has its own exact types.

A field that holds another type, model or ref, names it as a string (model_type, referenced_type). The package’s typeNamed(model, name) looks it up, and fieldNamed(struct, name) looks up a field. Both return undefined for a name there is none of.

A model type also carries the kind of the type it names: "struct", "enum" or "union" (the ModelKind type). That’s true for a field, a list’s or map’s values, and a union variant’s inner_type. ModelType<N, K> and ModelField<N, K> take that name and kind as type parameters, and a field read from a struct’s const has both as literals. So DefinitionOf<typeof model, F> gives the type of the definition it names, without a lookup:

import type { DefinitionOf } from "@omniblack/model-runtime";
import { model, Zoo } from "./generated_model.ts";

// typeof model.types.Animal
type Animal = DefinitionOf<typeof model, typeof Zoo.fields.animal>;

Every bound is a JSON value. A decimal field’s min and max are the strings they are written as, so no precision is lost. An integer field’s min and max are numbers.

The package’s peer dependencies are valibot, and, optionally, decimal.js and libnerd_font, for the types of decimal and nerd_font_glyph schemas.