FaunaDbStore — Fauna (FaunaDB) multi-model store

FaunaDbStore — Fauna (FaunaDB) multi-model store Overview Fauna is a distributed, multi-model database (document, relational, graph) driven by FQL — a functional query language expressed as composed function calls (Create, Get, Ref, Paginate, …) rather than SQL strings. That does not fit the SQL-shaped Dialect interface, so FaunaDbStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes Fauna's real document CRUD (built from FQL expressions) plus a raw FQL query escape hatch. Identity: Property | Value | --------- | ----------- | name | 'faunadb' | library | 'faunadb' | The store is built on the official faunadb driver. Requests are made by handing a composed FQL expression to client.query(expr); expressions are built with the FQL builder q (the driver's faunadb.query). Lazy loading — not a hard dependency faunadb is not a hard dependency of this package. It is an optional peer dependency loaded lazily via require('faunadb') inside connect(), rather than a top-level import. Importing this module therefore does not require the driver to be installed — it is only needed when a Fauna store is actually connected without an injected client. Injected client FaunaDbStoreOptions accepts a pre-built client (a native faunadb.Client) and, optionally, a pre-built FQL builder q (faunadb.query). When client is provided, connect() uses it directly; if q is not also injected, the store attempts a lazy require('faunadb').query but tolerates its absence. This is how the test suite injects both a mock client and a mock builder (no driver, no network). Connection Build a store from connection options and call connect(): FaunaDbStoreOptions: Option | Type | Purpose | -------- | ------------- | ------------------------------------------------------------------------------ | secret | string | Fauna database secret / access key. | domain | string | Fauna endpoint domain, e.g. db.fauna.com. | client | FaunaClient | A pre-built faunadb.Client to use directly. When set, the driver is not loaded to build a client. | q | FaunaQuery | A pre-built FQL builder (faunadb.query) to use instead of the driver's. | Injected-client form Supply your own client and builder (or mocks) to bypass driver-based construction: Methods Each CRUD method composes an FQL expression with the builder q and runs it via client.query(...). Driver failures are wrapped in a DatabaseError (preserving the original error); using any method before connect() (or after disconnect()) throws a ConnectionError, and an unavailable FQL builder also throws ConnectionError. Lifecycle Method | Signature | Behavior | ------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Uses an injected client/q if provided, otherwise lazy-requires faunadb and builds a Client from secret/domain. Idempotent when already connected. Wraps failures in ConnectionError. | disconnect | disconnect(): Promise<void> | Calls the client's close() if present (errors ignored), then clears connection state. | isConnected | isConnected(): boolean | true only when connected and a client is present. | getClient | getClient(): FaunaClient | Returns the underlying client. Throws ConnectionError if not connected. | Document CRUD & query Method | Signature | FQL composed | Behavior | -------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------- | insert | insert(collection: string, doc: Record<string, unknown>): Promise<unknown> | Create(Collection(collection), { data: doc }) | Creates a document. Returns the new document's ref.id (falling back to data.id). | get | get(collection: string, id: string): Promise<unknown> | Get(Ref(Collection(collection), id)) | Fetches a document. Returns its data. | update | update(collection: string, id: string, patch: Record<string, unknown>): Promise<unknown> | Update(Ref(Collection(collection), id), { data: patch }) | Merges patch into the document's data. Returns the updated data. | delete | delete(collection: string, id: string): Promise<unknown> | Delete(Ref(Collection(collection), id)) | Deletes a document. Returns the raw driver response. | query | query(collection: string, expr?: unknown): Promise<unknown[]> | provided expr, or a default paginate/map (see below) | Runs an FQL query and returns its data array (or []). | When query is called without expr, the store builds a default expression that paginates and dereferences every document in the collection: Map(Paginate(Documents(Collection(collection))), Lambda('ref', Get(Var('ref')))). Example Verification status Unit / mock-verified only. The tests in tests/nosql/faunadb.test.ts are fully mock-driven: a mock client (whose query() returns canned { ref, data }) and a mock FQL builder q (each function returns a { fn, args } marker) are injected via options. The real faunadb package is not installed, and there is no live Fauna access and no network in the test run. What this proves: insert composes Create(Collection(...), { data }) and returns ref.id; get/update/delete compose the expected Ref(Collection, id)-based expressions and shape their return values (data, updated data). query executes a provided FQL expression verbatim, and builds the default Documents/Paginate/Map expression when none is given. Lifecycle: connecting via an injected client without loading the driver, disconnect() calling close(), and ConnectionError before connect(). Error handling: driver failures wrapped in DatabaseError for both CRUD and query paths. What this does not prove: live execution against a real Fauna database. The composed FQL and response handling are verified against the driver's documented contract, but end-to-end execution over the wire has not been exercised here. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories