ts-prorm-orm 1.1.0 → 1.2.0

package/dist/nosql/faunadb/index.js

@@ -19,6 +19,188 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FaunaDbStore = void 0;
 const errors_1 = require("../../errors");
+/** Parse an ORM `where` object (string + `Op` symbol keys) into a tree. */
+function parseWhere(where) {
+    if (!where || typeof where !== 'object')
+        return null;
+    const nodes = [];
+    for (const sym of Object.getOwnPropertySymbols(where)) {
+        const name = sym.description;
+        const val = where[sym];
+        if (name === 'and' && Array.isArray(val)) {
+            nodes.push({ kind: 'and', nodes: val.map(parseWhere).filter(Boolean) });
+        }
+        else if (name === 'or' && Array.isArray(val)) {
+            nodes.push({ kind: 'or', nodes: val.map(parseWhere).filter(Boolean) });
+        }
+        else if (name === 'not') {
+            const inner = parseWhere(val);
+            if (inner)
+                nodes.push({ kind: 'not', node: inner });
+        }
+    }
+    for (const field of Object.keys(where)) {
+        nodes.push(parseFieldCondition(field, where[field]));
+    }
+    const flat = nodes.filter(Boolean);
+    if (flat.length === 0)
+        return null;
+    return flat.length === 1 ? flat[0] : { kind: 'and', nodes: flat };
+}
+/** Parse the value for a single field into a comparison (or AND of them). */
+function parseFieldCondition(field, value) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        const symbols = Object.getOwnPropertySymbols(value);
+        if (symbols.length > 0) {
+            const cmps = symbols.map((sym) => ({
+                kind: 'cmp',
+                field,
+                op: sym.description ?? 'eq',
+                value: value[sym],
+            }));
+            return cmps.length === 1 ? cmps[0] : { kind: 'and', nodes: cmps };
+        }
+    }
+    return { kind: 'cmp', field, op: value === null ? 'isNull' : 'eq', value };
+}
+/** Escape a string for safe embedding in a Fauna `ContainsStrRegex` pattern. */
+function escapeRegex(value) {
+    return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Convert a SQL `LIKE` pattern (`%`/`_` wildcards) to a regex source. */
+function likeToRegex(pattern) {
+    let out = '^';
+    for (const ch of String(pattern)) {
+        if (ch === '%')
+            out += '.*';
+        else if (ch === '_')
+            out += '.';
+        else
+            out += ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    return out + '$';
+}
+/**
+ * Build an FQL boolean predicate over the bound document variable `doc`
+ * (a materialized Fauna document, so fields live under `data`). Returns a
+ * raw FQL expression built with the injected query builder `q`.
+ */
+function buildFaunaPredicate(q, doc, node) {
+    if (!node)
+        return true;
+    const sel = (field) => q.Select(['data', ...field.split('.')], doc, null);
+    switch (node.kind) {
+        case 'and': {
+            if (node.nodes.length === 0)
+                return true;
+            if (node.nodes.length === 1)
+                return buildFaunaPredicate(q, doc, node.nodes[0]);
+            return q.And(...node.nodes.map((n) => buildFaunaPredicate(q, doc, n)));
+        }
+        case 'or': {
+            if (node.nodes.length === 0)
+                return false;
+            if (node.nodes.length === 1)
+                return buildFaunaPredicate(q, doc, node.nodes[0]);
+            return q.Or(...node.nodes.map((n) => buildFaunaPredicate(q, doc, n)));
+        }
+        case 'not':
+            return q.Not(buildFaunaPredicate(q, doc, node.node));
+        case 'cmp':
+            return buildFaunaCmp(q, sel(node.field), node.op, node.value);
+    }
+}
+function buildFaunaCmp(q, sel, op, value) {
+    switch (op) {
+        case 'eq':
+            return q.Equals(sel, value ?? null);
+        case 'ne':
+            return q.Not(q.Equals(sel, value ?? null));
+        case 'gt':
+            return q.GT(sel, value);
+        case 'gte':
+            return q.GTE(sel, value);
+        case 'lt':
+            return q.LT(sel, value);
+        case 'lte':
+            return q.LTE(sel, value);
+        case 'in': {
+            const arr = value ?? [];
+            if (arr.length === 0)
+                return false;
+            return q.Or(...arr.map((v) => q.Equals(sel, v)));
+        }
+        case 'notIn': {
+            const arr = value ?? [];
+            if (arr.length === 0)
+                return true;
+            return q.Not(q.Or(...arr.map((v) => q.Equals(sel, v))));
+        }
+        case 'between': {
+            const [a, b] = value;
+            return q.And(q.GTE(sel, a), q.LTE(sel, b));
+        }
+        case 'notBetween': {
+            const [a, b] = value;
+            return q.Not(q.And(q.GTE(sel, a), q.LTE(sel, b)));
+        }
+        case 'like':
+            return q.ContainsStrRegex(sel, likeToRegex(value));
+        case 'notLike':
+            return q.Not(q.ContainsStrRegex(sel, likeToRegex(value)));
+        case 'startsWith':
+            return q.ContainsStrRegex(sel, `^${escapeRegex(value)}`);
+        case 'endsWith':
+            return q.ContainsStrRegex(sel, `${escapeRegex(value)}$`);
+        case 'substring':
+            return q.ContainsStr(sel, String(value));
+        case 'regexp':
+            return q.ContainsStrRegex(sel, String(value));
+        case 'isNull':
+            return q.Equals(sel, null);
+        case 'isNotNull':
+            return q.Not(q.Equals(sel, null));
+        default:
+            throw new errors_1.DatabaseError(`FaunaDB ORM layer does not support operator "${op}"`, {
+                code: 'QUERY_ERROR',
+            });
+    }
+}
+/** A raw Fauna document (`{ ref, data, ts }`); normalize to `data` + `id`. */
+function normalizeFaunaDoc(doc) {
+    const data = (doc?.data ?? {});
+    const id = doc?.ref?.id ?? doc?.ref?.value?.id;
+    return (id !== undefined ? { id, ...data } : data);
+}
+/** Apply ORM order/limit/offset to already-fetched documents, client-side. */
+function applyClientSideShape(rows, options) {
+    let out = rows;
+    if (options.order && options.order.length > 0) {
+        const order = options.order;
+        out = [...out].sort((a, b) => {
+            for (const [field, dir] of order) {
+                const av = a?.[field];
+                const bv = b?.[field];
+                if (av === bv)
+                    continue;
+                const cmp = av === undefined || av === null
+                    ? -1
+                    : bv === undefined || bv === null
+                        ? 1
+                        : av < bv
+                            ? -1
+                            : 1;
+                return dir.toUpperCase() === 'DESC' ? -cmp : cmp;
+            }
+            return 0;
+        });
+    }
+    if (typeof options.offset === 'number')
+        out = out.slice(options.offset);
+    if (typeof options.limit === 'number')
+        out = out.slice(0, options.limit);
+    return out;
+}
 class FaunaDbStore {
     constructor(options = {}) {
         this.name = 'faunadb';
@@ -176,6 +358,153 @@ class FaunaDbStore {
             throw wrapDatabaseError(err, 'FaunaDB query failed');
         }
     }
+    // ---------------------------------------------------------------------
+    // ORM model surface (no hand-written FQL needed)
+    // ---------------------------------------------------------------------
+    /**
+     * Fetch every document in `collection` matching the ORM `where` clause. The
+     * `where` is compiled to an FQL predicate applied via `Filter` over the
+     * collection's documents; `order`/`limit`/`offset` are applied client-side.
+     * Each result is normalized to its `data` fields plus an `id`.
+     *
+     * This scans the collection (bounded by `pageSize`). For large collections,
+     * define a Fauna index and use the raw {@link query} escape hatch for an
+     * index-driven read.
+     */
+    async findAll(collection, options = {}) {
+        const client = this.requireClient();
+        const q = this.requireQuery();
+        const node = parseWhere(options.where);
+        const size = options.pageSize ?? 100000;
+        try {
+            const materialized = q.Map(q.Paginate(q.Documents(q.Collection(collection)), { size }), q.Lambda('ref', q.Get(q.Var('ref'))));
+            const filtered = node
+                ? q.Filter(materialized, q.Lambda('doc', buildFaunaPredicate(q, q.Var('doc'), node)))
+                : materialized;
+            const result = await client.query(filtered);
+            const docs = result?.data ?? [];
+            const rows = docs.map((d) => normalizeFaunaDoc(d));
+            return applyClientSideShape(rows, options);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'FaunaDB findAll failed');
+        }
+    }
+    /** Fetch the first document matching `where` (client-side `limit 1`), or `null`. */
+    async findOne(collection, options = {}) {
+        const rows = await this.findAll(collection, { ...options, limit: 1 });
+        return rows[0] ?? null;
+    }
+    /** Count documents in `collection` matching `where`. */
+    async count(collection, where) {
+        const rows = await this.findAll(collection, { where });
+        return rows.length;
+    }
+    /** Insert `data` and return the new document's id. Alias of {@link insert}. */
+    async create(collection, data) {
+        return this.insert(collection, data);
+    }
+    /**
+     * Insert many documents atomically in a single FQL `Map`/`Create`, returning
+     * the new document ids in order.
+     */
+    async bulkCreate(collection, docs) {
+        if (docs.length === 0)
+            return [];
+        const client = this.requireClient();
+        const q = this.requireQuery();
+        try {
+            const result = await client.query(q.Map(docs, q.Lambda('d', q.Create(q.Collection(collection), { data: q.Var('d') }))));
+            const created = Array.isArray(result) ? result : (result?.data ?? []);
+            return created.map((r) => r?.ref?.id ?? r?.data?.id);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'FaunaDB bulkCreate failed');
+        }
+    }
+    /**
+     * Update every document matching `where`, merging `values` into each match's
+     * `data`, all in a single atomic FQL expression. Returns the number of
+     * documents updated.
+     */
+    async updateMany(collection, values, where) {
+        const client = this.requireClient();
+        const q = this.requireQuery();
+        const node = parseWhere(where);
+        try {
+            const materialized = q.Map(q.Paginate(q.Documents(q.Collection(collection)), { size: 100000 }), q.Lambda('ref', q.Get(q.Var('ref'))));
+            const filtered = node
+                ? q.Filter(materialized, q.Lambda('doc', buildFaunaPredicate(q, q.Var('doc'), node)))
+                : materialized;
+            const result = await client.query(q.Map(filtered, q.Lambda('doc', q.Update(q.Select('ref', q.Var('doc')), { data: values }))));
+            const updated = Array.isArray(result) ? result : (result?.data ?? []);
+            return updated.length;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'FaunaDB updateMany failed');
+        }
+    }
+    /**
+     * Delete every document matching `where` in a single atomic FQL expression.
+     * Returns the number of documents deleted.
+     */
+    async destroy(collection, where) {
+        const client = this.requireClient();
+        const q = this.requireQuery();
+        const node = parseWhere(where);
+        try {
+            const materialized = q.Map(q.Paginate(q.Documents(q.Collection(collection)), { size: 100000 }), q.Lambda('ref', q.Get(q.Var('ref'))));
+            const filtered = node
+                ? q.Filter(materialized, q.Lambda('doc', buildFaunaPredicate(q, q.Var('doc'), node)))
+                : materialized;
+            const result = await client.query(q.Map(filtered, q.Lambda('doc', q.Delete(q.Select('ref', q.Var('doc'))))));
+            const deleted = Array.isArray(result) ? result : (result?.data ?? []);
+            return deleted.length;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'FaunaDB destroy failed');
+        }
+    }
+    /**
+     * Insert-or-update: if a document matching `where` exists, merge `data` into
+     * the first match; otherwise create a new document seeded with the `where`
+     * equality keys plus `data`. Returns `{ created }`.
+     */
+    async upsert(collection, data, where) {
+        const existing = await this.findAll(collection, { where, limit: 1 });
+        if (existing.length > 0 && existing[0].id !== undefined) {
+            await this.update(collection, String(existing[0].id), data);
+            return { created: false };
+        }
+        const seed = {};
+        for (const field of Object.keys(where)) {
+            const val = where[field];
+            if (val === null || typeof val !== 'object' || Array.isArray(val))
+                seed[field] = val;
+        }
+        await this.insert(collection, { ...seed, ...data });
+        return { created: true };
+    }
+    /**
+     * Run several FQL write expressions atomically in a single transaction via
+     * FQL's `Do` (Fauna evaluates a single query as one serializable
+     * transaction). Pass expressions built with the query builder from
+     * {@link getQuery}. Returns the value of the last expression.
+     */
+    async transaction(expressions) {
+        const client = this.requireClient();
+        const q = this.requireQuery();
+        try {
+            return await client.query(q.Do(...expressions));
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'FaunaDB transaction failed');
+        }
+    }
+    /** Exposes the FQL query builder (`faunadb.query`) for building raw expressions. */
+    getQuery() {
+        return this.requireQuery();
+    }
 }
 exports.FaunaDbStore = FaunaDbStore;
 function wrapDatabaseError(err, message) {

package/dist/nosql/firestore/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Google Cloud Firestore store implementation for the Prorm NoSQL layer.
+ *
+ * Firestore is a document database organized as collections of documents,
+ * each addressed by an id, with rich structured querying. It does not fit the
+ * SQL-shaped `Dialect` interface, so this class implements the minimal
+ * `NoSqlStore` marker interface for connection lifecycle and exposes
+ * Firestore's real `collection().doc()` CRUD plus `where()` query API through
+ * a small convenience layer.
+ *
+ * Uses the official `@google-cloud/firestore` driver. That driver is an
+ * optional peer dependency and is loaded lazily inside `connect()` so
+ * importing this module never requires it to be installed. Tests inject a
+ * pre-built mock `client` via `options.client`, which bypasses the lazy
+ * `require` entirely - no real driver and no network are needed.
+ */
+import { NoSqlStore } from '../store';
+/** A native `Firestore` handle, left untyped because the driver is an optional
+ * dependency not imported here. */
+type Firestore = any;
+/** A single Firestore query condition: `[field, operator, value]`. */
+export type FirestoreCondition = [string, string, unknown];
+/**
+ * Connection options for `FirestoreStore`.
+ *
+ * `projectId`/`keyFilename` configure the underlying `Firestore` client. When
+ * a pre-built `client` is supplied (e.g. in tests), `connect()` uses it
+ * directly and skips loading the `@google-cloud/firestore` driver.
+ */
+export interface FirestoreStoreOptions {
+    projectId?: string;
+    keyFilename?: string;
+    /** A pre-built `Firestore` client to use instead of the driver. */
+    client?: Firestore;
+}
+export declare class FirestoreStore implements NoSqlStore {
+    readonly name = "firestore";
+    readonly library = "@google-cloud/firestore";
+    private readonly options;
+    private client;
+    private connected;
+    constructor(options?: FirestoreStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getClient(): Firestore;
+    private requireClient;
+    /**
+     * Add a document to `collection`. If `doc.id` is set the document is written
+     * to that id via `doc(id).set(doc)`; otherwise Firestore auto-assigns one
+     * via `collection.add(doc)`. Returns the resulting document id.
+     */
+    insert(collection: string, doc: Record<string, unknown>): Promise<unknown>;
+    /** Fetch a document by id, returning its data (or `undefined` if missing). */
+    get(collection: string, id: string): Promise<unknown>;
+    /** Partially update a document by id, returning the applied `patch`. */
+    update(collection: string, id: string, patch: Record<string, unknown>): Promise<unknown>;
+    /** Delete a document by id. */
+    delete(collection: string, id: string): Promise<unknown>;
+    /**
+     * Query `collection`. `filter` may be an array of `[field, op, value]`
+     * conditions or a plain object (treated as equality on each key). Returns
+     * the matched documents, each shaped as `{ id, ...data }`.
+     */
+    query(collection: string, filter?: FirestoreCondition[] | Record<string, unknown>): Promise<unknown[]>;
+}
+export default FirestoreStore;

package/dist/nosql/fluree/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Fluree store implementation.
+ *
+ * Fluree is an immutable, time-travel ledger database: every transaction is
+ * appended as a set of cryptographically-hashed "flakes" into a blockchain-
+ * like log, so no data is ever overwritten and any past state (by block or
+ * time) is queryable. It speaks a JSON query/transaction API (FlureeQL) over
+ * HTTP, not SQL.
+ *
+ * ## No canonical driver - HTTP over `fetch`
+ *
+ * Fluree has no single canonical npm client; it is an HTTP/JSON API. Like the
+ * Prometheus store, this class talks to the server with the global `fetch`
+ * (so `library === 'fetch'`) and accepts an injected HTTP client via
+ * `FlureeStoreOptions.client` for tests / custom transports. It implements the
+ * minimal `NoSqlStore` marker interface plus the shared ledger surface:
+ *  - `append(collection, data)` -> `POST /fdb/<ledger>/transact`.
+ *  - `get(collection, id)`      -> `POST /fdb/<ledger>/query`.
+ *  - `history(collection, id)`  -> `POST /fdb/<ledger>/history`.
+ *  - `verify(collection, id)`   -> `POST /fdb/<ledger>/history` with block
+ *    metadata (the flake's block hash is its tamper-evidence proof).
+ *  - `query(flureeql)`          -> raw `POST /fdb/<ledger>/query`.
+ */
+import { NoSqlStore } from '../store';
+/** Default Fluree HTTP API base URL. */
+export declare const DEFAULT_FLUREE_BASE_URL = "http://localhost:8090";
+/** The subset of an HTTP client this store needs. */
+export interface FlureeHttpClient {
+    /** Issue a POST with a JSON body and return the parsed JSON response. */
+    post(path: string, body: unknown): Promise<any>;
+}
+/** Connection options for `FlureeStore`. */
+export interface FlureeStoreOptions {
+    /** Base URL of the Fluree server. Defaults to `http://localhost:8090`. */
+    baseURL?: string;
+    /** Ledger (network/db) name, e.g. `'my/ledger'`. */
+    ledger: string;
+    /** Optional pre-built HTTP client; when provided, `baseURL` is ignored. */
+    client?: FlureeHttpClient;
+    /** Extra HTTP headers (e.g. an auth `Authorization` bearer). */
+    headers?: Record<string, string>;
+}
+/** Build a `fetch`-backed JSON client for the given base URL. */
+export declare function createFlureeFetchClient(baseURL: string, headers?: Record<string, string>): FlureeHttpClient;
+/**
+ * `FlureeStore` wraps Fluree's HTTP query/transact API behind the shared
+ * ledger surface.
+ */
+export declare class FlureeStore implements NoSqlStore {
+    readonly name = "fluree";
+    readonly library = "fetch";
+    private readonly baseURL;
+    private readonly ledger;
+    private readonly injectedClient?;
+    private readonly headers?;
+    private client;
+    private connected;
+    constructor(options: FlureeStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying (internal or injected) HTTP client. */
+    getClient(): FlureeHttpClient;
+    private requireClient;
+    private endpoint;
+    private post;
+    /**
+     * Append `data` to `collection` as a transaction (`POST .../transact`).
+     * Returns the transaction response (block, flakes, temp-id map, and the
+     * block hash that anchors the write into the immutable log).
+     */
+    append(collection: string, data: Record<string, unknown>): Promise<unknown>;
+    /** Read subject `id` from `collection` (`POST .../query`). */
+    get(collection: string, id: string | number): Promise<unknown>;
+    /** Return the flake-level history of subject `id` (`POST .../history`). */
+    history(collection: string, id: string | number): Promise<unknown>;
+    /**
+     * Return the provenance/proof for subject `id`: its history with block
+     * metadata (`meta: true`), so callers see the block hash and instant that
+     * cryptographically anchor each revision into Fluree's tamper-evident log.
+     */
+    verify(collection: string, id: string | number): Promise<unknown>;
+    /** Run a raw FlureeQL query object (`POST .../query`). */
+    query(flureeql: unknown): Promise<unknown>;
+    /** Run a raw FlureeQL transaction (`POST .../transact`). */
+    transact(transaction: unknown): Promise<unknown>;
+}
+export default FlureeStore;

package/dist/nosql/fuseki/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Apache Jena Fuseki store implementation.
+ *
+ * Fuseki is a SPARQL server over the Jena RDF triplestore. It is queried and
+ * updated entirely over HTTP using the SPARQL 1.1 Protocol: a dataset exposes
+ * a query endpoint (`/<dataset>/query`) and an update endpoint
+ * (`/<dataset>/update`). There is no SQL-shaped surface (no rows, no DDL, no
+ * identifier escaping), so it implements the minimal `NoSqlStore` marker
+ * interface (`src/nosql/store.ts`) rather than the SQL `Dialect` interface.
+ *
+ * ## No canonical driver - HTTP over `fetch`
+ *
+ * Fuseki has no dedicated npm client; it is just a SPARQL/HTTP endpoint.
+ * Rather than depend on any package, this store talks to the server with the
+ * global `fetch`. For tests (and for callers who want their own transport) an
+ * alternative client can be injected via `FusekiStoreOptions.client`; when
+ * omitted, a tiny internal client over `fetch` + `endpoint` is built at
+ * connect time.
+ *
+ * ## Surface
+ *
+ * - `query(sparql)`  -> POST to `/<dataset>/query`, returns result bindings
+ * - `update(sparql)` -> POST to `/<dataset>/update`
+ * - `ask(sparql)`    -> POST an ASK query, returns the boolean
+ * - `add(triples)`   -> `INSERT DATA { ... }` update
+ * - `drop(graph?)`   -> `DROP GRAPH <g>` / `DROP ALL` update
+ */
+import { NoSqlStore } from '../store';
+/** Default Fuseki base URL. */
+export declare const DEFAULT_FUSEKI_ENDPOINT = "http://localhost:3030";
+/** Default dataset name. */
+export declare const DEFAULT_FUSEKI_DATASET = "ds";
+/**
+ * The subset of a SPARQL HTTP client this store needs. The internal
+ * `fetch`-based client implements this; tests inject a mock with the shape.
+ */
+export interface SparqlHttpClient {
+    /** POST a SPARQL query to `path`; returns the parsed results envelope. */
+    query(path: string, sparql: string): Promise<any>;
+    /** POST a SPARQL update to `path`. */
+    update(path: string, sparql: string): Promise<any>;
+}
+/** Connection options for `FusekiStore`. */
+export interface FusekiStoreOptions {
+    /** Base URL of the Fuseki server. Defaults to `http://localhost:3030`. */
+    endpoint?: string;
+    /** Dataset name. Defaults to `ds`. */
+    dataset?: string;
+    /**
+     * Optional pre-built SPARQL HTTP client. When provided it is used verbatim
+     * and `endpoint` is ignored; otherwise an internal `fetch`-based client is
+     * built against `endpoint` on `connect()`.
+     */
+    client?: SparqlHttpClient;
+    /** Extra HTTP headers sent with every internal-client request. */
+    headers?: Record<string, string>;
+}
+/** Build a `fetch`-backed SPARQL client for the given endpoint. */
+export declare function createFetchClient(endpoint: string, headers?: Record<string, string>): SparqlHttpClient;
+/**
+ * `FusekiStore` wraps a Fuseki dataset's SPARQL query/update endpoints behind
+ * the `NoSqlStore` lifecycle.
+ */
+export declare class FusekiStore implements NoSqlStore {
+    readonly name = "fuseki";
+    readonly library = "fetch";
+    private readonly endpoint;
+    private readonly dataset;
+    private readonly injectedClient?;
+    private readonly headers?;
+    private client;
+    private connected;
+    constructor(options?: FusekiStoreOptions);
+    /** SPARQL query endpoint path for the configured dataset. */
+    get queryPath(): string;
+    /** SPARQL update endpoint path for the configured dataset. */
+    get updatePath(): string;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying (internal or injected) SPARQL HTTP client. */
+    getClient(): SparqlHttpClient;
+    private requireClient;
+    /** Runs a SPARQL SELECT/CONSTRUCT query; returns the result bindings. */
+    query(sparql: string): Promise<any[]>;
+    /** Runs a SPARQL ASK query; returns the boolean answer. */
+    ask(sparql: string): Promise<boolean>;
+    /** Runs a SPARQL UPDATE (INSERT/DELETE/DROP/...). */
+    update(sparql: string): Promise<any>;
+    /** Inserts triples via `INSERT DATA { ... }`. Accepts a triple string or array. */
+    add(triples: string | string[], graph?: string): Promise<any>;
+    /** Drops a named graph, or all graphs when no graph is given. */
+    drop(graph?: string): Promise<any>;
+}

package/dist/nosql/gcs/index.d.ts

@@ -0,0 +1,62 @@
+import type { NoSqlStore } from '../store';
+/**
+ * Connection options for `GCSStore`.
+ */
+export interface GCSStoreOptions {
+    /** GCP project ID. Falls back to the ambient credentials' project when omitted. */
+    projectId?: string;
+    /** Path to a service-account key JSON file. Omit to use Application Default Credentials. */
+    keyFilename?: string;
+    /**
+     * A pre-built `Storage` instance (from `new Storage(...)`). When provided,
+     * `connect()` uses it directly and skips loading `@google-cloud/storage`.
+     * Primarily an injection seam for tests, but also useful for sharing a
+     * client or supplying custom constructor options.
+     */
+    client?: unknown;
+}
+/** Options passed straight through to `file.save()` (contentType, metadata, resumable, etc). */
+export type UploadObjectOptions = Record<string, unknown>;
+/**
+ * Google Cloud Storage store, implementing the minimal `NoSqlStore` marker
+ * interface. Unlike the SQL dialects there is no `query(sql)` - GCS's
+ * operations are object-shaped (`bucket(name).file(key).<op>()`) and that
+ * shape is preserved here rather than forced into a SQL string.
+ */
+export declare class GCSStore implements NoSqlStore {
+    readonly name = "gcs";
+    readonly library = "@google-cloud/storage";
+    private readonly options;
+    private client;
+    private connected;
+    constructor(options?: GCSStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `@google-cloud/storage` `Storage` client for anything not wrapped here. */
+    getClient(): unknown;
+    private requireClient;
+    /** Resolve a `File` handle for `(bucket, key)` off the live client. */
+    private file;
+    private wrapError;
+    /**
+     * Upload (or overwrite) an object. `data` may be a `Buffer` or string;
+     * `options` is passed straight through to `file.save()` (e.g.
+     * `{ contentType, metadata, resumable }`).
+     */
+    uploadObject(bucket: string, key: string, data: Buffer | string, options?: UploadObjectOptions): Promise<void>;
+    /** Download an object's contents as a `Buffer`. Throws if the object does not exist. */
+    downloadObject(bucket: string, key: string): Promise<Buffer>;
+    /** Delete an object. Throws if the object does not exist. */
+    deleteObject(bucket: string, key: string): Promise<void>;
+    /** Returns whether an object exists. */
+    objectExists(bucket: string, key: string): Promise<boolean>;
+    /**
+     * List objects in a bucket, optionally restricted to those whose name
+     * starts with `prefix`. Returns the raw `File` objects from the driver.
+     */
+    listObjects(bucket: string, prefix?: string): Promise<any[]>;
+    /** Fetch an object's metadata (size, contentType, updated, custom metadata, etc). */
+    getMetadata(bucket: string, key: string): Promise<Record<string, unknown>>;
+}
+export default GCSStore;