ts-prorm-orm 1.1.0 → 1.2.0

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

@@ -0,0 +1,88 @@
+/**
+ * Blazegraph store implementation.
+ *
+ * Blazegraph is a high-performance RDF triplestore. It speaks the SPARQL 1.1
+ * Protocol over HTTP: a namespace exposes a single combined SPARQL endpoint
+ * (`/blazegraph/namespace/<ns>/sparql`) used for both queries and updates
+ * (dispatched by request content-type). There is no SQL-shaped surface, so it
+ * implements the minimal `NoSqlStore` marker interface (`src/nosql/store.ts`)
+ * rather than the SQL `Dialect` interface.
+ *
+ * ## No canonical driver - HTTP over `fetch`
+ *
+ * Blazegraph has no dedicated npm client; it is just a SPARQL/HTTP endpoint.
+ * 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 `BlazegraphStoreOptions.client`; when omitted, a tiny internal client
+ * over `fetch` + `endpoint` is built at connect time.
+ *
+ * ## Surface
+ *
+ * - `query(sparql)`  -> POST to `/blazegraph/namespace/<ns>/sparql`, bindings
+ * - `update(sparql)` -> POST to the same endpoint
+ * - `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 Blazegraph base URL. */
+export declare const DEFAULT_BLAZEGRAPH_ENDPOINT = "http://localhost:9999";
+/** Default namespace. */
+export declare const DEFAULT_BLAZEGRAPH_NAMESPACE = "kb";
+/** The subset of a SPARQL HTTP client this store needs. */
+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 `BlazegraphStore`. */
+export interface BlazegraphStoreOptions {
+    /** Base URL of the Blazegraph server. Defaults to `http://localhost:9999`. */
+    endpoint?: string;
+    /** Namespace name. Defaults to `kb`. */
+    namespace?: string;
+    /** Optional pre-built SPARQL HTTP client (used verbatim; `endpoint` ignored). */
+    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;
+/**
+ * `BlazegraphStore` wraps a Blazegraph namespace's combined SPARQL endpoint
+ * behind the `NoSqlStore` lifecycle.
+ */
+export declare class BlazegraphStore implements NoSqlStore {
+    readonly name = "blazegraph";
+    readonly library = "fetch";
+    private readonly endpoint;
+    private readonly namespace;
+    private readonly injectedClient?;
+    private readonly headers?;
+    private client;
+    private connected;
+    constructor(options?: BlazegraphStoreOptions);
+    /** Combined SPARQL endpoint path for the configured namespace. */
+    get sparqlPath(): string;
+    /** SPARQL query endpoint path (same combined endpoint). */
+    get queryPath(): string;
+    /** SPARQL update endpoint path (same combined endpoint). */
+    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/bullmq/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * BullMQ job/task-queue store.
+ *
+ * BullMQ is a Redis-backed queue: a `Queue` object adds jobs to a named
+ * queue, and a `Worker` object pulls jobs from that queue and runs a handler.
+ * Each queue is a distinct object bound to a name, so this store caches one
+ * `Queue` (and, once `process()`d, one `Worker`) per queue name. BullMQ is
+ * not a database and does not fit the SQL-shaped `Dialect` interface, so this
+ * class implements the minimal `NoSqlStore` marker interface and exposes
+ * BullMQ's real add/process/getJob operations instead.
+ *
+ * Uses the `bullmq` driver. It is an optional peer loaded lazily (via
+ * `require`) inside `connect()`, so importing this module does not require it
+ * to be installed unless you actually connect. A pre-built driver module
+ * (providing `Queue` and `Worker` constructors) can be injected via
+ * `BullMQStoreOptions.client`, in which case `connect()` adopts it and skips
+ * the `require` entirely (used by the unit tests to inject mocks).
+ */
+import type { NoSqlStore } from '../store';
+/** Connection options for `BullMQStore`. */
+export interface BullMQStoreOptions {
+    /**
+     * ioredis-style connection options passed to every `Queue`/`Worker`
+     * (e.g. `{ host, port }` or `{ url }`). Defaults to `{ host: '127.0.0.1',
+     * port: 6379 }`.
+     */
+    connection?: any;
+    /**
+     * A pre-built `bullmq` module (or a stand-in exposing `Queue` and `Worker`
+     * constructors). When provided, `connect()` adopts it and does not
+     * `require('bullmq')` — used for injecting mocks in tests.
+     */
+    client?: any;
+}
+/** Options for `enqueue()` — BullMQ job options plus an optional job name. */
+export interface BullMQEnqueueOptions {
+    /** The BullMQ "job name" (defaults to the queue name). */
+    name?: string;
+    /** BullMQ `JobsOptions` (delay, attempts, backoff, priority, etc.). */
+    [key: string]: any;
+}
+/**
+ * `BullMQStore` manages a pool of BullMQ `Queue`/`Worker` objects keyed by
+ * queue name and exposes the common queue surface
+ * (`enqueue`/`process`/`getJob`/`remove`/`stats`).
+ */
+export declare class BullMQStore implements NoSqlStore {
+    readonly name = "bullmq";
+    readonly library = "bullmq";
+    private readonly options;
+    private driver;
+    private connected;
+    private readonly queues;
+    private readonly workers;
+    constructor(options?: BullMQStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `bullmq` driver module (with `Queue`/`Worker`). */
+    getClient(): any;
+    private requireDriver;
+    private get connectionOpts();
+    /** Get (creating and caching on first use) the `Queue` for a queue name. */
+    private getQueue;
+    /**
+     * Add a job to the named queue via `queue.add(name, data, opts)`. Returns
+     * the id BullMQ assigns to the job.
+     */
+    enqueue(queue: string, jobData: unknown, opts?: BullMQEnqueueOptions): Promise<string>;
+    /**
+     * Register a `Worker` for the named queue that runs `handler(job)` for each
+     * job. One worker is cached per queue name; a second `process()` on the
+     * same name returns the existing worker.
+     */
+    process(queue: string, handler: (job: any) => any | Promise<any>, opts?: any): Promise<any>;
+    /** Fetch a job by id from the named queue (`null` if it no longer exists). */
+    getJob(queue: string, id: string): Promise<any>;
+    /** Remove a job by id from the named queue. */
+    remove(queue: string, id: string): Promise<void>;
+    /** Return job counts by state (`waiting`/`active`/`completed`/`failed`/...). */
+    stats(queue: string): Promise<any>;
+}
+export default BullMQStore;

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

@@ -0,0 +1,119 @@
+import type { NoSqlStore } from '../store';
+/**
+ * A single statement for `batch()`: a CQL string plus its bound parameters.
+ * Mirrors the `cassandra-driver` batch query shape.
+ */
+export interface CassandraBatchQuery {
+    query: string;
+    params?: unknown[];
+}
+/**
+ * Options for `execute()` / `batch()`. These are forwarded straight through
+ * to the driver's query-options bag (consistency, fetchSize, pageState,
+ * timestamp, etc.). `prepare` defaults to `true` here (see `execute()`), but
+ * can be overridden per call.
+ */
+export interface CassandraQueryOptions {
+    prepare?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * The shape of a `cassandra-driver` result. Only `rows` is relied on here;
+ * the rest of the driver's result metadata is preserved via the index
+ * signature so callers get the full result back from `execute()`.
+ */
+export interface CassandraResult<T = Record<string, unknown>> {
+    rows?: T[];
+    [key: string]: unknown;
+}
+/**
+ * Minimal structural type for the pieces of a `cassandra-driver` `Client`
+ * this store uses. Kept local (rather than importing from `cassandra-driver`)
+ * so this module type-checks without the optional driver installed.
+ */
+export interface CassandraClientLike {
+    connect(): Promise<void>;
+    execute(query: string, params?: unknown[], options?: Record<string, unknown>): Promise<CassandraResult>;
+    batch(queries: CassandraBatchQuery[], options?: Record<string, unknown>): Promise<CassandraResult>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Connection options for `CassandraStore`. These map onto the
+ * `cassandra-driver` `Client` constructor options.
+ */
+export interface CassandraStoreOptions {
+    /** Seed node addresses, e.g. `['127.0.0.1']` or `['10.0.0.1:9042']`. */
+    contactPoints?: string[];
+    /** Local data center name (required by the driver's default load-balancing policy). */
+    localDataCenter?: string;
+    /** Default keyspace to bind the session to. */
+    keyspace?: string;
+    /** Plain-text auth credentials passed to the driver. */
+    credentials?: {
+        username: string;
+        password: string;
+    };
+    /**
+     * Escape hatch for any other `cassandra-driver` `Client` option
+     * (pooling, SSL, policies, socketOptions, ...). Merged into the options
+     * passed to the `Client` constructor.
+     */
+    clientOptions?: Record<string, unknown>;
+    /**
+     * A pre-built driver `Client` (or a compatible mock). When provided,
+     * `connect()` uses it directly and skips `require('cassandra-driver')`
+     * entirely — this is how tests inject a mock without the real driver
+     * installed.
+     */
+    client?: CassandraClientLike;
+}
+/**
+ * `CassandraStore` wraps a `cassandra-driver` `Client` and exposes CQL
+ * execution (`execute`), atomic multi-statement batches (`batch`), and a few
+ * parameterized convenience helpers (`insert`, `selectAll`).
+ *
+ * Statements are prepared by default (`prepare: true`) so the driver can cache
+ * query metadata, infer parameter types, and route requests to replica nodes
+ * that own the partition — the recommended default for anything run more than
+ * once.
+ */
+export declare class CassandraStore implements NoSqlStore {
+    readonly name = "cassandra";
+    readonly library = "cassandra-driver";
+    private readonly options;
+    private client;
+    private connected;
+    constructor(options?: CassandraStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `cassandra-driver` `Client` for anything not wrapped here. */
+    getClient(): CassandraClientLike;
+    private requireClient;
+    private wrapError;
+    /**
+     * Execute a single CQL statement with optional bound `params`. Statements
+     * are prepared by default (`prepare: true`); pass `opts.prepare = false` to
+     * run a one-off unprepared. Any other driver query options (consistency,
+     * fetchSize, pageState, ...) are forwarded via `opts`. Returns the full
+     * driver result (with `.rows`).
+     */
+    execute<T = Record<string, unknown>>(query: string, params?: unknown[], opts?: CassandraQueryOptions): Promise<CassandraResult<T>>;
+    /**
+     * Execute multiple statements as a single logged batch (atomic across the
+     * statements, though not isolated — Cassandra batches are not SQL
+     * transactions). Each entry is a `{ query, params }` pair. Prepared by
+     * default; forward other driver batch options via `opts`.
+     */
+    batch(queries: CassandraBatchQuery[], opts?: CassandraQueryOptions): Promise<CassandraResult>;
+    /**
+     * Convenience `INSERT`: builds a parameterized
+     * `INSERT INTO table (cols...) VALUES (?, ?, ...)` from `obj`'s keys and
+     * executes it (prepared). For upserts with TTL, IF NOT EXISTS, or other
+     * clauses, write the CQL yourself and call `execute()`.
+     */
+    insert(table: string, obj: Record<string, unknown>, opts?: CassandraQueryOptions): Promise<CassandraResult>;
+    /** Convenience `SELECT * FROM table`. Returns the full driver result (with `.rows`). */
+    selectAll<T = Record<string, unknown>>(table: string, opts?: CassandraQueryOptions): Promise<CassandraResult<T>>;
+}
+export default CassandraStore;

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

@@ -0,0 +1,151 @@
+/**
+ * Chroma (ChromaDB) vector-database store.
+ *
+ * Chroma is an embedding database organized around *collections*: a
+ * collection holds records that are `{ id, embedding, metadata?, document? }`
+ * tuples, and the core operation is an approximate-nearest-neighbor `query`
+ * over a collection's embeddings (optionally narrowed by a metadata `where`
+ * filter) - not SQL, not joins, not a transaction log. None of that fits
+ * the SQL-shaped `Dialect` interface used by the SQL dialects in this repo,
+ * so this class implements the minimal `NoSqlStore` marker interface
+ * (`src/nosql/store.ts`) and exposes Chroma's real collection- and
+ * embedding-level operations directly.
+ *
+ * Uses the `chromadb` driver, lazy-loaded inside `connect()` via `require()`
+ * so the dependency is only needed when a Chroma store is actually
+ * constructed (tests inject a pre-built mock `client` instead). The client
+ * talks to Chroma's HTTP API and is stateless, so `connect()`/`disconnect()`
+ * construct/discard the client rather than opening a real socket.
+ *
+ * Every embedding-level method takes a collection *name*; the underlying
+ * `Collection` handle is resolved (and cached) via
+ * `client.getOrCreateCollection(...)` so callers never have to thread a
+ * collection object through by hand.
+ */
+import { NoSqlStore } from '../store';
+/**
+ * Connection options for `ChromaStore`. `path` is the base URL of the
+ * Chroma server (e.g. `http://localhost:8000`) and is forwarded to
+ * `new ChromaClient({ path })`; any other `ChromaClient` options pass
+ * through unchanged.
+ */
+export interface ChromaStoreOptions {
+    /** Base URL of the Chroma server (e.g. `http://localhost:8000`). */
+    path?: string;
+    /**
+     * A pre-built `ChromaClient`. When provided, `connect()` skips the
+     * `require('chromadb')` / `new ChromaClient(...)` step and uses this
+     * instead - the injection point used by tests to supply a mock.
+     */
+    client?: ChromaClientLike;
+    /** Any other option accepted by `new ChromaClient(...)`. */
+    [key: string]: unknown;
+}
+/** A Chroma collection handle - the subset of its surface this store uses. */
+export interface ChromaCollectionLike {
+    name?: string;
+    add(params: AddEmbeddingsParams): Promise<unknown>;
+    query(params: QueryEmbeddingsParams): Promise<unknown>;
+    get(params: GetEmbeddingsParams): Promise<unknown>;
+    delete(params: DeleteEmbeddingsParams): Promise<unknown>;
+    [key: string]: unknown;
+}
+/** The subset of the `ChromaClient` surface this store uses. */
+export interface ChromaClientLike {
+    createCollection(params: {
+        name: string;
+        [key: string]: unknown;
+    }): Promise<ChromaCollectionLike>;
+    getOrCreateCollection(params: {
+        name: string;
+        [key: string]: unknown;
+    }): Promise<ChromaCollectionLike>;
+    getCollection?(params: {
+        name: string;
+        [key: string]: unknown;
+    }): Promise<ChromaCollectionLike>;
+    deleteCollection(params: {
+        name: string;
+    }): Promise<unknown>;
+    [key: string]: unknown;
+}
+/** Args for `addEmbeddings()` - index-aligned parallel arrays. */
+export interface AddEmbeddingsParams {
+    ids: string[];
+    embeddings: number[][];
+    metadatas?: Array<Record<string, unknown>>;
+    documents?: string[];
+}
+/** Args for `query()`. */
+export interface QueryEmbeddingsParams {
+    queryEmbeddings: number[][];
+    nResults?: number;
+    where?: Record<string, unknown>;
+    whereDocument?: Record<string, unknown>;
+    include?: string[];
+}
+/** Args for `get()`. */
+export interface GetEmbeddingsParams {
+    ids: string[];
+    where?: Record<string, unknown>;
+    include?: string[];
+}
+/** Args for `deleteEmbeddings()`. */
+export interface DeleteEmbeddingsParams {
+    ids?: string[];
+    where?: Record<string, unknown>;
+    whereDocument?: Record<string, unknown>;
+}
+/** Options for `createCollection()`/`getOrCreateCollection()`. */
+export interface CollectionOptions {
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * `ChromaStore` wraps a `chromadb` `ChromaClient` and exposes Chroma's
+ * collection management plus the embedding data-plane operations
+ * (add/query/get/delete) as a typed, promise-based API.
+ */
+export declare class ChromaStore implements NoSqlStore {
+    readonly name = "chroma";
+    readonly library = "chromadb";
+    private readonly options;
+    private client;
+    private connected;
+    /** One `Collection` handle per collection name, reused across calls. */
+    private readonly collectionCache;
+    constructor(options?: ChromaStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `ChromaClient` for anything not wrapped here. */
+    getClient(): ChromaClientLike;
+    private requireClient;
+    private exec;
+    /** Resolve (and cache) a `Collection` handle for `name` via `getOrCreateCollection`. */
+    private resolveCollection;
+    /** Create a new collection. Fails if a collection with `name` already exists. */
+    createCollection(name: string, options?: CollectionOptions): Promise<ChromaCollectionLike>;
+    /** Get an existing collection, creating it if it doesn't exist. Idempotent. */
+    getOrCreateCollection(name: string, options?: CollectionOptions): Promise<ChromaCollectionLike>;
+    /** Delete a collection and all of its embeddings. */
+    deleteCollection(name: string): Promise<unknown>;
+    /**
+     * Add embeddings to a collection. `ids`/`embeddings` (and optional
+     * `metadatas`/`documents`) are index-aligned parallel arrays - the i-th
+     * id/embedding/metadata/document all describe the same record.
+     */
+    addEmbeddings(collection: string, params: AddEmbeddingsParams): Promise<unknown>;
+    /**
+     * Find, for each query embedding, the `nResults` closest records in a
+     * collection (optionally narrowed by a metadata `where` filter). Returns
+     * the driver's raw response (`{ ids, distances, metadatas, documents, ... }`,
+     * each an array-per-query-embedding).
+     */
+    query(collection: string, params: QueryEmbeddingsParams): Promise<unknown>;
+    /** Fetch records by id (and/or a metadata `where` filter) from a collection. */
+    get(collection: string, params: GetEmbeddingsParams): Promise<unknown>;
+    /** Delete records from a collection by id (and/or a metadata `where` filter). */
+    deleteEmbeddings(collection: string, params: DeleteEmbeddingsParams): Promise<unknown>;
+}
+export default ChromaStore;

package/dist/nosql/cloudflare-kv/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Cloudflare Workers KV store implementation.
+ *
+ * Cloudflare Workers KV is a globally-distributed, eventually-consistent
+ * key-value store exposed over Cloudflare's REST API. It has no query
+ * language and does not fit the SQL-shaped `Dialect` interface, so this
+ * class implements the minimal `NoSqlStore` marker interface and exposes a
+ * small edge-KV surface (`get`/`set`/`del`/`list`/`incr`) mapped onto the
+ * REST endpoints.
+ *
+ * ## No canonical driver - HTTP over `fetch`
+ *
+ * Workers KV has no first-party Node client; it is just an HTTP/JSON API.
+ * This store talks to it with the global `fetch` (so `library` is
+ * `'fetch'`). For tests (and callers who want their own transport) an
+ * alternative HTTP client can be injected via `client`; when omitted a tiny
+ * internal `fetch`-based client is built at `connect()` time using the
+ * account/namespace/token options.
+ *
+ * ## Endpoints wrapped
+ *
+ * All under `/accounts/<accountId>/storage/kv/namespaces/<namespaceId>`:
+ * - `get(key)`    -> `GET    .../values/<key>`   (404 => `null`)
+ * - `set(k,v)`    -> `PUT    .../values/<key>`   (body + optional expiration)
+ * - `del(key)`    -> `DELETE .../values/<key>`
+ * - `list(pref?)` -> `GET    .../keys?prefix=`   (returns the key names)
+ * - `incr(k,by?)` -> read-modify-write over `get`/`set` (KV has no atomic
+ *   increment; documented as non-atomic).
+ *
+ * ## Serialization
+ *
+ * String values are stored verbatim; every other value is `JSON.stringify`'d
+ * before being written.
+ */
+import { NoSqlStore } from '../store';
+/** Default Cloudflare API base URL. */
+export declare const DEFAULT_CLOUDFLARE_API_BASE_URL = "https://api.cloudflare.com/client/v4";
+/** A minimal `fetch`-`Response`-like shape used by the HTTP client. */
+export interface FetchLikeResponse {
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+    json(): Promise<any>;
+}
+/** Request init recognized by the HTTP client. */
+export interface HttpRequestInit {
+    body?: string;
+    /** Query-string params; `undefined` values are dropped. */
+    query?: Record<string, string | undefined>;
+}
+/**
+ * The subset of an HTTP client this store needs. The internal `fetch`-based
+ * client implements this; tests inject a mock of the same shape that records
+ * every request.
+ */
+export interface CloudflareKvHttpClient {
+    request(method: string, path: string, init?: HttpRequestInit): Promise<FetchLikeResponse>;
+}
+/** Options for `set()`. */
+export interface CloudflareKvSetOptions {
+    /** Expire after this many seconds (Cloudflare `expiration_ttl`). */
+    ttl?: number;
+    /** Absolute expiration as a Unix timestamp in seconds (Cloudflare `expiration`). */
+    expiration?: number;
+}
+/** Connection options for `CloudflareKvStore`. */
+export interface CloudflareKvStoreOptions {
+    /** Cloudflare account ID (required unless a `client` is injected). */
+    accountId?: string;
+    /** KV namespace ID (required unless a `client` is injected). */
+    namespaceId?: string;
+    /** Cloudflare API token used as a `Bearer` credential. */
+    apiToken?: string;
+    /** API base URL. Defaults to `https://api.cloudflare.com/client/v4`. */
+    baseURL?: string;
+    /** Pre-built HTTP client; when given `connect()` uses it verbatim. */
+    client?: CloudflareKvHttpClient;
+}
+/** Build a `fetch`-backed HTTP client for the Cloudflare KV REST API. */
+export declare function createFetchClient(baseURL: string, apiToken?: string): CloudflareKvHttpClient;
+/**
+ * `CloudflareKvStore` wraps the Cloudflare Workers KV REST API behind the
+ * `NoSqlStore` lifecycle and an edge-KV `get`/`set`/`del`/`list`/`incr`
+ * surface.
+ */
+export declare class CloudflareKvStore implements NoSqlStore {
+    readonly name = "cloudflare-kv";
+    readonly library = "fetch";
+    private readonly options;
+    private readonly baseURL;
+    private client;
+    private connected;
+    constructor(options?: CloudflareKvStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying (internal or injected) HTTP client. */
+    getClient(): CloudflareKvHttpClient;
+    private requireClient;
+    private namespacePath;
+    private valuePath;
+    /** Read a key. Returns `null` on a 404 (missing key). */
+    get(key: string): Promise<string | null>;
+    /**
+     * Write `value` under `key`. Strings are stored verbatim; other values are
+     * JSON-serialized. `options.ttl` maps to `expiration_ttl` (seconds),
+     * `options.expiration` to `expiration` (absolute Unix seconds).
+     */
+    set(key: string, value: unknown, options?: CloudflareKvSetOptions): Promise<void>;
+    /** Delete a key. */
+    del(key: string): Promise<void>;
+    /** List key names, optionally filtered by `prefix`. */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Increment the numeric value at `key` by `by` (default `1`). Workers KV
+     * has no atomic increment, so this is a non-atomic read-modify-write.
+     */
+    incr(key: string, by?: number): Promise<number>;
+}
+export default CloudflareKvStore;

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

@@ -0,0 +1,91 @@
+/**
+ * Oracle Coherence store implementation.
+ *
+ * Oracle Coherence is a distributed in-memory data grid. Data lives in named
+ * caches (its distributed maps). There is no SQL-shaped `query(sql)` surface
+ * for key/value access, so this class implements the minimal `NoSqlStore`
+ * marker interface and exposes Coherence's cache operations
+ * (getMap/put/get/remove/keys/size) as a typed, promise-based API.
+ *
+ * ## Transport: the Coherence REST API over `fetch`
+ *
+ * Coherence exposes a language-neutral REST API rather than a canonical
+ * Node.js driver, so this store talks to it with the global `fetch` (exactly
+ * like `PrometheusStore`) and `library` is `'fetch'`. For tests (and callers
+ * who want their own transport) an alternative client can be injected via
+ * `CoherenceStoreOptions.client`; when omitted a tiny internal `fetch`
+ * client is built at connect time.
+ *
+ * Endpoints wrapped (cache name is the first path segment):
+ * - `mapPut`    -> `PUT    /<cache>/<key>`
+ * - `mapGet`    -> `GET    /<cache>/<key>`
+ * - `mapRemove` -> `DELETE /<cache>/<key>`
+ * - `mapKeys`   -> `GET    /<cache>/keys`
+ * - `mapSize`   -> `GET    /<cache>/count`
+ */
+import { NoSqlStore } from '../store';
+/** Default Coherence REST base URL. */
+export declare const DEFAULT_COHERENCE_BASE_URL = "http://localhost:8080";
+/**
+ * The subset of an HTTP client this store needs. The internal `fetch`-based
+ * client implements this; tests inject a mock with the same shape.
+ */
+export interface CoherenceHttpClient {
+    /** GET `path`; return the parsed body, or `null` on 404. */
+    get(path: string): Promise<any>;
+    /** PUT `body` to `path`. */
+    put(path: string, body: string, contentType?: string): Promise<any>;
+    /** DELETE `path`. */
+    delete(path: string): Promise<any>;
+}
+/** A resolved cache handle. `getMap(name)` returns one; the `map*` methods consume it. */
+export interface CoherenceCache {
+    readonly name: string;
+}
+/** Connection options for `CoherenceStore`. */
+export interface CoherenceStoreOptions {
+    /** Base URL of the Coherence REST server. Defaults to `http://localhost:8080`. */
+    baseURL?: string;
+    /** Pre-built HTTP client; when given it is used verbatim and `baseURL` is ignored. */
+    client?: CoherenceHttpClient;
+    /** Extra HTTP headers sent with every internal-client request. */
+    headers?: Record<string, string>;
+}
+/** Build a `fetch`-backed REST client for the given base URL. */
+export declare function createFetchClient(baseURL: string, headers?: Record<string, string>): CoherenceHttpClient;
+/**
+ * `CoherenceStore` wraps Coherence's REST API behind the `NoSqlStore`
+ * lifecycle and exposes named-cache key/value operations.
+ */
+export declare class CoherenceStore implements NoSqlStore {
+    readonly name = "coherence";
+    readonly library = "fetch";
+    private readonly baseURL;
+    private readonly injectedClient?;
+    private readonly headers?;
+    private client;
+    private connected;
+    /** Cached cache handles, keyed by name so `getMap` is idempotent. */
+    private readonly caches;
+    constructor(options?: CoherenceStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying (internal or injected) HTTP client. */
+    getClient(): CoherenceHttpClient;
+    private requireClient;
+    private wrap;
+    /** Resolve (and cache) a named-cache handle. */
+    getMap(name: string): Promise<CoherenceCache>;
+    /** Store `value` under `key` in `map` (`PUT /<cache>/<key>`). */
+    mapPut(map: CoherenceCache, key: string, value: unknown): Promise<void>;
+    /** Read `key` from `map` (`GET /<cache>/<key>`); `null` if absent. */
+    mapGet(map: CoherenceCache, key: string): Promise<any>;
+    /** Remove `key` from `map` (`DELETE /<cache>/<key>`). */
+    mapRemove(map: CoherenceCache, key: string): Promise<any>;
+    /** List all keys in `map` (`GET /<cache>/keys`). */
+    mapKeys(map: CoherenceCache): Promise<any[]>;
+    /** Number of entries in `map` (`GET /<cache>/count`). */
+    mapSize(map: CoherenceCache): Promise<number>;
+}
+export default CoherenceStore;