# gizmodel/data

A stored application's typed records, by their Model.Shape: on a GizDB engine this process serves, or on a SQL store. Actions, packages and the platform write and read them here; one transaction is one Connection.begin. A page follows them with Db.watch and Web.live (web/app.giz).

```gizlang
import * as Data from "gizmodel/data";
```

## Types

### `Engine`

```gizlang
interface Engine { connect(self: Self, name: string): Db throws DbError; of(self: Self, name: string): Db throws DbError; }
```

A GizDB engine this process serves, as typed records take it (db/local.giz Endpoint): an interface, so this module
links no engine, and a thread may hold it (a record of closures it may not). `connect` gives NAME on a connection whose
calls go to its data actor; `of` one whose reads run on the thread of SYS.

- `connect`
- `of`

### `Watch`

```gizlang
type Watch = { db: Db; find: Query.Query<Vec<Value>>; id: string; }
```

A follow kept open: `Watch.wait` follows again when the store retired the follow (Changed.lost), so a loop that waits
for changes never asks a lost follow, which answers at once (a chat loop spun on one, af0e1e0).

- `db`: `M131.Db`
- `find`: `M131.Query<Vec<M143.Value>>`
- `id`: `string`

### `Options`

```gizlang
type Options = { name?: string; engine?: Engine; live?: bool; rowLimit?: i64; }
```

What `open` may be told. `name` names the connection ("data"). `engine` is the GizDB engine this process serves
(gizdb/local Served.engine): the records then ride it, not SQL text. `live` gives a SQL store the change feed that
`watch` reads (an engine needs none). `rowLimit` is the most rows `rows` answers: one row more is refused, never
cut; without it a read has no limit.

- `name`: `_gizlang_sdk_core.Option<string>`
- `engine`: `_gizlang_sdk_core.Option<M127.Engine>`
- `live`: `_gizlang_sdk_core.Option<bool>`
- `rowLimit`: `_gizlang_sdk_core.Option<i64>`

## Functions

### `newKey`

```gizlang
function newKey(): string
```

A key that is made for a record: the time in milliseconds (12 hex digits) and 4 random bytes, so the keys sort by
creation time.

Effects: fail, io, alloc.

### `connect`

```gizlang
function connect(store: Sql.Database, engine: Option<Engine>, feed: Option<Relay.Relay>, name: string): Db throws DbError
```

The records of a store that a server holds already: of ENGINE when this process serves the store (Served.engine),
else SQL on `store` itself, with its `feed` for live views (without one a watch fails). An application opens its
records with `open`; this is for the server that owns the store and the feed.

Effects: fail, io, alloc.

### `heldRefusal`

```gizlang
function heldRefusal(): Model.Rejection
```

What a held transaction does not do: define tables.

### `inside`

```gizlang
function inside(tx: Sql.Database, feed: Option<Relay.Relay> = undefined, name: string = "data"): Db
```

The records inside the open transaction TX of a SQL store, for a server that holds the transaction itself (a feed's
`Relay.transaction` callback): its reads and writes join TX, and FEED hears the writes at TX's commit. An
application uses `Db.transaction`.

Effects: fail, alloc.

### `statement`

```gizlang
function statement(command: Tree.Statement, params: Vec<Value>, rows: Option<i64> = undefined): Policy.Write
```

The statement COMMAND (a syntax tree that Query builds) with its parameters $1.. PARAMS; when ROWS is set, it must
change exactly that many rows, else the transaction is a conflict.

Effects: fail, alloc.

### `changing`

```gizlang
function changing<R>(find: Query.Query<R>, sets: Vec<Query.Assignment>, rows: Option<i64> = undefined): Policy.Write throws Model.Rejection
```

The UPDATE that sets SETS (Query.set) on the records FIND selects, as `statement`. FIND needs a condition.

### `deleting`

```gizlang
function deleting<R>(find: Query.Query<R>, rows: Option<i64> = undefined): Policy.Write throws Model.Rejection
```

