RavenDbStore — RavenDB multi-model store

RavenDbStore — RavenDB multi-model store Overview RavenDB is a transactional, multi-model document database with a unit-of-work session API (store/load/delete + saveChanges) and a fluent, indexed query builder. That access pattern does not fit the SQL-shaped Dialect interface, so RavenDbStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes RavenDB's real session CRUD plus query API through a small document-CRUD convenience layer. Each operation opens its own short-lived session and commits with saveChanges(). Identity: Property | Value | --------- | ----------- | name | 'ravendb' | library | 'ravendb' | The store is built on the official ravendb driver. It holds a DocumentStore; each method calls store.openSession() and drives that session's store/load/delete/query/saveChanges API. Lazy loading — not a hard dependency ravendb is not a hard dependency of this package. It is an optional peer dependency loaded lazily via require('ravendb') 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 RavenDB store is actually connected without an injected client. Injected client RavenDbStoreOptions accepts a pre-built client (a native DocumentStore). When provided, connect() uses it directly and never loads the driver (it still calls initialize() on the store if that method exists). This is how the test suite injects a mock DocumentStore (no driver, no network), and how callers can supply a custom-configured store. Connection Build a store from connection options and call connect(): Without an injected client, connect() builds new DocumentStore(urls, database) and calls initialize() on it. RavenDbStoreOptions: Option | Type | Purpose | ---------- | --------------- | -------------------------------------------------------------------------- | urls | string[] | RavenDB server URLs, e.g. ['http://localhost:8080']. | database | string | Default database name. | client | DocumentStore | A pre-built DocumentStore to use directly. When set, the driver is not loaded. | Injected-client form Supply your own store (or a mock) to bypass driver-based construction: Methods Each CRUD/query method opens a fresh session via store.openSession() and commits writes with saveChanges(). Driver failures are wrapped in a DatabaseError (preserving the original error); using any method before connect() (or after disconnect()) throws a ConnectionError. Note that get/update/delete ignore the collection argument (documents are addressed by full id); it is retained for a consistent CRUD signature. Lifecycle Method | Signature | Behavior | ------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Uses an injected client if provided, otherwise lazy-requires ravendb and builds a DocumentStore(urls, database). Calls initialize() if present. Idempotent when already connected. Wraps failures in ConnectionError. | disconnect | disconnect(): Promise<void> | Calls the store's dispose() if present (failures wrapped in DatabaseError), then clears state. | isConnected | isConnected(): boolean | true only when connected and a store is present. | getClient | getClient(): DocumentStore | Returns the underlying DocumentStore. Throws ConnectionError if not connected. | Document CRUD & query Method | Signature | Behavior | -------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | insert | insert(collection: string, doc: Record<string, unknown>): Promise<unknown> | session.store(doc, id) + saveChanges(). Uses doc.id if present, otherwise a generated collection-scoped id <collection>/<gen>. Returns the id used. | get | get(collection: string, id: string): Promise<unknown> | session.load(id). Returns the loaded entity. (collection is ignored.) | update | update(collection: string, id: string, patch: Record<string, unknown>): Promise<unknown> | session.load(id), Object.assign(entity, patch), saveChanges(). Returns the merged entity. (collection is ignored.) | delete | delete(collection: string, id: string): Promise<unknown> | session.delete(id) + saveChanges(). Returns { id }. (collection is ignored.) | query | query(collection: string, filter?: Record<string, unknown>): Promise<unknown[]> | session.query({ collection }), applies whereEquals(field, value) for each filter entry, then .all(). Returns all matched documents (or []). | Example Verification status Unit / mock-verified only. The tests in tests/nosql/ravendb.test.ts are fully mock-driven: a mock DocumentStore whose openSession() returns a jest-mocked session (store/load/delete/saveChanges/query, with a chainable whereEquals) is injected via RavenDbStoreOptions.client. The real ravendb package is not installed, and there is no live RavenDB access and no network in the test run. What this proves: connect() calls initialize() on the injected store; disconnect() calls dispose(). insert stores with an explicit or generated collection-scoped id and calls saveChanges(), returning the id. get loads by id; update loads-merges-saves and returns the merged entity; delete deletes by id and saves. query calls session.query({ collection }), applies whereEquals per filter entry, and returns the results (whereEquals is skipped when no filter is given). Lifecycle: connecting via an injected store without loading the driver, 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 RavenDB server. The session call/response shapes 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