@twin.org/entity-storage-connector-mongodb 0.0.2-next.9 → 0.0.3-next.10

package/README.md

@@ -1,6 +1,6 @@
-# TWIN Entity Storage Connector MongoDb
+# Entity Storage Connector MongoDB
 
-Entity Storage connector implementation using MongoDb storage.
+This package provides a MongoDB backend for flexible document persistence and evolving schemas. It is designed to work with the wider storage ecosystem so applications can keep behaviour consistent across connectors and environments.
 
 ## Installation
 
@@ -8,18 +8,13 @@ Entity Storage connector implementation using MongoDb storage.
 npm install @twin.org/entity-storage-connector-mongodb
 ```
 
-## Testing
+## Docker
 
-The tests developed are functional tests and need an instance of MongoDb up and running. To run MongoDb locally:
+To perform testing of this component it may be necessary to launch a local instance to communicate with.
 
-```sh
-docker run -p 27500:27017 --name twin-entity-storage-mongodb --hostname mongo -d mongo
-```
-
-Afterwards you can run the tests as follows:
-
-```sh
-npm run test
+```shell
+docker pull mongo:latest
+docker run -d --name twin-entity-storage-mongodb -p 27500:27017 mongo:latest
 ```
 
 ## Examples

package/dist/es/index.js

@@ -0,0 +1,6 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export * from "./mongoDbEntityStorageConnector.js";
+export * from "./models/IMongoDbEntityStorageConnectorConfig.js";
+export * from "./models/IMongoDbEntityStorageConnectorConstructorOptions.js";
+//# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,oCAAoC,CAAC;AACnD,cAAc,kDAAkD,CAAC;AACjE,cAAc,8DAA8D,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./mongoDbEntityStorageConnector.js\";\nexport * from \"./models/IMongoDbEntityStorageConnectorConfig.js\";\nexport * from \"./models/IMongoDbEntityStorageConnectorConstructorOptions.js\";\n"]}

package/dist/es/models/IMongoDbEntityStorageConnectorConfig.js

@@ -0,0 +1,4 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=IMongoDbEntityStorageConnectorConfig.js.map

package/dist/es/models/IMongoDbEntityStorageConnectorConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMongoDbEntityStorageConnectorConfig.js","sourceRoot":"","sources":["../../../src/models/IMongoDbEntityStorageConnectorConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Configuration for the MongoDb Entity Storage Connector.\n */\nexport interface IMongoDbEntityStorageConnectorConfig {\n\t/**\n\t * The host for the MongoDb instance.\n\t */\n\thost: string;\n\n\t/**\n\t * The port for the MongoDb instance.\n\t */\n\tport?: number;\n\n\t/**\n\t * The user for the MongoDb instance.\n\t */\n\tuser?: string;\n\n\t/**\n\t * The password for the MongoDb instance.\n\t */\n\tpassword?: string;\n\n\t/**\n\t * The name of the database to be used.\n\t */\n\tdatabase: string;\n\n\t/**\n\t * The name of the collection to be used.\n\t */\n\tcollection: string;\n}\n"]}

package/dist/es/models/IMongoDbEntityStorageConnectorConstructorOptions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IMongoDbEntityStorageConnectorConstructorOptions.js.map

package/dist/es/models/IMongoDbEntityStorageConnectorConstructorOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IMongoDbEntityStorageConnectorConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/IMongoDbEntityStorageConnectorConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IMongoDbEntityStorageConnectorConfig } from \"./IMongoDbEntityStorageConnectorConfig.js\";\n\n/**\n * The options for the MongoDb entity storage connector constructor.\n */\nexport interface IMongoDbEntityStorageConnectorConstructorOptions {\n\t/**\n\t * The schema for the entity.\n\t */\n\tentitySchema: string;\n\n\t/**\n\t * The keys to use from the context ids to create partitions.\n\t */\n\tpartitionContextIds?: string[];\n\n\t/**\n\t * The type of logging component to use.\n\t * @default logging\n\t */\n\tloggingComponentType?: string;\n\n\t/**\n\t * The configuration for the connector.\n\t */\n\tconfig: IMongoDbEntityStorageConnectorConfig;\n}\n"]}