The DELETE of the records FIND selects, as `statement`. FIND needs a condition.

### `insertRows`

```gizlang
function insertRows(shape: Model.Shape, rows: Vec<Model.Row>, existing?: Query.Existing): Policy.Write throws Model.Rejection
```

Insert rows of a stored Shape in one statement (Query.insertion): a row whose key is there is refused (a conflict),
kept or replaced, as EXISTING says (refused when it is left out).

Effects: fail, alloc.

### `insert`

```gizlang
function insert<T>(shape: Model.Shape, v: T, existing?: Query.Existing): Policy.Write throws Model.Rejection
```

Insert the record `v` of a stored Shape, as `insertRows`.

### `counted`

```gizlang
function counted<R>(source: Source.Source, find: Query.Query<R>): i64 throws Model.Rejection
```

How many rows FIND's conditions select in SOURCE.

### `changedKey`

```gizlang
function changedKey(keys: mut Vec<Value>, seen: mut Map<bytes, bool>, key: Value): void
```

A key invalidates one record even when both images or several writes select it.

Effects: fail, alloc.

### `sameFollow`

```gizlang
function sameFollow(a: string, b: string): bool
```

Whether the follow ids A and B name one watch: a page's next answer moves the position, not the watch.

Effects: fail, alloc.

### `holdsWatch`

```gizlang
function holdsWatch(id: string): bool
```

Whether the follow id ID holds a watch that `unfollow` ends: an engine's, or a SQL store's feed follow. A topic of an
app's own (a position of its feed) holds none.

Effects: fail, alloc.

### `watching`

```gizlang
function watching<R>(db: Db, q: Query.Query<R>): Watch throws Model.Rejection
```

The Watch of the records that Q selects on DB (Query.watch).

### `open`

```gizlang
function open(location: string, options: Options = {}): Db throws Model.Rejection
```

The records at LOCATION: a GizDB folder (served by gizdb or by this process), a SQLite file or :memory:, or a
postgres://, mysql:// or odbc: address. The same Query and the same verbs run on each.

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

### `readRefusal`

```gizlang
function readRefusal(self: Db, e: DbError): Model.Rejection
```

A failed read as a rejection: a read past the Db's row limit is a 413, anything else a storage error.

Effects: fail, alloc.

### `updated`

```gizlang
function updated<R, A>(self: Db, find: Query.Query<R>, set: Lambda.Expr<R, A>): i64 throws Model.Rejection
```

`Query.update` on DB: the UPDATE of the records FIND selects, with the fields that SET makes.

### `removed`

```gizlang
function removed<R>(self: Db, find: Query.Query<R>): i64 throws Model.Rejection
```

`Query.remove` on DB: the DELETE of the records FIND selects; on a scoped Db, each one through the Gate.

## Methods

### `Db.inSchema`

```gizlang
function Db.inSchema(self: Db, schema: string): Db throws Model.Rejection
```

The same records in the schema SCHEMA of the store (GizDB, PostgreSQL or SQLite), made when it is not there: every
table they install, read and write is SCHEMA.table. A write is one statement on one table (INSERT INTO, UPDATE or
DELETE FROM it); a write that names another table, and a scoped use, are refused, so nothing reaches outside the
schema unseen.

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

### `Db.dispose`

```gizlang
function Db.dispose(self: Db): bool throws Model.Rejection
```

End the connection.

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

### `Db.selected`

```gizlang
function Db.selected<R>(self: Db, q: Query.Query<R>): Query.Query<R> throws Model.Rejection
```

Q as SELF reads it: on the tables of its schema, and for a scoped Db only the rows that its actor may read
(Gate.readable). A projection, a summary or a union has no rows of its own to judge, so a scoped Db refuses it.

### `Db.prepared`

```gizlang
function Db.prepared<R>(self: Db, q: Query.Query<R>): Tree.Prepared<bool, R> throws Model.Rejection
```

