#flatdb API reference

A file-backed JSON document store. Load a JSON file once into a value-semantic handle, query and edit it in memory through JSON Pointer, and write it back with a crash-atomic whole-file replace (temp file + rename). It is deliberately NOT a database engine: crash-atomic snapshotting of small data. Atomicity is whole-file (temp + rename); there is no isolation (one process, reload-the-whole-file, no concurrent transactions) and durability is only as strong as the OS's buffering of the rename. For a real database, use a client over net (e.g. redis), not this. It is a thin file-lifecycle + ergonomics layer over the json write surface, not a re-implementation of it. Runs on both binaries (pure json + fs, no network).

Import with import "flatdb.j" as flatdb;. See the flatdb guide for prose and examples.

#Functions

#flatdb.append(db as DB, pointer as string, value as json.Value)

Push value onto the list addressed by pointer, returning a new DB. The list must already exist (create it first with set($db, ptr, json.list())).

Parameters

• db {DB} - the store to edit
• pointer {string} - the JSON Pointer to a list
• value {json.Value} - the value to append

Returns {DB} - a new store with the element appended

Throws

• {Error} - when pointer does not resolve to an existing list

#flatdb.get(db as DB, pointer as string)

Return the sub-document at pointer (the whole document for "").

Parameters

• db {DB} - the store to read
• pointer {string} - the JSON Pointer

Returns {json.Value} - the node at pointer

Throws

• {Error} - when pointer does not resolve

#flatdb.has(db as DB, pointer as string)

Report whether pointer resolves to an existing node.

Parameters

• db {DB} - the store to read
• pointer {string} - the JSON Pointer

Returns {bool} - true when the node exists

#flatdb.keys(db as DB, pointer as string)

List the keys of the object at pointer, in document order.

Parameters

• db {DB} - the store to read
• pointer {string} - the JSON Pointer to an object

Returns {list of string} - the object's keys

Throws

• {Error} - when pointer does not resolve to an object

#flatdb.length(db as DB, pointer as string)

Return the element count of a list, or entry count of an object, at pointer.

Parameters

• db {DB} - the store to read
• pointer {string} - the JSON Pointer to a list or object

Returns {int} - the element or entry count

Throws

• {Error} - when pointer does not resolve to a list or object

#flatdb.open(path as string)

Load the JSON document at path into a DB. A missing file yields an empty document (an empty object), so open never fails on a first run.

Parameters

• path {string} - the backing file path

Returns {DB} - the loaded store

#flatdb.openString(text as string)

Load a DB from an in-memory JSON string instead of a file - for a database fetched over the network (http.get(url, {}).body), embedded in the program, or built elsewhere. The returned DB has no backing path, so it is read-only: every reader verb works and the mutating verbs still return a fresh in-memory DB, but save throws (there is nowhere to write). Whitespace-only text yields an empty document, matching open on a missing file. This keeps flatdb transport-agnostic: it never imports http / net, so it stays fs-only and builds on both binaries; the caller brings the bytes.

Parameters

• text {string} - the JSON document

Returns {DB} - a read-only store

#flatdb.remove(db as DB, pointer as string)

Drop the key or element at pointer, returning a new DB.

Parameters

• db {DB} - the store to edit
• pointer {string} - the JSON Pointer to remove

Returns {DB} - a new store with the node removed

Throws

• {Error} - when pointer does not resolve

#flatdb.save(db as DB)

Write the document back to its own backing file, crash-atomically (temp + rename). A read-only DB (from openString, no backing file) has nowhere to write - use saveAs to give it a path.

Parameters

• db {DB} - the store to persist

Throws

• {Error} - kind "flatdb" if the DB is read-only (no backing file), or on a filesystem write or rename failure

#flatdb.saveAs(db as DB, path as string)

Write the document to path (not necessarily its own) and return a fresh DB bound to that path - the passed-in db is unchanged (value semantics, like set / append / remove). Two uses: the first dump to disk of a read-only openString DB, and copying / forking an on-disk store to a new file (a snapshot or a new version). Which store is "current" for the next save is whichever handle you keep - reassign ($db = flatdb.saveAs($db, path);) to make the new file current, or hold both to keep the original too. Same crash-atomic temp+rename as save.

Parameters

• db {DB} - the store whose data to write
• path {string} - the destination file path

Returns {DB} - a new DB bound to path (its data equals db's)

Throws

• {Error} - kind "flatdb" if path is empty, or on a filesystem failure

#flatdb.set(db as DB, pointer as string, value as json.Value)

Write value at pointer (upsert an object key / replace a list index), returning a new DB. Strict: intermediate containers must already exist.

Parameters

• db {DB} - the store to edit
• pointer {string} - the JSON Pointer to write
• value {json.Value} - the value to write (build scalars with json.decode, objects and lists with json.map / json.list)

Returns {DB} - a new store with the write applied

Throws

• {Error} - when an intermediate container does not exist

#Structs

#flatdb.DB

The value the caller holds: the file path plus the decoded document. A module holds no mutable state and spawn deep-copies scope, so a store cannot be a shared open connection - it is a value. Mutating verbs return a fresh DB; save is the only side effect.