JavaScript and TypeScript

@fenecdb/web/client is client.js, which re-exports the builder (builder.js) and the HTTP client (http.js), the two modules fenec.js imports beside its glue, persistence and the sync layer. It reaches nothing else — no WebAssembly, no IndexedDB, no files — and a test fails if it does. An app that calls connect and reads a builder query's rows bundles to 9 KB brotli through it and to 12 KB through @fenecdb/web, whose Fenec class and its glue a bundler cannot drop (esbuild, minified): 2.5 KB of JavaScript, and no .wasm either way.

Its live queries open a subscription to each collection the query reads (GET /<collection>/changes), of a shape that holds no row: the seed is empty, and every write to the collection is a change that runs the query again on the server. The first rows wait for every stream's seed, a burst of writes runs it once after the run under way, and a stream that ends is opened again, its seed running the query, since writes may have come between. useLiveQuery takes the endpoint as it takes a replica. Under a scoped token the server tells such a stream of the writes to rows the token may read, and of no other (HTTP). A token refused, or lapsed under an open stream -- the server ends a stream at its token's exp -- is a FenecError of status 401 to onError, and the live query stops there, for the app to open it again with a fresh token.

web/fenec.js is a dependency-free ES module: the WebAssembly glue, persistence and the sync layer, with the query builder and the HTTP client in the two modules it imports and re-exports. Copy four files — and the collate/ directory beside the module, for text in a collation — and you are done.

db.run() is synchronous because raw FenecQL is a single wasm call. The builder's endpoints return promises, because a builder has to pick its transport first.

openFile keeps the database in a file of the origin private file system, byte for byte the file fenec-server keeps on disk: download it and fenec notes.fenec opens it, and a server's file handed to a page loads there. run appends each statement's writes to it and flushes the file before it answers. It needs a dedicated worker, the one place a page gets synchronous access to a file, and it takes the file for itself: a second worker or tab that opens the file is refused, where a second process over a server's file would corrupt it.

A compact, and writes appended past half the image (and past 64 KB), put a new image in the file. It is written into a copy beside the file (notes.fenec~) and flushed before the file is touched, so a crash at any point leaves one of the two whole, and the next openFile takes whichever holds every write run answered. A write a crash cut short is cut off. A new image holds the live records alone, so what updates and deletes left behind goes with it, from the file and from persist's images alike; the page's memory keeps those versions until it opens the file again or runs compact, since a page has no thread to compact beside its queries the way a server and an app do. Once the file refuses a write, every later write is refused too; the database has to be opened from the file again.

persist and restore keep the same bytes in IndexedDB, wherever a page runs: the image once, then only the writes since the last call, as chunks. persist stores what was written when it is called, and IndexedDB decides when that reaches the disk; the file is flushed before every answer. Over 32.4 MB (61 000 rows with a vector<128>), in a worker (make file-bench):

The file's row includes its statement, 0.03 ms in Chrome and 0.10 ms in Safari, its vector handed over as f32s, and its flush. Firefox was not measured.

With a cryptoKey (AES-GCM, from WebCrypto) the image and every chunk are sealed before they reach IndexedDB, each with a random nonce and a tag over the key it is stored under and its place. A chunk moved, dropped from the middle, or left from an image before is refused, as is one byte changed. A restore without the key refuses a sealed record, and a restore with one refuses a record stored in the clear. Where the key comes from is the page's decision: derived from a passphrase, as above, or handed over by the server after a login, so that what IndexedDB holds on the disk reads as nothing without it. A key kept in IndexedDB beside the data protects nothing. The sync layer takes it as sync({ persist, cryptoKey }). Its cursors and unsent writes are collections of the replica, sealed with it. The same 32.4 MB in Chrome 154: the first image 129 ms against 76, a new row 0.16 ms p50 either way, a restore 37 ms against 29. Only the image pays: it is 32 MB to seal. The file of openFile stays plain, since it is the file fenec-server opens. The disk's own encryption covers it.

The engine notes every write in its change ring, a collection id and a document id each, and fenec_changes(since) names the collections written since a cursor. A block's writes are noted as it lands, so a text of several statements that fails names nothing. A create, an alter and a create index name their collection. A drop answers null, which means every collection: a dropped collection has no name left to give. Its live query runs again and gets the error that the collection is gone. Queries over other collections also run again for nothing, which is harmless.

The notice costs a write nothing. A statement's answer does not carry it. A page with a live query asks once, in a microtask after the task that wrote: a write to a collection no live query reads costs that one call, about 2 µs in Node. Running a query again is the query itself: a page of 50 open todos out of 1 000 to 3 000, ordered by an @sorted field, took 0.19 ms. No incremental maintenance is needed (Sync says why). The module did not grow, and make wasm-speed's put did not move.