Q as the typed query that SELF runs (Tree.Prepared), in field order: for a scoped Db the fields that the actor may
not read are NULL (Gate.masks). Q's order and limit stay; without an order the rows come in key order.

### `Db.row`

```gizlang
function Db.row(self: Db, shape: Model.Shape, key: Vec<Value>): Vec<Value> throws Model.Rejection
```

The one row of SHAPE with these key values (KEY in field order; only its key fields are read), as SELF may read it,
or a 404.

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

### `Db.hasRow`

```gizlang
function Db.hasRow(self: Db, shape: Model.Shape, key: Vec<Value>): bool throws Model.Rejection
```

Whether the row with these key values is in the table at all, whoever may read it (a trusted question: a host asks
it to tell a removed row from one that a person may not read).

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

### `Db.createRow`

```gizlang
function Db.createRow(self: Db, shape: Model.Shape, values: Vec<Value>): Vec<Value> throws Model.Rejection
```

Creates a row of SHAPE (all the fields in order) as the actor of a scoped Db may, and answers it as stored: the actor
needs the Shape's write role on the row's parent. The row is inserted and placed in one transaction.

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

### `Db.createRows`

```gizlang
function Db.createRows(self: Db, shape: Model.Shape, rows: Vec<Vec<Value>>): i64 throws Model.Rejection
```

Creates ROWS as `createRow` creates each, in one transaction of a few statements: an import of thousands of rows is
one write, not thousands. The rows are not read back; how many.

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

### `Db.saveRow`

```gizlang
function Db.saveRow(self: Db, shape: Model.Shape, values: Vec<Value>, expected: Vec<Value> = []): Vec<Value> throws Model.Rejection
```

Writes VALUES (all the fields in order, the key as it is) over the stored row of their key, and answers the row as
stored. The write holds only while the stored row is the one the writer read: a @Version field must still have
its value in VALUES (the write adds one to it), and with EXPECTED every stored field must still have its value there.
A row that another writer changed meanwhile is a conflict (409); a row that is not there is a 404. On a scoped Db
the actor needs the write role on the row, and only the fields it may write are written.

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

### `Db.patchRow`

```gizlang
function Db.patchRow(self: Db, shape: Model.Shape, key: Vec<Value>, at: i64, value: Value, expected: Option<Value>): bool throws Model.Rejection
```

Changes the field AT of the row with these key values to VALUE, as one UPDATE of one column: the actor of a scoped Db
needs the write role on the field. When EXPECTED is given the update holds only while the stored field still has that
value (checked by the database inside the write), else it is a 409: two people who change one field never overwrite
each other unseen. A value that is the stored one changes nothing. For a grid's cell.

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

### `Db.removeRow`

```gizlang
function Db.removeRow(self: Db, shape: Model.Shape, key: Vec<Value>): bool throws Model.Rejection
```

Removes the row of SHAPE with these key values: the actor of a scoped Db needs the write role on it. Its place and
grants go in the same transaction.

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

### `Db.follow`

```gizlang
function Db.follow<R>(self: Db, q: Query.Query<R>, dependencies: Vec<string> = []): string throws Model.Rejection
```

Follows the records that Q selects; the follow's id, which `changed` reads and `unfollow` ends. Open it before the
page reads the records: a change in between is delivered again. A page keeps the id between its requests; a loop in
one place uses `watch`.

### `Db.unfollow`

```gizlang
function Db.unfollow(self: Db, id: string): bool throws Model.Rejection
```

Ends the follow `id`: its page went away. An unknown or lost one ends too.

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

### `Db.changed`

```gizlang
function Db.changed(self: Db, id: string, waitMs: i64): Changed throws Model.Rejection
```

The changes of the follow `id` since its position, waiting up to `waitMs` for one; each read renews the watch's
lease.

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

### `Watch.wait`

```gizlang
function Watch.wait(self: mut Watch, waitMs: i64): Changed throws Model.Rejection
```

