@semics-tech/mongolite 1.0.0

package/dist/collection.d.ts

@@ -0,0 +1,274 @@
+import type { IDatabaseAdapter } from './db.js';
+import { DocumentWithId, Filter, UpdateFilter, InsertOneResult, InsertManyResult, UpdateResult, DeleteResult, Projection, IndexSpecification, CreateIndexOptions, CreateIndexResult, DropIndexResult, IndexInfo, FindOneAndUpdateOptions, FindOneAndDeleteOptions, FindOneAndReplaceOptions, ReplaceOptions, AggregationPipeline } from './types.js';
+import { FindCursor } from './cursors/findCursor.js';
+import { ChangeStream, ChangeStreamOptions } from './changeStream.js';
+/**
+ * MongoLiteCollection provides methods to interact with a specific SQLite table
+ * as if it were a MongoDB collection.
+ */
+export declare class MongoLiteCollection<T extends DocumentWithId> {
+    private db;
+    readonly name: string;
+    private readonly options;
+    constructor(db: IDatabaseAdapter, name: string, options?: {
+        verbose?: boolean;
+    });
+    /**
+     * Ensures the SQLite table for this collection exists, creating it if necessary.
+     * The table will have an `_id` column (indexed) and a `data` column for JSON.
+     * @private
+     */
+    ensureTable(): Promise<void>;
+    /**
+     * Inserts a single document into the collection.
+     * If `_id` is not provided, a UUID will be generated.
+     * @param doc The document to insert.
+     * @returns {Promise<InsertOneResult>} An object containing the outcome of the insert operation.
+     */
+    insertOne(doc: Omit<T, '_id'> & {
+        _id?: string;
+    }): Promise<InsertOneResult>;
+    /**
+     * Inserts multiple documents into the collection.
+     * If any document does not have an `_id`, a UUID will be generated.
+     * Uses batch insert with transactions for improved performance.
+     * @param docs An array of documents to insert.
+     * @returns {Promise<InsertManyResult>} An object containing the outcome of all insert operations.
+     * */
+    insertMany(docs: (Omit<T, '_id'> & {
+        _id?: string;
+    })[]): Promise<InsertManyResult>;
+    /**
+     * Inserts a batch of documents using a single transaction for optimal performance.
+     * @private
+     */
+    private insertBatch;
+    /**
+     * Finds a single document matching the filter.
+     * @param filter The query criteria.
+     * @param projection Optional. Specifies the fields to return.
+     * @returns {Promise<T | null>} The found document or `null`.
+     * @remarks When using a projection, some fields may be undefined at runtime despite the
+     * return type being `T`. This provides better ergonomics for the common case where no
+     * projection is used.
+     */
+    findOne(filter: Filter<T>, projection?: Projection<T>): Promise<T | null>;
+    /**
+     * Finds multiple documents matching the filter and returns a cursor.
+     * @param filter The query criteria.
+     * @returns {FindCursor<T>} A `FindCursor` instance.
+     */
+    find(filter?: Filter<T>): FindCursor<T>;
+    /**
+     * Updates a single document matching the filter.
+     * @param filter The selection criteria for the update.
+     * @param update The modifications to apply.
+     * @returns {Promise<UpdateResult>} An object describing the outcome.
+     */
+    updateOne(filter: Filter<T>, update: UpdateFilter<T>, options?: {
+        upsert?: boolean;
+    }): Promise<UpdateResult>;
+    /**
+     * Updates multiple documents matching the filter.
+     * @param filter The selection criteria for the update.
+     * @param update The modifications to apply.
+     * @returns {Promise<UpdateResult>} An object describing the outcome.
+     */
+    updateMany(filter: Filter<T>, update: UpdateFilter<T>): Promise<UpdateResult>;
+    /**
+     * Creates an index on the specified field(s) of the collection.
+     *
+     * @param fieldOrSpec The field or specification to create the index on.
+     * @param options Options for creating the index.
+     * @returns A promise that resolves to the result of the operation.
+     *
+     * @example
+     * // Create a simple index on the "name" field
+     * collection.createIndex({ name: 1 });
+     *
+     * // Create a unique index on the "email" field
+     * collection.createIndex({ email: 1 }, { unique: true });
+     *
+     * // Create a compound index on multiple fields
+     * collection.createIndex({ name: 1, age: -1 });
+     */
+    createIndex(fieldOrSpec: string | IndexSpecification, options?: CreateIndexOptions): Promise<CreateIndexResult>;
+    /**
+     * Generate a MongoDB-like index name from an index specification.
+     * Format: collectionName_field1_1_field2_-1
+     */
+    private generateIndexName;
+    /**
+     * Lists all indexes on the collection.
+     *
+     * @returns A promise that resolves to an object with a toArray method
+     * that returns the list of indexes.
+     */
+    listIndexes(): {
+        toArray: () => Promise<IndexInfo[]>;
+    };
+    /**
+     * Drops a specified index from the collection.
+     *
+     * @param indexName The name of the index to drop.
+     * @returns A promise that resolves to the result of the operation.
+     */
+    dropIndex(indexName: string): Promise<DropIndexResult>;
+    /**
+     * Drops all indexes from the collection, except for the index on _id.
+     *
+     * @returns A promise that resolves to the result of the operation.
+     */
+    dropIndexes(): Promise<{
+        acknowledged: boolean;
+        droppedCount: number;
+    }>;
+    /**
+     * Prepends '$.' to the path for SQLite JSON functions.
+     * @private
+     * @param path Field path, e.g., 'address.city'
+     * @returns JSON path string for SQLite, e.g., '$.address.city'
+     */
+    private parseJsonPath;
+    private setNestedValue;
+    private unsetNestedValue;
+    private getNestedValue;
+    /**
+     * Deletes a single document matching the filter.
+     * @param filter The criteria to select the document to delete.
+     * @returns {Promise<DeleteResult>} An object describing the outcome.
+     */
+    deleteOne(filter: Filter<T>): Promise<DeleteResult>;
+    /**
+     * Deletes multiple documents matching the filter.
+     * @param filter The criteria to select documents to delete.
+     * @returns {Promise<DeleteResult>} An object describing the outcome.
+     */
+    deleteMany(filter: Filter<T>): Promise<DeleteResult>;
+    /**
+     * Counts the number of documents matching the filter.
+     * @param filter The criteria to select documents to count.
+     * @returns {Promise<number>} The count of matching documents.
+     */
+    countDocuments(filter?: Filter<T>): Promise<number>;
+    /**
+     * Returns the number of documents in the collection.
+     * This is an estimate and may not reflect the exact count in concurrent environments.
+     * @returns {Promise<number>} The estimated count.
+     */
+    estimatedDocumentCount(): Promise<number>;
+    /**
+     * Finds a single document matching the filter, applies the update, and returns the document.
+     * @param filter The selection criteria.
+     * @param update The modifications to apply.
+     * @param options Options including returnDocument ('before'|'after') and upsert.
+     * @returns {Promise<T | null>} The document before or after the update, or null.
+     */
+    findOneAndUpdate(filter: Filter<T>, update: UpdateFilter<T>, options?: FindOneAndUpdateOptions<T>): Promise<T | null>;
+    /**
+     * Finds a single document matching the filter, deletes it, and returns it.
+     * @param filter The selection criteria.
+     * @param options Options including field projection.
+     * @returns {Promise<T | null>} The deleted document or null.
+     */
+    findOneAndDelete(filter: Filter<T>, options?: FindOneAndDeleteOptions<T>): Promise<T | null>;
+    /**
+     * Finds a single document matching the filter and replaces it entirely.
+     * @param filter The selection criteria.
+     * @param replacement The replacement document (replaces all fields except _id).
+     * @param options Options including returnDocument, upsert, and projection.
+     * @returns {Promise<T | null>} The document before or after the replacement, or null.
+     */
+    findOneAndReplace(filter: Filter<T>, replacement: Omit<T, '_id'>, options?: FindOneAndReplaceOptions<T>): Promise<T | null>;
+    /**
+     * Replaces a single document matching the filter.
+     * @param filter The selection criteria.
+     * @param replacement The replacement document (replaces all fields except _id).
+     * @param options Options including upsert.
+     * @returns {Promise<UpdateResult>} An object describing the outcome.
+     */
+    replaceOne(filter: Filter<T>, replacement: Omit<T, '_id'>, options?: ReplaceOptions): Promise<UpdateResult>;
+    /**
+     * Returns distinct values for a field across all documents matching the filter.
+     * @param field The field to find distinct values for.
+     * @param filter Optional filter to narrow the documents.
+     * @returns {Promise<unknown[]>} An array of distinct values.
+     */
+    distinct(field: string, filter?: Filter<T>): Promise<unknown[]>;
+    /**
+     * Drops the entire collection (table) from the database.
+     * @returns {Promise<void>}
+     */
+    drop(): Promise<void>;
+    /**
+     * Executes an aggregation pipeline on the collection.
+     * Supports: $match, $project, $sort, $limit, $skip, $count, $group, $unwind, $addFields.
+     * @param pipeline An array of pipeline stage documents.
+     * @returns An object with a toArray() method that returns the aggregation result.
+     */
+    aggregate(pipeline: AggregationPipeline): {
+        toArray: () => Promise<Record<string, unknown>[]>;
+    };
+    /**
+     * Runs an aggregation pipeline and returns results.
+     * @private
+     */
+    private runAggregationPipeline;
+    /**
+     * Applies a $group pipeline stage.
+     * @private
+     */
+    private applyGroupStage;
+    /**
+     * Applies a $project stage to a document.
+     * @private
+     */
+    private applyAggregateProjection;
+    /**
+     * Checks if a document matches a filter (for in-memory aggregation stages).
+     * Uses the same logic as FindCursor but applied in JavaScript.
+     * @private
+     */
+    private matchesFilter;
+    /**
+     * Checks if a value matches a set of query operators (for in-memory filtering).
+     * @private
+     */
+    private matchesOperators;
+    /**
+     * Opens a change stream to watch for changes on this collection.
+     * Returns a ChangeStream that emits events when documents are inserted, updated, or deleted.
+     *
+     * @param options Options for the change stream
+     * @returns A ChangeStream instance
+     *
+     * @example
+     * ```typescript
+     * const changeStream = collection.watch();
+     *
+     * changeStream.on('change', (change) => {
+     *   console.log('Change detected:', change);
+     * });
+     *
+     * // Or use async iteration
+     * for await (const change of changeStream) {
+     *   console.log('Change detected:', change);
+     * }
+     *
+     * // Close the change stream when done
+     * changeStream.close();
+     * ```
+     */
+    watch(options?: ChangeStreamOptions<T>): ChangeStream<T>;
+    /**
+     * Retries an operation with exponential backoff when SQLITE_BUSY errors occur.
+     * @param operation The operation function to retry.
+     * @param operationDescription A description of the operation for logging purposes.
+     * @param maxRetries The maximum number of retry attempts (default: 5).
+     * @param initialDelayMs The initial delay before the first retry in milliseconds (default: 100).
+     * @param maxDelayMs The maximum delay between retries in milliseconds (default: 10000).
+     * @returns The result of the operation once successful.
+     * @private
+     */
+    private retryWithBackoff;
+}