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 |
|---|---|
|
A model: |
|
|
|
|
|
The names of its |
|
|
|
|
|
|
|
One of the |
|
One of the |
|
One interface per field type, |
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.