The changes since the last wait, waiting up to WAIT_MS for one (`changed`). A lost follow is followed again and
answers lost: the caller reads the selection again.

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

### `Watch.dispose`

```gizlang
function Watch.dispose(self: Watch): bool throws Model.Rejection
```

Ends the watch (`unfollow`).

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

### `Db.as`

```gizlang
function Db.as(self: Db, space: string, actor: Security.Principal, now?: i64): Db throws Model.Rejection
```

The same records as ACTOR of the Space SPACE may use them at NOW (ms since 1970; left out: the clock's now): every
verb of the Db this gives is checked by the Gate. A row the actor may not read is absent, and a field it may not
read is none: declare such a field (@Read) optional in its type, else a typed record shows the type's empty value.

Effects: fail, write, io, alloc.

### `Db.trusted`

```gizlang
function Db.trusted(self: Db): Db
```

The same records without an actor: for the host's own work on a scoped Db (a worker's claim, an audit line), which
no Gate judges. A caller's code never needs it.

### `Db.version`

```gizlang
function Db.version(self: Db): i64
```

A count that moves when any thread commits a change, so an answer made at one version is right while the count
stays; -1 when the store cannot say (a SQL store, a transaction).

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

### `Db.install`

```gizlang
function Db.install(self: Db, shapes: Vec<Model.Shape>): bool throws Model.Rejection
```

Makes the tables and indexes of SHAPES that are not there, and adds the columns a table lacks.

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

### `Db.transaction`

```gizlang
function Db.transaction<T>(self: Db, work: (tx: Db) => T throws Model.Rejection): T throws Model.Rejection
```

WORK as one transaction: TX is this Db inside it, WORK's answer is the transaction's, and an error undoes all of it.
TX lives only inside WORK.

### `Db.from`

```gizlang
function Db.from<R>(self: Db): Query.Query<R>
```

Every stored record of R, as a Query that this Db runs: its operators say what to read, and `rows`, `first`, `one`,
`count`, `sum`, `stream` or `watch` answers: `db.from<Task>().filter((t) => !t.done).first()`.

### `Db.sql`

```gizlang
function Db.sql(self: Db, text: string, params: Vec<Option<string>> = []): Sql.Rows throws Model.Rejection
```

Runs SQL text on the store, with its parameters $1.. PARAMS: for a tool or a script. A scoped Db refuses it (text
passes no Gate), and so does a Db that rides an engine.

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

### `Db.lock`

```gizlang
function Db.lock(self: Db, name: string): bool throws Model.Rejection
```

Inside a transaction: takes the lock NAME until the transaction ends, so that two transactions of one subject (a
thread, a payment) run in turn. A Db that rides an engine has no such lock and refuses.

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

### `Db.script`

```gizlang
function Db.script(self: Db, text: string): bool throws Model.Rejection
```

Runs a script of SQL statements, without parameters or results, on the store: a tool's schema or seed file. As
`sql`, a scoped Db and a Db that rides an engine refuse it.

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

### `Db.write`

```gizlang
function Db.write(self: Db, writes: Vec<Policy.Write>, conflict: string): i64 throws Model.Rejection
```

Runs WRITES (the write specs of this module) as one transaction; how many rows they changed. A key that is there
or a guard that fails is a 409 with CONFLICT. The typed verbs below are built on it.

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

### `Db.insert`

```gizlang
function Db.insert<T>(self: Db, record: T, existing?: Query.Existing): i64 throws Model.Rejection
```

Inserts RECORD. A record whose key is there is refused (409), kept, replaced or added to, as EXISTING says (refused
when left out). On a scoped Db the actor needs the write role on the record's parent.

### `Db.insertAll`

```gizlang
function Db.insertAll<T>(self: Db, records: Vec<T>, existing?: Query.Existing): i64 throws Model.Rejection
```

Inserts RECORDS in one transaction of a few statements, as `insert` inserts each.

### `Db.save`

```gizlang
function Db.save<T>(self: Db, record: T, expected?: T): bool throws Model.Rejection
```