A synced replica runs its live queries at the next frame instead, so that a seed landing in chunks is not shown half done. Both share one implementation. A load runs every live query whatever the ring says, since the image's counter may stand where the cursor did.

With openFile, the database and its live queries live in the dedicated worker that holds the file. The worker runs them, and posts the rows to the page that draws them. The page holds no database to subscribe to.

The key field in the example is what a replica reconciles an optimistic insert by. It fills the field in for you. Without a key, the row shows up once the server has it, not at once.

A column builder takes no name: the key is the field's name. Columns are nullable unless .notNull(), FenecQL's required. A field takes one index, declared on the column (.unique()) or in the third argument; two on one field are refused as the table is declared, as is anything FenecQL cannot hold. An index over several fields is .on() with several columns, each .desc() or .asc() as Drizzle writes it, beside a field's own (Indexes over several fields), and dropIndex(table, ...fields) is the migration that takes one off.

typeof products.$inferSelect is a row as read, id and all, a nullable column T | null: the same type fenec types generates for the collection, which the tests hold it to field for field. $inferInsert is what insert takes: the .notNull() columns given, the rest optional. db.from(table), lookup(table, ...), a shape's collection and useLiveQuery are typed by the table, and a misspelt field or a wrong value's type is a compile error.

A relation of defineRelations is a lookup: on <to> = <from>, its rows attached under the table it reaches. to must be id or a column with a hash or unique index, since lookup finds children by an index and never by a scan; a relation it cannot answer is refused as it is declared. r.one attaches the first child, still in a list.

The engine compares, in the module or on the server, so every SDK applies and refuses the same things with the same words. What it does:

FenecError: the database's schema differs from the code's, and nothing was applied:
  - `todos.title` is in the database and not in the code
    if it was renamed to `name`, the migration `alter collection todos rename field title to name`; if it goes, `alter collection todos drop field title`

Everything an open applies is one block: the migrations not yet recorded, their records, and the additions land together, or — on a refusal or an error — none of them. A database made from the code records its migrations without running them, since they lead from schemas it never had. A migration is known by its place in the list and held to its text: one changed after it ran, or a database holding more migrations than the code lists — an older app opening what a newer one migrated — is refused, and nothing runs. rebuild adds the field again as declared, copies its values with set, drops the old field and renames the new one; a field it rebuilds is not required.

db.describe() is the database's schema as the engine describes a server's (GET /_schema), and db.describe('fenecql') the statements that make it. db.checkSchema(description, 'plan') says what an open would do and writes nothing, the pending migrations run in a block put back. The check costs an open of 10 collections 0.09 ms in Node (0.11 ms without, 0.20 with), and the module 7.5 KB brotli (23 KB raw): the comparison and its messages, and FenecQL read into a schema. make wasm SCHEMA=0 leaves it out.

A database in the page (Fenec.open, restore, openFile) is the code's, and the check applies. A synced replica's schema is its server's: sync({ schema }) compares the code with the server's (POST /_schema/plan?mode=follow), refuses what the code declares and the server lacks, and applies nothing; the replica takes its collections as the server declares them, as it always did. connect(url, { schema }) compares the same way; with migrate: true and the server's token it runs the migrations and the additions on the server (POST /_schema/apply), as a deploy step runs drizzle-kit's migrate.

Every SDK's declarations compile to one description, versioned JSON: {"format": 1, "collections": [...], "migrations": [...]}, a field {"name", "type", "required", "collate", "nocase", "index", "paths"} and an index {"kind": "hnsw", "metric", "m", ...} holding what the declaration says, the engine's defaults for the rest — or the same collections as FenecQL text, {"format": 1, "fenecql": "create collection ..."}, which the module reads. integrations/schema-golden.json holds declarations and the description each compiles to, FenecQL texts, and plans with the statements and refusals the engine makes of them, which the Rust tests run and every SDK will be held to.

One to one: a table function with columns and an array of indexes, column builders without a name, .notNull(), .unique(), .array(), $type, index and uniqueIndex with .on, .using and .with, pgvector's vector, halfvec and sparsevec with their operator classes, $inferSelect, $inferInsert, getColumns and defineRelations with r.many and r.one.

fenecdb's own: fenecTable (also collection), bm25 and inverted methods, .ttl(), .collate(), t.meta.path(...), and quant. Not there: .default() (FenecQL has no defaults), .primaryKey() (every document has its id), .references() (no foreign keys; a relation is defineRelations), an index on two columns, and index names, which are checked to be distinct and kept nowhere. Drizzle generates SQL migrations from a diff; here the engine applies what only adds by itself, and only what it refuses needs a migration, written beside the schema.

