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
collectionsanddescribegive. - 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
incandexpr. 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
Mapis one too, the JS builder's object condition: each field's value is equality,nullisis null, and a map is its operators --{'year': {'gte': 2024}}-- in the map's order, which is the text's. - FacetCount
-
One value a
facetcounted, 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, asconnectdoes 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
facetcounted 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 ofrows()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 (atext @hashfield). - ShapeState
- SortKey
-
One key of a lookup's order: a field,
ascordesc, and a collation (trorund). - 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
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.