Writes RECORD over the stored record of its key. When the type has a @Version field, the write holds only while the
stored count is RECORD's, and adds one to it: a record that another writer saved meanwhile is a conflict (409), and
a record that is not there is a 404. With EXPECTED (the record as the writer read it) the write holds only while
every stored field still has its value there, for a type without a @Version field. On a scoped Db the actor needs
the write role on the record, and only the fields it may write are written.

### `Read.on`

```gizlang
function Read.on<R>(self: Read<R>, db: Db): Read<R>
```

The same read on DB: its answers come from DB, as DB's actor may read them.

### `Read.rows`

```gizlang
function Read.rows<R>(self: Read<R>): Vec<R> throws Model.Rejection
```

The records that this read selects. With a row limit (Data.Options.rowLimit), an answer of more rows is refused.

### `Read.first`

```gizlang
function Read.first<R>(self: Read<R>): Option<R> throws Model.Rejection
```

The first record that this read selects, if any.

### `Read.one`

```gizlang
function Read.one<R>(self: Read<R>): R throws Model.Rejection
```

The first record that this read selects; none is a rejection (404).

### `Read.count`

```gizlang
function Read.count<R>(self: Read<R>): i64 throws Model.Rejection
```

How many records this read selects: a COUNT, not the records.

### `Read.sum`

```gizlang
function Read.sum<R>(self: Read<R>, field: Lambda.Expr<R, i64>): i64 throws Model.Rejection
```

The sum of the integer value that the lambda FIELD makes of each record this read selects; 0 when there are none.

### `Read.stream`

```gizlang
function Read.stream<R>(self: Read<R>, each: (batch: Batch) => bool throws DbError): i64 throws Model.Rejection
```

Reads what this read selects a batch of typed columns at a time: EACH takes a batch and says whether to go on
(false ends the read at the store). The memory of the read is one batch, and nothing of it outlives the call; how
many rows EACH took. A grid, a chart, an export and a tensor read this.

### `Read.keys`

```gizlang
function Read.keys<R>(self: Read<R>): Vec<Vec<Value>> throws Model.Rejection
```

The keys of the records that this read selects, in the same order and window, without decoding every record.

### `Read.watch`

```gizlang
function Read.watch<R>(self: Read<R>): Watch throws Model.Rejection
```

Follows the records that this read selects, as a Watch: `wait` answers when they change. Open it before the records
are read: a change in between is told again. A watch means what a read means: on a scoped Db a change says only that
the selection changed (`whole`), so no key of a hidden row is told, and the caller reads again through the Gate.

### `Read.update`

```gizlang
function Read.update<R, A>(self: Read<R>, set: Lambda.Expr<R, A>): i64 throws Model.Rejection
```

Sets the fields of the record that SET makes on every stored record this Query selects, each to its value over the
stored record; how many changed: `db.from<Task>().filter((t) => t.owner === id).update((t) => ({ tries: t.tries + 1 }))`.
A write needs a condition, and a page, a projection or a union reaches no write: each is refused. A scoped Db
writes one record at a time (`save`): it refuses this.

### `Read.remove`

```gizlang
function Read.remove<R>(self: Read<R>): i64 throws Model.Rejection
```

Removes every stored record this Query selects; how many went: `db.from<Task>().filter((t) => t.done).remove()`.
On a scoped Db each record the actor may read is removed as the Gate admits it, in one transaction.

## Constants

### `WRITE_POINT`

```gizlang
const WRITE_POINT = "giz_write"
```

The savepoint of one write inside a held transaction: a refused write undoes itself only, so the work can go on to
show why, and the caller ends the whole transaction.

### `WITHIN_POINT`

```gizlang
const WITHIN_POINT = "giz_within"
```

The savepoint of a `within` inside a held transaction: its work joins the outer transaction, and a refusal undoes that work
only. A page action is one transaction, so a module that holds its own (a queued Run and its input) runs inside it.

