# gizmodel/held

the types of a typed read and of the Db that runs it. A Query names its Db and a Db's operations take a Query, so the two types are declared together, below both files: model/query.giz builds a Query, model/data.giz opens a Db and answers a Query, and each gives its type's name again.

```gizlang
import * as Held from "gizmodel/held";
```

## Types

### `Query`

```gizlang
type Query<R> = { shape: Model.Shape; read: (row: Vec<Value>) => R effects {fail, alloc}; where: Vec<Tree.Expr>; order: Vec<Tree.Order>; skip: i64; limit: i64; distinct: bool; fault: string; source: Vec<Tree.From>; db: Option<Db>; }
```

A read of the stored records R of `shape`: the conjunction `where` of typed conditions over its columns, the order
(none: the key order), the rows skipped and the most rows (0: all), and `read`, which makes a record of a row. A field
the Model.Shape does not have, or a value its column does not take, is the `fault` the read fails with.

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

### `Ops`

```gizlang
type Ops = { install: (shapes: Vec<Model.Shape>) => bool throws Model.Rejection; define: (statements: Vec<string>) => bool throws Model.Rejection; write: (writes: Vec<Policy.Write>, conflict: string, schema: string) => i64 throws Model.Rejection; follow: (find: Query<Vec<Value>>, dependencies: Vec<string>) => string throws Model.Rejection; changed: (id: string, waitMs: i64) => Changed throws Model.Rejection; unfollow: (id: string) => bool throws Model.Rejection; dispose: () => bool throws DbError; within: (work: (held: Db) => bool throws Model.Rejection) => bool throws Model.Rejection; version: () => i64; }
```

What differs between the two stores, as closures: each constructor (`db`, `connect`) gives the operations of its store, so no call branches on which one holds the records.

- `install`: `(shapes: Vec<M133.Shape>) => bool throws M133.Rejection`
- `define`: `(statements: Vec<string>) => bool throws M133.Rejection`
- `write`: `(writes: Vec<M134.Write>, conflict: string, schema: string) => i64 throws M133.Rejection`
- `follow`: `(find: M131.Query<Vec<M143.Value>>, dependencies: Vec<string>) => string throws M133.Rejection`
- `changed`: `(id: string, waitMs: i64) => M131.Changed throws M133.Rejection`
- `unfollow`: `(id: string) => bool throws M133.Rejection`
- `dispose`: `() => bool throws M129.DbError`
- `within`: `(work: (held: M131.Db) => bool throws M133.Rejection) => bool throws M133.Rejection`
- `version`: `() => i64`

### `Db`

```gizlang
type Db = { source: Source.Source; ops: Ops; schema: string; scope: Option<Gate.Scope>; rowLimit: i64; store: Option<Sql.Database>; }
```

A database and the operations of its store, which every call of this module takes. `schema` is the PostgreSQL schema its
tables are in ("" the store's own): a library's records (auth.users) stand beside the team's tables of the same name.

- `source`: `M140.Source`
- `ops`: `M131.Ops`
- `schema`: `string`
- `scope`: `_gizlang_sdk_core.Option<M130.Scope>` — The actor whose Gate checks every call (`as`); none: a trusted Db.
- `rowLimit`: `i64` — The most rows `rows` answers; 0: no limit.
- `store`: `_gizlang_sdk_core.Option<gizlang_sql.Database>` — The SQL store that holds the records, when one does: `sql` runs on it.

### `Changed`

```gizlang
type Changed = { keys: Vec<Value>; lost: bool; follow: string; whole: bool; }
```

What changed in a followed selection: the first key of each row that came,
went or changed, and the id to follow on with. `lost` is true when the
follow is unknown or expired: render the selection again with a new follow.

- `keys`: `Vec<M143.Value>`
- `lost`: `bool`
- `follow`: `string`
- `whole`: `bool`

