SurrealStore (SurrealDB)

SurrealStore (SurrealDB) Reference for the SurrealStore NoSQL store. Source: src/nosql/surrealdb/index.ts · Tests: tests/nosql/surrealdb.test.ts · Base interface: src/nosql/store.ts Overview SurrealDB is a multi-model database with its own record/graph model and the SurrealQL (SurQL) query language. Because it has no SQL-shaped DDL, no identifier escaping, and no query(sql) shape, it does not implement the SQL Dialect interface. Instead, SurrealStore implements the minimal NoSqlStore marker interface (connection lifecycle plus a getClient() escape hatch) and exposes SurrealDB's real API surface directly: record CRUD over "things" plus raw SurrealQL. Identity: Key characteristics: Implements NoSqlStore — connect, disconnect, isConnected, getClient, plus store-specific record methods. Driver is lazy-loaded. The surrealdb driver is loaded via require('surrealdb') inside connect(), only when a connection actually needs to be built. Importing this module never forces the optional surrealdb dependency to be installed. Injected client supported. A pre-built Surreal instance can be supplied through the client option. When present, connect() uses it directly and skips the require('surrealdb') call entirely — used for tests and for reusing an existing connection. A "thing" is SurrealDB's record identifier, typed as Thing = string. It is either a table name ('user' — operates on every record in the table, or auto-generates an id on create) or a specific record id ('user:jane'). Connection Options url is required. The constructor throws a DatabaseError (code: 'INVALIDCONNECTION') if options is missing or url is falsy. Real driver connect() performs, in order: 1. require('surrealdb') and new Surreal() — skipped when a client is injected. 2. db.connect(url). 3. db.signin({ username, password }) — only when username or password is configured (!== undefined). 4. db.use({ namespace, database }) — only when namespace or database is configured (!== undefined). If none of username/password/namespace/database are set, connect() calls connect(url) alone and skips both signin() and use(). connect() is idempotent: if already connected (connected && db), it returns immediately without reconnecting. Any failure during connect resets state (db = null, connected = false) and throws a ConnectionError wrapping the underlying error. Injected client Supply an existing Surreal instance via client to reuse a connection or to test without the real driver installed: Methods Lifecycle Establishes the connection as described above. Idempotent. Throws ConnectionError on failure. Clears internal state (db = null, connected = false) first, then calls db.close() on the previous client. If there was no client, returns without error. A failure in close() throws a DatabaseError. Returns true only when connected is true and db !== null. Returns the underlying native Surreal client. Throws ConnectionError (code: 'INVALIDCONNECTION') if the store is not connected. Record operations Each record method routes to the driver through an internal exec() wrapper that requires an active connection (throwing ConnectionError otherwise) and wraps any driver error in a DatabaseError (code: 'QUERYERROR', with the operation name in the message). Create a record. thing may be a table name ('user' — id auto-generated) or a specific record id ('user:jane'). Passthrough to Surreal.create(thing, data). Select a single record ('user:jane') or all records in a table ('user'). Passthrough to Surreal.select(thing). Replace the entire content of a record (or every record in a table). Passthrough to Surreal.update(thing, data). Merge the given data into a record (or every record in a table), leaving unspecified fields intact. Passthrough to Surreal.merge(thing, data). Delete a record (or every record in a table). Passthrough to Surreal.delete(thing). Run a raw SurrealQL statement (or several ;-separated statements), optionally binding vars as $name parameters. Returns the driver's result array — one entry per statement (each entry is the driver's per-statement result object/array). Passthrough to Surreal.query(surql, vars). Example Verification status Unit / mock-verified only. The real surrealdb driver is not installed in this repository, and the tests do not touch a network. tests/nosql/surrealdb.test.ts runs as pure unit tests: a fake Surreal client (jest spies returning canned values) is injected via the client option, so no real driver and no network are involved. Coverage includes: Identity (name/library) and the required-url constructor guard. Full connect path: connect(url) → signin({ username, password }) → use({ namespace, database }) with the configured values. Injected-client path resolves without requiring the (uninstalled) real driver. Idempotent double-connect (driver connect called once). signin/use skipped when no creds/ns/db are configured. Connection failures wrapped in ConnectionError; state reset to disconnected. getClient() returns the raw client, and throws ConnectionError before connect. Operations before connect() throw ConnectionError. disconnect() calls close() and clears connected state. Each record method (create/select/update/merge/delete/query) routes to the matching driver call with the expected arguments; query() returns the driver's result array. Driver errors wrapped in DatabaseError. No integration test against a live SurrealDB instance exists. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories