GizStack
View .mdOpen in ChatGPTOpen in Claude

gizapp/table

the typed table of a page. A route file declares const todos = table<Todo>("created desc"); and reads and writes it as the records of its type; the generated code calls this module. Every read and write goes through Data and its Gate, so a page shows and changes only what the person who asks may. The condition of where and count is the model's typed tree of the lambda (gizlang/expr), made at build time; each value of the page in it is a typed slot, so a value cannot become SQL.

gizlang
import * as Table from "gizapp/table";

Types

Meter

gizlang
type Meter = { fault: Task.Cell<Model.Rejection>; reads: Task.Atomic; rows: Task.Atomic; writes: Task.Atomic; counted: Task.Cell<Vec<Counted>>; go: Task.Cell<string>; }

What a request of a page leaves in its tables: the first refusal or failure (the status and reason of the answer; 200 when none), and how many reads and writes it made. A page reads a table as a list, so a failed read cannot be a value of the list: it is kept here, and the host answers with it instead of a list that looks empty.

  • fault: gizlang_task.Cell<M141.Rejection>
  • reads: gizlang_task.Atomic
  • rows: gizlang_task.Atomic — The rows the reads gave: a count gives one, so a page that shows a number reads no rows to count them.
  • writes: gizlang_task.Atomic
  • counted: gizlang_task.Cell<Vec<M118.Counted>>
  • go: gizlang_task.Cell<string> — Where an action of the request sends the person (Model.redirecting); "" none.

Focus

gizlang
type Focus = { mode: Task.Atomic; only: Task.Atomic; table: string; keys: Vec<Value>; order?: Task.Cell<Vec<string>>; out: Option<Task.Cell<Patches.Patch>> }

What a live request of a page asks (app/region.giz): the table that changed and the keys of its rows that changed (none: any row may have), the patches that the ranges of the page made, and two switches. mode is 1 while the page is looked through for the ranges that read the table (nothing else is rendered), 0 while a range renders. only is 1 while the reads of the table are limited to the rows of those keys. An ordinary request has no patches (out is none) and its mode is 0.

  • mode: gizlang_task.Atomic
  • only: gizlang_task.Atomic
  • table: string
  • keys: Vec<M151.Value>
  • order: _gizlang_sdk_core.Option<gizlang_task.Cell<Vec<string>>>
  • out: _gizlang_sdk_core.Option<gizlang_task.Cell<_gizlang_lib_app__html.Patch>>

Context

gizlang
type Context = { scoped: Option<Data.Db>; me: string; live: bool; meter: Meter; focus: Focus; files?: string; origin?: string; act?: (name: string, fields: Model.Fields) => Model.Outcome; }

What a page needs of its host: the records as the person who asks may use them (none when the host has no database), who that is, and whether the client runs the kernel (live: only such a client polls, so only it gets a watch).

  • scoped: _gizlang_sdk_core.Option<M139.Db>
  • me: string
  • live: bool
  • meter: M118.Meter
  • focus: M118.Focus
  • files: _gizlang_sdk_core.Option<string> — The host's file storage directory, when this context may persist files.
  • origin: _gizlang_sdk_core.Option<string> — The origin the request reached (Http.originOf), for a link an Action mails; none outside a request.
  • act: _gizlang_sdk_core.Option<(arg0: string, arg1: M141.Fields) => M141.Outcome> — Runs the app's action NAME (POST /_a/NAME) with FIELDS as this person: how a page calls an action by its contract (Pages.call), whichever app hosts the page and however that app does it. None outside a page.

Table

gizlang
type Table<T> = { context: Context; shape: Model.Shape; order: string; }

The records of type T that the person may read and write; ORDER is the order of every read (field names, as table takes).

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

Functions

meter

gizlang
function meter(): Meter

A meter of one request: no fault, no reads, no rows, no writes.

Effects: fail, read, write, console, io, alloc.

quiet

gizlang
function quiet(): Focus

The focus of an ordinary request.

Effects: fail, io, alloc.

seeking

gizlang
function seeking(table: string, keys: Vec<Value>): Focus

The focus of the request that tells a page of the change of the rows KEYS of the table TABLE.

Effects: fail, io, alloc.

context

