ts-prorm-orm 1.1.0 → 1.2.0

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

@@ -0,0 +1,231 @@
+/**
+ * Qdrant store implementation.
+ *
+ * Qdrant is a vector-similarity search engine: collections hold points
+ * (an ID, one or more dense/sparse vectors, and an arbitrary JSON payload),
+ * and the primary query shape is "find the points whose vector is closest
+ * to this query vector" (optionally constrained by a payload filter) -
+ * not SQL, not `WHERE`, not joins. It does not fit the SQL-shaped `Dialect`
+ * interface used by the SQL dialects in this repo, so this class implements
+ * the minimal `NoSqlStore` marker interface and exposes Qdrant's real
+ * collection/point/payload/alias operations instead of forcing them into a
+ * `query(sql)` shape.
+ *
+ * Uses the official `@qdrant/js-client-rest` driver, which talks to Qdrant's
+ * HTTP REST API (there is also a gRPC client, `@qdrant/js-client-grpc`, not
+ * used here). The REST client is stateless (plain HTTP requests, no
+ * persistent socket) - `connect()` verifies the server is reachable and the
+ * API key (if any) is accepted by calling `versionInfo()`, and
+ * `disconnect()` simply drops the client reference.
+ */
+import { QdrantClient, QdrantClientParams, Schemas } from '@qdrant/js-client-rest';
+import { NoSqlStore } from '../store';
+/** Connection options for `QdrantStore` - passed straight through to `QdrantClient`. */
+export type QdrantStoreOptions = QdrantClientParams;
+/** Size + distance metric (and optional tuning knobs) for one vector space. */
+export type VectorParams = Schemas['VectorParams'];
+/** Similarity metric used to compare vectors. */
+export type Distance = Schemas['Distance'];
+/** A single vector space config, or a map of named vector spaces. */
+export type VectorsConfig = Schemas['VectorsConfig'];
+/** A point to upsert: id, vector(s), and optional payload. */
+export type PointStruct = Schemas['PointStruct'];
+/** Payload filter (`must`/`should`/`must_not`/`min_should` of `Condition`s). */
+export type Filter = Schemas['Filter'];
+/** A single filter condition (field match/range, geo, has-id, nested filter, etc). */
+export type Condition = Schemas['Condition'];
+/** A point returned from `search()`/`query()`, with its similarity `score`. */
+export type ScoredPoint = Schemas['ScoredPoint'];
+/** A stored point as returned from `retrieve()`/`scroll()`. */
+export type PointRecord = Schemas['Record'];
+/** Detailed collection status/config, as returned by `getCollection()`. */
+export type CollectionInfo = Schemas['CollectionInfo'];
+/** `{ name }` entry as returned by `listCollections()`. */
+export type CollectionDescription = Schemas['CollectionDescription'];
+/** Result of a write operation (upsert/delete/payload change/etc). */
+export type UpdateResult = Schemas['UpdateResult'];
+/** Which payload fields (if any) to attach to returned points. */
+export type WithPayload = Schemas['WithPayloadInterface'];
+/** Which vector(s) (if any) to attach to returned points. */
+export type WithVectorOption = Schemas['WithVector'];
+/** A point ID - either a `number` or a UUID `string`. */
+export type PointId = Schemas['ExtendedPointId'];
+/** Selects points by explicit ID list or by filter, for delete/payload ops. */
+export type PointsSelector = Schemas['PointsSelector'];
+/** Arbitrary JSON payload stored alongside a point's vector(s). */
+export type Payload = Schemas['Payload'];
+/** Result of `count()`. */
+export type CountResult = Schemas['CountResult'];
+/** Result of `getCollectionAliases()`/`getAliases()`. */
+export type CollectionAliasesResponse = Schemas['CollectionsAliasesResponse'];
+/** `'weak' | 'medium' | 'strong'` write-ordering guarantee. */
+export type WriteOrdering = Schemas['WriteOrdering'];
+/** Read-consistency requirement for a query (replica count, or `'majority'`/`'quorum'`/`'all'`). */
+export type ReadConsistency = Schemas['ReadConsistency'];
+/** Payload field index type, for `createPayloadIndex()`. */
+export type PayloadFieldSchema = Schemas['PayloadFieldSchema'];
+/** `points`/`shard_key` shape for `PointStruct[]` batch inserts (see `upsertBatch()`). */
+export type Batch = Schemas['Batch'];
+/** Common args accepted by write operations (upsert/delete/payload mutation). */
+export interface WriteOptions {
+    /** Wait for the change to be applied before responding. Default: `true`. */
+    wait?: boolean;
+    /** Write-ordering guarantee. Default: `'weak'`. */
+    ordering?: WriteOrdering;
+    /** Per-request timeout override, in seconds. */
+    timeout?: number;
+}
+/** Args accepted by read operations (search/scroll/retrieve/count). */
+export interface ReadOptions {
+    /** Read-consistency requirement. */
+    consistency?: ReadConsistency;
+    /** Per-request timeout override, in seconds. */
+    timeout?: number;
+}
+/** Args for `createCollection()`/`recreateCollection()` beyond the vector config. */
+export type CreateCollectionOptions = Omit<Schemas['CreateCollection'], 'vectors'> & {
+    timeout?: number;
+};
+/** Args for `search()`. */
+export interface SearchOptions extends ReadOptions {
+    /** Restrict results to points matching this filter. */
+    filter?: Filter;
+    /** Max number of results to return. Default: `10`. */
+    limit?: number;
+    /** Skip this many results (for pagination). */
+    offset?: number;
+    /** Which payload fields to attach. Default: `false` (none). */
+    withPayload?: WithPayload;
+    /** Which vector(s) to attach. Default: `false`. */
+    withVector?: WithVectorOption;
+    /** Drop results scoring worse than this threshold. */
+    scoreThreshold?: number;
+    /** Named vector to search against, for multi-vector collections. */
+    vectorName?: string;
+}
+/** Args for `scroll()`. */
+export interface ScrollOptions extends ReadOptions {
+    /** Restrict results to points matching this filter. */
+    filter?: Filter;
+    /** Page size. Default: `10`. */
+    limit?: number;
+    /** Start ID to read from (the `nextPageOffset` of a prior page, for pagination). */
+    offset?: PointId;
+    /** Which payload fields to attach. Default: `true` (all). */
+    withPayload?: WithPayload;
+    /** Which vector(s) to attach. Default: `false`. */
+    withVector?: WithVectorOption;
+}
+/** Result of `scroll()`: a page of points plus the offset to fetch the next page. */
+export interface ScrollPage {
+    points: PointRecord[];
+    /** Pass to `scroll()`'s `offset` to fetch the next page; `null` when there is no more data. */
+    nextPageOffset: Schemas['ScrollResult']['next_page_offset'];
+}
+/** Args for `retrieve()`. */
+export interface RetrieveOptions extends ReadOptions {
+    /** Which payload fields to attach. Default: `true` (all). */
+    withPayload?: WithPayload;
+    /** Which vector(s) to attach. Default: `false`. */
+    withVector?: WithVectorOption;
+}
+/**
+ * `QdrantStore` wraps a `@qdrant/js-client-rest` `QdrantClient` and exposes
+ * Qdrant's collection management, point upsert/search/scroll/retrieve/delete,
+ * payload management, and collection-alias operations as a typed,
+ * promise-based API.
+ */
+export declare class QdrantStore implements NoSqlStore {
+    readonly name = "qdrant";
+    readonly library = "@qdrant/js-client-rest";
+    private readonly options;
+    private client;
+    private connected;
+    constructor(options?: QdrantStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `QdrantClient` for anything not wrapped here. */
+    getClient(): QdrantClient;
+    private requireClient;
+    private exec;
+    /**
+     * Create a new, empty collection. `vectors` is either a single
+     * `{ size, distance }` (unnamed/default vector space) or a map of named
+     * vector spaces (for collections with multiple vector fields per point).
+     */
+    createCollection(collectionName: string, vectors: VectorsConfig, options?: CreateCollectionOptions): Promise<boolean>;
+    /** Delete a collection and all of its data. */
+    deleteCollection(collectionName: string, options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    /** Detailed status, point counts, and configuration for a collection. */
+    getCollection(collectionName: string): Promise<CollectionInfo>;
+    /** List the names of all collections. */
+    listCollections(): Promise<CollectionDescription[]>;
+    /** Whether a collection with this name exists. */
+    collectionExists(collectionName: string): Promise<boolean>;
+    /** Update mutable collection parameters (optimizer config, HNSW params, etc). */
+    updateCollection(collectionName: string, args?: Schemas['UpdateCollection'] & {
+        timeout?: number;
+    }): Promise<boolean>;
+    /** Create an index on a payload field so filtered search on it is fast. */
+    createPayloadIndex(collectionName: string, fieldName: string, fieldSchema?: PayloadFieldSchema, options?: WriteOptions): Promise<UpdateResult>;
+    /** Remove an index previously created with `createPayloadIndex()`. */
+    deletePayloadIndex(collectionName: string, fieldName: string, options?: WriteOptions): Promise<UpdateResult>;
+    /** Insert or update one or more points (matched by ID). */
+    upsert(collectionName: string, points: PointStruct[], options?: WriteOptions): Promise<UpdateResult>;
+    /**
+     * Insert or update points given in Qdrant's columnar "batch" shape
+     * (`{ ids, vectors, payloads }`, index-aligned across the three arrays)
+     * rather than an array of `{ id, vector, payload }` objects. Equivalent
+     * to `upsert()`, just a more compact wire format for large batches.
+     */
+    upsertBatch(collectionName: string, batch: Batch, options?: WriteOptions): Promise<UpdateResult>;
+    /** Find the points whose vector is closest to `vector`, optionally constrained by a filter. */
+    search(collectionName: string, vector: number[], options?: SearchOptions): Promise<ScoredPoint[]>;
+    /** Run several `search()` requests against the same collection in a single round trip. */
+    searchBatch(collectionName: string, searches: Schemas['SearchRequest'][], options?: ReadOptions): Promise<ScoredPoint[][]>;
+    /**
+     * Page through all (optionally filtered) points in a collection without
+     * doing a similarity search. Pass the returned `nextPageOffset` back in
+     * as `options.offset` to fetch the next page; a `null` `nextPageOffset`
+     * means there's no more data.
+     */
+    scroll(collectionName: string, options?: ScrollOptions): Promise<ScrollPage>;
+    /** Fetch specific points by ID. IDs not found are simply omitted from the result. */
+    retrieve(collectionName: string, ids: PointId[], options?: RetrieveOptions): Promise<PointRecord[]>;
+    /** Count points in a collection, optionally matching a filter. */
+    count(collectionName: string, filter?: Filter, options?: ReadOptions & {
+        exact?: boolean;
+    }): Promise<number>;
+    /** Delete points by explicit ID list. */
+    deleteByIds(collectionName: string, ids: PointId[], options?: WriteOptions): Promise<UpdateResult>;
+    /** Delete every point matching a filter. */
+    deleteByFilter(collectionName: string, filter: Filter, options?: WriteOptions): Promise<UpdateResult>;
+    /**
+     * Merge `payload` into the existing payload of the selected points
+     * (existing keys not present in `payload` are left untouched).
+     */
+    setPayload(collectionName: string, payload: Payload, selector: PointsSelector, options?: WriteOptions): Promise<UpdateResult>;
+    /**
+     * Replace the entire payload of the selected points with `payload`
+     * (unlike `setPayload()`, keys not present in `payload` are removed).
+     */
+    overwritePayload(collectionName: string, payload: Payload, selector: PointsSelector, options?: WriteOptions): Promise<UpdateResult>;
+    /** Remove specific payload keys from the selected points. */
+    deletePayload(collectionName: string, keys: string[], selector: PointsSelector, options?: WriteOptions): Promise<UpdateResult>;
+    /** Remove the entire payload (all keys) from the selected points. */
+    clearPayload(collectionName: string, selector: PointsSelector, options?: WriteOptions): Promise<UpdateResult>;
+    /** Create an alternative name (`aliasName`) for a collection; the collection is queryable under both names. */
+    createAlias(collectionName: string, aliasName: string, timeout?: number): Promise<boolean>;
+    /** Delete an alias (the underlying collection and its other aliases are unaffected). */
+    deleteAlias(aliasName: string, timeout?: number): Promise<boolean>;
+    /** Atomically rename an alias (equivalent to delete + create in one operation). */
+    renameAlias(oldAliasName: string, newAliasName: string, timeout?: number): Promise<boolean>;
+    /** List the aliases pointing at a specific collection. */
+    getCollectionAliases(collectionName: string): Promise<CollectionAliasesResponse>;
+    /** List every alias across all collections. */
+    getAliases(): Promise<CollectionAliasesResponse>;
+}
+export default QdrantStore;

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

@@ -0,0 +1,182 @@
+/**
+ * Amazon QLDB store implementation.
+ *
+ * Amazon QLDB (Quantum Ledger Database) is a fully managed, append-only,
+ * cryptographically verifiable ledger database. Data is written as documents
+ * into ledger tables and queried with PartiQL (a SQL-compatible query
+ * language). Every revision of every document is retained in an immutable
+ * journal; the built-in `history(<table>)` PartiQL function exposes prior
+ * revisions, and each revision carries `metadata` (document id, version,
+ * transaction time, and a content hash) that forms the basis of QLDB's
+ * tamper-evidence.
+ *
+ * QLDB is not a SQL `Dialect` (no client-side DDL escaping, no row-level
+ * UPDATE/DELETE semantics beyond PartiQL), so this class implements the
+ * minimal `NoSqlStore` marker interface plus the ledger surface shared by
+ * this family of stores: `append`/`get`/`history`/`verify`/`query`.
+ *
+ * ## Lazy driver loading
+ *
+ * The official `amazon-qldb-driver-nodejs` package is loaded lazily inside
+ * `connect()`, so importing this module never requires the driver to be
+ * installed. Tests (and callers with their own transport) inject a pre-built
+ * driver via `QldbStoreOptions.client`, which bypasses the `require` entirely.
+ */
+import { NoSqlStore } from '../store';
+/**
+ * The subset of the `amazon-qldb-driver-nodejs` `QldbDriver` this store uses.
+ * The real driver implements this; tests inject a mock with the same shape.
+ */
+export interface QldbDriverLike {
+    /**
+     * Run `fn` inside an implicitly-managed transaction (auto-retried on
+     * optimistic-concurrency conflicts). `fn` receives a transaction executor
+     * whose `execute(statement, ...params)` returns a QLDB `Result`.
+     */
+    executeLambda<T>(fn: (txn: QldbTransactionLike) => Promise<T> | T): Promise<T>;
+    /** List the (active) table names in the ledger. */
+    getTableNames?(): Promise<string[]>;
+    /** Close the underlying session pool. */
+    close?(): void | Promise<void>;
+}
+/** The transaction executor handed to `executeLambda`'s callback. */
+export interface QldbTransactionLike {
+    execute(statement: string, ...parameters: unknown[]): Promise<QldbResultLike>;
+}
+/** The `Result` returned by `txn.execute` - `getResultList()` yields the rows. */
+export interface QldbResultLike {
+    getResultList(): unknown[];
+}
+/** Connection options for `QldbStore`. */
+export interface QldbStoreOptions {
+    /** The QLDB ledger name (e.g. `'my-ledger'`). */
+    ledgerName: string;
+    /** AWS region hosting the ledger (passed through to the driver). */
+    region?: string;
+    /**
+     * A pre-built driver to use instead of constructing one via the lazy
+     * `require`. When provided, `connect()` uses it verbatim and never loads
+     * `amazon-qldb-driver-nodejs`.
+     */
+    client?: QldbDriverLike;
+}
+/** Sort direction accepted by {@link QldbStore.findAll}'s `order`. */
+export type QldbOrderDirection = 'ASC' | 'DESC' | 'asc' | 'desc';
+/** Options for {@link QldbStore.findAll}/{@link QldbStore.findOne}. */
+export interface QldbFindOptions {
+    /** ORM `where` clause (plain equality and/or `Op`-keyed conditions). */
+    where?: Record<string, any>;
+    /** Restrict the returned columns, e.g. `['id', 'name']` (PartiQL projection). */
+    attributes?: string[];
+    /** Client-side ordering: `[['age', 'DESC'], ['name', 'ASC']]`. */
+    order?: Array<[string, QldbOrderDirection]>;
+    /** Client-side row cap (QLDB PartiQL has no `LIMIT`). */
+    limit?: number;
+    /** Client-side rows to skip (QLDB PartiQL has no `OFFSET`). */
+    offset?: number;
+}
+/**
+ * `QldbStore` wraps an `amazon-qldb-driver-nodejs` driver behind the shared
+ * ledger surface. `append` inserts a new document (returning its QLDB
+ * document id), `get` reads the current revision by document id, `history`
+ * returns every prior revision via the `history()` PartiQL function,
+ * `verify` returns a document's revision metadata (content hash +
+ * block address - QLDB's tamper-evidence proof material), and `query` is the
+ * raw PartiQL escape hatch.
+ */
+export declare class QldbStore implements NoSqlStore {
+    readonly name = "qldb";
+    readonly library = "amazon-qldb-driver-nodejs";
+    private readonly options;
+    private driver;
+    private connected;
+    constructor(options: QldbStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `QldbDriver` for anything not wrapped here. */
+    getClient(): QldbDriverLike;
+    private requireDriver;
+    /** Run a PartiQL statement inside a managed transaction and return the rows. */
+    private execute;
+    /**
+     * Insert `data` as a new document into `table`, returning its QLDB document
+     * id (the stable identifier every revision of the document shares). Runs
+     * `INSERT INTO <table> ?`.
+     */
+    append(table: string, data: unknown): Promise<string>;
+    /**
+     * Read the current revision of the document with QLDB document id `id`,
+     * addressed via PartiQL's `BY` clause. Returns the row or `null`.
+     */
+    get(table: string, id: string): Promise<unknown | null>;
+    /**
+     * Return every revision (including deletions) of the document with id `id`
+     * via the `history(<table>)` PartiQL function. Each entry carries `data`,
+     * `metadata`, `blockAddress` and `hash`.
+     */
+    history(table: string, id: string): Promise<unknown[]>;
+    /**
+     * Return the tamper-evidence proof material for document `id`: its revision
+     * `metadata` (content hash + version) and `blockAddress` from the journal,
+     * pulled from `history()`. This is the data QLDB's server-side digest/proof
+     * APIs cryptographically verify a revision against.
+     */
+    verify(table: string, id: string): Promise<{
+        documentId: string;
+        revisions: unknown[];
+    }>;
+    /** Run a raw PartiQL `statement` with optional positional `params`. */
+    query(statement: string, params?: unknown[]): Promise<unknown[]>;
+    /**
+     * Fetch every document in `table` matching the ORM `where` clause. The
+     * `where` clause is compiled to a parameterized PartiQL `WHERE`; `order`,
+     * `limit` and `offset` are applied client-side because QLDB's PartiQL
+     * dialect supports none of them.
+     */
+    findAll<T = Record<string, unknown>>(table: string, options?: QldbFindOptions): Promise<T[]>;
+    /** Fetch the first document matching `where` (client-side `limit 1`), or `null`. */
+    findOne<T = Record<string, unknown>>(table: string, options?: QldbFindOptions): Promise<T | null>;
+    /** Count documents in `table` matching `where`. */
+    count(table: string, where?: Record<string, any>): Promise<number>;
+    /**
+     * Insert `data` as a new document, returning its QLDB document id. Alias
+     * of {@link append} using ORM naming.
+     */
+    create(table: string, data: Record<string, unknown>): Promise<string>;
+    /**
+     * Insert many documents in a single managed transaction, returning the new
+     * document ids in order.
+     */
+    bulkCreate(table: string, rows: Array<Record<string, unknown>>): Promise<string[]>;
+    /**
+     * Update every document matching `where`, SETting each key in `values`.
+     * Returns the number of documents QLDB reported as modified.
+     */
+    update(table: string, values: Record<string, unknown>, where?: Record<string, any>): Promise<number>;
+    /**
+     * Delete every document matching `where`. Returns the number of documents
+     * QLDB reported as deleted. QLDB retains all prior revisions in the
+     * journal, so a delete is itself a new (tombstone) revision - use
+     * {@link history} to recover deleted data.
+     */
+    destroy(table: string, where?: Record<string, any>): Promise<number>;
+    /**
+     * Insert-or-update: within a single transaction, look for a document
+     * matching `where`; if one exists, SET `data` onto the matches, otherwise
+     * INSERT `data` (merged with the `where` equality keys). Returns
+     * `{ created }` indicating which branch ran.
+     */
+    upsert(table: string, data: Record<string, unknown>, where: Record<string, any>): Promise<{
+        created: boolean;
+    }>;
+    /**
+     * Run `fn` inside a single managed QLDB transaction (auto-retried on
+     * optimistic-concurrency conflicts). The callback receives the raw
+     * transaction executor so it can compose several statements atomically.
+     */
+    transaction<T>(fn: (txn: QldbTransactionLike) => Promise<T> | T): Promise<T>;
+    /** List the active table names in the ledger (thin passthrough). */
+    tableNames(): Promise<string[]>;
+}
+export default QldbStore;