Declare the schema in code for an app that makes its own database: a page's state, an app's file, a service that owns its server. Generate the types from the database (TypeScript) for an app over a database another owns, a server's whose schema changes elsewhere. To move from the second to the first, fenec types --schema data.fenec > schema.ts writes the tables the file holds, every option written, and fenec types --fenecql the same schema as FenecQL; an open with either finds no difference.

collate und and collate tr need the weights of the scripts they compare (Collation). The module carries the Latin ones and is handed the others as a page first needs them, a chunk a group of scripts, from collate/ beside the module — or from where Fenec.open(src, { collation }) says: a URL, or a function handed the chunk's name that returns its bytes. make wasm writes the chunks next to fenec.wasm.

A statement that would compare text of a script whose chunk the module has not got is refused rather than answered in another order: db.run(), which is synchronous, throws a FenecError whose collation names the chunks, and db.query() and the builder fetch them and run the statement again. A write is refused before it changes anything, so running it again is safe; of several statements in one text only the first is run again by itself. restore and db.loadAsync() fetch what an image's collated text needs — its @sorted indexes would be out of order without it — and the sync layer fetches what its seed, the changes it is sent and its optimistic writes need (sync({ collation }) says where from). A chunk of another version's tables is refused: its ranks would mean something else.

The module carries five indexes and six more parts of the language, and a page that uses fewer can load one built without the rest: FEATURES names what it keeps, indexes and language each group. The release and @fenecdb/web carry fenec.wasm alone; another set is a make wasm away. What each feature weighs is in Benchmarks. The builds without the indexes and without anything are also tests: CI builds them (make wasm-lite, make wasm-min) and opens the full module's files in them.

Everything else is in every build: documents, filters, order, count, sum, avg, min and max by group, lookup, in (get ...), json fields and their paths, @ttl, the change feed, persistence and the sync layer.

The file does not change with the build. A collection that declares an index the module lacks is made and loaded all the same, and its documents are read and written. A near over it measures every vector, a sparse one scores every document; a match, or a create index of the kind, throws a FenecError naming the feature. A file declaring a nocase or collated field loads too; a statement over that collection throws, the feature named, and the file's other collections answer. A module that has the feature builds what it needs when it loads what the other wrote, so a page can hand a store to the other module and take it back.

FenecQL reads well, but on the application side the job is still building a string — and every interface with conditional filters ends up here:

let q = 'get articles where 1=1';
if (year) q += ` and year >= ${year}`;    // quote escaping and $n by hand

What usually drives people to an ORM is not the ORM but two things: dynamic queries and type safety. The builder gives both, without npm, a build step, or a second schema definition.

Every where is anded with the previous one, and the query object is immutable — so a body can be shared and branched:

let q = db.from('articles').select('title');
if (year) q = q.where('year', '>=', year);
if (tag)  q = q.where('tags', 'has', tag);
const rows = await q.limit(20).rows();

Use whichever spelling reads better at the call site.

lookup hangs another collection's matching documents off each row. Everything in its options object binds to that collection, so limit there counts children per parent — twenty products with three reviews each, in one query:

const rows = await db.from('products')
  .where('price', '>=', 10000)
  .limit(20)
  .lookup('reviews', {
    on: 'product_id',
    where: { stars: { gte: 4 } },
    order: [['created', 'desc']],
    limit: 3,
  })
  .rows();

// [{ id: 1, name: 'Kahve', price: 12000, reviews: [ {...}, {...} ] }, ...]

Calling it again chains rather than replaces: the second call binds to the collection the first one named, the way position scopes it in FenecQL.

const rows = await db.from('shops')
  .limit(20)
  .lookup('orders', { on: 'shop_id', limit: 3 })
  .lookup('lines',  { on: 'order_id', limit: 5 })
  .rows();

// [{ name: 'Merkez', orders: [{ code: 'A', lines: [ {...} ] }, ...] }, ...]

A level's select may aggregate, as the query's own does: each parent's children folded — one row a parent, or with group one a group, ordered and paged a parent at a time. Ungrouped, order and limit pick the children folded. A query whose list aggregates hangs a lookup off its groups, parentKey naming a column; and bucket(field, interval, zone) counts by a zone's clock, the zone a parameter.

import { bucket } from './fenec.js';

// Each product's latest 50 reviews, counted and averaged.
const page = await db.from('products').limit(20)
  .lookup('reviews', { on: 'product_id', order: [['created', 'desc']], limit: 50,
                       select: ['count(*)', 'avg(stars)'] })
  .rows();
// The ten most reviewed, with their names.
const most = await db.from('reviews')
  .select('product_id', 'count(*)').group('product_id').order('count(*)', 'desc').limit(10)
  .lookup('products', { on: 'id', parentKey: 'product_id', select: ['name'] })
  .rows();
