# gizdb/local

the GizDB engine in this process, the one owner of that path. It serves a folder (serve), and gives typed records (gizmodel/data) their engine as a Data.Engine. gizmodel/data, gizmodel/store and the record layer import no engine module, so an app on SQLite or PostgreSQL links none. Only .giz programs reach it.

```gizlang
import * as Local from "gizdb/local";
```

## Types

### `Endpoint`

```gizlang
type Endpoint = { endpoint: Access.Endpoint; identity: string; secret: bytes; }
```

Where typed connections reach an engine this process serves, from any thread.

- `endpoint`: `M101.Endpoint`
- `identity`: `string`
- `secret`: `bytes`

### `Served`

```gizlang
type Served = { engine: Data.Engine; endpoint: Endpoint; stop: () => void; }
```

A GizDB folder this process serves (serve): its engine for typed records (Data.open with `engine`, Data.connect), where it is, and STOP,
which stops its server after a checkpoint. A connection to it is Store.open of its folder, as from any other process.

- `engine`: `M127.Engine`
- `endpoint`: `M106.Endpoint`
- `stop`: `() => void`

### `Options`

```gizlang
type Options = { sync: bool; }
```

How a served folder keeps a commit. With `sync` (the default) a commit answers after the disk holds it: it survives a
power loss. Without it a commit answers when the operating system has it: it survives the end of the process, and a
power loss may lose the last commits (never a part of one).

- `sync`: `bool`

## Functions

### `memory`

```gizlang
function memory(): Served throws SqlError
```

Serves a new, empty GizDB in memory until Served.stop, which ends it: nothing of it stays. Its files are in the
host's memory file system where there is one, else in the temporary folder, and no commit waits for a disk. A
database to keep, in memory or not, is `serve` of a folder you name, with `{ sync: false }` to not wait for the disk.

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

### `serve`

```gizlang
function serve(location: string, how: Options = { sync: true }): Served throws SqlError
```

Serves the GizDB folder `location` in this process until Served.stop: its engine for typed records (Data.open with `engine`), and the
PostgreSQL server at its unix socket, which every connection reaches with Store.open, this process's too. Its first
start moves in the SQLite file `location`.db when there is one (Store.movedIn). A folder that a process serves already
is an error: serving has one owner.

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

### `engineOf`

```gizlang
function engineOf(endpoint: Endpoint): Data.Engine
```

The engine at ENDPOINT as typed records take it (Data.Engine).

Effects: fail, alloc.

### `connectTo`

```gizlang
function connectTo(endpoint: Endpoint): Access.Connection throws DbError
```

A connection of its own to ENDPOINT.

Effects: fail, io, alloc.

### `db`

```gizlang
function db(connection: Access.Connection, name: string): Data.Db
```

The database NAME of CONNECTION, on the GizDB engine: every call goes to its data actor. Data.open reads on its thread.

Effects: fail, alloc.

### `engineDb`

```gizlang
function engineDb(connection: Access.Connection, name: string, lane: Option<Access.Lane>): Data.Db
```

The database NAME of CONNECTION, whose reads run on LANE when it has one (Data.open makes its own lane).

Effects: fail, alloc.

## Methods

### `Endpoint.connect`

```gizlang
function Endpoint.connect(self: Endpoint, name: string): Data.Db throws DbError
```

NAME on a connection of its own whose calls all go to the data actor (a factory that may make no state of its thread,
App.Serving.uploads).

Effects: fail, io, alloc.

### `Endpoint.of`

```gizlang
function Endpoint.of(self: Endpoint, name: string): Data.Db throws DbError
```

NAME on a connection of its own whose reads run on the thread of SYS (Access.Lane).

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

