# gizlang/state

typed values at paths, for one program to own and others to read, change and watch: an operating system's settings, an app's preferences, a service's configuration.

- A path is segments joined by "/" (`display/monitor/del-a12f`). A value is JSON. A schema ties a path pattern to a Gizlang type and a rule: every write is read as that type, checked by its constraint annotations (gizlang/constraints) and the rule, and stored as the type writes it (gizlang/json encode), so a value has one form and a typo in a field name is refused, not stored. - A commit is a list of edits (put, patch as RFC 7396 JSON Merge Patch, delete), each optionally on the condition of its path's revision. It is atomic and durable when it answers. - A watch is a prefix and a revision: each path changed after it, once, at its last change, then those of each new commit. A watcher too far behind gets the prefix's current values instead (reset). - A medium keeps the keys (Medium): the KV engine's log (gizdb/kv/local medium) or one TOML file (tomlFile). A program imports the one it keeps, so a small image links this module and gizlang/toml alone. - One process owns the store. serve answers JSON-RPC 2.0 lines on a unix-domain socket; one task runs every request in turn, so commits that arrive together share one sync. `gizdb state` is its command line.

```gizlang
import * as State from "gizlang/state";
```

## Types

### `Entry`

```gizlang
type Entry = { key: bytes; value: bytes; revision: i64; }
```

A key, its value and the revision of the commit that wrote it.

- `key`: `bytes`
- `value`: `bytes`
- `revision`: `i64`

### `Write`

```gizlang
type Write = { key: bytes; value: Option<bytes>; expect: i64; }
```

One write of a commit: KEY gets VALUE, or goes when VALUE is none. EXPECT: the key has not changed after that revision
(0: it is absent), so one revision a reader read at guards every key it read; -1 for no condition.

- `key`: `bytes`
- `value`: `_gizlang_sdk_core.Option<bytes>`
- `expect`: `i64`

### `Change`

```gizlang
type Change = { revision: i64; key: bytes; value: Option<bytes>; }
```

A key that a commit of REVISION wrote (VALUE) or deleted (none).

- `revision`: `i64`
- `key`: `bytes`
- `value`: `_gizlang_sdk_core.Option<bytes>`

### `Changed`

```gizlang
type Changed = { reset: bool; changes: Vec<Change>; revision: i64; }
```

The durable changes after a revision, up to REVISION. RESET: the changes were no longer kept, so CHANGES holds every
current key of the prefix instead, and the reader replaces what it knew of the prefix.

- `reset`: `bool`
- `changes`: `Vec<gizlang_state.Change>`
- `revision`: `i64`

### `KvError`

```gizlang
type KvError = | { kind: "conflict"; key: bytes; revision: i64 } | { kind: "invalid"; key: bytes; message: string } | { kind: "io"; message: string }
```

Why a commit failed: a condition did not hold (the key and its revision), a key the medium cannot keep, or the
medium could not be written.

- `conflict`
- `invalid`
- `io`

### `Medium`

```gizlang
type Medium = { get: (key: bytes) => Option<Entry>; range: (prefix: bytes) => Vec<Entry>; apply: (writes: Vec<Write>) => i64 throws KvError; flush: () => void throws KvError; changes: (prefix: bytes, after: i64) => Changed; committed: () => i64; dispose: () => void throws KvError; }
```

A medium of a store: what keeps its keys, as functions over the medium's own state (gizdb/kv/local medium,
tomlFile). A program holds the one it opened; the store calls nothing else.

- `get`: `(key: bytes) => _gizlang_sdk_core.Option<gizlang_state.Entry>` — The entry of KEY, or none.
- `range`: `(prefix: bytes) => Vec<gizlang_state.Entry>` — The entries whose keys start with PREFIX, in byte order.
- `apply`: `(writes: Vec<gizlang_state.Write>) => i64 throws gizlang_state.KvError` — Runs WRITES as the next commit, in memory: its revision.
- `flush`: `() => void throws gizlang_state.KvError` — Makes every applied commit durable.
- `changes`: `(prefix: bytes, after: i64) => gizlang_state.Changed` — The durable changes after revision AFTER of the keys that start with PREFIX.
- `committed`: `() => i64` — The last durable revision.
- `dispose`: `() => void throws gizlang_state.KvError` — Flushes and closes the medium.