package/dist/es/mongoDbEntityStorageConnector.js

@@ -0,0 +1,583 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { ContextIdHelper, ContextIdStore } from "@twin.org/context";
+import { BaseError, ComponentFactory, GeneralError, Guards, HealthStatus, Is, ObjectHelper } from "@twin.org/core";
+import { ComparisonOperator, EntitySchemaFactory, EntitySchemaHelper, EntitySchemaPropertyType, LogicalOperator } from "@twin.org/entity";
+import { MongoClient } from "mongodb";
+/**
+ * Class for performing entity storage operations using MongoDb.
+ */
+export class MongoDbEntityStorageConnector {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "MongoDbEntityStorageConnector";
+    /**
+     * Limit the number of entities when finding.
+     * @internal
+     */
+    static _DEFAULT_LIMIT = 40;
+    /**
+     * Partition id field name.
+     * @internal
+     */
+    static _PARTITION_KEY = "partitionId";
+    /**
+     * The schema for the entity.
+     * @internal
+     */
+    _entitySchema;
+    /**
+     * The keys to use from the context ids to create partitions.
+     * @internal
+     */
+    _partitionContextIds;
+    /**
+     * The configuration for the connector.
+     * @internal
+     */
+    _config;
+    /**
+     * The MongoDb client.
+     * @internal
+     */
+    _client;
+    /**
+     * Create a new instance of MongoDbEntityStorageConnector.
+     * @param options The options for the connector.
+     */
+    constructor(options) {
+        Guards.object(MongoDbEntityStorageConnector.CLASS_NAME, "options", options);
+        Guards.stringValue(MongoDbEntityStorageConnector.CLASS_NAME, "options.entitySchema", options.entitySchema);
+        Guards.object(MongoDbEntityStorageConnector.CLASS_NAME, "options.config", options.config);
+        Guards.stringValue(MongoDbEntityStorageConnector.CLASS_NAME, "options.config.host", options.config.host);
+        Guards.stringValue(MongoDbEntityStorageConnector.CLASS_NAME, "options.config.database", options.config.database);
+        Guards.stringValue(MongoDbEntityStorageConnector.CLASS_NAME, "options.config.collection", options.config.collection);
+        this._entitySchema = EntitySchemaFactory.get(options.entitySchema);
+        this._partitionContextIds = options.partitionContextIds;
+        this._config = options.config;
+        this._client = new MongoClient(this.createConnectionConfig());
+    }
+    /**
+     * Initialize the MongoDb environment.
+     * @param nodeLoggingComponentType Optional type of the logging component.
+     * @returns A promise that resolves to a boolean indicating success.
+     */
+    async bootstrap(nodeLoggingComponentType) {
+        const nodeLogging = ComponentFactory.getIfExists(nodeLoggingComponentType);
+        try {
+            await this._client.connect();
+            await nodeLogging?.log({
+                level: "info",
+                source: MongoDbEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "databaseCreating",
+                data: {
+                    databaseName: this._config.database
+                }
+            });
+            // Create the database if it does not exist
+            this._client.db(this._config.database);
+            await nodeLogging?.log({
+                level: "info",
+                source: MongoDbEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "databaseExists",
+                data: {
+                    databaseName: this._config.database
+                }
+            });
+            await this.getCollection();
+            await nodeLogging?.log({
+                level: "info",
+                source: MongoDbEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "collectionExists",
+                data: {
+                    collectionName: this._config.collection
+                }
+            });
+        }
+        catch (error) {
+            await nodeLogging?.log({
+                level: "error",
+                source: MongoDbEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "databaseCreateFailed",
+                error: BaseError.fromError(error),
+                data: {
+                    databaseName: this._config.database
+                }
+            });
+            return false;
+        }
+        return true;
+    }
+    /**
+     * The component needs to be stopped when the node is closed.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns Nothing.
+     */
+    async stop(nodeLoggingComponentType) {
+        await this._client.close();
+    }
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className() {
+        return MongoDbEntityStorageConnector.CLASS_NAME;
+    }
+    /**
+     * Returns the health status of the component.
+     * @returns The health status of the component.
+     */
+    async health() {
+        try {
+            await this._client
+                .db(this._config.database)
+                .collection(this._config.collection)
+                .estimatedDocumentCount();
+            return [
+                {
+                    source: MongoDbEntityStorageConnector.CLASS_NAME,
+                    status: HealthStatus.Ok,
+                    description: "healthDescription"
+                }
+            ];
+        }
+        catch {
+            return [
+                {
+                    source: MongoDbEntityStorageConnector.CLASS_NAME,
+                    status: HealthStatus.Error,
+                    description: "healthDescription",
+                    message: "connectionFailed"
+                }
+            ];
+        }
+    }
+    /**
+     * Get the schema for the entities.
+     * @returns The schema for the entities.
+     */
+    getSchema() {
+        return this._entitySchema;
+    }
+    /**
+     * Get an entity from MongoDb.
+     * @param id The id of the entity to get, or the index value if secondaryIndex is set.
+     * @param secondaryIndex Get the item using a secondary index.
+     * @param conditions The optional conditions to match for the entities.
+     * @returns The object if it can be found or undefined.
+     */
+    async get(id, secondaryIndex, conditions) {
+        Guards.stringValue(MongoDbEntityStorageConnector.CLASS_NAME, "id", id);
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        try {
+            const primaryKey = EntitySchemaHelper.getPrimaryKey(this.getSchema());
+            const query = Is.empty(secondaryIndex)
+                ? { [primaryKey.property]: id }
+                : { [secondaryIndex]: id };
+            if (Is.stringValue(partitionKey)) {
+                query[MongoDbEntityStorageConnector._PARTITION_KEY] = partitionKey;
+            }
+            if (conditions) {
+                for (const condition of conditions) {
+                    query[condition.property] = condition.value;
+                }
+            }
+            const collection = await this.getCollection();
+            const result = await collection.findOne(query);
+            ObjectHelper.propertyDelete(result, "_id");
+            ObjectHelper.propertyDelete(result, MongoDbEntityStorageConnector._PARTITION_KEY);
+            return result;
+        }
+        catch (err) {
+            throw new GeneralError(MongoDbEntityStorageConnector.CLASS_NAME, "getFailed", {
+                id
+            }, err);
+        }
+    }
+    /**
+     * Set an entity.
+     * @param entity The entity to set.
+     * @param conditions The optional conditions to match for the entities.
+     * @returns The id of the entity.
+     */
+    async set(entity, conditions) {
+        Guards.object(MongoDbEntityStorageConnector.CLASS_NAME, "entity", entity);
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        EntitySchemaHelper.validateEntity(entity, this.getSchema());
+        const primaryKey = EntitySchemaHelper.getPrimaryKey(this.getSchema());
+        const id = entity[primaryKey.property];
+        try {
+            const filter = { [primaryKey.property]: id };
+            const finalEntity = ObjectHelper.clone(entity);
+            if (Is.stringValue(partitionKey)) {
+                filter[MongoDbEntityStorageConnector._PARTITION_KEY] = partitionKey;
+                ObjectHelper.propertySet(finalEntity, MongoDbEntityStorageConnector._PARTITION_KEY, partitionKey);
+            }
+            if (Is.arrayValue(conditions)) {
+                for (const condition of conditions) {
+                    filter[condition.property] = condition.value;
+                }
+            }
+            const collection = await this.getCollection();
+            await collection.findOneAndUpdate(filter, { $set: ObjectHelper.removeEmptyProperties(finalEntity) }, { upsert: true });
+        }
+        catch (err) {
+            throw new GeneralError(MongoDbEntityStorageConnector.CLASS_NAME, "setFailed", {
+                id
+            }, err);
+        }
+    }
+    /**
+     * Set multiple entities in a batch.
+     * @param entities The entities to set.
+     * @returns Nothing.
+     */
+    async setBatch(entities) {
+        Guards.arrayValue(MongoDbEntityStorageConnector.CLASS_NAME, "entities", entities);
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        const primaryKey = EntitySchemaHelper.getPrimaryKey(this.getSchema());
+        for (const entity of entities) {
+            EntitySchemaHelper.validateEntity(entity, this.getSchema());
+        }
+        try {
+            const collection = await this.getCollection();
+            await collection.bulkWrite(entities.map(entity => {
+                const finalEntity = ObjectHelper.clone(entity);
+                const filter = {
+                    [primaryKey.property]: entity[primaryKey.property]
+                };
+                if (Is.stringValue(partitionKey)) {
+                    filter[MongoDbEntityStorageConnector._PARTITION_KEY] = partitionKey;
+                    ObjectHelper.propertySet(finalEntity, MongoDbEntityStorageConnector._PARTITION_KEY, partitionKey);
+                }
+                return {
+                    updateOne: {
+                        filter,
+                        update: {
+                            $set: ObjectHelper.removeEmptyProperties(finalEntity)
+                        },
+                        upsert: true
+                    }
+                };
+            }));
+        }
+        catch (err) {
+            throw new GeneralError(MongoDbEntityStorageConnector.CLASS_NAME, "setBatchFailed", undefined, err);
+        }
+    }
+    /**
+     * Empty the entity storage.
+     * @returns Nothing.
+     */
+    async empty() {
+        try {
+            const contextIds = await ContextIdStore.getContextIds();
+            const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+            const filter = {};
+            if (Is.stringValue(partitionKey)) {
+                filter[MongoDbEntityStorageConnector._PARTITION_KEY] = partitionKey;
+            }
+            const collection = await this.getCollection();
+            await collection.deleteMany(filter);
+        }
+        catch (err) {
+            throw new GeneralError(MongoDbEntityStorageConnector.CLASS_NAME, "emptyFailed", undefined, err);
+        }
+    }
+    /**
+     * Remove the entity.
+     * @param id The id of the entity to remove.
+     * @param conditions The optional conditions to match for the entities.
+     * @returns Nothing.
+     */
+    async remove(id, conditions) {
+        Guards.stringValue(MongoDbEntityStorageConnector.CLASS_NAME, "id", id);
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        try {
+            const primaryKey = EntitySchemaHelper.getPrimaryKey(this.getSchema());
+            const query = { [primaryKey.property]: id };
+            if (Is.stringValue(partitionKey)) {
+                query[MongoDbEntityStorageConnector._PARTITION_KEY] = partitionKey;
+            }
+            if (conditions) {
+                for (const condition of conditions) {
+                    query[condition.property] = condition.value;
+                }
+            }
+            const collection = await this.getCollection();
+            await collection.deleteOne(query);
+        }
+        catch (err) {
+            throw new GeneralError(MongoDbEntityStorageConnector.CLASS_NAME, "removeFailed", { id }, err);
+        }
+    }
+    /**
+     * Remove multiple entities by id.
+     * @param ids The ids of the entities to remove.
+     * @returns Nothing.
+     */
+    async removeBatch(ids) {
+        Guards.arrayValue(MongoDbEntityStorageConnector.CLASS_NAME, "ids", ids);
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        try {
+            const primaryKey = EntitySchemaHelper.getPrimaryKey(this.getSchema());
+            const filter = {
+                [primaryKey.property]: { $in: ids }
+            };
+            if (Is.stringValue(partitionKey)) {
+                filter[MongoDbEntityStorageConnector._PARTITION_KEY] = partitionKey;
+            }
+            const collection = await this.getCollection();
+            await collection.deleteMany(filter);
+        }
+        catch (err) {
+            throw new GeneralError(MongoDbEntityStorageConnector.CLASS_NAME, "removeBatchFailed", undefined, err);
+        }
+    }
+    /**
+     * Teardown the entity storage by dropping the collection.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns True if the teardown process was successful.
+     */
+    async teardown(nodeLoggingComponentType) {
+        const nodeLogging = ComponentFactory.getIfExists(nodeLoggingComponentType);
+        await nodeLogging?.log({
+            level: "info",
+            source: MongoDbEntityStorageConnector.CLASS_NAME,
+            ts: Date.now(),
+            message: "collectionDropping",
+            data: { collection: this._config.collection }
+        });
+        try {
+            const collection = await this.getCollection();
+            await collection.drop();
+            await nodeLogging?.log({
+                level: "info",
+                source: MongoDbEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "collectionDropped",
+                data: { collection: this._config.collection }
+            });
+            return true;
+        }
+        catch (err) {
+            await nodeLogging?.log({
+                level: "error",
+                source: MongoDbEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "teardownFailed",
+                error: BaseError.fromError(err)
+            });
+            return false;
+        }
+    }
+    /**
+     * Find all the entities which match the conditions.
+     * @param conditions The conditions to match for the entities.
+     * @param sortProperties The optional sort order.
+     * @param properties The optional properties to return, defaults to all.
+     * @param cursor The cursor to request the next chunk of entities.
+     * @param limit The suggested number of entities to return in each chunk, in some scenarios can return a different amount.
+     * @returns All the entities for the storage matching the conditions,
+     * and a cursor which can be used to request more entities.
+     */
+    async query(conditions, sortProperties, properties, cursor, limit) {
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        const returnSize = limit ?? MongoDbEntityStorageConnector._DEFAULT_LIMIT;
+        const finalConditions = {
+            conditions: [],
+            logicalOperator: LogicalOperator.And
+        };
+        if (Is.stringValue(partitionKey)) {
+            finalConditions.conditions.push({
+                property: MongoDbEntityStorageConnector._PARTITION_KEY,
+                comparison: ComparisonOperator.Equals,
+                value: partitionKey
+            });
+        }
+        if (!Is.empty(conditions)) {
+            finalConditions.conditions.push(conditions);
+        }
+        const filter = {};
+        if (finalConditions.conditions.length > 0) {
+            this.buildQueryParameters("", finalConditions, filter);
+        }
+        const sort = new Map();
+        if (Array.isArray(sortProperties)) {
+            for (const sortProperty of sortProperties) {
+                sort.set(sortProperty.property, sortProperty.sortDirection);
+            }
+        }
+        const projection = {};
+        if (properties) {
+            for (const property of properties) {
+                projection[property] = 1;
+            }
+        }
+        const cursorValue = cursor ? Number(cursor) : 0;
+        const collection = await this.getCollection();
+        const entitiesResult = await collection
+            // False positive, this is not an array find call
+            // eslint-disable-next-line unicorn/no-array-callback-reference
+            ?.find(filter, { projection })
+            .sort(sort)
+            .skip(cursorValue)
+            .limit(returnSize)
+            .toArray();
+        const entities = entitiesResult ?? [];
+        for (const entity of entities) {
+            ObjectHelper.propertyDelete(entity, "_id");
+            ObjectHelper.propertyDelete(entity, MongoDbEntityStorageConnector._PARTITION_KEY);
+        }
+        return {
+            entities,
+            cursor: entities?.length === returnSize ? String(cursorValue + returnSize) : undefined
+        };
+    }
+    /**
+     * Count all the entities which match the conditions.
+     * @returns The total count of entities in the storage.
+     */
+    async count() {
+        try {
+            const contextIds = await ContextIdStore.getContextIds();
+            const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+            const filter = {};
+            if (Is.stringValue(partitionKey)) {
+                filter[MongoDbEntityStorageConnector._PARTITION_KEY] = partitionKey;
+            }
+            return await this._client
+                .db(this._config.database)
+                .collection(this._config.collection)
+                .countDocuments(filter);
+        }
+        catch (err) {
+            throw new GeneralError(MongoDbEntityStorageConnector.CLASS_NAME, "countFailed", undefined, err);
+        }
+    }
+    /**
+     * Create a new DB connection configuration.
+     * @returns The MongoDb connection configuration.
+     * @internal
+     */
+    createConnectionConfig() {
+        const { host, port, user, password, database } = this._config;
+        const portPart = port ? `:${port}` : "";
+        if (user && password) {
+            return `mongodb://${user}:${password}@${host}${portPart}/${database}`;
+        }
+        return `mongodb://${host}${portPart}/${database}`;
+    }
+    /**
+     * Return a Mongo DB collection.
+     * @returns The MongoDb collection.
+     * @internal
+     */
+    async getCollection() {
+        const { database, collection } = this._config;
+        return this._client.db(database).collection(collection);
+    }
+    /**
+     * Create an MongoDB filter query.
+     * @param objectPath The path for the nested object.
+     * @param condition The conditions to create the query from.
+     * @param filter The filter query to use.
+     * @internal
+     */
+    buildQueryParameters(objectPath, condition, filter) {
+        if (!condition) {
+            return;
+        }
+        if ("conditions" in condition) {
+            const subConditions = condition.conditions.map(c => {
+                const subFilter = {};
+                this.buildQueryParameters(objectPath, c, subFilter);
+                return subFilter;
+            });
+            if (condition.logicalOperator === LogicalOperator.And) {
+                filter.$and = subConditions;
+            }
+            else if (condition.logicalOperator === LogicalOperator.Or) {
+                filter.$or = subConditions;
+            }
+            else {
+                Object.assign(filter, subConditions[0]);
+            }
+        }
+        else {
+            const propertyPath = String(condition.property);
+            const prop = objectPath ? `${objectPath}.${propertyPath}` : propertyPath;
+            const propertyParts = propertyPath.split(".");
+            const schemaLookupName = propertyParts.length > 1 ? propertyParts[0] : propertyPath;
+            const propertySchema = this._entitySchema.properties?.find(p => p.property === schemaLookupName);
+            // For dot-notation paths the leaf field is always a string value; using the root
+            // type directly would send Includes into $elemMatch which does not work for nested
+            // string fields. Keeping String here causes mapComparisonOperator to emit $regex,
+            // which MongoDB handles correctly for both nested object and array traversal.
+            const propertyType = propertyParts.length > 1 ? EntitySchemaPropertyType.String : propertySchema?.type;
+            const comparison = this.mapComparisonOperator(condition.comparison, condition.value, propertyType);
+            filter[prop] = comparison;
+        }
+    }
+    /**
+     * Map the framework comparison operators to those in MongoDB.
+     * @param comparison The comparison operator.
+     * @param value The value to compare.
+     * @param type The type of the property from the schema.
+     * @returns The MongoDB comparison expression.
+     * @internal
+     */
+    mapComparisonOperator(comparison, value, type) {
+        switch (comparison) {
+            case ComparisonOperator.Equals:
+                return value;
+            case ComparisonOperator.NotEquals:
+                return { $ne: value };
+            case ComparisonOperator.GreaterThan:
+                return { $gt: value };
+            case ComparisonOperator.LessThan:
+                return { $lt: value };
+            case ComparisonOperator.GreaterThanOrEqual:
+                return { $gte: value };
+            case ComparisonOperator.LessThanOrEqual:
+                return { $lte: value };
+            case ComparisonOperator.In:
+                return { $in: Array.isArray(value) ? value : [value] };
+            case ComparisonOperator.Includes:
+                // For string fields, use regex for substring matching
+                if (type === EntitySchemaPropertyType.String) {
+                    // Escape special regex characters in the value
+                    const escapedValue = String(value).replace(/[$()*+.?[\\\]^{|}]/g, "\\$&");
+                    return { $regex: escapedValue };
+                }
+                // For array and object fields, use $elemMatch
+                if (type === EntitySchemaPropertyType.Array || type === EntitySchemaPropertyType.Object) {
+                    return { $elemMatch: { $eq: value } };
+                }
+                // Fallback to $elemMatch for backwards compatibility
+                return { $elemMatch: { $eq: value } };
+            case ComparisonOperator.NotIncludes:
+                // For string fields, use negated regex
+                if (type === EntitySchemaPropertyType.String) {
+                    const escapedValue = String(value).replace(/[$()*+.?[\\\]^{|}]/g, "\\$&");
+                    return { $not: { $regex: escapedValue } };
+                }
+                // For arrays, use $elemMatch with $ne
+                return { $elemMatch: { $ne: value } };
+            default:
+                throw new GeneralError(MongoDbEntityStorageConnector.CLASS_NAME, "unsupportedComparisonOperator", { comparison });
+        }
+    }
+}
+//# sourceMappingURL=mongoDbEntityStorageConnector.js.map