gizlang
function context(scoped: Option<Data.Db>, me: string, live: bool): Context

The context of an ordinary request.

Effects: fail, read, write, console, io, alloc.

table

gizlang
function table<T>(context: Context, order: string): Table<T>

The table of T, ordered by ORDER (field names, each with asc or desc: "created desc, id"; empty is by key).

fieldOf

gizlang
function fieldOf(shape: Model.Shape, name: string): Option<Model.Field>

The field name of shape, or none.

Effects: fail.

ordered

gizlang
function ordered(shape: Model.Shape, order: string, limit: i64): Query.Query<Vec<Value>>

The read of the rows of SHAPE in ORDER (field names, each with asc or desc; empty is by key), at most LIMIT of them (0 or more than a page reads is the most a page reads). A name the Shape does not hold is a defect of the page.

Effects: fail, alloc.

storedValue

gizlang
function storedValue(f: Model.Field, wire: string): Value throws Model.Rejection

The value of the field F that the wire text WIRE stands for, as it is stored, without the checks of a new value (a key, or what a cell showed).

Effects: fail, alloc.

keyText

gizlang
function keyText(key: Value): Option<string>

The text of a key value as a page writes it (the data-k of a row), or none for a type that a key text cannot stand for.

Effects: fail, alloc.

gridScript

gizlang
function gridScript(): string

The script of giz-grid, the client of a view, for Web.enhancement(shell, "giz-grid", utf8(gridScript()), b"").

Effects: fail, alloc.

viewGrid

gizlang
function viewGrid(src: string, spec: string, link: string, edit: bool, state: string, names: Vec<string>, rows: Vec<Vec<Option<string>>>, given: bool = false): Html

A grid of the view at SRC (app/view.giz) of any size, which the element reads window by window: SPEC is its first state (data-spec, JSON: the layout, the Spec and the look), LINK the name of the views that filter one another, EDIT whether a person may change its rows. NAMES and ROWS are its first rows, the table a browser without script shows. STATE is the id of a page input that the element keeps its state in (JSON, as SPEC), so the page can save it; "" for none. GIVEN shows SPEC as it is and keeps nothing of what a person changes (a tile of a report, whose file is its state); else the element starts from what this person last left in this view.

Effects: fail, alloc.

typed

gizlang
function typed<R, V>(table: Table<R>, field: (row: R) => V, value: V): V

VALUE, which a where condition of a page compares with a field of TABLE's rows. FIELD is never called: it only makes the compiler check that VALUE has the field's type (t.done === 3 is an error, not a query).

newKeys

gizlang
function newKeys(): () => string

Keys for many records made at once (an import): one newKey and a count after it (10 hex digits). Within a millisecond a draw of 4 bytes for each of a million records repeats; the count never does, and it takes no randomness.

Effects: fail, write, io, alloc.

withKeys

gizlang
function withKeys(shape: Model.Shape, fields: Model.Fields): Model.Fields

FIELDS with a made key for each text key of SHAPE that is missing.

Effects: fail, io, alloc.

writeInput

gizlang
function writeInput(shape: Model.Shape): Model.Shape

SHAPE as the input of a write: a field with a read or a write role is optional, since a person whose role does not reach it sends none.

written

gizlang
function written(context: Context, shape: Model.Shape, op: string, values: Vec<Value>): Vec<Value> throws Model.Rejection

The one path of every write to a table: a page's add, set and remove, a <form create> and the tools add_T, update_T and remove_T. OP ("add", "update" or "remove") writes VALUES, a row of SHAPE, as the person of CONTEXT and gives the row as written. An add or an update is checked by the Shape, as a form's fields are; an add makes each empty text key.

Effects: fail, read, write, console, io, alloc.

form

gizlang
function form(request: Http.Request): Http.Params

The fields of REQUEST's form body (application/x-www-form-urlencoded), as an endpoint that writes tables reads them; none when it is not one.

Effects: fail, alloc.

written

gizlang
function written(why: string): Http.Response

An endpoint's answer to its writes: 204 when each said nothing (""), else 422 with the first reason.

Effects: fail, alloc.

Methods

Table.key

gizlang
function Table.key<T>(self: Table<T>, v: T): string