### `Mark`

```gizlang
type Mark = { revision: i64; key: bytes; gone: bool; }
```

A key a commit of REVISION wrote, or deleted (GONE).

- `revision`: `i64`
- `key`: `bytes`
- `gone`: `bool`

### `Recent`

```gizlang
type Recent = { marks: Vec<Mark>; floor: i64; }
```

The changes kept for readers behind the newest revision, after `floor`, in order: about 80 bytes each. A reader at
or after `floor` sees every change since; one before it does not, and neither does a condition.

- `marks`: `Vec<gizlang_state.Mark>`
- `floor`: `i64`

### `Schema`

```gizlang
type Schema = { pattern: Vec<string>; check: (value: Json) => Checked; }
```

A path pattern ("*" is one segment, a last "**" any number) and what its values must be: CHECK gives a value's
stored form, or why it is refused.

- `pattern`: `Vec<string>`
- `check`: `(value: gizlang_json.Json) => gizlang_state.Checked`

### `Checked`

```gizlang
type Checked = { text: string; error: string; }
```

A value's stored form (TEXT), or the reason it is refused (ERROR, with TEXT empty).

- `text`: `string`
- `error`: `string`

### `Item`

```gizlang
type Item = { path: string; text: string; revision: i64; }
```

A path, its value as stored JSON text ("null" for a deleted path in changes), and the revision of the commit that
wrote it. The text is parsed only when asked (Item.value): a list need not parse what it hands on.

- `path`: `string`
- `text`: `string`
- `revision`: `i64`

### `Edit`

```gizlang
type Edit = { path: string; op: string; value: Json; expect: i64; }
```

One edit of a commit. OP is "put" (VALUE is the value), "patch" (VALUE is a merge patch of the current value, or of
{} when there is none) or "delete". EXPECT: the path has not changed after that revision (0: it is absent), so the
revision a reader read at guards all it read; -1 for none.

- `path`: `string`
- `op`: `string`
- `value`: `gizlang_json.Json`
- `expect`: `i64`

### `StateError`

```gizlang
type StateError = { kind: string; path: string; message: string; }
```

