OrientDbStore — OrientDB multi-model store

OrientDbStore — OrientDB multi-model store Overview OrientDB is a multi-model database combining document, graph, key/value, and object models, queried with an extended SQL dialect over a session. Although its query language is SQL-like, it does not fit Prorm's SQL-shaped Dialect interface (no shared identifier escaping / DDL builder), so OrientDbStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes OrientDB's real session command/query API through a small document-CRUD convenience layer. Identity: Property | Value | --------- | ------------ | name | 'orientdb' | library | 'orientjs' | The store is built on the official orientjs driver. Reads go through session.query(sql).all(); writes (INSERT/UPDATE/DELETE) go through session.command(sql).all(). Lazy loading — not a hard dependency orientjs is not a hard dependency of this package. It is an optional peer dependency loaded lazily via require('orientjs') 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 an OrientDB store is actually connected without an injected session. Injected client OrientDbStoreOptions accepts a pre-built client (an already-open OrientDB session). When provided, connect() uses it directly and never loads the driver or opens a server client/session. This is how the test suite injects a mock session (no driver, no network), and how callers can supply a custom-configured session. Connection Build a store from connection options and call connect(): Without an injected client, connect() calls OrientDBClient.connect({ host, port }) and then orientClient.session({ name: database, username, password }). OrientDbStoreOptions: Option | Type | Purpose | ---------- | --------------- | ------------------------------------------------------------------- | host | string | Server host. | port | number | Server binary port, e.g. 2424. | database | string | Database name to open a session against (session({ name })). | username | string | Session username. | password | string | Session password. | client | OrientSession | A pre-built, open session to use directly. When set, the driver is not loaded. | Injected-client form Supply your own session (or a mock) to bypass driver-based connection: Methods CRUD methods build an OrientDB SQL string (interpolating collection, JSON-serialized documents, and the @rid) and execute it against the session. Driver failures are wrapped in a DatabaseError (preserving the original error); using any method before connect() (or after disconnect()) throws a ConnectionError. The collection argument is the OrientDB class name. Lifecycle Method | Signature | Behavior | ------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Uses an injected client (session) if provided, otherwise lazy-requires orientjs, connects a server client, and opens a session. Idempotent when already connected. Wraps failures in ConnectionError. | disconnect | disconnect(): Promise<void> | Closes the session and (if it opened one) the server client, then clears state. Close failures are wrapped in DatabaseError. | isConnected | isConnected(): boolean | true only when connected and a session is present. | getClient | getClient(): OrientSession | Returns the underlying session. Throws ConnectionError if not connected. | Document CRUD & query Method | Signature | SQL issued | Behavior | -------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------- | insert | insert(collection: string, doc: Record<string, unknown>): Promise<unknown> | INSERT INTO <collection> CONTENT <json> | session.command(sql).all(). Returns the new record's @rid (stringified), falling back to id. | get | get(collection: string, id: string): Promise<unknown> | SELECT FROM <collection> WHERE @rid = <id> | session.query(sql).all(). Returns the first row. | update | update(collection: string, id: string, patch: Record<string, unknown>): Promise<unknown> | UPDATE <collection> MERGE <json> WHERE @rid = <id> | session.command(sql).all(). Returns the command result. | delete | delete(collection: string, id: string): Promise<unknown> | DELETE FROM <collection> WHERE @rid = <id> | session.command(sql).all(). Returns the command result. | query | query(collection: string, statement: string, options?: OrientDbQueryOptions): Promise<unknown[]> | the given statement | session.query(statement, options).all(). Returns the rows (or []). | OrientDbQueryOptions carries a params field (Record<string, unknown> \| unknown[]) for named/positional parameter binding, plus any additional native options. Example Verification status Unit / mock-verified only. The tests in tests/nosql/orientdb.test.ts are fully mock-driven: a mock session whose command()/query() return objects with an all() promise is injected via OrientDbStoreOptions.client. The real orientjs package is not installed, and there is no live OrientDB access and no network in the test run. What this proves: Each CRUD method builds the exact SQL string expected (INSERT INTO User CONTENT {...}, SELECT FROM User WHERE @rid = #12:0, UPDATE ... MERGE ..., DELETE FROM ...) and routes writes to command() and reads to query(). insert returns the stringified @rid; get returns the first row. query forwards the statement and options to session.query(...) and returns the rows. Lifecycle: connecting via an injected session without loading the driver, disconnect() calling session.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 OrientDB server. The SQL strings and result 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