// Reviews a day, by the page's own clock.
const days = await db.from('reviews')
  .select(bucket('created', '1d', Intl.DateTimeFormat().resolvedOptions().timeZone).as('day'), 'count(*)')
  .group('day').rows();

The row type follows the nesting, so rows[0].orders[0].lines[0] is typed without a cast; a level that folds is typed as the children it folds, its columns not narrowed to. required keeps meaning what it means at its own level: on lines it drops the orders that have none, and the shops stay unless orders asks for it too.

The child's field names cannot be reached from a builder that carries one collection's types, so in TypeScript they default to a loose row; naming them tightens it: .lookup<'reviews', FenecSchema['reviews']>('reviews', {...}).

or and not are separate functions because the where chain is an and. A nested group is written explicitly and the parenthesising is left to the builder:

import { or } from './fenec.js';

db.from('articles')
  .where('year', '>=', 2024)
  .where(or({ tags: { has: 'rust' } }, { title: { like: 'rust' } }))
// get articles where year >= $1 and (tags has $2 or title ~ $3)

raw covers what the builder cannot express, which in practice today means function calls. Its ? placeholders bind to parameters in order, so the escape hatch does not become string concatenation either.

.highlight(field, { pre, post }) answers the marked text instead of the offsets, and .snippet(field, words, { ellipsis, pre, post }) a window of that many words around the marks — see Highlights and snippets. Text with tags is not escaped, which is why the page above builds its nodes from the offsets. .facet(field, { top }) takes a field or a path into a json one, and run() hands the counts as its facets too — see Facets. A facet beside near is refused: near ranks every row rather than selecting some, so the counts would be the filter's alone. { disjunctive: true } counts a facet without the filter's own conditions on its field, and { ranges: [0, 2500, 5000] } counts a number by range ( Counted without its own filter, Ranges).

A query built in steps keeps the type it was declared with, so a facet asked after the declaration is typed as any facet: rows.facets is there, each field's counts FacetCount[], and maybe absent. To keep each field's own type, ask the facets in the declaration and add the steps that keep the row's type after it:

import { connect } from '@fenecdb/web/client';

const db = connect('https://db.example.com');
const chosen: string | undefined = 'acme';
let q = db.from('products').select('name').facet('brand', { disjunctive: true });
if (chosen) q = q.where('brand', chosen);
const rows = await q.limit(24).rows();
rows.facets.brand.map((f) => f.count);   // typed

Nothing is hidden. Every leaf value is bound to a parameter and text is never embedded into the query, which leaves a single injection boundary: names. Collection and field names cannot be parameterised, so they are validated against FenecQL's identifier rule and anything that does not fit errors out.

db.from('articles').where('title', '"; del articles; --')
// get articles where title = $1     ← a value, not text

A parameter that is a vector — a Float32Array, or any array of finite numbers, which the module reads as a vector either way — goes into the module as its f32s beside the JSON rather than as text: 200 768-dim vectors are put in 4.4 ms, against 21.9 written out as digits and read back. The vector stored is the same, -0 as 0 as JSON writes it; over HTTP a parameter is JSON. Where such a parameter is given a json field, or compared with a path into one, the module names it before running anything and run sends it again as JSON, so a plain array keeps its numbers as written and a Float32Array goes as the numbers it holds.

connect() returns the same builder; the FenecQL it produces goes to POST /query as is. See HTTP endpoint.

The schema is not written a second time — it is generated from the live file, so the two cannot drift apart. A schema declared in code is written a second time on purpose, and the check at every open is what keeps the two one.

What the types catch: a collection or field that does not exist, a wrong value type, access to an unselected field, near applied to a non-vector field, and a type mismatch inside insert. Objects inside or, and and not are checked against the query's collection rather than the first argument. A query using near or match gains _score: number.

A standalone from() cannot know the collection name, since the schema lives in the call rather than in db. In TypeScript it binds through TypedFrom; at runtime it is the same function and the only difference is name completion.

import { from as fenecFrom, type TypedFrom } from './fenec.js';
import type { FenecSchema } from './fenec-schema.js';

const from: TypedFrom<FenecSchema> = fenecFrom;
from('articles').where('year', '>=', 2024);   // completes like db.from

fenec.d.ts is hand-written — it is the client's own surface — and fenec-schema.d.ts is generated. There is no link between them: the Timestamp, Vector and Bytes brands are structural, so the generated file stands alone and imports nothing.

The Python, Go and .NET clients have the same builder, and integrations/builder-golden.json holds all four to one text: the chains there and what this builder makes of each, which every language's tests run (Your language).

The tests run with node --test web/fenec.test.js and are part of make test. When web/fenec.wasm is present, an end-to-end test that actually parses the generated text runs too.