GizStack
View .mdOpen in ChatGPTOpen in Claude

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.