ts-prorm-orm 1.1.0

package/dist/nosql/tigergraph/index.js

@@ -0,0 +1,469 @@
+"use strict";
+/**
+ * TigerGraph store implementation.
+ *
+ * TigerGraph is a native graph database (vertices/edges/GSQL), not a SQL
+ * engine, so this class does not implement the SQL-shaped `Dialect`
+ * interface (see `src/dialects/dialect.ts`). It implements the minimal
+ * `NoSqlStore` marker interface (`src/nosql/store.ts`) and exposes
+ * TigerGraph's real capabilities directly: installed-query execution,
+ * vertex/edge upsert and retrieval, ad-hoc "interpreted" GSQL queries, and
+ * schema introspection.
+ *
+ * ## Why `fetch`, not a driver
+ *
+ * Unlike every sibling in `src/nosql/` (MongoDB -> `mongodb`, Redis ->
+ * `ioredis`, DynamoDB -> `@aws-sdk/*`), there is no official,
+ * actively-maintained Node.js/JavaScript SDK for TigerGraph on npm as of
+ * this writing. The only packages found (`tigergraph.js`, `tiger-graph`)
+ * are small, unmaintained community wrappers last published in 2022, not
+ * published or endorsed by TigerGraph Inc, and TigerGraph's own GitHub org
+ * ships `pyTigerGraph` (Python) but nothing for Node. TigerGraph *is*
+ * fully usable from Node, though: it's a plain HTTP/JSON REST API
+ * ("REST++", plus the GSQL server's own HTTP endpoints), so this store
+ * talks to it with Node's built-in global `fetch` (Node >=18, this repo's
+ * minimum engine) instead of adding a new npm dependency for a thin HTTP
+ * wrapper. This is a deliberate choice, not an oversight - see the
+ * package's README for the endpoint shapes this was verified against.
+ *
+ * `library` is reported as `'fetch'` (there is no driver name to report).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TigerGraphStore = void 0;
+const errors_1 = require("../../errors");
+// ---------------------------------------------------------------------
+// Error helpers
+// ---------------------------------------------------------------------
+function wrapConnectionError(err, host) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /fetch failed|econnrefused/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to TigerGraph: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database: 'tigergraph', host });
+}
+function wrapDatabaseError(err, message) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const combined = message ? `${message}: ${parent.message}` : parent.message;
+    return errors_1.DatabaseError.from(parent, { message: combined });
+}
+/** Convert plain attribute values into TigerGraph's `{"value": x}` wire format, passing already-wrapped values through unchanged. */
+function toWireAttributes(attrs = {}) {
+    const wire = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value !== null && typeof value === 'object' && 'value' in value) {
+            wire[key] = value;
+        }
+        else {
+            wire[key] = { value };
+        }
+    }
+    return wire;
+}
+// ---------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------
+/**
+ * `TigerGraphStore` wraps TigerGraph's REST++ and GSQL-server HTTP APIs
+ * behind a typed, promise-based interface: token-based auth, installed
+ * (pre-compiled GSQL) query execution, vertex/edge upsert and retrieval,
+ * ad-hoc interpreted queries, and vertex/edge-type schema introspection.
+ */
+class TigerGraphStore {
+    constructor(options) {
+        this.name = 'tigergraph';
+        this.library = 'fetch';
+        this.token = null;
+        this.connected = false;
+        if (!options.host) {
+            throw new errors_1.ConnectionError('TigerGraphStore requires a "host"', { database: 'tigergraph' });
+        }
+        if (!options.graph) {
+            throw new errors_1.ConnectionError('TigerGraphStore requires a "graph"', { database: 'tigergraph' });
+        }
+        this.options = options;
+        this.restBaseUrl = `${options.host}:${options.restPort ?? 9000}`;
+        this.gsqlBaseUrl = `${options.host}:${options.gsqlPort ?? 14240}`;
+        this.restPathPrefix = options.restPathPrefix ?? '';
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected) {
+            return;
+        }
+        try {
+            if (this.options.token) {
+                this.token = this.options.token;
+            }
+            else if (this.options.secret) {
+                this.token = await this.requestToken(this.options.secret, this.options.tokenLifetime);
+            }
+            else if (!this.options.username || !this.options.password) {
+                throw new Error('no "token", "secret", or "username"/"password" provided - TigerGraph requires one of these to authenticate');
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.token = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.host);
+        }
+    }
+    async disconnect() {
+        this.token = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected;
+    }
+    /**
+     * Returns a small facade over the underlying HTTP transport for
+     * operations not wrapped here - there is no native driver client to
+     * expose, since this store talks to TigerGraph over plain `fetch`.
+     */
+    getClient() {
+        this.requireConnected();
+        return {
+            token: this.token,
+            restBaseUrl: this.restBaseUrl,
+            gsqlBaseUrl: this.gsqlBaseUrl,
+            restRequest: (path, init) => this.restRequest(path, init),
+            gsqlRequest: (path, init) => this.gsqlRequest(path, init),
+        };
+    }
+    requireConnected() {
+        if (!this.connected) {
+            throw new errors_1.ConnectionError('Not connected to TigerGraph', { database: 'tigergraph' });
+        }
+    }
+    getFetch() {
+        // Resolved per-call (not cached at construction time) so tests can
+        // swap `global.fetch` per-test (`jest.spyOn(global, 'fetch')` or
+        // reassigning `global.fetch`) and have it take effect immediately.
+        return this.options.fetch ?? globalThis.fetch;
+    }
+    // ---------------------------------------------------------------------
+    // Auth
+    // ---------------------------------------------------------------------
+    /**
+     * `POST /requesttoken` - exchange a GSQL secret for a REST++ bearer
+     * token. Confirmed request/response shape (pre-4.1 REST++; TigerGraph
+     * 4.1+ additionally offers `POST /gsql/v1/tokens` on the unified GSQL
+     * port, whose exact request/response shape was not independently
+     * confirmed while building this store - see README "Known
+     * limitations").
+     */
+    async requestToken(secret, lifetime) {
+        const body = { secret };
+        if (lifetime !== undefined) {
+            body.lifetime = String(lifetime);
+        }
+        const fetchImpl = this.getFetch();
+        let response;
+        try {
+            response = await fetchImpl(`${this.restBaseUrl}/requesttoken`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            throw wrapConnectionError(err, this.options.host);
+        }
+        const json = await this.parseEnvelope(response, 'requesttoken');
+        if (!json.token) {
+            throw new errors_1.DatabaseError(json.message || 'TigerGraph did not return a token', {
+                original: json.message,
+            });
+        }
+        return json.token;
+    }
+    // ---------------------------------------------------------------------
+    // Low-level HTTP helpers
+    // ---------------------------------------------------------------------
+    async parseEnvelope(response, action) {
+        let json;
+        try {
+            json = (await response.json());
+        }
+        catch (err) {
+            // Non-JSON body (e.g. a gateway/proxy error page). Whether TigerGraph
+            // itself ever returns a non-2xx status was not confirmed during
+            // research (see README) - surface both the HTTP status and body-parse
+            // failure so callers can tell the two failure modes apart.
+            throw wrapDatabaseError(err, `TigerGraph ${action} failed (HTTP ${response.status} ${response.statusText}, non-JSON response)`);
+        }
+        // TigerGraph's documented error signal is `error: true` in the JSON
+        // envelope; treat a non-2xx HTTP status as a failure too, since it was
+        // not confirmed whether every deployment/version always replies 200
+        // with `error: true` (see README "Known limitations").
+        if (!response.ok || json.error) {
+            const code = json.code ? ` (${json.code})` : '';
+            throw new errors_1.DatabaseError(`TigerGraph ${action} failed${code}: ${json.message ?? response.statusText}`, {
+                original: json.message,
+            });
+        }
+        return json;
+    }
+    authHeaders() {
+        if (this.token) {
+            return { Authorization: `Bearer ${this.token}` };
+        }
+        return {};
+    }
+    basicAuthHeaders() {
+        const { username, password } = this.options;
+        if (username && password) {
+            const encoded = Buffer.from(`${username}:${password}`).toString('base64');
+            return { Authorization: `Basic ${encoded}` };
+        }
+        // Fall back to the REST++ bearer token if no Basic-auth credentials
+        // were configured. TigerGraph 4.1+ unifies REST++/GSQL auth behind
+        // the same token in some configurations, but this fallback was not
+        // independently confirmed - prefer configuring `username`/`password`
+        // for GSQL-server calls when possible (see README).
+        return this.authHeaders();
+    }
+    /** Issue a request against the REST++ API (vertex/edge/query endpoints), with bearer-token auth. */
+    async restRequest(path, init = {}, action = path) {
+        this.requireConnected();
+        const fetchImpl = this.getFetch();
+        let response;
+        try {
+            response = await fetchImpl(`${this.restBaseUrl}${this.restPathPrefix}${path}`, {
+                ...init,
+                headers: { ...this.authHeaders(), ...init.headers },
+            });
+        }
+        catch (err) {
+            throw wrapConnectionError(err, this.options.host);
+        }
+        return this.parseEnvelope(response, action);
+    }
+    /** Issue a request against the GSQL server (interpreted queries, schema), with Basic auth. */
+    async gsqlRequest(path, init = {}, action = path) {
+        this.requireConnected();
+        const fetchImpl = this.getFetch();
+        let response;
+        try {
+            response = await fetchImpl(`${this.gsqlBaseUrl}${path}`, {
+                ...init,
+                headers: { ...this.basicAuthHeaders(), ...init.headers },
+            });
+        }
+        catch (err) {
+            throw wrapConnectionError(err, this.options.host);
+        }
+        return this.parseEnvelope(response, action);
+    }
+    // ---------------------------------------------------------------------
+    // Installed (pre-compiled GSQL) queries
+    // ---------------------------------------------------------------------
+    /**
+     * Run an installed GSQL query: `GET /query/{graph}/{queryName}?param=value`
+     * (simple/scalar params) or `POST /query/{graph}/{queryName}` with a JSON
+     * body (complex params, e.g. sets/vertex lists). Confirmed endpoint
+     * shape and response envelope (`{version, error, message, results}`).
+     */
+    async runInstalledQuery(queryName, params = {}, options = {}) {
+        const graph = options.graph ?? this.options.graph;
+        const method = options.method ?? 'GET';
+        const path = `/query/${encodeURIComponent(graph)}/${encodeURIComponent(queryName)}`;
+        if (method === 'GET') {
+            const qs = new URLSearchParams(params).toString();
+            const envelope = await this.restRequest(qs ? `${path}?${qs}` : path, { method: 'GET' }, `installed query "${queryName}"`);
+            return envelope.results;
+        }
+        const envelope = await this.restRequest(path, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(params),
+        }, `installed query "${queryName}"`);
+        return envelope.results;
+    }
+    // ---------------------------------------------------------------------
+    // Vertex/edge upsert
+    // ---------------------------------------------------------------------
+    /**
+     * `POST /graph/{graph}` - raw upsert matching TigerGraph's documented
+     * wire format exactly (attribute values pre-wrapped as `{value: x}`).
+     * Prefer `upsertVertex`/`upsertVertices`/`upsertEdge`/`upsertEdges` for
+     * the common case of plain attribute values.
+     */
+    async upsert(payload, graph = this.options.graph) {
+        const envelope = await this.restRequest(`/graph/${encodeURIComponent(graph)}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+        }, 'upsert');
+        return envelope.results;
+    }
+    /** Upsert a single vertex with plain (unwrapped) attribute values. */
+    async upsertVertex(vertexType, id, attributes = {}, graph) {
+        return this.upsert({ vertices: { [vertexType]: { [id]: toWireAttributes(attributes) } } }, graph ?? this.options.graph);
+    }
+    /** Upsert multiple vertices of the same type in one round trip. */
+    async upsertVertices(vertexType, vertices, graph) {
+        const wired = {};
+        for (const [id, attrs] of Object.entries(vertices)) {
+            wired[id] = toWireAttributes(attrs);
+        }
+        return this.upsert({ vertices: { [vertexType]: wired } }, graph ?? this.options.graph);
+    }
+    /** Upsert a single edge with plain (unwrapped) attribute values. */
+    async upsertEdge(fromType, fromId, edgeType, toType, toId, attributes = {}, graph) {
+        return this.upsertEdges([{ fromType, fromId, edgeType, toType, toId, attributes }], graph);
+    }
+    /** Upsert multiple edges (possibly spanning different types/vertices) in one round trip. */
+    async upsertEdges(edges, graph) {
+        var _a, _b, _c;
+        const edgeMap = {};
+        for (const { fromType, fromId, edgeType, toType, toId, attributes } of edges) {
+            edgeMap[fromType] ?? (edgeMap[fromType] = {});
+            (_a = edgeMap[fromType])[fromId] ?? (_a[fromId] = {});
+            (_b = edgeMap[fromType][fromId])[edgeType] ?? (_b[edgeType] = {});
+            (_c = edgeMap[fromType][fromId][edgeType])[toType] ?? (_c[toType] = {});
+            edgeMap[fromType][fromId][edgeType][toType][toId] = toWireAttributes(attributes);
+        }
+        return this.upsert({ edges: edgeMap }, graph ?? this.options.graph);
+    }
+    // ---------------------------------------------------------------------
+    // Vertex/edge retrieval
+    // ---------------------------------------------------------------------
+    /**
+     * `GET /graph/{graph}/vertices/{type}/{id}` - fetch a single vertex by
+     * ID. Confirmed endpoint/response shape. Returns `null` if the vertex
+     * does not exist (TigerGraph reports this as `error: true` with a
+     * "does not exist" message rather than an empty result set).
+     */
+    async getVertex(vertexType, id, graph) {
+        const g = graph ?? this.options.graph;
+        const path = `/graph/${encodeURIComponent(g)}/vertices/${encodeURIComponent(vertexType)}/${encodeURIComponent(id)}`;
+        try {
+            const envelope = await this.restRequest(path, { method: 'GET' }, `get vertex "${vertexType}/${id}"`);
+            const results = envelope.results ?? [];
+            return results[0] ?? null;
+        }
+        catch (err) {
+            if (err instanceof errors_1.DatabaseError && /does not exist/i.test(err.message)) {
+                return null;
+            }
+            throw err;
+        }
+    }
+    /**
+     * `GET /graph/{graph}/vertices/{type}` - list vertices of a type
+     * (omitting the ID segment of the single-vertex endpoint above).
+     * TigerGraph's built-in-endpoints documentation confirms the
+     * single-vertex form; the list form (same resource without an ID, plus
+     * an optional `limit` query parameter) follows the standard REST++
+     * collection-resource pattern but its full parameter set (`filter`,
+     * `select`, `sort`, etc.) was not independently re-verified while
+     * building this store - only `limit` is wired up here (see README).
+     */
+    async listVerticesByType(vertexType, options = {}) {
+        const graph = options.graph ?? this.options.graph;
+        let path = `/graph/${encodeURIComponent(graph)}/vertices/${encodeURIComponent(vertexType)}`;
+        if (options.limit !== undefined) {
+            path += `?limit=${encodeURIComponent(options.limit)}`;
+        }
+        const envelope = await this.restRequest(path, { method: 'GET' }, `list vertices "${vertexType}"`);
+        return envelope.results ?? [];
+    }
+    /** `DELETE /graph/{graph}/vertices/{type}/{id}` - delete a single vertex (and its incident edges). Returns the number of vertices deleted (`0` or `1`). */
+    async deleteVertex(vertexType, id, graph) {
+        const g = graph ?? this.options.graph;
+        const path = `/graph/${encodeURIComponent(g)}/vertices/${encodeURIComponent(vertexType)}/${encodeURIComponent(id)}`;
+        const envelope = await this.restRequest(path, { method: 'DELETE' }, `delete vertex "${vertexType}/${id}"`);
+        return envelope.results?.deleted_vertices ?? 0;
+    }
+    /**
+     * `GET /graph/{graph}/edges/{fromType}/{fromId}/{edgeType}/{toType}/{toId}`
+     * - fetch the edge(s) between two specific vertices. Confirmed
+     * endpoint/response shape. Returns an empty array if no such edge
+     * exists.
+     */
+    async getEdge(fromType, fromId, edgeType, toType, toId, graph) {
+        const g = graph ?? this.options.graph;
+        const path = `/graph/${encodeURIComponent(g)}/edges/${encodeURIComponent(fromType)}/${encodeURIComponent(fromId)}/${encodeURIComponent(edgeType)}/${encodeURIComponent(toType)}/${encodeURIComponent(toId)}`;
+        try {
+            const envelope = await this.restRequest(path, { method: 'GET' }, `get edge "${fromType}/${fromId}->${toType}/${toId}"`);
+            return envelope.results ?? [];
+        }
+        catch (err) {
+            if (err instanceof errors_1.DatabaseError && /does not exist/i.test(err.message)) {
+                return [];
+            }
+            throw err;
+        }
+    }
+    /**
+     * `GET /graph/{graph}/edges/{fromType}/{fromId}[/{edgeType}]` - list all
+     * edges (of the given type, if provided) originating from a vertex.
+     * Same confidence note as `getEdge()`'s partial-path collection form.
+     */
+    async listEdgesFrom(fromType, fromId, edgeType, graph) {
+        const g = graph ?? this.options.graph;
+        let path = `/graph/${encodeURIComponent(g)}/edges/${encodeURIComponent(fromType)}/${encodeURIComponent(fromId)}`;
+        if (edgeType) {
+            path += `/${encodeURIComponent(edgeType)}`;
+        }
+        const envelope = await this.restRequest(path, { method: 'GET' }, `list edges from "${fromType}/${fromId}"`);
+        return envelope.results ?? [];
+    }
+    /** `DELETE /graph/{graph}/edges/{fromType}/{fromId}/{edgeType}/{toType}/{toId}` - delete a single edge. Returns the number of edges deleted. */
+    async deleteEdge(fromType, fromId, edgeType, toType, toId, graph) {
+        const g = graph ?? this.options.graph;
+        const path = `/graph/${encodeURIComponent(g)}/edges/${encodeURIComponent(fromType)}/${encodeURIComponent(fromId)}/${encodeURIComponent(edgeType)}/${encodeURIComponent(toType)}/${encodeURIComponent(toId)}`;
+        const envelope = await this.restRequest(path, { method: 'DELETE' }, `delete edge "${fromType}/${fromId}->${toType}/${toId}"`);
+        return envelope.results?.deleted_edges ?? 0;
+    }
+    // ---------------------------------------------------------------------
+    // Ad-hoc "interpreted" GSQL queries
+    // ---------------------------------------------------------------------
+    /**
+     * `POST /gsql/v1/queries/interpret` - compile and run a GSQL query
+     * string on the fly, without installing it first. Confirmed endpoint,
+     * auth (HTTP Basic, not the REST++ bearer token), and request shape:
+     * the request body is the raw GSQL text (`Content-Type: text/plain`),
+     * and GSQL query parameters are passed as URL query-string parameters.
+     *
+     * The older path `/gsqlserver/interpreted_query` (used by some
+     * pre-4.x deployments) is documented only in community sources, not in
+     * TigerGraph's current official docs, and its exact request shape was
+     * not independently confirmed - this store intentionally does not
+     * implement that alias rather than guess at its shape. If you're on a
+     * version that needs it, issue the request yourself via
+     * `getClient().restRequest()`/`gsqlRequest()` (or plain `fetch`) once
+     * you've confirmed the shape against your deployment.
+     */
+    async runInterpretedQuery(gsql, options = {}) {
+        const params = options.params ?? {};
+        const qs = new URLSearchParams(params).toString();
+        const path = qs ? `/gsql/v1/queries/interpret?${qs}` : '/gsql/v1/queries/interpret';
+        const envelope = await this.gsqlRequest(path, {
+            method: 'POST',
+            headers: { 'Content-Type': 'text/plain' },
+            body: gsql,
+        }, 'interpreted query');
+        return envelope.results;
+    }
+    // ---------------------------------------------------------------------
+    // Schema introspection
+    // ---------------------------------------------------------------------
+    /** `GET /gsql/v1/schema/vertices?graph={graph}` - list the graph's vertex types. Confirmed endpoint/response shape. */
+    async listVertexTypes(graph) {
+        const g = graph ?? this.options.graph;
+        const envelope = await this.gsqlRequest(`/gsql/v1/schema/vertices?graph=${encodeURIComponent(g)}`, { method: 'GET' }, 'list vertex types');
+        return envelope.results ?? [];
+    }
+    /** `GET /gsql/v1/schema/edges?graph={graph}` - list the graph's edge types. Confirmed endpoint/response shape. */
+    async listEdgeTypes(graph) {
+        const g = graph ?? this.options.graph;
+        const envelope = await this.gsqlRequest(`/gsql/v1/schema/edges?graph=${encodeURIComponent(g)}`, { method: 'GET' }, 'list edge types');
+        return envelope.results ?? [];
+    }
+}
+exports.TigerGraphStore = TigerGraphStore;
+exports.default = TigerGraphStore;

package/dist/nosql/typesense/index.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Typesense store implementation.
+ *
+ * Typesense is a typo-tolerant search engine built around an inverted index
+ * with faceting, filtering and ranking rather than SQL: no `JOIN`, no
+ * transaction log, documents grouped into strongly-typed collections (each
+ * described by a schema of fields). It therefore does not fit the SQL-shaped
+ * `Dialect` interface used by the SQL dialects in this repo. Instead it
+ * implements the minimal `NoSqlStore` marker interface (`src/nosql/store.ts`)
+ * and exposes Typesense's real capabilities grouped by concern: connection
+ * lifecycle, collection management and document CRUD/search.
+ *
+ * Uses the official `typesense` JS driver. The driver is loaded lazily via
+ * `require` so importing this module does not force the dependency to be
+ * resolved unless a Typesense store is actually constructed. For unit-testing
+ * without a live server, the constructor also accepts an already-built
+ * `client`, which `connect()` will use as-is instead of instantiating a new
+ * one.
+ *
+ * Operations are reached through the driver's fluent, resource-scoped API:
+ * `client.collections()` / `client.collections(name)` for collections and
+ * `client.collections(name).documents()` / `.documents(id)` for documents.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypesenseStore = void 0;
+const errors_1 = require("../../errors");
+function wrapConnectionError(err, nodes) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /econnrefused/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to Typesense: ${parent.message}`;
+    const first = Array.isArray(nodes) ? nodes[0] : undefined;
+    return new errors_1.ConnectionError(message, {
+        parent,
+        database: 'typesense',
+        host: first?.host,
+    });
+}
+function wrapDatabaseError(err, message) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const statusCode = err?.httpStatus;
+    const detail = statusCode ? `${parent.message} (HTTP ${statusCode})` : parent.message;
+    const combined = message ? `${message}: ${detail}` : detail;
+    return errors_1.DatabaseError.from(parent, { message: combined });
+}
+/**
+ * `TypesenseStore` wraps the official `typesense` client and exposes
+ * collection management, document CRUD, and search as a typed, promise-based
+ * API.
+ */
+class TypesenseStore {
+    constructor(options) {
+        this.name = 'typesense';
+        this.library = 'typesense';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        let client = this.options.client;
+        if (!client) {
+            // Lazy-load the driver so importing this module doesn't require the
+            // dependency to be present unless a store is actually constructed.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const Typesense = require('typesense');
+            client = new Typesense.Client({ nodes: this.options.nodes, apiKey: this.options.apiKey });
+        }
+        try {
+            // `health.retrieve()` surfaces connection failures (bad host, refused
+            // connection) immediately instead of on the caller's first real
+            // operation.
+            await client.health.retrieve();
+            this.client = client;
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.nodes);
+        }
+    }
+    async disconnect() {
+        // The Typesense client is stateless HTTP; there's no socket to close.
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `typesense` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Typesense', { database: 'typesense' });
+        }
+        return this.client;
+    }
+    async exec(fn, action) {
+        const client = this.requireClient();
+        try {
+            return await fn(client);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Typesense ${action} failed`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Collection management
+    // ---------------------------------------------------------------------
+    /** Create a collection from a schema (`{ name, fields, default_sorting_field? }`). */
+    async createCollection(schema) {
+        return this.exec((c) => c.collections().create(schema), 'CREATE COLLECTION');
+    }
+    /** Delete a collection by name. */
+    async deleteCollection(name) {
+        return this.exec((c) => c.collections(name).delete(), 'DELETE COLLECTION');
+    }
+    // ---------------------------------------------------------------------
+    // Document CRUD + search
+    // ---------------------------------------------------------------------
+    /** Index (create) a single document in a collection. */
+    async indexDocument(collection, document) {
+        return this.exec((c) => c.collections(collection).documents().create(document), 'INDEX DOCUMENT');
+    }
+    /** Run a search against a collection's documents. */
+    async search(collection, params) {
+        return this.exec((c) => c.collections(collection).documents().search(params), 'SEARCH');
+    }
+    /** Retrieve a single document by its `id`. */
+    async getDocument(collection, id) {
+        return this.exec((c) => c.collections(collection).documents(id).retrieve(), 'GET DOCUMENT');
+    }
+    /** Delete a single document by its `id`. */
+    async deleteDocument(collection, id) {
+        return this.exec((c) => c.collections(collection).documents(id).delete(), 'DELETE DOCUMENT');
+    }
+}
+exports.TypesenseStore = TypesenseStore;
+exports.default = TypesenseStore;