ts-prorm-orm 1.1.0 → 1.2.0

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

@@ -0,0 +1,314 @@
+/**
+ * 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).
+ */
+/**
+ * Connection options for `TigerGraphStore`.
+ *
+ * TigerGraph traditionally splits traffic across two ports: the REST++
+ * data-plane API (vertex/edge CRUD, installed queries - historically port
+ * 9000) and the GSQL server (schema/DDL, ad-hoc "interpreted" queries -
+ * historically port 14240). TigerGraph 4.1+ unifies external traffic
+ * behind port 14240 with `/restpp/...` and `/gsql/...` path prefixes and
+ * makes 9000 internal-only; this store defaults to the classic two-port
+ * layout (confirmed against documented pre-4.1 REST++ endpoint shapes -
+ * see README) but every port/prefix is configurable so it can be pointed
+ * at a 4.1+ unified deployment too.
+ */
+export interface TigerGraphStoreOptions {
+    /** Protocol + hostname, e.g. `'http://localhost'` or `'https://my-cluster.i.tgcloud.io'`. No trailing slash, no port. */
+    host: string;
+    /** REST++ port (vertex/edge/query endpoints). Default `9000`. */
+    restPort?: number;
+    /** GSQL server port (interpreted queries, schema introspection). Default `14240`. */
+    gsqlPort?: number;
+    /** Path prefix in front of REST++ routes, e.g. `'/restpp'` on a 4.1+ unified deployment. Default `''`. */
+    restPathPrefix?: string;
+    /** Default graph name used when a call doesn't override it. */
+    graph: string;
+    /**
+     * GSQL secret used to mint a token via `POST /requesttoken`
+     * (see README - confirmed pre-4.1 shape). Provide this, or a pre-minted
+     * `token`, to authenticate REST++ (vertex/edge/query) calls.
+     */
+    secret?: string;
+    /** A pre-minted REST++ auth token. Skips the `/requesttoken` round trip in `connect()`. */
+    token?: string;
+    /** Requested token lifetime in seconds, passed to `/requesttoken`. */
+    tokenLifetime?: number;
+    /**
+     * Username/password used for HTTP Basic auth against GSQL-server
+     * endpoints (interpreted queries, schema introspection). TigerGraph's
+     * documented example for the interpreted-query endpoint uses Basic
+     * auth rather than the REST++ bearer token; the same credentials are
+     * reused here for schema introspection since both are GSQL-server
+     * routes.
+     */
+    username?: string;
+    password?: string;
+    /** Injectable fetch implementation, primarily for tests. Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * TigerGraph's documented upsert wire format wraps every attribute value
+ * as `{"value": <actual value>}`, with an optional `op` accumulator code
+ * (e.g. `'+'`/`'max'`) for attributes backed by an accumulator. Confirmed
+ * against TigerGraph's REST++ upsert documentation (see README).
+ */
+export interface AttributeValue<T = unknown> {
+    value: T;
+    op?: string;
+}
+/** Plain (unwrapped) attribute values, as accepted by the convenience `upsertVertex`/`upsertEdge` helpers. */
+export type PlainAttributes = Record<string, unknown>;
+/** Already-wrapped attributes, as sent on the wire and returned by read endpoints. */
+export type WireAttributes = Record<string, AttributeValue>;
+/** Raw upsert payload matching TigerGraph's `POST /graph/{graph}` body shape exactly. */
+export interface UpsertPayload {
+    vertices?: Record<string, Record<string, WireAttributes>>;
+    edges?: Record<string, Record<string, Record<string, Record<string, Record<string, WireAttributes>>>>>;
+}
+/** A single edge to upsert via `upsertEdges()`. */
+export interface EdgeUpsert {
+    fromType: string;
+    fromId: string;
+    edgeType: string;
+    toType: string;
+    toId: string;
+    attributes?: PlainAttributes;
+}
+/** A vertex as returned by `GET /graph/{graph}/vertices/{type}/{id}` (confirmed shape). */
+export interface TigerGraphVertex<T = Record<string, unknown>> {
+    v_id: string;
+    v_type: string;
+    attributes: T;
+}
+/** An edge as returned by `GET /graph/{graph}/edges/...` (confirmed shape). */
+export interface TigerGraphEdge<T = Record<string, unknown>> {
+    e_type: string;
+    directed: boolean;
+    from_id: string;
+    from_type: string;
+    to_id: string;
+    to_type: string;
+    attributes: T;
+}
+/** One vertex type as returned by GSQL schema introspection. */
+export interface VertexTypeSchema {
+    Name: string;
+    PrimaryId?: Record<string, unknown>;
+    Attributes?: {
+        AttributeName: string;
+        AttributeType?: Record<string, unknown>;
+    }[];
+}
+/** One edge type as returned by GSQL schema introspection. */
+export interface EdgeTypeSchema {
+    Name: string;
+    FromVertexTypeName?: string;
+    ToVertexTypeName?: string;
+    IsDirected?: boolean;
+    Attributes?: {
+        AttributeName: string;
+        AttributeType?: Record<string, unknown>;
+    }[];
+}
+/** Options for `runInstalledQuery()`. */
+export interface RunQueryOptions {
+    graph?: string;
+    /** `GET` (query-string params) or `POST` (JSON body). Default `'GET'`. */
+    method?: 'GET' | 'POST';
+}
+/** Options for `runInterpretedQuery()`. */
+export interface InterpretedQueryOptions {
+    graph?: string;
+    /** GSQL query parameters, sent as URL query-string parameters per TigerGraph's documented example. */
+    params?: Record<string, string | number | boolean>;
+}
+/** Options for `listVerticesByType()`. */
+export interface ListVerticesOptions {
+    graph?: string;
+    limit?: number;
+}
+/**
+ * TigerGraph's standard REST++/GSQL response envelope. Confirmed
+ * consistent shape across the endpoints this store wraps: `error`/
+ * `message` (and `code` on failures) alongside the payload in `results`.
+ */
+interface TigerGraphEnvelope<T = unknown> {
+    version?: unknown;
+    error: boolean;
+    message?: string;
+    code?: string;
+    token?: string;
+    results?: T;
+}
+/**
+ * `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.
+ */
+export declare class TigerGraphStore {
+    readonly name = "tigergraph";
+    readonly library = "fetch";
+    private readonly options;
+    private readonly restBaseUrl;
+    private readonly gsqlBaseUrl;
+    private readonly restPathPrefix;
+    private token;
+    private connected;
+    constructor(options: TigerGraphStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /**
+     * 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(): {
+        token: string | null;
+        restBaseUrl: string;
+        gsqlBaseUrl: string;
+        restRequest: (path: string, init?: RequestInit) => Promise<TigerGraphEnvelope>;
+        gsqlRequest: (path: string, init?: RequestInit) => Promise<TigerGraphEnvelope>;
+    };
+    private requireConnected;
+    private getFetch;
+    /**
+     * `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").
+     */
+    private requestToken;
+    private parseEnvelope;
+    private authHeaders;
+    private basicAuthHeaders;
+    /** Issue a request against the REST++ API (vertex/edge/query endpoints), with bearer-token auth. */
+    private restRequest;
+    /** Issue a request against the GSQL server (interpreted queries, schema), with Basic auth. */
+    private gsqlRequest;
+    /**
+     * 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}`).
+     */
+    runInstalledQuery<T = unknown>(queryName: string, params?: Record<string, string | number | boolean>, options?: RunQueryOptions): Promise<T>;
+    /**
+     * `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.
+     */
+    upsert(payload: UpsertPayload, graph?: string): Promise<{
+        accepted_vertices: number;
+        accepted_edges: number;
+    }>;
+    /** Upsert a single vertex with plain (unwrapped) attribute values. */
+    upsertVertex(vertexType: string, id: string, attributes?: PlainAttributes, graph?: string): Promise<{
+        accepted_vertices: number;
+        accepted_edges: number;
+    }>;
+    /** Upsert multiple vertices of the same type in one round trip. */
+    upsertVertices(vertexType: string, vertices: Record<string, PlainAttributes>, graph?: string): Promise<{
+        accepted_vertices: number;
+        accepted_edges: number;
+    }>;
+    /** Upsert a single edge with plain (unwrapped) attribute values. */
+    upsertEdge(fromType: string, fromId: string, edgeType: string, toType: string, toId: string, attributes?: PlainAttributes, graph?: string): Promise<{
+        accepted_vertices: number;
+        accepted_edges: number;
+    }>;
+    /** Upsert multiple edges (possibly spanning different types/vertices) in one round trip. */
+    upsertEdges(edges: EdgeUpsert[], graph?: string): Promise<{
+        accepted_vertices: number;
+        accepted_edges: number;
+    }>;
+    /**
+     * `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).
+     */
+    getVertex<T = Record<string, unknown>>(vertexType: string, id: string, graph?: string): Promise<TigerGraphVertex<T> | null>;
+    /**
+     * `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).
+     */
+    listVerticesByType<T = Record<string, unknown>>(vertexType: string, options?: ListVerticesOptions): Promise<TigerGraphVertex<T>[]>;
+    /** `DELETE /graph/{graph}/vertices/{type}/{id}` - delete a single vertex (and its incident edges). Returns the number of vertices deleted (`0` or `1`). */
+    deleteVertex(vertexType: string, id: string, graph?: string): Promise<number>;
+    /**
+     * `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.
+     */
+    getEdge<T = Record<string, unknown>>(fromType: string, fromId: string, edgeType: string, toType: string, toId: string, graph?: string): Promise<TigerGraphEdge<T>[]>;
+    /**
+     * `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.
+     */
+    listEdgesFrom<T = Record<string, unknown>>(fromType: string, fromId: string, edgeType?: string, graph?: string): Promise<TigerGraphEdge<T>[]>;
+    /** `DELETE /graph/{graph}/edges/{fromType}/{fromId}/{edgeType}/{toType}/{toId}` - delete a single edge. Returns the number of edges deleted. */
+    deleteEdge(fromType: string, fromId: string, edgeType: string, toType: string, toId: string, graph?: string): Promise<number>;
+    /**
+     * `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.
+     */
+    runInterpretedQuery<T = unknown>(gsql: string, options?: InterpretedQueryOptions): Promise<T>;
+    /** `GET /gsql/v1/schema/vertices?graph={graph}` - list the graph's vertex types. Confirmed endpoint/response shape. */
+    listVertexTypes(graph?: string): Promise<VertexTypeSchema[]>;
+    /** `GET /gsql/v1/schema/edges?graph={graph}` - list the graph's edge types. Confirmed endpoint/response shape. */
+    listEdgeTypes(graph?: string): Promise<EdgeTypeSchema[]>;
+}
+export default TigerGraphStore;

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

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ */
+import { NoSqlStore } from '../store';
+/** A single Typesense node's connection details. */
+export interface TypesenseNode {
+    host: string;
+    port: number;
+    protocol: string;
+    [key: string]: unknown;
+}
+/**
+ * Connection options for `TypesenseStore`.
+ *
+ * `nodes` and `apiKey` are passed straight through to the driver's
+ * `new Typesense.Client(...)`. Pass `client` to inject an already-built client
+ * instance (used in tests and when the caller wants full control over driver
+ * configuration); when present, `nodes`/`apiKey` are ignored.
+ */
+export interface TypesenseStoreOptions {
+    /** One or more Typesense nodes to connect to. */
+    nodes?: TypesenseNode[];
+    /** API key used to authenticate against the server. */
+    apiKey?: string;
+    /** An already-constructed Typesense client to use instead of building one. */
+    client?: any;
+    /** Any additional options passed through to the driver's client. */
+    [key: string]: unknown;
+}
+/**
+ * `TypesenseStore` wraps the official `typesense` client and exposes
+ * collection management, document CRUD, and search as a typed, promise-based
+ * API.
+ */
+export declare class TypesenseStore implements NoSqlStore {
+    readonly name = "typesense";
+    readonly library = "typesense";
+    private readonly options;
+    private client;
+    private connected;
+    constructor(options: TypesenseStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `typesense` client for anything not wrapped here. */
+    getClient(): any;
+    private requireClient;
+    private exec;
+    /** Create a collection from a schema (`{ name, fields, default_sorting_field? }`). */
+    createCollection(schema: Record<string, unknown>): Promise<any>;
+    /** Delete a collection by name. */
+    deleteCollection(name: string): Promise<any>;
+    /** Index (create) a single document in a collection. */
+    indexDocument(collection: string, document: Record<string, unknown>): Promise<any>;
+    /** Run a search against a collection's documents. */
+    search<T = Record<string, unknown>>(collection: string, params: Record<string, unknown>): Promise<T>;
+    /** Retrieve a single document by its `id`. */
+    getDocument<T = Record<string, unknown>>(collection: string, id: string): Promise<T>;
+    /** Delete a single document by its `id`. */
+    deleteDocument(collection: string, id: string): Promise<any>;
+}
+export default TypesenseStore;

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

@@ -0,0 +1,68 @@
+import type { NoSqlStore } from '../store';
+/** A single entry in a `batch()` write: a `put` (with value) or a `del`. */
+export type UnqliteBatchOp = {
+    type: 'put';
+    key: string;
+    value: unknown;
+} | {
+    type: 'del';
+    key: string;
+};
+type NodeCallback<T> = (err: unknown, result?: T) => void;
+/**
+ * Minimal structural type for the pieces of an `unqlite` client this store
+ * uses. Kept local (rather than importing from `unqlite`) so this module
+ * type-checks without the optional driver installed.
+ */
+export interface UnqliteClientLike {
+    store(key: string, value: unknown, cb: NodeCallback<void>): void;
+    fetch(key: string, cb: NodeCallback<unknown>): void;
+    delete(key: string, cb: NodeCallback<void>): void;
+    each(iterator: (key: unknown, value: unknown) => void, done: NodeCallback<void>): void;
+    close?(cb: NodeCallback<void>): void;
+}
+/** Connection options for `UnqliteStore`. */
+export interface UnqliteStoreOptions {
+    /** Filesystem path for the UnQLite database file. Defaults to `'./data/unqlite.db'`. */
+    path?: string;
+    /**
+     * A pre-built `unqlite` client (or a compatible mock). When provided,
+     * `connect()` uses it directly and skips `require('unqlite')` entirely —
+     * this is how tests inject a mock without the real driver installed.
+     */
+    client?: UnqliteClientLike;
+}
+/**
+ * `UnqliteStore` wraps an `unqlite` client and exposes its embedded KV
+ * surface: `put`/`get`/`del` (mapped to `store`/`fetch`/`delete`), `batch` for
+ * multi-key writes, and `list` for key iteration.
+ */
+export declare class UnqliteStore implements NoSqlStore {
+    readonly name = "unqlite";
+    readonly library = "unqlite";
+    private readonly options;
+    private readonly path;
+    private client;
+    private connected;
+    constructor(options?: UnqliteStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `unqlite` client for anything not wrapped here. */
+    getClient(): UnqliteClientLike;
+    private requireClient;
+    private wrapError;
+    /** Wrap a callback-style UnQLite call into a Promise. */
+    private promisify;
+    /** Writes (or overwrites) the value at `key` (UnQLite `store`). */
+    put(key: string, value: unknown): Promise<void>;
+    /** Reads the value at `key` (UnQLite `fetch`). */
+    get(key: string): Promise<unknown>;
+    /** Deletes the value at `key` (UnQLite `delete`). */
+    del(key: string): Promise<void>;
+    /** Applies a list of `put`/`del` operations sequentially. */
+    batch(ops: UnqliteBatchOp[]): Promise<void>;
+    /** Lists all keys by iterating records with UnQLite's `each` cursor. */
+    list(): Promise<string[]>;
+}
+export default UnqliteStore;

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

@@ -0,0 +1,80 @@
+/**
+ * Upstash Redis store implementation.
+ *
+ * Upstash Redis is a serverless, globally-replicated Redis served over an
+ * HTTP/REST connection via the `@upstash/redis` client. It has no SQL query
+ * surface, so this class implements the minimal `NoSqlStore` marker
+ * interface and exposes an edge-KV `get`/`set`/`del`/`list`/`incr` surface
+ * mapped onto the `@upstash/redis` client.
+ *
+ * ## Driver
+ *
+ * Uses `@upstash/redis` (`new Redis({ url, token })`). The driver is loaded
+ * lazily inside `connect()` (or supplied pre-built via the `client` option)
+ * so importing this module never requires `@upstash/redis` to be installed
+ * unless a store is actually connected. Tests inject a mock `client`.
+ *
+ * ## Serialization
+ *
+ * String values are passed through verbatim; every other value is
+ * `JSON.stringify`'d before being written.
+ */
+import { NoSqlStore } from '../store';
+/** Options for `set()`. */
+export interface UpstashSetOptions {
+    /** Expire after this many seconds (Redis `EX`). */
+    ttl?: number;
+    /** Absolute expiration as a Unix timestamp in seconds (Redis `EXAT`). */
+    expiration?: number;
+}
+/** The subset of the `@upstash/redis` client surface this store drives. */
+export interface UpstashRedisClient {
+    get(key: string): Promise<any>;
+    set(key: string, value: unknown, options?: Record<string, unknown>): Promise<any>;
+    del(...keys: string[]): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    incr(key: string): Promise<number>;
+    incrby(key: string, amount: number): Promise<number>;
+}
+/** Connection options for `UpstashStore`. */
+export interface UpstashStoreOptions {
+    /** REST URL of the Upstash Redis database. */
+    url?: string;
+    /** REST API token. */
+    token?: string;
+    /** Pre-built `@upstash/redis` client; when given `connect()` uses it and skips `require('@upstash/redis')`. */
+    client?: UpstashRedisClient;
+}
+/**
+ * `UpstashStore` wraps an `@upstash/redis` client behind the `NoSqlStore`
+ * lifecycle and an edge-KV `get`/`set`/`del`/`list`/`incr` surface.
+ */
+export declare class UpstashStore implements NoSqlStore {
+    readonly name = "upstash";
+    readonly library = "@upstash/redis";
+    private readonly options;
+    private client;
+    private connected;
+    constructor(options?: UpstashStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `@upstash/redis` client for anything not wrapped here. */
+    getClient(): UpstashRedisClient;
+    private requireClient;
+    /** Read a key. Returns whatever the client returns (`null` if missing). */
+    get(key: string): Promise<any>;
+    /**
+     * Write `value` under `key`. Strings are stored verbatim; other values are
+     * JSON-serialized. `options.ttl` maps to Redis `EX` (seconds),
+     * `options.expiration` to `EXAT` (absolute Unix seconds).
+     */
+    set(key: string, value: unknown, options?: UpstashSetOptions): Promise<any>;
+    /** Delete a key. Returns the number of keys removed. */
+    del(key: string): Promise<number>;
+    /** List key names, optionally filtered by `prefix` (matched as `<prefix>*`). */
+    list(prefix?: string): Promise<string[]>;
+    /** Atomically increment the numeric value at `key` by `by` (default `1`). */
+    incr(key: string, by?: number): Promise<number>;
+}
+export default UpstashStore;

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

@@ -0,0 +1,82 @@
+/**
+ * Vercel KV store implementation.
+ *
+ * Vercel KV is a serverless, globally-replicated Redis-compatible key-value
+ * store fronted by the `@vercel/kv` client (a durable-HTTP Redis client). It
+ * has no SQL query surface, so this class implements the minimal
+ * `NoSqlStore` marker interface and exposes an edge-KV
+ * `get`/`set`/`del`/`list`/`incr` surface mapped onto the `@vercel/kv`
+ * client.
+ *
+ * ## Driver
+ *
+ * Uses `@vercel/kv` (`createClient({ url, token })`). The driver is loaded
+ * lazily inside `connect()` (or supplied pre-built via the `client` option)
+ * so importing this module never requires `@vercel/kv` to be installed
+ * unless a store is actually connected. Tests inject a mock `client`.
+ *
+ * ## Serialization
+ *
+ * String values are passed through verbatim; every other value is
+ * `JSON.stringify`'d before being written, so reads via `get()` return the
+ * serialized string.
+ */
+import { NoSqlStore } from '../store';
+/** Options for `set()`. */
+export interface VercelKvSetOptions {
+    /** Expire after this many seconds (Redis `EX`). */
+    ttl?: number;
+    /** Absolute expiration as a Unix timestamp in seconds (Redis `EXAT`). */
+    expiration?: number;
+}
+/** The subset of the `@vercel/kv` client surface this store drives. */
+export interface VercelKvClient {
+    get(key: string): Promise<any>;
+    set(key: string, value: unknown, options?: Record<string, unknown>): Promise<any>;
+    del(...keys: string[]): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    incr(key: string): Promise<number>;
+    incrby(key: string, amount: number): Promise<number>;
+}
+/** Connection options for `VercelKvStore`. */
+export interface VercelKvStoreOptions {
+    /** REST URL of the KV database (`KV_REST_API_URL`). */
+    url?: string;
+    /** REST API token (`KV_REST_API_TOKEN`). */
+    token?: string;
+    /** Pre-built `@vercel/kv` client; when given `connect()` uses it and skips `require('@vercel/kv')`. */
+    client?: VercelKvClient;
+}
+/**
+ * `VercelKvStore` wraps a `@vercel/kv` client behind the `NoSqlStore`
+ * lifecycle and an edge-KV `get`/`set`/`del`/`list`/`incr` surface.
+ */
+export declare class VercelKvStore implements NoSqlStore {
+    readonly name = "vercel-kv";
+    readonly library = "@vercel/kv";
+    private readonly options;
+    private client;
+    private connected;
+    constructor(options?: VercelKvStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `@vercel/kv` client for anything not wrapped here. */
+    getClient(): VercelKvClient;
+    private requireClient;
+    /** Read a key. Returns whatever the client returns (`null` if missing). */
+    get(key: string): Promise<any>;
+    /**
+     * Write `value` under `key`. Strings are stored verbatim; other values are
+     * JSON-serialized. `options.ttl` maps to Redis `EX` (seconds),
+     * `options.expiration` to `EXAT` (absolute Unix seconds).
+     */
+    set(key: string, value: unknown, options?: VercelKvSetOptions): Promise<any>;
+    /** Delete a key. Returns the number of keys removed. */
+    del(key: string): Promise<number>;
+    /** List key names, optionally filtered by `prefix` (matched as `<prefix>*`). */
+    list(prefix?: string): Promise<string[]>;
+    /** Atomically increment the numeric value at `key` by `by` (default `1`). */
+    incr(key: string, by?: number): Promise<number>;
+}
+export default VercelKvStore;