ts-prorm-orm 1.1.0

package/dist/nosql/mongodb/index.js

@@ -0,0 +1,461 @@
+"use strict";
+/**
+ * MongoDB store implementation for the Prorm NoSQL layer.
+ *
+ * MongoDB is a document store, 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)
+ * for connection lifecycle, and otherwise exposes MongoDB's real API shape
+ * directly: filters, projections, aggregation pipelines, sessions/
+ * transactions, and typed collections - rather than forcing everything
+ * through a `query(sql)` method that doesn't make sense for a document
+ * database.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MongoStore = void 0;
+const mongodb_1 = require("mongodb");
+const index_1 = require("../../errors/index");
+/**
+ * `MongoStore` wraps the official `mongodb` driver's `MongoClient`/`Db`/
+ * `Collection` API in a small, typed convenience layer.
+ */
+class MongoStore {
+    constructor(options) {
+        this.name = 'mongodb';
+        this.library = 'mongodb';
+        this.client = null;
+        this.db = null;
+        this._isConnected = false;
+        if (!options || !options.uri) {
+            throw new index_1.DatabaseError('MongoStore requires a connection `uri`', {
+                code: index_1.ErrorCodes.INVALID_CONNECTION,
+            });
+        }
+        if (!options.database) {
+            throw new index_1.DatabaseError('MongoStore requires a `database` name', {
+                code: index_1.ErrorCodes.INVALID_CONNECTION,
+            });
+        }
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        try {
+            const client = new mongodb_1.MongoClient(this.options.uri, this.options.clientOptions);
+            await client.connect();
+            this.client = client;
+            this.db = client.db(this.options.database);
+            this._isConnected = true;
+        }
+        catch (error) {
+            this.client = null;
+            this.db = null;
+            this._isConnected = false;
+            throw new index_1.DatabaseError('Failed to connect to MongoDB', {
+                code: index_1.ErrorCodes.CONNECTION_ERROR,
+                parent: error instanceof Error ? error : undefined,
+                original: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async disconnect() {
+        if (!this.client) {
+            this._isConnected = false;
+            return;
+        }
+        try {
+            await this.client.close();
+        }
+        catch (error) {
+            throw new index_1.DatabaseError('Failed to disconnect from MongoDB', {
+                code: index_1.ErrorCodes.CONNECTION_ERROR,
+                parent: error instanceof Error ? error : undefined,
+                original: error instanceof Error ? error.message : String(error),
+            });
+        }
+        finally {
+            this.client = null;
+            this.db = null;
+            this._isConnected = false;
+        }
+    }
+    isConnected() {
+        return this._isConnected;
+    }
+    /** Returns the underlying native `MongoClient`. */
+    getClient() {
+        return this.requireClient();
+    }
+    /** Returns the underlying native `Db` handle for the configured database. */
+    getDb() {
+        return this.requireDb();
+    }
+    requireClient() {
+        if (!this.client || !this._isConnected) {
+            throw new index_1.DatabaseError('MongoStore is not connected. Call connect() first.', {
+                code: index_1.ErrorCodes.INVALID_CONNECTION,
+            });
+        }
+        return this.client;
+    }
+    requireDb() {
+        if (!this.db || !this._isConnected) {
+            throw new index_1.DatabaseError('MongoStore is not connected. Call connect() first.', {
+                code: index_1.ErrorCodes.INVALID_CONNECTION,
+            });
+        }
+        return this.db;
+    }
+    /** Typed collection accessor, e.g. `store.collection<User>('users')`. */
+    collection(name) {
+        return this.requireDb().collection(name);
+    }
+    wrapError(op, error) {
+        throw new index_1.DatabaseError(`MongoDB operation "${op}" failed`, {
+            code: this.mapErrorCode(error),
+            parent: error instanceof Error ? error : undefined,
+            original: error instanceof Error ? error.message : String(error),
+        });
+    }
+    /**
+     * Maps a raw MongoDB driver error to one of our well-known `ErrorCodes`.
+     *
+     * MongoDB surfaces most server-side failures as a numeric `code` (and a
+     * human-readable `codeName`) on the error object itself - unlike some SQL
+     * drivers, this is not tucked away behind `.parent`/`.metadata.original`.
+     * We sniff those fields here so callers get a meaningful, dialect-
+     * agnostic error code (e.g. `UNIQUE_CONSTRAINT_ERROR` for duplicate key
+     * violations) instead of a generic `QUERY_ERROR` for everything.
+     */
+    mapErrorCode(error) {
+        if (error && typeof error === 'object') {
+            const mongoCode = error.code;
+            const codeName = error.codeName;
+            // MongoDB duplicate-key error: code 11000 (or 11001 for legacy
+            // insertMany-old-style errors), codeName "DuplicateKey".
+            if (mongoCode === 11000 || mongoCode === '11000' || mongoCode === 11001 || codeName === 'DuplicateKey') {
+                return index_1.ErrorCodes.UNIQUE_CONSTRAINT_ERROR;
+            }
+        }
+        return index_1.ErrorCodes.QUERY_ERROR;
+    }
+    // ---------------------------------------------------------------------
+    // Reads
+    // ---------------------------------------------------------------------
+    async findOne(collectionName, filter = {}, options) {
+        try {
+            return await this.collection(collectionName).findOne(filter, options);
+        }
+        catch (error) {
+            return this.wrapError('findOne', error);
+        }
+    }
+    async find(collectionName, filter = {}, options = {}) {
+        try {
+            const { sort, limit, skip, projection, ...rest } = options;
+            const cursor = this.collection(collectionName).find(filter, { ...rest, projection, sort });
+            if (typeof skip === 'number')
+                cursor.skip(skip);
+            if (typeof limit === 'number')
+                cursor.limit(limit);
+            return (await cursor.toArray());
+        }
+        catch (error) {
+            return this.wrapError('find', error);
+        }
+    }
+    /**
+     * Like {@link find}, but returns the native `FindCursor` instead of
+     * materializing the results with `toArray()`. Use this for large result
+     * sets that shouldn't be pulled fully into memory - iterate with
+     * `for await (const doc of cursor)` or use `cursor.next()`/`cursor.forEach()`.
+     */
+    findCursor(collectionName, filter = {}, options = {}) {
+        try {
+            const { sort, limit, skip, projection, ...rest } = options;
+            const cursor = this.collection(collectionName).find(filter, { ...rest, projection, sort });
+            if (typeof skip === 'number')
+                cursor.skip(skip);
+            if (typeof limit === 'number')
+                cursor.limit(limit);
+            return cursor;
+        }
+        catch (error) {
+            return this.wrapError('findCursor', error);
+        }
+    }
+    async countDocuments(collectionName, filter = {}, options) {
+        try {
+            return await this.collection(collectionName).countDocuments(filter, options);
+        }
+        catch (error) {
+            return this.wrapError('countDocuments', error);
+        }
+    }
+    /**
+     * Returns a fast, metadata-based approximate count of all documents in
+     * `collectionName`. Unlike {@link countDocuments}, this does not accept a
+     * filter and does not scan the collection - it reads the collection's
+     * cached document count, so it's cheap but can be stale/approximate
+     * (e.g. immediately after bulk writes, or on a sharded cluster).
+     */
+    async estimatedDocumentCount(collectionName, options) {
+        try {
+            return await this.collection(collectionName).estimatedDocumentCount(options);
+        }
+        catch (error) {
+            return this.wrapError('estimatedDocumentCount', error);
+        }
+    }
+    async aggregate(collectionName, pipeline, options) {
+        try {
+            const cursor = this.collection(collectionName).aggregate(pipeline, options);
+            return await cursor.toArray();
+        }
+        catch (error) {
+            return this.wrapError('aggregate', error);
+        }
+    }
+    /** Returns the distinct values for `field` across documents matching `filter`. */
+    async distinct(collectionName, field, filter = {}, options) {
+        try {
+            return await this.collection(collectionName).distinct(field, filter, options);
+        }
+        catch (error) {
+            return this.wrapError('distinct', error);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Writes
+    // ---------------------------------------------------------------------
+    async insertOne(collectionName, doc, options) {
+        try {
+            return await this.collection(collectionName).insertOne(doc, options);
+        }
+        catch (error) {
+            return this.wrapError('insertOne', error);
+        }
+    }
+    async insertMany(collectionName, docs, options) {
+        try {
+            return await this.collection(collectionName).insertMany(docs, options);
+        }
+        catch (error) {
+            return this.wrapError('insertMany', error);
+        }
+    }
+    /**
+     * Executes a mix of insert/update/delete/upsert operations against a
+     * single collection in one round trip. Thin passthrough to the native
+     * driver's `Collection.bulkWrite()`.
+     */
+    async bulkWrite(collectionName, operations, options) {
+        try {
+            return await this.collection(collectionName).bulkWrite(operations, options);
+        }
+        catch (error) {
+            return this.wrapError('bulkWrite', error);
+        }
+    }
+    async updateOne(collectionName, filter, update, options) {
+        try {
+            return await this.collection(collectionName).updateOne(filter, update, options);
+        }
+        catch (error) {
+            return this.wrapError('updateOne', error);
+        }
+    }
+    async updateMany(collectionName, filter, update, options) {
+        try {
+            return await this.collection(collectionName).updateMany(filter, update, options);
+        }
+        catch (error) {
+            return this.wrapError('updateMany', error);
+        }
+    }
+    /** Atomically finds a document matching `filter` and updates it, returning it (or `null`). */
+    async findOneAndUpdate(collectionName, filter, update, options) {
+        try {
+            return await this.collection(collectionName).findOneAndUpdate(filter, update, options ?? {});
+        }
+        catch (error) {
+            return this.wrapError('findOneAndUpdate', error);
+        }
+    }
+    async deleteOne(collectionName, filter, options) {
+        try {
+            return await this.collection(collectionName).deleteOne(filter, options);
+        }
+        catch (error) {
+            return this.wrapError('deleteOne', error);
+        }
+    }
+    async deleteMany(collectionName, filter, options) {
+        try {
+            return await this.collection(collectionName).deleteMany(filter, options);
+        }
+        catch (error) {
+            return this.wrapError('deleteMany', error);
+        }
+    }
+    /** Atomically finds a document matching `filter` and deletes it, returning it (or `null`). */
+    async findOneAndDelete(collectionName, filter, options) {
+        try {
+            return await this.collection(collectionName).findOneAndDelete(filter, options ?? {});
+        }
+        catch (error) {
+            return this.wrapError('findOneAndDelete', error);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Indexes
+    // ---------------------------------------------------------------------
+    async createIndex(collectionName, indexSpec, options) {
+        try {
+            return await this.collection(collectionName).createIndex(indexSpec, options);
+        }
+        catch (error) {
+            return this.wrapError('createIndex', error);
+        }
+    }
+    async dropIndex(collectionName, indexName) {
+        try {
+            return await this.collection(collectionName).dropIndex(indexName);
+        }
+        catch (error) {
+            return this.wrapError('dropIndex', error);
+        }
+    }
+    /**
+     * Lists the indexes defined on `collectionName`. Fills the asymmetry with
+     * {@link createIndex}/{@link dropIndex}, which have no built-in way to
+     * inspect what indexes already exist. Thin passthrough to the native
+     * driver's `Collection.listIndexes().toArray()`.
+     */
+    async listIndexes(collectionName, options) {
+        try {
+            return await this.collection(collectionName).listIndexes(options).toArray();
+        }
+        catch (error) {
+            return this.wrapError('listIndexes', error);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Collection administration
+    // ---------------------------------------------------------------------
+    /**
+     * Explicitly creates `collectionName`, rather than relying on MongoDB's
+     * implicit creation of a collection on first write. This is the only way
+     * to create a **timeseries collection** (`options.timeseries: { timeField,
+     * metaField?, granularity? }`) or a **view** (`options.viewOn` +
+     * `options.pipeline`), since both must be declared at creation time -
+     * previously this required dropping down to `getDb().createCollection(...)`
+     * directly.
+     */
+    async createCollection(collectionName, options) {
+        try {
+            return await this.requireDb().createCollection(collectionName, options);
+        }
+        catch (error) {
+            return this.wrapError('createCollection', error);
+        }
+    }
+    /**
+     * Lists the collections (and views) defined in the configured database.
+     * Thin passthrough to the native driver's `Db.listCollections().toArray()`.
+     */
+    async listCollections(filter = {}, options) {
+        try {
+            return (await this.requireDb().listCollections(filter, options).toArray());
+        }
+        catch (error) {
+            return this.wrapError('listCollections', error);
+        }
+    }
+    /**
+     * Renames `oldName` to `newName`. Uses `Db.renameCollection()` (rather
+     * than `Collection.rename()`) because it's the driver API that stays
+     * generic over the document type, matching the rest of this class's
+     * typed-collection conventions.
+     */
+    async renameCollection(oldName, newName, options) {
+        try {
+            return await this.requireDb().renameCollection(oldName, newName, options);
+        }
+        catch (error) {
+            return this.wrapError('renameCollection', error);
+        }
+    }
+    /** Drops `collectionName` entirely. Thin passthrough to `Collection.drop()`. */
+    async dropCollection(collectionName, options) {
+        try {
+            return await this.collection(collectionName).drop(options);
+        }
+        catch (error) {
+            return this.wrapError('dropCollection', error);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Change streams
+    // ---------------------------------------------------------------------
+    /**
+     * Opens a change stream on `collectionName`, delivering real-time
+     * notifications of insert/update/replace/delete operations. Thin
+     * passthrough to the native driver's `Collection.watch()`.
+     *
+     * Like {@link withTransaction}, this requires a replica set / sharded
+     * cluster deployment - a standalone `mongod` does not support change
+     * streams (see README "Known limitations").
+     *
+     * Returns the native `ChangeStream`, which is itself an async iterable
+     * and event emitter (`on('change', ...)`, `on('error', ...)`, `close()`).
+     *
+     * ```typescript
+     * const stream = store.watch<User>('users', [{ $match: { operationType: 'insert' } }]);
+     * stream.on('change', (change) => {
+     *   // change.operationType, change.fullDocument, ...
+     * });
+     * // later: await stream.close();
+     * ```
+     */
+    watch(collectionName, pipeline, options) {
+        try {
+            return this.collection(collectionName).watch(pipeline, options);
+        }
+        catch (error) {
+            return this.wrapError('watch', error);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Sessions / transactions
+    // ---------------------------------------------------------------------
+    /** Starts a new client session (for multi-document transactions). */
+    startSession(options) {
+        return this.requireClient().startSession(options);
+    }
+    /**
+     * Runs `fn` inside a MongoDB multi-document transaction. Requires a
+     * replica set / mongos deployment - standalone servers do not support
+     * transactions (see README "Known limitations").
+     */
+    async withTransaction(fn, options) {
+        const session = this.requireClient().startSession();
+        let result;
+        try {
+            await session.withTransaction(async () => {
+                result = await fn(session);
+            }, options);
+        }
+        catch (error) {
+            return this.wrapError('withTransaction', error);
+        }
+        finally {
+            await session.endSession();
+        }
+        return result;
+    }
+}
+exports.MongoStore = MongoStore;
+exports.default = MongoStore;