GizStack
View .mdOpen in ChatGPTOpen in Claude

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).

gizlang
import * as Model from "gizmodel/model";

Types

Table

gizlang
type Table = { name: string; }

Stores the record in the table of this name (a lower-case SQL name).

  • name: string

Key

gizlang
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

gizlang
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

gizlang
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

gizlang
type Index = { name: string; }

The field belongs to the named index, whose columns are its fields in order.

  • name: string
gizlang
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

gizlang
type Unique = { name: string; }

The field belongs to the named unique constraint.

  • name: string

References

gizlang
type References = { table: string; column: string; onDelete: string; }

The stored field references this table and column.

  • table: string
  • column: string
  • onDelete: string

Column

gizlang
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

gizlang
type Label = { text: string; }

What people see the field as.

  • text: string

Hidden

gizlang
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

gizlang
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: string
  • maxBytes: i64
  • multiple: bool

Multiline

gizlang
type Multiline = {}

A text field written over several lines.

Opaque: create and use it through this module's functions.

Trim

gizlang
type Trim = {}

Leading and trailing white space is not part of the value.

Opaque: create and use it through this module's functions.

Submit

gizlang
type Submit = { text: string; }

The label of the record's form button.

  • text: string

Access

gizlang
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: string
  • write: string

Read

gizlang
type Read = { role: string; }

On a field: the least role that sees it.

  • role: string

Write

gizlang
type Write = { role: string; }

On a field: the least role that writes it.

  • role: string

Within

gizlang
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

gizlang
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

gizlang
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

gizlang
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: string
  • column: string
  • onDelete: string

Field

gizlang
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: string
  • column: string
  • contract: M142.Contract
  • key: bool
  • identity: bool
  • version: bool
  • unique: _gizlang_sdk_core.Option<string>
  • index: _gizlang_sdk_core.Option<string>
  • references: _gizlang_sdk_core.Option<M133.Reference>
  • values: Vec<string>
  • hidden: bool
  • multiline: bool
  • trim: bool
  • search: bool
  • label: string
  • doc: string
  • min: _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: string
  • writeRole: string
  • within: bool
  • computed: _gizlang_sdk_core.Option<string>
  • display: bool
  • path: Vec<i64>
  • accept: _gizlang_sdk_core.Option<string>
  • maxBytes: i64
  • multiple: bool

Shape

gizlang
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: string
  • table: _gizlang_sdk_core.Option<string>
  • doc: string
  • submit: string
  • hash: string
  • fields: Vec<M133.Field>
  • read: string
  • write: string

Operation

gizlang
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.Role
  • readOnly: bool
  • destructive: bool
  • idempotent: bool
  • approval: bool

Handler

gizlang
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: string
  • id: string
  • doc: string
  • input: M133.Shape
  • operation: M133.Operation

Rejection

gizlang
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: i64
  • field: _gizlang_sdk_core.Option<string>
  • message: string
  • problems: Vec<M133.Problem>
  • cause: _gizlang_sdk_core.Option<M129.Diagnostic>

Problem

gizlang
type Problem = { field: string; message: string; }

A problem of one field: its name and what is wrong.

  • field: string
  • message: string

Outcome

gizlang
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).

  • done
  • rejected
  • redirect
  • unknown

AnyAction

gizlang
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

gizlang
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

gizlang
type Row = Vec<Option<string>>

A stored row: each column as text, none for NULL.

Fields

gizlang
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

gizlang
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

gizlang
function operation(): Operation

Unclassified actions require approval and must not be replayed automatically.

invalid

gizlang
function invalid(field: string, message: string): Rejection

A rejection (422) of the value of FIELD, with MESSAGE.

Effects: fail, alloc.

rejection

gizlang
function rejection(status: i64, message: string): Rejection

A rejection of the input as a whole.

diagnosed

gizlang
function diagnosed(status: i64, d: Diagnostic): Rejection

A rejection from a database failure: the field and message of diagnostic D, and D as its cause.

Effects: fail, alloc.

forbidden

gizlang
function forbidden(message: string): Rejection

A rejection (403): the actor may not do this.

missing

gizlang
function missing(message: string): Rejection

A rejection (404): the record is not there.

unauthenticated

gizlang
function unauthenticated(): Rejection

