fenecdb_flutter library

fenecdb in a Flutter app: the fenecdb package, its native library bundled by this plugin for iOS and macOS (FenecFFI.framework, a dynamic framework CocoaPods embeds in the app) and Android (libfenec_ffi.so for each ABI).

final dir = await getApplicationDocumentsDirectory();   // path_provider
final db = await Fenec.open('${dir.path}/app.fenec');

StreamBuilder(
  stream: db.live(db.from('todos').where('done', false)),
  builder: (context, snap) => ListView(children: [
    for (final t in snap.data ?? const []) Text(t['title'] as String),
  ]),
);

Classes

Answer
An answer to a statement: rows, a count of what a write wrote, a word that it was done, or the schemas collections and describe give.
BatchAnswer
What FenecRemote.batch answers: each statement's answer in order, the change the batch left the database at, and whether the answer is the one kept for its idempotency key (replayed) -- a replayed answer carries no seq.
Changes
What Fenec.changes answers: the counter now, and the collections written since -- null when it cannot be told which, everything stale.
Computed
A value a write works out over the row it writes, rendered as FenecQL with its values as parameters: Computed.inc and Computed.expr, as the JS builder's inc and expr. An expression is a column too -- of Query.select, or a key of Query.group -- as are Computed.bucket, Computed.countDistinct, Computed.first and Computed.last, and as names the column it answers under.
Cond
A condition: what Cond.or, Cond.and, Cond.not, Cond.raw and Cond.cmp make. A Map is one too, the JS builder's object condition: each field's value is equality, null is is null, and a map is its operators -- {'year': {'gte': 2024}} -- in the map's order, which is the text's.
FacetCount
One value a facet counted, and how many matching rows hold it. The value is as JSON reads it: text, a number, a boolean, a list, a map, or null for the rows whose field is null.
Fenec
A fenecdb database in a file on the device -- or in memory -- through the native library (crates/fenec-ffi): the engine and the file format of the server and the browser.
FenecRemote
A fenec-server over HTTP, with no file on the device: every query goes to the server (POST /query), through the same builder. What Fenec.connect makes, as connect does in JS.
Query
A query over one collection, made by Fenec.from or Query.from. Immutable: each call hands back a new one, so a base query can be kept and branched from.
Refusal
A write the server refused: it was put back on the replica.
Replica
A replica's sync with its server: its status, its token, and the network as the app sees it. The engine is told of what happens one thing at a time, in order (a chain of futures), so a stream's pieces arrive as they came and an action is never performed before the one it cancels.
Rows
A query's rows: a list of maps keyed by field, as before, carrying what facet counted beside them -- the counts are over every matching row, not the page, so they belong to no row. A list rather than a type that holds one, so that every caller of rows() and every live query reads it as it did.
SchemaPlan
What the engine found comparing the database with the schema the app declares, and did: the FenecQL that adds what is missing, the migrations it recorded, and what it refused.
SchemaRefusal
A difference no open applies -- one that would lose data or could mean two things -- and how to resolve it, as the engine writes them.
Shape
The rows of one collection a replica keeps: a filter the server applies, in the JS sync layer's form -- {'status': 'open', 'priority': {'gte': 3}} -- the fields it carries, and the business key an optimistic insert is matched with the server's copy by (a text @hash field).
ShapeState
SortKey
One key of a lookup's order: a field, asc or desc, and a collation (tr or und).
SyncFailure
An error, and its HTTP status (0: the network, or the replica).
SyncStatus

Enums

FenecCode
Reads
Where a connection's reads go. home, the default: every request to the tenant's home. nearest: the builder's reads, and a FenecRemote.asRead copy's requests, are marked (Fenec-Read: replica) so that a fenec-shard router near a region holding the tenant's read replica answers them there, each sent after the furthest position an answer from home named to this connection (Fenec-After, Fenec-History: the change and its history) -- never older than its own writes, nor a write a failover replaced. Writes go home.
SyncState
Where a replica stands with its server.

Extensions

FenecSchema on Fenec
A schema declared as FenecQL, checked and applied in the engine.
LiveQueries on Fenec

Typedefs

Facets = Map<String, List<FacetCount>>
What facet counted: each field or path in the order asked, its values most first.
Statement = ({List<Object?> params, String text})
A statement and its parameters, as they would be run.

Exceptions / Errors

FenecException
What the library or the builder refused, and why. code is the kind: the engine's (FenecCode.notFound, FenecCode.duplicate ...), the boundary's (FenecCode.misuse, FenecCode.locked, FenecCode.panic), or FenecCode.builder for a chain the query builder refused before anything ran -- its message the JS builder's, word for word.
SchemaException
A schema the database differs from in what no open applies: refusals says each difference.