The key of a record as text (its first key field), or empty.

Table.rows

gizlang
function Table.rows<T>(self: Table<T>): Vec<T>

All the records, in the order of the table.

Table.first

gizlang
function Table.first<T>(self: Table<T>, limit: i64): Vec<T>

The first LIMIT records, in the order of the table: a list shows a bounded page and sends a person to a grid for the rest.

Table.where

gizlang
function Table.where<T>(self: Table<T>, root: Lambda.Node, slots: Vec<Lambda.Constant>, order: string, limit: i64): Vec<T>

The records that a condition selects. ROOT is the typed tree (gizlang/expr) that the GHTML build makes of a page's where lambda, over the fields of the table; SLOTS are the values of the page in it, each checked against its field's type (typed). The model lowers it as Find.filter does. ORDER is the order of this read (empty is the order of the table) and LIMIT its most rows (0 is the most a page reads).

Table.count

gizlang
function Table.count<T>(self: Table<T>, root: Lambda.Node, slots: Vec<Lambda.Constant>): i64

How many records a condition (ROOT and SLOTS as where reads them) selects, counted by the database.

Table.total

gizlang
function Table.total<T>(self: Table<T>): i64

How many records the table holds that the person may read.

Table.grid

gizlang
function Table.grid<T>(self: Table<T>): Html

The rows of the table as a <giz-grid> around an HTML <table>: a column for each field that is not hidden, headed by its label (data-field its name), each cell the field as a person reads it (Model.display). A row is data-k its key, so a page that reads the table with grid() is a range that renders again whole on a change. The element (app/components/giz-grid.js, Web.gridScript()) reads the table's view at data-src (/_view/NAME, app/view.giz) window by window: every row of any count, sorted, filtered, grouped, pivoted and charted by the database. The HTML table is the first rows for a browser without script.

Table.editableGrid

gizlang
function Table.editableGrid<T>(self: Table<T>, name: string): Html

grid() whose cells of the fields that are not keys are bound controls of the page (_f.NAME.field.key, with _o. what the cell showed), as value={t.field} in an each: a change is one update of that field through the Gate, and a field that another person changed meanwhile is a conflict. Without script the grid is a form of the page; with the element, it sends an edit, a paste or a fill to the view as one transaction instead. NAME is the table's name in the page (the GHTML compiler gives it).

Table.fresh

gizlang
function Table.fresh<T>(self: Table<T>): string

A new key for a row the page adds now (chats.add({ id: chats.fresh(), … })), when the page needs it before the row is read back: it sorts by time.

Table.add

gizlang
function Table.add<T>(self: Table<T>, v: T): string

Add the record V; a text key that is empty is made. A <form create={table}> adds through the same path (add_T).

Table.set

gizlang
function Table.set<T>(self: Table<T>, v: T): string

Replace the record with the key of V by V.

Table.put

gizlang
function Table.put<T>(self: Table<T>, v: T): string

Add V, or replace the record with the key of V by V when it is stored: one keyed read, not a read of the table.

Table.remove

gizlang
function Table.remove<T>(self: Table<T>, v: T): string

Delete the record with the key of V.

Table.removeWhere

gizlang
function Table.removeWhere<T>(self: Table<T>, root: Lambda.Node, slots: Vec<Lambda.Constant>): string

Delete every record that a condition selects, as where selects them: it stops at the first refusal and gives its reason. A pass reads at most MOST_ROWS records, so it reads again until none is left.

Table.apply

gizlang
function Table.apply<T>(self: Table<T>, name: string, posted: Http.Params): string

The changes that the page posted for the table NAME, as _f.NAME.field.key = value, in the order posted (the last value of a control counts). _o. + the same name is what the control showed: a control that shows what it posts did not change, and a change whose old value is gone is a conflict.

Table.watch

gizlang
function Table.watch<T>(self: Table<T>): Html

The element that keeps a page current: the kernel long-polls the changes of the table (a watch on all its rows; the host tells a person only the changes of rows the person may read, Pages told) and gets the page again when one comes. Nothing leaves the server but that a change happened; the page reads its rows again under the same grants.

Constants

MOST_ROWS

gizlang
const MOST_ROWS: i64 = 1000

The most rows a page reads from one table.