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

