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).
import * as Data from "gizmodel/data";Types
Engine
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.
connectof
Watch
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.Dbfind:M131.Query<Vec<M143.Value>>id:string
Options
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
function newKey(): stringA 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
function connect(store: Sql.Database, engine: Option<Engine>, feed: Option<Relay.Relay>, name: string): Db throws DbErrorThe 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
function heldRefusal(): Model.RejectionWhat a held transaction does not do: define tables.
inside
function inside(tx: Sql.Database, feed: Option<Relay.Relay> = undefined, name: string = "data"): DbThe 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
function statement(command: Tree.Statement, params: Vec<Value>, rows: Option<i64> = undefined): Policy.WriteThe 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
function changing<R>(find: Query.Query<R>, sets: Vec<Query.Assignment>, rows: Option<i64> = undefined): Policy.Write throws Model.RejectionThe UPDATE that sets SETS (Query.set) on the records FIND selects, as statement. FIND needs a condition.
deleting
function deleting<R>(find: Query.Query<R>, rows: Option<i64> = undefined): Policy.Write throws Model.RejectionThe DELETE of the records FIND selects, as statement. FIND needs a condition.
insertRows
function insertRows(shape: Model.Shape, rows: Vec<Model.Row>, existing?: Query.Existing): Policy.Write throws Model.RejectionInsert 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
function insert<T>(shape: Model.Shape, v: T, existing?: Query.Existing): Policy.Write throws Model.RejectionInsert the record v of a stored Shape, as insertRows.
counted
function counted<R>(source: Source.Source, find: Query.Query<R>): i64 throws Model.RejectionHow many rows FIND's conditions select in SOURCE.
changedKey
function changedKey(keys: mut Vec<Value>, seen: mut Map<bytes, bool>, key: Value): voidA key invalidates one record even when both images or several writes select it.
Effects: fail, alloc.
sameFollow
function sameFollow(a: string, b: string): boolWhether the follow ids A and B name one watch: a page's next answer moves the position, not the watch.
Effects: fail, alloc.
holdsWatch
function holdsWatch(id: string): boolWhether 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
function watching<R>(db: Db, q: Query.Query<R>): Watch throws Model.RejectionThe Watch of the records that Q selects on DB (Query.watch).
open
function open(location: string, options: Options = {}): Db throws Model.RejectionThe 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
function readRefusal(self: Db, e: DbError): Model.RejectionA 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
function updated<R, A>(self: Db, find: Query.Query<R>, set: Lambda.Expr<R, A>): i64 throws Model.RejectionQuery.update on DB: the UPDATE of the records FIND selects, with the fields that SET makes.
removed
function removed<R>(self: Db, find: Query.Query<R>): i64 throws Model.RejectionQuery.remove on DB: the DELETE of the records FIND selects; on a scoped Db, each one through the Gate.
Methods
Db.inSchema
function Db.inSchema(self: Db, schema: string): Db throws Model.RejectionThe 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
function Db.dispose(self: Db): bool throws Model.RejectionEnd the connection.
Effects: fail, read, write, console, io, alloc.
Db.selected
function Db.selected<R>(self: Db, q: Query.Query<R>): Query.Query<R> throws Model.RejectionQ 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
function Db.prepared<R>(self: Db, q: Query.Query<R>): Tree.Prepared<bool, R> throws Model.RejectionQ 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
function Db.row(self: Db, shape: Model.Shape, key: Vec<Value>): Vec<Value> throws Model.RejectionThe 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
function Db.hasRow(self: Db, shape: Model.Shape, key: Vec<Value>): bool throws Model.RejectionWhether 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
function Db.createRow(self: Db, shape: Model.Shape, values: Vec<Value>): Vec<Value> throws Model.RejectionCreates 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
function Db.createRows(self: Db, shape: Model.Shape, rows: Vec<Vec<Value>>): i64 throws Model.RejectionCreates 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
function Db.saveRow(self: Db, shape: Model.Shape, values: Vec<Value>, expected: Vec<Value> = []): Vec<Value> throws Model.RejectionWrites 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
function Db.patchRow(self: Db, shape: Model.Shape, key: Vec<Value>, at: i64, value: Value, expected: Option<Value>): bool throws Model.RejectionChanges 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
function Db.removeRow(self: Db, shape: Model.Shape, key: Vec<Value>): bool throws Model.RejectionRemoves 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
function Db.follow<R>(self: Db, q: Query.Query<R>, dependencies: Vec<string> = []): string throws Model.RejectionFollows 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
function Db.unfollow(self: Db, id: string): bool throws Model.RejectionEnds the follow id: its page went away. An unknown or lost one ends too.
Effects: fail, read, write, console, io, alloc.
Db.changed
function Db.changed(self: Db, id: string, waitMs: i64): Changed throws Model.RejectionThe 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
function Watch.wait(self: mut Watch, waitMs: i64): Changed throws Model.RejectionThe 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
function Watch.dispose(self: Watch): bool throws Model.RejectionEnds the watch (unfollow).
Effects: fail, read, write, console, io, alloc.
Db.as
function Db.as(self: Db, space: string, actor: Security.Principal, now?: i64): Db throws Model.RejectionThe 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
function Db.trusted(self: Db): DbThe 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
function Db.version(self: Db): i64A 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
function Db.install(self: Db, shapes: Vec<Model.Shape>): bool throws Model.RejectionMakes 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
function Db.transaction<T>(self: Db, work: (tx: Db) => T throws Model.Rejection): T throws Model.RejectionWORK 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
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
function Db.sql(self: Db, text: string, params: Vec<Option<string>> = []): Sql.Rows throws Model.RejectionRuns 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
function Db.lock(self: Db, name: string): bool throws Model.RejectionInside 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
function Db.script(self: Db, text: string): bool throws Model.RejectionRuns 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
function Db.write(self: Db, writes: Vec<Policy.Write>, conflict: string): i64 throws Model.RejectionRuns 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
function Db.insert<T>(self: Db, record: T, existing?: Query.Existing): i64 throws Model.RejectionInserts 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
function Db.insertAll<T>(self: Db, records: Vec<T>, existing?: Query.Existing): i64 throws Model.RejectionInserts RECORDS in one transaction of a few statements, as insert inserts each.
Db.save
function Db.save<T>(self: Db, record: T, expected?: T): bool throws Model.RejectionWrites 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
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
function Read.rows<R>(self: Read<R>): Vec<R> throws Model.RejectionThe records that this read selects. With a row limit (Data.Options.rowLimit), an answer of more rows is refused.
Read.first
function Read.first<R>(self: Read<R>): Option<R> throws Model.RejectionThe first record that this read selects, if any.
Read.one
function Read.one<R>(self: Read<R>): R throws Model.RejectionThe first record that this read selects; none is a rejection (404).
Read.count
function Read.count<R>(self: Read<R>): i64 throws Model.RejectionHow many records this read selects: a COUNT, not the records.
Read.sum
function Read.sum<R>(self: Read<R>, field: Lambda.Expr<R, i64>): i64 throws Model.RejectionThe sum of the integer value that the lambda FIELD makes of each record this read selects; 0 when there are none.
Read.stream
function Read.stream<R>(self: Read<R>, each: (batch: Batch) => bool throws DbError): i64 throws Model.RejectionReads 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
function Read.keys<R>(self: Read<R>): Vec<Vec<Value>> throws Model.RejectionThe keys of the records that this read selects, in the same order and window, without decoding every record.
Read.watch
function Read.watch<R>(self: Read<R>): Watch throws Model.RejectionFollows 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
function Read.update<R, A>(self: Read<R>, set: Lambda.Expr<R, A>): i64 throws Model.RejectionSets 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
function Read.remove<R>(self: Read<R>): i64 throws Model.RejectionRemoves 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
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
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.