# 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`

### `Search`

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