A rejection (401): the request has no signed-in actor.

noFields

gizlang
function noFields(): Fields

No fields.

formFields

gizlang
function formFields(body: string): Fields throws Rejection

A 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

gizlang
function jsonFields(text: string, shape: Option<Shape> = undefined): Fields throws Rejection

JSON 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

gizlang
function read(shape: Shape, input: Fields): Vec<Value> throws Rejection

The 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

gizlang
function readField(f: Field, wire: string): Value throws Rejection

The 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

gizlang
function values(shape: Shape, row: Row): Vec<Value>

Decode stored wire cells under the same declared contracts, without form constraints.

Effects: fail, alloc.

wireValue

gizlang
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

gizlang
function slotField(slot: Typed.Slot): Field

A field with no declaration annotations: a query result slot, or a form or tool input that no Shape declares.

plainField

gizlang
function plainField(name: string, scalar: string, nullable: bool, doc: string): Field

An undeclared input of a Gizlang scalar type ("string", "i64", "bool", ...). An unknown scalar name is a programming error.

Effects: fail, alloc.

display

gizlang
function display(field: Field, value: Value): string

Exact, human-readable values. Temporal storage uses microseconds.

Effects: fail, alloc.

sqlType

gizlang
function sqlType(f: Field, dialect: SqlDialect): string

The SQL column type of F in DIALECT.

Effects: fail, alloc.

tableOf

gizlang
function tableOf(shape: Shape): string

The table of SHAPE.

Effects: fail.

schema

gizlang
function schema(shape: Shape, dialect: SqlDialect): Schema.Table

The 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

gizlang
function ddl(shape: Shape, dialect: SqlDialect): Vec<string> throws string

CREATE 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

gizlang
function json(shape: Shape, row: Vec<Option<string>>): bytes

A 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

gizlang
function tools(actions: Vec<Handler>): bytes

The 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

gizlang
function shapeOfFields(name: string, names: Vec<string>, types: Vec<string>): Shape throws string

The 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

gizlang
function shapeOf<T>(): Shape throws string

The 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

gizlang
function actionId(name: string, input: Shape, output: Shape): string

The id of the action name from the shapes of its input and output: the same while both meanings are.

Effects: fail, alloc.

valuesOf

gizlang
function valuesOf<T>(shape: Shape, v: T): Vec<Value>

The values of the record V, one per field of its Shape.

loadOf

gizlang
function loadOf<T>(shape: Shape, records: Vec<T>, from: i64, to: i64): Batch

RECORDS 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

gizlang
function rowOf<T>(shape: Shape, v: T): Row

The record V as a stored row.

valueOf

gizlang
function valueOf<T>(shape: Shape, row: Vec<Value>): T

The 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

gizlang
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

gizlang
function shape<T>(): Shape

The Shape of the record type T; a declaration the Shape cannot hold is a defect of the program, reported with its message.

action

gizlang
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

gizlang
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

gizlang
function handlers<C>(actions: Vec<AnyAction<C>>): Vec<Handler>

The actions as handlers: forms and agent tools.

dispatch

gizlang
function dispatch<C>(actions: Vec<AnyAction<C>>, context: C, id: string, bare: bool, fields: Fields): Outcome

Runs the action id names ("name.hash"; a bare name when bare, as an agent calls a tool) with checked inputs.

Methods

Rejection.kind

gizlang
function Rejection.kind(self: Rejection): string

What 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

gizlang
function DbError.rejection(self: DbError): Rejection

The 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

gizlang
function SqlError.rejection(self: SqlError): Rejection

A SQL failure as a request rejection: status 500 with the storage message.

Effects: fail, alloc.

Fields.get

gizlang
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

gizlang
function Fields.with(self: Fields, name: string, value: string): Fields

The fields with NAME set to VALUE.

Effects: fail, alloc.

Fields.isNull

gizlang
function Fields.isNull(self: Fields, name: string): bool

Whether the field NAME is NULL.

Effects: fail.

Fields.present

gizlang
function Fields.present(self: Fields, name: string): bool

Whether the field NAME has a value or is NULL.

Effects: fail.

Field.required

gizlang
function Field.required(self: Field): bool

Whether a required field may be empty: only a text whose minimum is 0.