gizmodel/model
a record type's meaning as a value (a Shape), and what is derived from it besides HTML: typed input validation, SQL wire rows, DDL for SQLite and PostgreSQL, additive migration, JSON and agent tool schemas. A Shape comes from the record type's declaration, docs and annotations at run time (shapeOf), so the declaration stays the one source; so do a record's rows (rowOf, valueOf) and the actions' table (action, handlers, dispatch).
import * as Model from "gizmodel/model";Types
Table
type Table = { name: string; }Stores the record in the table of this name (a lower-case SQL name).
name:string
Key
type Key = {}The field is the primary key, or part of it with the other key fields.
Opaque: create and use it through this module's functions.
Identity
type Identity = {}The i64 field is the key, and the store numbers it upward as rows come in: an insert leaves it out, so a record is written with 0 there and read with its number.
Opaque: create and use it through this module's functions.
Version
type Version = {}The i64 field counts the record's saves: Db.save writes a record only while the stored count is the record's, and
adds one to it, so two writers of one record never overwrite each other unseen.
Opaque: create and use it through this module's functions.
Index
type Index = { name: string; }The field belongs to the named index, whose columns are its fields in order.
name:string
Search
type Search = {}The text field has a full-text (BM25) index: Query.matching and Tree.matches search it. GizDB only.
Opaque: create and use it through this module's functions.
Unique
type Unique = { name: string; }The field belongs to the named unique constraint.
name:string
References
type References = { table: string; column: string; onDelete: string; }The stored field references this table and column.
table:stringcolumn:stringonDelete:string
Column
type Column = { name: string; }The field's stored column, when it is not the field's name: renaming a field then never renames or drops its column.
name:string
Label
type Label = { text: string; }What people see the field as.
text:string
Hidden
type Hidden = {}The field travels in forms without being shown (a target, a parent).
Opaque: create and use it through this module's functions.
File
type File = { accept: string; maxBytes: i64; multiple: bool; }A text field holds a file: its form control is a file input for the media types in accept (as the HTML attribute: image/png,.pdf; empty
for any), each file at most maxBytes bytes (0: the server's limit). The field's value is the file's name; the bytes come with Web.uploads.
With multiple the field takes several files and its value is the JSON list of their names.
accept:stringmaxBytes:i64multiple:bool
Multiline
type Multiline = {}A text field written over several lines.
Opaque: create and use it through this module's functions.
Trim
type Trim = {}Leading and trailing white space is not part of the value.
Opaque: create and use it through this module's functions.
Submit
type Submit = { text: string; }The label of the record's form button.
text:string
Access
type Access = { read: string; write: string; }The least role that reads the rows of the record and the least that writes them (default: viewer and editor).
read:stringwrite:string
Read
type Read = { role: string; }On a field: the least role that sees it.
role:string
Write
type Write = { role: string; }On a field: the least role that writes it.
role:string
Within
type Within = {}On a field that references another record: that record is the parent of this one, and grants on a parent reach it.
Opaque: create and use it through this module's functions.
Computed
type Computed = { sql: string; }On a field: the SQL expression over the record's columns that gives its value. It is read, never stored or written.
sql:string
Display
type Display = {}On a field: the record is shown as this field in lists and in the choices of a reference.
Opaque: create and use it through this module's functions.
Reference
type Reference = { table: string; column: string; onDelete: string; }A field that refers to a record of TABLE by its COLUMN, and what a delete of that record does (ON DELETE).
table:stringcolumn:stringonDelete:string
Field
type Field = { name: string; column: string; contract: Typed.Contract; key: bool; identity: bool; version: bool; unique: Option<string>; index: Option<string>; references: Option<Reference>; values: Vec<string>; hidden: bool; multiline: bool; trim: bool; search: bool; label: string; doc: string; min: Option<i64>; max: Option<i64>; maxLength: Option<i64>; pattern: Option<string>; was: Vec<string>; readRole: string; writeRole: string; within: bool; computed: Option<string>; display: bool; path: Vec<i64>; accept: Option<string>; maxBytes: i64; multiple: bool; }One field contract owns storage, validation and presentation.
name:stringcolumn:stringcontract:M142.Contractkey:boolidentity:boolversion:boolunique:_gizlang_sdk_core.Option<string>index:_gizlang_sdk_core.Option<string>references:_gizlang_sdk_core.Option<M133.Reference>values:Vec<string>hidden:boolmultiline:booltrim:boolsearch:boollabel:stringdoc:stringmin:_gizlang_sdk_core.Option<i64>max:_gizlang_sdk_core.Option<i64>maxLength:_gizlang_sdk_core.Option<i64>pattern:_gizlang_sdk_core.Option<string>was:Vec<string>readRole:stringwriteRole:stringwithin:boolcomputed:_gizlang_sdk_core.Option<string>display:boolpath:Vec<i64>accept:_gizlang_sdk_core.Option<string>maxBytes:i64multiple:bool
Shape
type Shape = { name: string; table: Option<string>; doc: string; submit: string; hash: string; fields: Vec<Field>; read: string; write: string; }A record type, stored in table or not stored (an action's input). hash
is the meaning hash of its fields, so a handler id names the input it was
rendered for. submit is its form's button. read and write are the least roles that read and write its rows.
name:stringtable:_gizlang_sdk_core.Option<string>doc:stringsubmit:stringhash:stringfields:Vec<M133.Field>read:stringwrite:string
Operation
type Operation = { role: Security.Role; readOnly: bool; destructive: bool; idempotent: bool; approval: bool; }Execution facts are independent: a role does not imply reads, approval or safe replay.
role:gizlang_security.RolereadOnly:booldestructive:boolidempotent:boolapproval:bool
Handler
type Handler = { name: string; id: string; doc: string; input: Shape; operation: Operation; }A function a person, a page or an agent calls by its id, "name.hash".
name:stringid:stringdoc:stringinput:M133.Shapeoperation:M133.Operation
Rejection
type Rejection = { status: i64; field: Option<string>; message: string; problems: Vec<Problem>; cause: Option<Diagnostic>; }A rejection, the one error answer of GizWeb: the HTTP status it answers with, the field it is about (none for the
input as a whole), a message for the person, every field problem of the input (the first is field and
message), and for a database failure its diagnostic, the machine-readable cause.
status:i64field:_gizlang_sdk_core.Option<string>message:stringproblems:Vec<M133.Problem>cause:_gizlang_sdk_core.Option<M129.Diagnostic>
Problem
type Problem = { field: string; message: string; }A problem of one field: its name and what is wrong.
field:stringmessage:string
Outcome
type Outcome = | { kind: "done"; json: bytes; } | { kind: "rejected"; rejection: Rejection; } | { kind: "redirect"; url: string; } | { kind: "unknown"; }What calling an action gave: its result as JSON, an address to send the person to (redirecting), a rejection, or no
action with that id (the page was rendered by other code, so it reloads).
donerejectedredirectunknown
AnyAction
type AnyAction<C> = { handler: Handler; run: (context: C, values: Vec<Value>) => Outcome; }An action as a host lists it: people (a page's form), agents (a tool) and the JSON API call it by its handler id. run
takes the input as the values read checked.
Opaque: create and use it through this module's functions.
Action
type Action<C, I, O> = { any: AnyAction<C>; call: (context: C, input: I) => O throws Rejection; }An action with its types: call runs it in server code with a typed input I, and any is its entry in a host's list.
A page's <form action={a}> and a call a({ … }) in its event handler are checked against I.
Opaque: create and use it through this module's functions.
Row
type Row = Vec<Option<string>>A stored row: each column as text, none for NULL.
Fields
type Fields = { names: Vec<string>; values: Vec<string>; nulls: Vec<string>; }Named text inputs, from a form or a JSON object.
names:Vec<string>values:Vec<string>nulls:Vec<string>
Redirect
type Redirect = { url: string; }Where a redirecting action sends the person: a path of this site ("/credits"), or an https:// address of a host the
action names.
url:string
Functions
operation
function operation(): OperationUnclassified actions require approval and must not be replayed automatically.
invalid
function invalid(field: string, message: string): RejectionA rejection (422) of the value of FIELD, with MESSAGE.
Effects: fail, alloc.
rejection
function rejection(status: i64, message: string): RejectionA rejection of the input as a whole.
diagnosed
function diagnosed(status: i64, d: Diagnostic): RejectionA rejection from a database failure: the field and message of diagnostic D, and D as its cause.
Effects: fail, alloc.
forbidden
function forbidden(message: string): RejectionA rejection (403): the actor may not do this.
missing
function missing(message: string): RejectionA rejection (404): the record is not there.
unauthenticated
function unauthenticated(): RejectionA rejection (401): the request has no signed-in actor.
noFields
function noFields(): FieldsNo fields.
formFields
function formFields(body: string): Fields throws RejectionA form body (application/x-www-form-urlencoded) as fields: one value per decoded name. Malformed or excess input and duplicate names fail before any action sees a partial input.
Effects: fail, alloc.
jsonFields
function jsonFields(text: string, shape: Option<Shape> = undefined): Fields throws RejectionJSON numbers retain their validated source token, including exact i64/u64. Explicit NULL is separate from omission. Duplicate decoded names are rejected.
Effects: fail, alloc.
read
function read(shape: Shape, input: Fields): Vec<Value> throws RejectionThe input checked against the shape, as a row the shape's typed decoder reads without failing: required values present, texts within their character bounds, integers and numbers well formed and within range, booleans as 1 or 0 (absent is false, as an unchecked checkbox). A rejection lists the problem of every field that fails, in shape order.
Effects: fail, read, write, console, io, alloc.
readField
function readField(f: Field, wire: string): Value throws RejectionThe value of ONE field from its wire text, checked as read checks it (required, bounds, pattern, allowed values).
Effects: fail, read, write, console, io, alloc.
values
function values(shape: Shape, row: Row): Vec<Value>Decode stored wire cells under the same declared contracts, without form constraints.
Effects: fail, alloc.
wireValue
function wireValue(field: Field, value: Value): Option<string>A field value as a Row cell: the text a form, the JSON and the admin console carry (a blob in base64, a time in ISO 8601). A SQL store takes its parameters from sql/types textParameter.
Effects: fail, alloc.
slotField
function slotField(slot: Typed.Slot): FieldA field with no declaration annotations: a query result slot, or a form or tool input that no Shape declares.
plainField
function plainField(name: string, scalar: string, nullable: bool, doc: string): FieldAn undeclared input of a Gizlang scalar type ("string", "i64", "bool", ...). An unknown scalar name is a programming error.
Effects: fail, alloc.
display
function display(field: Field, value: Value): stringExact, human-readable values. Temporal storage uses microseconds.
Effects: fail, alloc.
sqlType
function sqlType(f: Field, dialect: SqlDialect): stringThe SQL column type of F in DIALECT.
Effects: fail, alloc.
tableOf
function tableOf(shape: Shape): stringThe table of SHAPE.
Effects: fail.
schema
function schema(shape: Shape, dialect: SqlDialect): Schema.TableThe checked schema of a shape's table: columns in field order, the key, each Unique group (named TABLE_NAME), each References column (TABLE_COLUMN_fkey) and each named index. Each index ends with the key, so rows equal on the index come in key order (ORDER BY created, id reads the index and sorts nothing).
Effects: fail, alloc.
ddl
function ddl(shape: Shape, dialect: SqlDialect): Vec<string> throws stringCREATE TABLE (with its unique and foreign keys), then CREATE INDEX for each named index; all idempotent. A table made before a constraint was declared keeps its columns and does not get it. A keyed SQLite table is WITHOUT ROWID: the key is the table's one b-tree, instead of a rowid table and a second b-tree for the key; an @Identity key is the rowid itself, which SQLite numbers. Every name is delimited as DIALECT writes it (quotedPath), so a column named by a reserved word (group, order) is made like any other; a name it cannot hold is refused.
Effects: fail, read, write, console, io, alloc.
json
function json(shape: Shape, row: Vec<Option<string>>): bytesA row as a JSON object keyed by field name. An integer beyond 2^53 - 1 is a string, so a browser reads it exactly; decimals are strings.
Effects: fail, alloc.
tools
function tools(actions: Vec<Handler>): bytesThe actions as agent tools: name, description and a JSON Schema of the input, from the same Shape the form and the validator use.
Effects: fail, alloc.
shapeOfFields
function shapeOfFields(name: string, names: Vec<string>, types: Vec<string>): Shape throws stringThe Shape of the record NAME whose fields are NAMES of the scalar TYPES (string, bool, i64, f64): a record type that no declaration gives, as a TypeScript app names its table's columns (web/start.giz schema), the same on every host.
Effects: fail, alloc.
shapeOf
function shapeOf<T>(): Shape throws stringThe Shape of the record type T, from its declaration, docs and annotations: the one source of its storage, validation, forms and tools. A declaration the Shape cannot hold gives its message. It is made once a World (SHAPES).
actionId
function actionId(name: string, input: Shape, output: Shape): stringThe id of the action name from the shapes of its input and output: the same while both meanings are.
Effects: fail, alloc.
valuesOf
function valuesOf<T>(shape: Shape, v: T): Vec<Value>The values of the record V, one per field of its Shape.
loadOf
function loadOf<T>(shape: Shape, records: Vec<T>, from: i64, to: i64): BatchRECORDS from FROM to TO as columns: one for each field of SHAPE that an INSERT writes (not a computed or an identity field), in the order of the fields. An integer, float, Boolean or text field goes from the record's words into its typed column, with no Value for a cell: the Values of 1M records were a third of their load. A record with another kind of field gives its Values as they are (a mixed column), which the engine converts.
rowOf
function rowOf<T>(shape: Shape, v: T): RowThe record V as a stored row.
valueOf
function valueOf<T>(shape: Shape, row: Vec<Value>): TThe record of type T that values (one per field of its Shape, as read and values give them) make. Its words are
written as they are read (writeFields): a tree of each record (Memory.Dyn), written out and freed, was most of the
reading of a page's records.
rowReader
function rowReader<T>(shape: Shape): (row: Vec<Value>) => T effects {fail, alloc}valueOf<T> for a Shape as the row reader that the reads of a Db and the queries of a Shape take.
shape
function shape<T>(): ShapeThe Shape of the record type T; a declaration the Shape cannot hold is a defect of the program, reported with its message.
action
function action<C, I, O>(name: string, doc: string, run: (context: C, input: I) => O throws Rejection, execution: Option<Operation> = undefined): Action<C, I, O>The action name: a function of the app's context and an input record I that gives a record O or a Rejection.
The input arrives checked against I's Shape. Stored scalar results use their Shape;
structured results use the SDK's typed JSON codec and memory schema identity.
redirecting
function redirecting<C, I>(name: string, doc: string, hosts: Vec<string>, run: (context: C, input: I) => Redirect throws Rejection, execution: Option<Operation> = undefined): Action<C, I, Redirect>An action that sends the person to an address, as a checkout sends them to the payment provider: a form without script
follows it (303), the page kernel opens it, and an agent reads it as redirect. Its address is a path of this site or an
https:// address on one of HOSTS; any other (an address made from the input) is refused, so it is never an open
redirect.
handlers
function handlers<C>(actions: Vec<AnyAction<C>>): Vec<Handler>The actions as handlers: forms and agent tools.
dispatch
function dispatch<C>(actions: Vec<AnyAction<C>>, context: C, id: string, bare: bool, fields: Fields): OutcomeRuns the action id names ("name.hash"; a bare name when bare, as an agent calls a tool) with checked inputs.
Methods
Rejection.kind
function Rejection.kind(self: Rejection): stringWhat went wrong, in the words of data access, so that code which reads and writes records names no HTTP status: "missing" (no such record), "conflict" (a key that is there, or a record another writer changed), "denied" (the caller may not), "invalid" (a value the record does not take), "tooLarge" (an answer past the Db's row limit), else "failed" (the store itself).
DbError.rejection
function DbError.rejection(self: DbError): RejectionThe error as a rejection: a database error is a defect (500), with its diagnostic. A data failure of a store or
GizDB reaches an action as this rejection: f().mapErr((e) => e.rejection()).
Effects: fail, alloc.
SqlError.rejection
function SqlError.rejection(self: SqlError): RejectionA SQL failure as a request rejection: status 500 with the storage message.
Effects: fail, alloc.
Fields.get
function Fields.get(self: Fields, name: string): Option<string>The value of the field NAME, or none when it is absent or NULL.
Effects: fail.
Fields.with
function Fields.with(self: Fields, name: string, value: string): FieldsThe fields with NAME set to VALUE.
Effects: fail, alloc.
Fields.isNull
function Fields.isNull(self: Fields, name: string): boolWhether the field NAME is NULL.
Effects: fail.
Fields.present
function Fields.present(self: Fields, name: string): boolWhether the field NAME has a value or is NULL.
Effects: fail.
Field.required
function Field.required(self: Field): boolWhether a required field may be empty: only a text whose minimum is 0.