Why a request failed: "invalid" (a path or value its schema refuses), "conflict" (a path changed after its expected
revision), "denied" (the service's admit refused it), "io" (the log could not be written: the store stops) or
"closed" (no store answers).

- `kind`: `string`
- `path`: `string`
- `message`: `string`

### `Changes`

```gizlang
type Changes = { reset: bool; items: Vec<Item>; revision: i64; }
```

The changes after a revision; RESET: the values of the whole prefix, which replace what the reader knew.

- `reset`: `bool`
- `items`: `Vec<gizlang_state.Item>`
- `revision`: `i64`

### `State`

```gizlang
type State = { medium: Medium; schemas: Vec<Schema>; }
```

The store: its medium and the schemas of its paths.

- `medium`: `gizlang_state.Medium`
- `schemas`: `Vec<gizlang_state.Schema>`

### `Peer`

```gizlang
type Peer = PeerCredentials
```

Who asks, as the kernel saw the connection (no uid: -1).

### `Admit`

```gizlang
type Admit = (peer: Peer, method: string, path: string) => bool
```

Whether PEER may run METHOD (get, list, watch, commit) on PATH: a get's or commit edit's path, a list's or watch's
prefix. The store's owner gives its policy; the service asks it for every path of every request.

### `Client`

```gizlang
type Client = { lines: Lines; next: i64; }
```

A connection to a store that serve answers.

- `lines`: `gizlang_state.Lines`
- `next`: `i64`

### `TomlFile`

```gizlang
type TomlFile = { dir: Dir; name: string; values: SortedMap<bytes, Kept>; revision: i64; durable: i64; recent: Recent; }
```

A store in one TOML file, for a machine too small for a log (tomlFile): `revision = N`, then each path's value, an
object as the table ["path"] and any other value as the key "path" = value. A flush writes the whole file anew: a
temporary file, its sync, a rename over the old one, the folder's sync (settings are a few KB). After a restart
every path has the file's revision: a condition from before it conflicts, and a watcher from before it resets. TOML
has no null: a null field is left out, and a value with a null in an array cannot be kept.

- `dir`: `gizlang_system.Dir`
- `name`: `string`
- `values`: `_gizlang_sdk_collections.SortedMap<bytes, gizlang_state.Kept>`
- `revision`: `i64`
- `durable`: `i64`
- `recent`: `gizlang_state.Recent`

### `Kept`

```gizlang
type Kept = { value: bytes; revision: i64; }
```

A value of a TOML file and the revision that wrote it.

- `value`: `bytes`
- `revision`: `i64`

## Functions

### `recentAt`

```gizlang
function recentAt(revision: i64): Recent
```

Nothing kept yet, at REVISION: a reader from before it reads its prefix whole.

### `resetOf`

```gizlang
function resetOf(entries: Vec<Entry>, durable: i64): Changed
```

Every current entry of a prefix, ENTRIES, as the changes up to DURABLE of a reader behind the kept ones (reset).

Effects: fail, alloc.

### `changedOf`

```gizlang
function changedOf(since: Vec<Mark>, now: Vec<Option<Entry>>, durable: i64): Changed
```

The changes up to DURABLE of the marks SINCE gives (Recent.since), each with its key's entry NOW: the key once, at
its last change, with its value now (none: deleted).

Effects: fail, alloc.

### `schema`

```gizlang
function schema<T>(pattern: string, rule: (value: T) => string): Schema
```

Values at paths matching PATTERN are read as T: each field must meet its constraint annotations (Min, Max, MaxLength,
Pattern and Values of gizlang/constraints), and the whole must pass RULE, which gives "" or the reason (a check of
several fields, or of another path's value). The value is stored as T writes it.

### `partial`

```gizlang
function partial<T>(pattern: string, base: T, rule: (value: T) => string): Schema
```

Values at paths matching PATTERN hold some fields of T, as a layer of settings does: each field given is checked as
T's, BASE gives the others for the check and RULE sees the whole, and a field T lacks is refused. The value stores
only the fields given, in T's order.

### `layerOf`

```gizlang
function layerOf(stored: Json, given: Json): Json
```

The fields of STORED that GIVEN has, in STORED's order, and so on inside: the stored form of a layer (partial) that
gave the fields of GIVEN.

Effects: fail, alloc.

### `untyped`

```gizlang
function untyped(pattern: string): Schema
```

Values at paths matching PATTERN may be any JSON.

Effects: fail, alloc.

### `open`

```gizlang
function open(medium: Medium, schemas: Vec<Schema>): State
```

The store MEDIUM keeps, for paths SCHEMAS describe (the first match applies).

### `everyone`

```gizlang
function everyone(peer: Peer, method: string, path: string): bool
```

An Admit that lets everyone do everything: for a socket whose file mode already limits who connects.

### `serve`

```gizlang
function serve(state: State, listener: Listener, stop: Task.Cell<i64>, admit: Admit): void throws StateError
```

Serves STATE on LISTENER (a unix-domain socket the caller bound, and gave the mode its clients need) until STOP holds
a value other than 0; serve closes LISTENER then. Each path of each request goes as
ADMIT lets its peer. The methods:
- get {path}: {path, value, revision} or null
- list {prefix}: [{path, value, revision}]
- commit {edits: [{path, op, value, expect}]}: {revision}
- watch {prefix, after}: {revision}, then notices "changes" {reset, revision, items} with a deleted path's value null
- revision {}: {revision}
An error is code 1 invalid, 2 conflict, 3 io (the service stops after it) or 4 denied.

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

### `connect`

```gizlang
function connect(socket: string): Client throws StateError
```

A connection to the store at SOCKET.

Effects: fail, read, io, alloc.

### `tomlFile`

```gizlang
function tomlFile(dir: Dir, name: string): Medium throws StateError
```

The store in file NAME of DIR, read back when it is there.

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

## Methods

### `Recent.keep`

```gizlang
function Recent.keep(self: mut Recent, mark: Mark): void
```

Keeps MARK; past RECENT the oldest commits go, whole, to half of it.

Effects: fail, alloc.

### `Recent.holds`

```gizlang
function Recent.holds(self: Recent, key: bytes, now: i64, expect: i64): bool
```

Whether KEY, whose last write is at revision NOW (0: it is absent), holds condition EXPECT: 0, the key is absent;
N, its last write or delete is at or before N. A key absent now holds N only when no kept change of it is after N,
and N is not before the kept ones.

Effects: fail.

### `Recent.since`

```gizlang
function Recent.since(self: Recent, prefix: bytes, after: i64, durable: i64): Option<Vec<Mark>>
```

The kept changes after AFTER up to DURABLE of the keys that start with PREFIX, or none when AFTER is before them
(the reader resets).

Effects: fail, alloc.

### `Item.value`

```gizlang
function Item.value(self: Item): Json
```

The item's value.

Effects: fail, alloc.

### `State.revision`

```gizlang
function State.revision(self: State): i64
```

The current revision: the last durable commit.

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

### `State.get`

```gizlang
function State.get(self: mut State, path: string): Option<Item>
```

The item at PATH, or none.

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

### `State.read`

```gizlang
function State.read<T>(self: mut State, path: string): Option<T> throws StateError
```

The value at PATH as T, or none. A partial value (partial) reads as T only where it has every field.

### `State.list`

```gizlang
function State.list(self: mut State, prefix: string): Vec<Item>
```

The items whose paths start with PREFIX, in byte order of their paths.

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

### `State.apply`

```gizlang
function State.apply(self: mut State, edits: Vec<Edit>): i64 throws StateError
```

Checks EDITS and runs them as the next commit, in memory; durable after flush. Its revision.

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

### `State.flush`

```gizlang
function State.flush(self: mut State): void throws StateError
```

Makes every applied commit durable.

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

### `State.commit`

```gizlang
function State.commit(self: mut State, edits: Vec<Edit>): i64 throws StateError
```

apply, then flush: the commit is durable when it answers.

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

### `State.write`

```gizlang
function State.write<T>(self: mut State, path: string, value: T): i64 throws StateError
```

Puts VALUE at PATH: a commit of one edit.

### `State.changes`

```gizlang
function State.changes(self: mut State, prefix: string, after: i64): Changes
```

The durable changes after revision AFTER under PREFIX; a deleted path's value is null.

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

### `State.dispose`

```gizlang
function State.dispose(self: mut State): void throws StateError
```

Flushes and closes the store.

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

### `Client.call`

```gizlang
function Client.call(self: mut Client, method: string, params: Json): Json throws StateError
```

The result of METHOD with PARAMS, or its error.

Effects: fail, io, alloc.

### `Client.receive`

```gizlang
function Client.receive(self: mut Client): Json throws StateError
```

The next message the store sends: an answer, or a watch's notice.

Effects: fail, io, alloc.

### `Client.dispose`

```gizlang
function Client.dispose(self: Client): void
```

Closes the connection.

Effects: fail, io, alloc.

### `TomlFile.get`

```gizlang
function TomlFile.get(self: mut TomlFile, key: bytes): Option<Entry>
```

The entry at KEY, or none.

Effects: fail.

### `TomlFile.range`

```gizlang
function TomlFile.range(self: mut TomlFile, prefix: bytes): Vec<Entry>
```

The entries whose keys start with PREFIX, in key order.

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

### `TomlFile.apply`

```gizlang
function TomlFile.apply(self: mut TomlFile, writes: Vec<Write>): i64 throws KvError
```

Applies WRITES at once, after their conditions hold; the new revision. A condition that fails throws a conflict.

Effects: fail, alloc.

### `TomlFile.flush`

```gizlang
function TomlFile.flush(self: mut TomlFile): void throws KvError
```

Writes the file when it has changes it has not written (a temporary file, a sync, a rename).

Effects: fail, read, io, alloc.

### `TomlFile.changes`

```gizlang
function TomlFile.changes(self: mut TomlFile, prefix: bytes, after: i64): Changed
```

The changes under PREFIX after the revision AFTER, or a reset when they are no longer kept.

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

