ts-prorm-orm 1.1.0 → 1.2.0

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

@@ -0,0 +1,129 @@
+/**
+ * VictoriaMetrics store implementation.
+ *
+ * VictoriaMetrics is a fast, cost-effective time-series database. Crucially
+ * it is **API-compatible with Prometheus**: it exposes the same
+ * `/api/v1/query` and `/api/v1/query_range` PromQL endpoints (plus MetricsQL
+ * extensions), so PromQL queries written against Prometheus work unchanged
+ * here. Unlike Prometheus, VictoriaMetrics also accepts client-side writes -
+ * it can ingest data pushed to it in several line formats, including the
+ * Prometheus text exposition format via `/api/v1/import/prometheus`.
+ *
+ * Because there is no SQL-shaped query surface, no row-level UPDATE/DELETE,
+ * and no identifier escaping, this engine does not fit the SQL `Dialect`
+ * interface (`src/dialects/dialect.ts`). This class implements the minimal
+ * `NoSqlStore` marker interface (`src/nosql/store.ts`) and exposes the
+ * Prometheus-compatible read API plus VictoriaMetrics's write API.
+ *
+ * ## No canonical driver - HTTP over `fetch`
+ *
+ * VictoriaMetrics has no single canonical npm client; it is an HTTP/JSON
+ * (and text-ingest) API. This store talks to it with the global `fetch`.
+ * For tests (and custom transports) an alternative HTTP client can be
+ * injected via `VictoriaMetricsStoreOptions.client`; when omitted, a tiny
+ * internal client over `fetch` + `baseURL` is built at connect time.
+ *
+ * ## Endpoints wrapped
+ *
+ * Read (Prometheus-compatible, under `/api/v1`):
+ * - `instantQuery(promql, time?)`          -> `GET /api/v1/query`
+ * - `rangeQuery(promql, {start,end,step})` -> `GET /api/v1/query_range`
+ *
+ * Write (VictoriaMetrics-specific):
+ * - `importPrometheus(lines)`              -> `POST /api/v1/import/prometheus`
+ * - `write(metric, value, timestamp?, labels?)` builds one Prometheus
+ *   exposition line and POSTs it via `importPrometheus`.
+ *
+ * Read methods return the parsed `data` field of the response envelope.
+ */
+import { NoSqlStore } from '../store';
+/** Default VictoriaMetrics HTTP API base URL (single-node). */
+export declare const DEFAULT_VICTORIAMETRICS_BASE_URL = "http://localhost:8428";
+/** Query-string parameter value(s). `undefined` values are dropped. */
+export type QueryParams = Record<string, string | string[] | undefined>;
+/**
+ * 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 VictoriaMetricsHttpClient {
+    /** Issue a GET and return the parsed JSON response body. */
+    get(path: string, params?: QueryParams): Promise<any>;
+    /** Issue a POST with a text body and return the parsed/text response. */
+    post(path: string, body: string, contentType?: string): Promise<any>;
+}
+/** Connection options for `VictoriaMetricsStore`. */
+export interface VictoriaMetricsStoreOptions {
+    /** Base URL of the VictoriaMetrics server. Defaults to `http://localhost:8428`. */
+    baseURL?: string;
+    /**
+     * Optional pre-built HTTP client. When provided it is used verbatim and
+     * `baseURL` is ignored; otherwise an internal `fetch`-based client is
+     * built against `baseURL` on `connect()`.
+     */
+    client?: VictoriaMetricsHttpClient;
+    /** Extra HTTP headers sent with every internal-client request. */
+    headers?: Record<string, string>;
+}
+/** Time bounds + resolution for a PromQL/MetricsQL range query. */
+export interface RangeQueryOptions {
+    /** Start timestamp (RFC3339 or Unix seconds). */
+    start: string | number;
+    /** End timestamp (RFC3339 or Unix seconds). */
+    end: string | number;
+    /** Query resolution step (duration string like `15s` or seconds). */
+    step: string | number;
+}
+/** Build a `fetch`-backed client for the given base URL. */
+export declare function createFetchClient(baseURL: string, headers?: Record<string, string>): VictoriaMetricsHttpClient;
+/**
+ * Build a single Prometheus text-exposition line:
+ *
+ *   metric{label="value",...} value [timestamp_ms]
+ *
+ * Label values are escaped per the exposition format (`\`, `"`, newline).
+ */
+export declare function buildPrometheusLine(metric: string, value: number, timestamp?: number, labels?: Record<string, string>): string;
+/**
+ * `VictoriaMetricsStore` wraps VictoriaMetrics's Prometheus-compatible
+ * PromQL read API (instant/range queries) and its Prometheus-exposition
+ * write/import API behind the `NoSqlStore` lifecycle.
+ */
+export declare class VictoriaMetricsStore implements NoSqlStore {
+    readonly name = "victoriametrics";
+    readonly library = "fetch";
+    private readonly baseURL;
+    private readonly injectedClient?;
+    private readonly headers?;
+    private client;
+    private connected;
+    constructor(options?: VictoriaMetricsStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying (internal or injected) HTTP client. */
+    getClient(): VictoriaMetricsHttpClient;
+    private requireClient;
+    private doGet;
+    /**
+     * Runs a PromQL/MetricsQL instant query via `GET /api/v1/query`
+     * (identical to the Prometheus endpoint). Returns the `data` payload.
+     */
+    instantQuery(promql: string, time?: string | number): Promise<any>;
+    /**
+     * Runs a PromQL/MetricsQL range query via `GET /api/v1/query_range`
+     * (identical to the Prometheus endpoint). Returns the `data` payload.
+     */
+    rangeQuery(promql: string, options: RangeQueryOptions): Promise<any>;
+    /**
+     * Imports raw data in Prometheus text-exposition format via
+     * `POST /api/v1/import/prometheus`. Accepts a single newline-delimited
+     * string or an array of lines (joined with newlines).
+     */
+    importPrometheus(lines: string | string[]): Promise<any>;
+    /**
+     * Writes a single sample by building one Prometheus-exposition line
+     * (`metric{labels} value [timestamp_ms]`) and importing it via
+     * `importPrometheus`.
+     */
+    write(metric: string, value: number, timestamp?: number, labels?: Record<string, string>): Promise<any>;
+}

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

@@ -0,0 +1,87 @@
+/**
+ * OpenLink Virtuoso store implementation.
+ *
+ * Virtuoso is a multi-model server whose RDF triplestore is queried over the
+ * SPARQL 1.1 Protocol via a single combined HTTP endpoint (`/sparql`) used for
+ * both queries and updates (dispatched by request content-type). There is no
+ * SQL-shaped RDF surface here, so it implements the minimal `NoSqlStore`
+ * marker interface (`src/nosql/store.ts`) rather than the SQL `Dialect`
+ * interface.
+ *
+ * ## No canonical driver - HTTP over `fetch`
+ *
+ * Virtuoso's SPARQL endpoint is just an HTTP/SPARQL API. 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
+ * `VirtuosoStoreOptions.client`; when omitted, a tiny internal client over
+ * `fetch` + `endpoint` is built at connect time.
+ *
+ * ## Surface
+ *
+ * - `query(sparql)`  -> POST to `/sparql`, returns bindings
+ * - `update(sparql)` -> POST to `/sparql`
+ * - `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 Virtuoso base URL. */
+export declare const DEFAULT_VIRTUOSO_ENDPOINT = "http://localhost:8890";
+/** SPARQL endpoint path. */
+export declare const DEFAULT_VIRTUOSO_SPARQL_PATH = "/sparql";
+/** 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 `VirtuosoStore`. */
+export interface VirtuosoStoreOptions {
+    /** Base URL of the Virtuoso server. Defaults to `http://localhost:8890`. */
+    endpoint?: string;
+    /** SPARQL endpoint path. Defaults to `/sparql`. */
+    sparqlPath?: 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;
+/**
+ * `VirtuosoStore` wraps Virtuoso's `/sparql` endpoint behind the `NoSqlStore`
+ * lifecycle.
+ */
+export declare class VirtuosoStore implements NoSqlStore {
+    readonly name = "virtuoso";
+    readonly library = "fetch";
+    private readonly endpoint;
+    private readonly injectedClient?;
+    private readonly headers?;
+    private client;
+    private connected;
+    /** SPARQL endpoint path (queries and updates share it). */
+    readonly sparqlPath: string;
+    constructor(options?: VirtuosoStoreOptions);
+    /** SPARQL query endpoint path. */
+    get queryPath(): string;
+    /** SPARQL update endpoint path (same 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/weaviate/index.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Weaviate store implementation.
+ *
+ * Weaviate is a vector database: collections ("classes") hold objects (a
+ * UUID, a JSON `properties` bag, and one or more dense vectors), and the
+ * primary query shape is "find the objects whose vector is closest to this
+ * vector/text" (optionally constrained by a structured filter), plus plain
+ * property-filtered fetches - 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 Weaviate's real collection/object/query operations instead of
+ * forcing them into a `query(sql)` shape.
+ *
+ * Uses the official `weaviate-client` (v3) driver, which exposes a
+ * collection-oriented fluent API (`client.collections.get(name).data.*` /
+ * `.query.*`) built on gRPC, rather than the older `weaviate-ts-client` (v2)
+ * REST/GraphQL client.
+ */
+import { WeaviateClient, CollectionConfig, CollectionConfigCreate, ConnectToLocalOptions, ConnectToWeaviateCloudOptions, DataObject, InsertObject, UpdateObject, ReplaceObject, FilterValue, Filter, BaseNearOptions, BaseNearTextOptions, FetchObjectsOptions, FetchObjectByIdOptions, WeaviateReturn, WeaviateObject, BatchObjectsReturn, DeleteManyOptions, DeleteManyReturn } from 'weaviate-client';
+import { NoSqlStore } from '../store';
+/**
+ * `WeaviateStore` deliberately does not carry a generic `Properties` type
+ * parameter through to the objects it stores/returns - unlike the SQL
+ * dialects (which are backed by a static, declared model schema), object
+ * shapes in a Weaviate collection are only known at runtime from the
+ * collection's schema. All object-shaped values below are therefore plain
+ * `Record<string, WeaviateField>` bags, matching what `client.collections
+ * .get(name)` (called with no type argument) already returns.
+ */
+type UntypedProps = undefined;
+/** A single vector, or a map of named vectors (for multi-vector collections). */
+export type WeaviateVectorInput = number[] | Record<string, number[]>;
+/** One property definition for `createCollection()` - name, data type, indexing/tokenization knobs. */
+export type WeaviateProperty = NonNullable<CollectionConfigCreate<UntypedProps>['properties']>[number];
+/**
+ * A vectorizer/vector-index config, as produced by `weaviate.configure.vectorizer.*`
+ * (e.g. `weaviate.configure.vectorizer.none()`, `.text2VecOpenAI()`) or a list of
+ * such configs for named multi-vector collections.
+ */
+export type WeaviateVectorizerConfig = NonNullable<CollectionConfigCreate<UntypedProps>['vectorizers']>;
+/** Options accepted by `createCollection()` beyond the name/properties/vectorizer. */
+export type WeaviateCreateCollectionOptions = Omit<CollectionConfigCreate<UntypedProps>, 'name' | 'properties' | 'vectorizers'>;
+/** An object to insert - `properties` plus an optional explicit `id`/`vector`. */
+export type WeaviateInsertObject = InsertObject<UntypedProps>;
+/** An object for `insertMany()`'s batch shape (same fields as `WeaviateInsertObject`, `collection` implied). */
+export type WeaviateBatchObject = DataObject<UntypedProps>;
+/** Fields to update on an existing object via `updateObject()`. */
+export type WeaviateUpdateFields = Omit<UpdateObject<UntypedProps>, 'id'>;
+/** Fields to fully replace an existing object with, via `replaceObject()`. */
+export type WeaviateReplaceFields = Omit<ReplaceObject<UntypedProps>, 'id'>;
+/** Options shared by the `nearVector()`/`nearText()`/`nearObject()`-style similarity searches. */
+export type WeaviateNearOptions = BaseNearOptions<UntypedProps, UntypedProps, boolean>;
+/** Options for `nearText()` - `BaseNearOptions` plus text-specific knobs (`moveTo`/`moveAway`). */
+export type WeaviateNearTextOptions = BaseNearTextOptions<UntypedProps, UntypedProps, boolean>;
+/** Options for `fetchObjects()` - pagination/cursor, filters, sorting, property selection. */
+export type WeaviateFetchObjectsOptions = FetchObjectsOptions<UntypedProps, boolean>;
+/** Options for `fetchObjectById()` - property/reference selection. */
+export type WeaviateFetchObjectByIdOptions = FetchObjectByIdOptions<UntypedProps, boolean>;
+/** A single object as returned by any of the query methods below. */
+export type WeaviateResultObject = WeaviateObject<UntypedProps, undefined>;
+/** The `{ objects }` envelope returned by similarity-search and `fetchObjects()` calls. */
+export type WeaviateQueryReturn = WeaviateReturn<UntypedProps, undefined>;
+/** A prebuilt filter (see `filter()` below for how to construct one) accepted by queries/`deleteMany()`. */
+export type WeaviateFilterValue = FilterValue;
+/** Result of `insertMany()`: per-object success/failure plus the assigned UUIDs. */
+export type WeaviateBatchInsertResult = BatchObjectsReturn<UntypedProps>;
+/** Result of `deleteMany()`. */
+export type WeaviateDeleteManyResult<V extends boolean = false> = DeleteManyReturn<V>;
+/**
+ * Connection options for `WeaviateStore`.
+ *
+ * Pass `clusterURL` to connect to a Weaviate Cloud instance (via
+ * `weaviate.connectToWeaviateCloud`); otherwise a locally-reachable instance
+ * is assumed (via `weaviate.connectToLocal`, e.g. a Docker Compose stack).
+ * `headers` is the place to supply third-party module API keys (e.g.
+ * `{ 'X-OpenAI-Api-Key': '...' }`) that Weaviate forwards to a configured
+ * vectorizer/generative module.
+ */
+export type WeaviateStoreOptions = ({
+    clusterURL: string;
+} & ConnectToWeaviateCloudOptions) | (ConnectToLocalOptions & {
+    clusterURL?: undefined;
+});
+/**
+ * `WeaviateStore` wraps a `weaviate-client` (v3) `WeaviateClient` and exposes
+ * Weaviate's collection management, object insert/query/update/delete, and
+ * near-vector/near-text similarity search as a typed, promise-based API.
+ */
+export declare class WeaviateStore implements NoSqlStore {
+    readonly name = "weaviate";
+    readonly library = "weaviate-client";
+    private readonly options;
+    private client;
+    private connected;
+    constructor(options?: WeaviateStoreOptions);
+    connect(): Promise<void>;
+    private hostForErrors;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `weaviate-client` `WeaviateClient` for anything not wrapped here. */
+    getClient(): WeaviateClient;
+    private requireClient;
+    private exec;
+    private collection;
+    /**
+     * Build a `FilterValue` (see `nearVector()`/`fetchObjects()`/`deleteMany()`'s
+     * `filters` option) against a collection's schema, e.g.
+     * `store.filter('Article').byProperty('title').equal('Hello')`.
+     */
+    filter(collectionName: string): Filter<unknown>;
+    /**
+     * Create a new collection ("class"). `properties` declares the object
+     * schema (name/dataType/indexing per field); `vectorizer` configures how
+     * vectors are produced - pass `weaviate.configure.vectorizer.none()` for
+     * bring-your-own vectors, or a module config like
+     * `weaviate.configure.vectorizer.text2VecOpenAI()` to have Weaviate call
+     * out to an embedding provider (which requires the corresponding API key
+     * in `headers`, e.g. `X-OpenAI-Api-Key`, at connect time).
+     */
+    createCollection(collectionName: string, properties?: WeaviateProperty[], vectorizer?: WeaviateVectorizerConfig, options?: WeaviateCreateCollectionOptions): Promise<CollectionConfig>;
+    /** Delete a collection and all of its objects. */
+    deleteCollection(collectionName: string): Promise<void>;
+    /** List every collection's configuration. */
+    listCollections(): Promise<CollectionConfig[]>;
+    /** Whether a collection with this name exists. */
+    collectionExists(collectionName: string): Promise<boolean>;
+    /** Detailed schema/config for one collection (properties, vectorizer, replication, etc). */
+    getCollection(collectionName: string): Promise<CollectionConfig>;
+    /**
+     * Insert a single object. `object.vector` (renamed `vectors` on the wire)
+     * may be omitted entirely for collections with a server-side vectorizer
+     * module, or supplied explicitly (a plain array, or a `{ name: vector }`
+     * map for named-vector collections) for `none`/self-provided vectorizers.
+     * Returns the object's UUID (generated if `object.id` wasn't given).
+     */
+    insertObject(collectionName: string, object?: WeaviateInsertObject): Promise<string>;
+    /**
+     * Insert multiple objects in a single request (no client-side batching -
+     * all `objects` are sent together). Per-object failures are reported in
+     * the returned `errors`/`hasErrors` rather than rejecting the whole call;
+     * check `hasErrors` to detect partial failures.
+     */
+    insertMany(collectionName: string, objects: WeaviateBatchObject[]): Promise<WeaviateBatchInsertResult>;
+    /** Find the objects whose vector is closest to `vector`, optionally constrained by `options.filters`. */
+    nearVector(collectionName: string, vector: number[], options?: WeaviateNearOptions): Promise<WeaviateQueryReturn>;
+    /**
+     * Find the objects whose vector is closest to the vectorized form of
+     * `query` (a single string, or multiple strings averaged together).
+     * Requires the collection to have a text vectorizer module configured
+     * (this is not a keyword/BM25 search - use `getClient()` for that).
+     */
+    nearText(collectionName: string, query: string | string[], options?: WeaviateNearTextOptions): Promise<WeaviateQueryReturn>;
+    /**
+     * Fetch objects without a similarity search - the vector-store analogue
+     * of `SELECT ... WHERE ...`. Supports `limit`/`offset`/cursor-based
+     * pagination (`after`), `filters`, and `returnProperties` to select which
+     * fields come back.
+     */
+    fetchObjects(collectionName: string, options?: WeaviateFetchObjectsOptions): Promise<WeaviateQueryReturn>;
+    /** Fetch a single object by its UUID. Returns `null` if no object with that ID exists. */
+    fetchObjectById(collectionName: string, id: string, options?: WeaviateFetchObjectByIdOptions): Promise<WeaviateResultObject | null>;
+    /**
+     * Partially update an object (`PATCH` semantics) - only the fields in
+     * `fields.properties`/`fields.vectors` are changed; everything else on
+     * the object is left as-is.
+     */
+    updateObject(collectionName: string, id: string, fields: WeaviateUpdateFields): Promise<void>;
+    /**
+     * Fully replace an object (`PUT` semantics) - any property not present in
+     * `fields.properties` is cleared, unlike `updateObject()`.
+     */
+    replaceObject(collectionName: string, id: string, fields: WeaviateReplaceFields): Promise<void>;
+    /** Whether an object with this UUID exists in the collection. */
+    objectExists(collectionName: string, id: string): Promise<boolean>;
+    /**
+     * Delete a single object by its UUID. Returns `true` if an object was
+     * actually deleted.
+     *
+     * The real `weaviate-client` `data.deleteById()` issues a REST `DELETE`
+     * and resolves `true` unconditionally (Weaviate's `DELETE
+     * /objects/{id}` returns success whether or not an object with that id
+     * existed) - it does not itself report whether anything was deleted.
+     * Check existence first so the documented "returns whether something
+     * was actually deleted" contract holds against the real driver, not
+     * just the test mock (whose `Map.delete()` happens to return that for
+     * free).
+     */
+    deleteObject(collectionName: string, id: string): Promise<boolean>;
+    /**
+     * Delete every object matching `where` (build one with `filter()`). Pass
+     * `{ verbose: true }` to get back the per-object outcome in
+     * `result.objects`; otherwise only the aggregate counts are populated.
+     */
+    deleteMany<V extends boolean = false>(collectionName: string, where: WeaviateFilterValue, options?: DeleteManyOptions<V>): Promise<WeaviateDeleteManyResult<V>>;
+}
+export default WeaviateStore;

package/dist/operators/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Operators module - re-exports all operators and helper functions
+ */
+export { Op, Operators, isOperator, getOperatorString, operatorToWhereKey } from '../operators';
+export { where, and, or, not, eq, ne, gt, gte, lt, lte, like, notLike, iLike, notILike, regexp, notRegexp, iRegexp, notIRegexp, in as inOp, notIn, between, notBetween, isNull, isNotNull, exists, notExists, contains, overlap, json, jsonKey, jsonContains, jsonHasKey, jsonConcat, jsonDelete, jsonDeletePath, jsonPathExists, jsonPathQuery, arrayContains, arrayContainedBy, arrayOverlaps, arrayAny, arrayAll, startsWith, notStartsWith, endsWith, notEndsWith, substring, notSubstring, any, all, fn, col, literal, literalExpr, isFnExpression, isColExpression, isLiteralExpression, isRawLiteral, cast, extract, conv, isCastExpression, isExtractExpression, isConvExpression, Cast, matchAgainst, matchFulltext, toTsvector, toTsquery, plainToTsquery, phraseToTsquery, } from '../operators';
+export { asc, desc, random, isOrderExpression } from '../operators';
+export type { OperatorSymbol, WhereConditionOptions, FnExpression, ColExpression, LiteralExpression, LiteralValue, CastExpression, ExtractExpression, ConvExpression, ExtractPart, CastType, OrderExpression, } from '../operators';