@objectstack/driver-mongodb 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,201 @@
+import { DriverOptions, QueryAST } from '@objectstack/spec/data';
+import { IDataDriver } from '@objectstack/spec/contracts';
+import { MongoClientOptions, ClientSession, Db, MongoClient, Filter, Document } from 'mongodb';
+
+/**
+ * MongoDB Driver for ObjectStack
+ *
+ * Implements the IDataDriver contract using the official MongoDB Node.js driver.
+ * Provides native document database operations with full support for
+ * ObjectStack's query protocol, aggregations, transactions, and streaming.
+ */
+
+/**
+ * MongoDB driver configuration.
+ */
+interface MongoDBDriverConfig {
+    /** MongoDB connection URI (e.g., 'mongodb://localhost:27017/mydb') */
+    url: string;
+    /** Database name (overrides the database in the URI) */
+    database?: string;
+    /** Maximum connection pool size */
+    maxPoolSize?: number;
+    /** Minimum connection pool size */
+    minPoolSize?: number;
+    /** Connection timeout in milliseconds */
+    connectTimeoutMS?: number;
+    /** Server selection timeout in milliseconds */
+    serverSelectionTimeoutMS?: number;
+    /** Additional MongoClient options */
+    options?: MongoClientOptions;
+}
+/**
+ * MongoDB Driver for ObjectStack.
+ *
+ * Implements the IDataDriver contract via the official MongoDB driver.
+ * Uses native MongoDB queries, aggregation pipelines, and transactions.
+ */
+declare class MongoDBDriver implements IDataDriver {
+    readonly name: string;
+    readonly version: string;
+    readonly supports: {
+        create: boolean;
+        read: boolean;
+        update: boolean;
+        delete: boolean;
+        bulkCreate: boolean;
+        bulkUpdate: boolean;
+        bulkDelete: boolean;
+        transactions: boolean;
+        savepoints: boolean;
+        queryFilters: boolean;
+        queryAggregations: boolean;
+        querySorting: boolean;
+        queryPagination: boolean;
+        queryWindowFunctions: boolean;
+        querySubqueries: boolean;
+        queryCTE: boolean;
+        joins: boolean;
+        fullTextSearch: boolean;
+        jsonQuery: boolean;
+        geospatialQuery: boolean;
+        streaming: boolean;
+        jsonFields: boolean;
+        arrayFields: boolean;
+        vectorSearch: boolean;
+        schemaSync: boolean;
+        batchSchemaSync: boolean;
+        migrations: boolean;
+        indexes: boolean;
+        connectionPooling: boolean;
+        preparedStatements: boolean;
+        queryCache: boolean;
+    };
+    private client;
+    private db;
+    private config;
+    constructor(config: MongoDBDriverConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    checkHealth(): Promise<boolean>;
+    getPoolStats(): undefined;
+    execute(command: unknown, _parameters?: unknown[], options?: DriverOptions): Promise<unknown>;
+    find(object: string, query: QueryAST, options?: DriverOptions): Promise<Record<string, unknown>[]>;
+    findOne(object: string, query: QueryAST, options?: DriverOptions): Promise<Record<string, unknown> | null>;
+    findStream(object: string, query: QueryAST, options?: DriverOptions): AsyncGenerator<Record<string, unknown>>;
+    private _findStream;
+    create(object: string, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown>>;
+    update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown>>;
+    upsert(object: string, data: Record<string, unknown>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, unknown>>;
+    delete(object: string, id: string | number, options?: DriverOptions): Promise<boolean>;
+    count(object: string, query?: QueryAST, options?: DriverOptions): Promise<number>;
+    bulkCreate(object: string, dataArray: Record<string, unknown>[], options?: DriverOptions): Promise<Record<string, unknown>[]>;
+    bulkUpdate(object: string, updates: Array<{
+        id: string | number;
+        data: Record<string, unknown>;
+    }>, options?: DriverOptions): Promise<Record<string, unknown>[]>;
+    bulkDelete(object: string, ids: Array<string | number>, options?: DriverOptions): Promise<void>;
+    updateMany(object: string, query: QueryAST, data: Record<string, unknown>, options?: DriverOptions): Promise<number>;
+    deleteMany(object: string, query: QueryAST, options?: DriverOptions): Promise<number>;
+    aggregate(object: string, query: QueryAST, options?: DriverOptions): Promise<Record<string, unknown>[]>;
+    beginTransaction(_options?: {
+        isolationLevel?: string;
+    }): Promise<ClientSession>;
+    commit(transaction: unknown): Promise<void>;
+    rollback(transaction: unknown): Promise<void>;
+    syncSchema(object: string, schema: unknown, _options?: DriverOptions): Promise<void>;
+    syncSchemasBatch(schemas: Array<{
+        object: string;
+        schema: unknown;
+    }>, options?: DriverOptions): Promise<void>;
+    dropTable(object: string, _options?: DriverOptions): Promise<void>;
+    explain(object: string, query: QueryAST, _options?: DriverOptions): Promise<unknown>;
+    /** Get the underlying Db instance for advanced usage. */
+    getDb(): Db;
+    /** Get the underlying MongoClient for advanced usage. */
+    getClient(): MongoClient;
+    private getCollection;
+    private getSession;
+    private mapFieldName;
+    private extractDatabaseName;
+}
+
+/**
+ * MongoDB Filter Translator
+ *
+ * Converts ObjectStack FilterCondition / AST-style `where` clauses into
+ * native MongoDB filter documents.
+ *
+ * Supports:
+ * - Implicit equality: `{ field: value }`
+ * - Explicit operators: `{ field: { $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin } }`
+ * - String operators: `{ field: { $contains, $startsWith, $endsWith, $notContains } }`
+ * - Special: `{ field: { $null, $exists } }`
+ * - Logical: `{ $and, $or, $not }`
+ * - Range: `{ field: { $between: [min, max] } }`
+ * - Legacy array-style: `[field, op, value]`
+ */
+
+/**
+ * Translate an ObjectStack `where` clause into a MongoDB filter document.
+ *
+ * The `where` clause can be:
+ * 1. A FilterCondition object (MongoDB-style with `$` operators)
+ * 2. A legacy array-style filter `[[field, op, value], 'or', [field, op, value]]`
+ * 3. A plain key-value object for implicit equality
+ */
+declare function translateFilter(where: unknown): Filter<any>;
+
+/**
+ * MongoDB Aggregation Pipeline Builder
+ *
+ * Translates ObjectStack QueryAST aggregations + groupBy into
+ * MongoDB aggregation pipeline stages ($match, $group, $sort, $project).
+ */
+
+/**
+ * Aggregation function descriptor from QueryAST.
+ */
+interface AggregationInput {
+    function: string;
+    field?: string;
+    alias: string;
+    distinct?: boolean;
+    filter?: unknown;
+}
+/**
+ * Build a MongoDB aggregation pipeline from QueryAST components.
+ *
+ * @param where - Filter condition (translated to $match)
+ * @param aggregations - Array of aggregation descriptors
+ * @param groupBy - Fields to group by
+ * @param orderBy - Sort specification
+ * @param limit - Max results
+ * @param offset - Skip results
+ */
+declare function buildAggregationPipeline(opts: {
+    where?: unknown;
+    aggregations?: AggregationInput[];
+    groupBy?: string[];
+    orderBy?: Array<{
+        field: string;
+        order?: string;
+    }>;
+    limit?: number;
+    offset?: number;
+}): Document[];
+/**
+ * Post-process aggregation results.
+ *
+ * Handles count_distinct conversion ($addToSet → count) and
+ * string_agg conversion ($push → joined string).
+ */
+declare function postProcessAggregation(results: Document[], aggregations: AggregationInput[]): Document[];
+
+declare const _default: {
+    id: string;
+    version: string;
+    onEnable: (context: any) => Promise<void>;
+};
+
+export { type AggregationInput, MongoDBDriver, type MongoDBDriverConfig, buildAggregationPipeline, _default as default, postProcessAggregation, translateFilter };