@twin.org/entity-storage-connector-cosmosdb 0.0.3-next.9 → 0.9.0

package/README.md

@@ -14,7 +14,7 @@ To perform testing of this component it may be necessary to launch a local insta
 
 ```shell
 docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest
-docker run --publish 8081:8081 --name twin-entity-storage-cosmos --detach --platform=linux/amd64 --memory=3g --cpus=2.0 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest
+docker run -p 18081:8081 --detach --name twin-entity-storage-cosmos mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
 ```
 
 ## Examples

package/dist/es/cosmosDbEntityStorageConnector.js

@@ -1,9 +1,10 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-import { CosmosClient, CosmosDbDiagnosticLevel, PartitionKeyKind } from "@azure/cosmos";
+import { BulkOperationType, CosmosClient, PartitionKeyKind } from "@azure/cosmos";
 import { ContextIdHelper, ContextIdStore } from "@twin.org/context";
-import { BaseError, Coerce, ComponentFactory, GeneralError, Guards, Is, ObjectHelper } from "@twin.org/core";
+import { BaseError, Coerce, ComponentFactory, GeneralError, Guards, HealthStatus, Is, ObjectHelper, Validation } from "@twin.org/core";
 import { ComparisonOperator, EntitySchemaFactory, EntitySchemaHelper, LogicalOperator, SortDirection } from "@twin.org/entity";
+import { EntityStorageHelper } from "@twin.org/entity-storage-models";
 /**
  * Class for performing entity storage operations using Cosmos DB.
  */
@@ -27,6 +28,11 @@ export class CosmosDbEntityStorageConnector {
      * @internal
      */
     static _PARTITION_KEY_VALUE = "root";
+    /**
+     * The name for the schema.
+     * @internal
+     */
+    _entitySchemaName;
     /**
      * The schema for the entity.
      * @internal
@@ -70,13 +76,16 @@ export class CosmosDbEntityStorageConnector {
         Guards.stringValue(CosmosDbEntityStorageConnector.CLASS_NAME, "options.config.databaseId", options.config.databaseId);
         Guards.stringValue(CosmosDbEntityStorageConnector.CLASS_NAME, "options.config.containerId", options.config.containerId);
         this._entitySchema = EntitySchemaFactory.get(options.entitySchema);
+        this._entitySchemaName = options.entitySchema;
         this._partitionContextIds = options.partitionContextIds;
         this._primaryKey = EntitySchemaHelper.getPrimaryKey(this._entitySchema);
         this._config = options.config;
         this._client = new CosmosClient({
             endpoint: this._config.endpoint,
             key: this._config.key,
-            diagnosticLevel: CosmosDbDiagnosticLevel.debug
+            connectionPolicy: {
+                enableEndpointDiscovery: !this._config.disableEndpointDiscovery
+            }
         });
         this._container = this._client
             .database(this._config.databaseId)
@@ -188,6 +197,37 @@ export class CosmosDbEntityStorageConnector {
     className() {
         return CosmosDbEntityStorageConnector.CLASS_NAME;
     }
+    /**
+     * Returns the health status of the component.
+     * @returns The health status of the component.
+     */
+    async health() {
+        try {
+            await this._client
+                .database(this._config.databaseId)
+                .container(this._config.containerId)
+                .read();
+            return [
+                {
+                    source: CosmosDbEntityStorageConnector.CLASS_NAME,
+                    status: HealthStatus.Ok,
+                    description: "healthDescription",
+                    data: { databaseId: this._config.databaseId, containerId: this._config.containerId }
+                }
+            ];
+        }
+        catch {
+            return [
+                {
+                    source: CosmosDbEntityStorageConnector.CLASS_NAME,
+                    status: HealthStatus.Error,
+                    description: "healthDescription",
+                    message: "connectionFailed",
+                    data: { databaseId: this._config.databaseId, containerId: this._config.containerId }
+                }
+            ];
+        }
+    }
     /**
      * Get the schema for the entities.
      * @returns The schema for the entities.
@@ -214,9 +254,14 @@ export class CosmosDbEntityStorageConnector {
                     .read();
                 return this.itemToEntity(item);
             }
+            const conditionValues = [];
             const whereQuery = [
                 `c.${CosmosDbEntityStorageConnector._PARTITION_KEY} = @partitionKey`
             ];
+            conditionValues.push({
+                name: "@partitionKey",
+                value: partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE
+            });
             // With a secondary index
             if (Is.stringValue(secondaryIndex)) {
                 const secIndex = secondaryIndex.toString();
@@ -225,24 +270,20 @@ export class CosmosDbEntityStorageConnector {
             else {
                 whereQuery.push(`c.${this._primaryKey.property} = @id`);
             }
+            conditionValues.push({ name: "@id", value: id });
             // With conditions
             if (Is.arrayValue(conditions)) {
                 for (const c of conditions) {
-                    const schemaProp = this._entitySchema.properties?.find(p => p.property === c.property);
-                    whereQuery.push(
-                    // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
-                    `c.${String(c.property)} = ${this.propertyToDbValue(c.value, schemaProp?.type)}`);
+                    whereQuery.push(`c.${c.property} = @${c.property}`);
+                    conditionValues.push({
+                        name: `@${c.property}`,
+                        value: c.value
+                    });
                 }
             }
             const query = {
                 query: `SELECT * FROM c WHERE ${whereQuery.join(" AND ")}`,
-                parameters: [
-                    { name: "@id", value: id },
-                    {
-                        name: "@partitionKey",
-                        value: partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE
-                    }
-                ]
+                parameters: conditionValues
             };
             const { resources: items } = await this._container.items.query(query).fetchAll();
             if (items.length === 1) {
@@ -271,8 +312,10 @@ export class CosmosDbEntityStorageConnector {
         Guards.object(CosmosDbEntityStorageConnector.CLASS_NAME, "entity", entity);
         const contextIds = await ContextIdStore.getContextIds();
         const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
-        EntitySchemaHelper.validateEntity(entity, this.getSchema());
-        const id = entity[this._primaryKey.property];
+        const prepared = EntityStorageHelper.prepareEntity(entity, this._entitySchema, undefined, {
+            nullBehavior: "omit"
+        });
+        const id = prepared[this._primaryKey.property];
         try {
             if (Is.arrayValue(conditions)) {
                 const item = this._container.item(id, partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE);
@@ -284,7 +327,7 @@ export class CosmosDbEntityStorageConnector {
             await this._container.items.upsert({
                 id,
                 [CosmosDbEntityStorageConnector._PARTITION_KEY]: partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE,
-                ...entity
+                ...prepared
             });
         }
         catch (err) {
@@ -301,6 +344,66 @@ export class CosmosDbEntityStorageConnector {
             }, err);
         }
     }
+    /**
+     * Set multiple entities in a batch.
+     * @param entities The entities to set.
+     * @returns Nothing.
+     */
+    async setBatch(entities) {
+        Guards.arrayValue(CosmosDbEntityStorageConnector.CLASS_NAME, "entities", entities);
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        const preparedEntities = entities.map(entity => EntityStorageHelper.prepareEntity(entity, this._entitySchema, undefined, {
+            nullBehavior: "omit"
+        }));
+        try {
+            await this._container.items.executeBulkOperations(preparedEntities.map(prepared => ({
+                operationType: BulkOperationType.Upsert,
+                partitionKey: partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE,
+                resourceBody: {
+                    id: prepared[this._primaryKey.property],
+                    [CosmosDbEntityStorageConnector._PARTITION_KEY]: partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE,
+                    ...prepared
+                }
+            })));
+        }
+        catch (err) {
+            throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "setBatchFailed", undefined, err);
+        }
+    }
+    /**
+     * Empty all entities from the storage.
+     * @returns Nothing.
+     */
+    async empty() {
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        const pk = partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE;
+        try {
+            let continuationToken;
+            do {
+                const feedOptions = { maxItemCount: 100, continuationToken };
+                const { resources, continuationToken: nextToken } = await this._container.items
+                    .query({
+                    query: `SELECT c.id FROM c WHERE c.${CosmosDbEntityStorageConnector._PARTITION_KEY} = @pk`,
+                    parameters: [{ name: "@pk", value: pk }]
+                }, feedOptions)
+                    .fetchNext();
+                continuationToken = nextToken;
+                if (Is.arrayValue(resources)) {
+                    const operations = resources.map(r => ({
+                        operationType: BulkOperationType.Delete,
+                        id: r.id,
+                        partitionKey: pk
+                    }));
+                    await this._container.items.executeBulkOperations(operations);
+                }
+            } while (Is.stringValue(continuationToken));
+        }
+        catch (err) {
+            throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "emptyFailed", undefined, err);
+        }
+    }
     /**
      * Remove the entity.
      * @param id The id of the entity to remove.
@@ -332,6 +435,66 @@ export class CosmosDbEntityStorageConnector {
             }, err);
         }
     }
+    /**
+     * Remove multiple entities by id.
+     * @param ids The ids of the entities to remove.
+     * @returns Nothing.
+     */
+    async removeBatch(ids) {
+        Guards.arrayValue(CosmosDbEntityStorageConnector.CLASS_NAME, "ids", ids);
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        try {
+            const operations = ids.map(id => ({
+                operationType: BulkOperationType.Delete,
+                id,
+                partitionKey: partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE
+            }));
+            await this._container.items.executeBulkOperations(operations);
+        }
+        catch (err) {
+            throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "removeBatchFailed", undefined, err);
+        }
+    }
+    /**
+     * Teardown the storage by deleting the underlying container.
+     * @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: CosmosDbEntityStorageConnector.CLASS_NAME,
+            ts: Date.now(),
+            message: "containerDeleting",
+            data: { containerId: this._config.containerId }
+        });
+        try {
+            if (await this.containerExists()) {
+                await this._container.delete();
+                await this.waitForContainerNotExists();
+            }
+            await nodeLogging?.log({
+                level: "info",
+                source: CosmosDbEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "containerDeleted",
+                data: { containerId: this._config.containerId }
+            });
+            return true;
+        }
+        catch (err) {
+            await nodeLogging?.log({
+                level: "error",
+                source: CosmosDbEntityStorageConnector.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.
@@ -346,6 +509,13 @@ export class CosmosDbEntityStorageConnector {
         let sql = "";
         const contextIds = await ContextIdStore.getContextIds();
         const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        EntityStorageHelper.validateSortProperties(this._entitySchema, sortProperties);
+        EntityStorageHelper.validateProperties(this._entitySchema, properties);
+        if (!Is.empty(limit)) {
+            const validationFailures = [];
+            Validation.integer("limit", limit, validationFailures, undefined, { minValue: 1 });
+            Validation.asValidationError(CosmosDbEntityStorageConnector.CLASS_NAME, "query", validationFailures);
+        }
         try {
             const returnSize = limit ?? CosmosDbEntityStorageConnector._DEFAULT_LIMIT;
             let orderByClause = "";
@@ -354,15 +524,6 @@ export class CosmosDbEntityStorageConnector {
                     throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "sortSingle");
                 }
                 for (const sortProperty of sortProperties) {
-                    const propertySchema = this._entitySchema.properties?.find(e => e.property === sortProperty.property);
-                    if (!propertySchema ||
-                        (!propertySchema.isPrimary &&
-                            !propertySchema.isSecondary &&
-                            !propertySchema.sortDirection)) {
-                        throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "sortNotIndexed", {
-                            property: sortProperty.property
-                        });
-                    }
                     const direction = sortProperty.sortDirection === SortDirection.Ascending ? "asc" : "desc";
                     orderByClause = `ORDER BY c.${String(sortProperty.property)} ${direction}`;
                 }
@@ -373,9 +534,58 @@ export class CosmosDbEntityStorageConnector {
             if (queryClause.length > 0) {
                 queryClause = ` AND ${queryClause}`;
             }
-            sql = `SELECT ${properties ? properties.map(p => `c.${p}`).join(", ") : "*"} FROM c WHERE c.partitionId = @partitionId ${queryClause} ${orderByClause}`;
-            const querySpecs = {
-                query: sql,
+            const selectClause = properties ? properties.map(p => `c.${p}`).join(", ") : "*";
+            const baseQuery = `SELECT ${selectClause} FROM c WHERE c.${CosmosDbEntityStorageConnector._PARTITION_KEY} = @partitionId${queryClause}`;
+            const queryParameters = [
+                {
+                    name: "@partitionId",
+                    value: partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE
+                },
+                ...Object.keys(attributeValues).map(key => ({ name: `@${key}`, value: attributeValues[key] }))
+            ];
+            const queryPartitionKey = partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE;
+            // For sorted queries use OFFSET LIMIT — CosmosDB continuation tokens are
+            // not reliably returned for ORDER BY queries across all service versions.
+            // The cursor is a numeric offset encoded as a string (same as SQL connectors).
+            const startIndex = Coerce.number(cursor) ?? 0;
+            sql = `${baseQuery} ${orderByClause} OFFSET ${startIndex} LIMIT ${returnSize + 1}`;
+            const sortedQuerySpecs = { query: sql, parameters: queryParameters };
+            const sortedResponse = await this._container.items
+                .query(sortedQuerySpecs, {
+                partitionKey: queryPartitionKey,
+                maxItemCount: returnSize + 1
+            })
+                .fetchNext();
+            const allItems = sortedResponse.resources;
+            const hasMore = allItems.length > returnSize;
+            return {
+                entities: (hasMore ? allItems.slice(0, returnSize) : allItems).map(i => this.itemToEntity(i)),
+                cursor: hasMore ? Coerce.string(startIndex + returnSize) : undefined
+            };
+        }
+        catch (err) {
+            throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "queryFailed", { sql }, err);
+        }
+    }
+    /**
+     * Count all the entities which match the conditions.
+     * @param conditions The optional conditions to match for the entities.
+     * @returns The total count of entities in the storage.
+     */
+    async count(conditions) {
+        try {
+            const contextIds = await ContextIdStore.getContextIds();
+            const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+            const attributeNames = {};
+            const attributeValues = {};
+            let queryClause = Is.empty(conditions)
+                ? ""
+                : this.buildQueryParameters("", conditions, attributeNames, attributeValues);
+            if (queryClause.length > 0) {
+                queryClause = ` AND ${queryClause}`;
+            }
+            const querySpec = {
+                query: `SELECT VALUE COUNT(1) FROM c WHERE c.${CosmosDbEntityStorageConnector._PARTITION_KEY} = @partitionId${queryClause}`,
                 parameters: [
                     {
                         name: "@partitionId",
@@ -384,33 +594,127 @@ export class CosmosDbEntityStorageConnector {
                     ...Object.keys(attributeValues).map(key => ({ name: `@${key}`, value: attributeValues[key] }))
                 ]
             };
-            const feedOptions = {
-                maxItemCount: returnSize,
-                continuationToken: cursor
-            };
-            const feedResponse = await this._container.items.query(querySpecs, feedOptions).fetchNext();
-            return {
-                entities: feedResponse.resources.map(i => this.itemToEntity(i)),
-                cursor: feedResponse.continuationToken
-            };
+            const { resources } = await this._container.items.query(querySpec).fetchAll();
+            return resources[0] ?? 0;
         }
         catch (err) {
-            throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "queryFailed", { sql }, err);
+            throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "countFailed", undefined, err);
         }
     }
     /**
-     * Delete the container.
-     * @returns Nothing.
+     * Get a unique list of all the context ids from the storage.
+     * @returns The list of unique context ids.
      */
-    async containerDelete() {
-        const contextIds = await ContextIdStore.getContextIds();
-        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+    async getPartitionContextIds() {
+        const partitionContextIds = this._partitionContextIds;
+        if (!Is.arrayValue(partitionContextIds)) {
+            return [];
+        }
         try {
-            await this._container.deleteAllItemsForPartitionKey(partitionKey ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE);
-            await this._container.delete();
+            const { resources: partitionIds } = await this._container.items
+                .query({
+                query: `SELECT DISTINCT VALUE c.${CosmosDbEntityStorageConnector._PARTITION_KEY} FROM c`
+            })
+                .fetchAll();
+            return partitionIds
+                .filter(id => Is.stringValue(id))
+                .map(id => ContextIdHelper.shortSplit(partitionContextIds, id));
         }
-        catch {
-            // Ignore errors
+        catch (err) {
+            throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "getPartitionContextIdsFailed", undefined, err);
+        }
+    }
+    /**
+     * Create the target connector for performing the migration using a temporary container.
+     * @param newEntitySchema The name of the new entity schema to create the connector for.
+     * @returns Connector for performing the migration.
+     */
+    async createTargetConnector(newEntitySchema) {
+        const migrationContainerId = `${this._config.containerId}Migration${Date.now()}`;
+        return new CosmosDbEntityStorageConnector({
+            entitySchema: newEntitySchema,
+            config: { ...this._config, containerId: migrationContainerId },
+            partitionContextIds: this._partitionContextIds
+        });
+    }
+    /**
+     * Finalize the migration by tearing down the old container and replacing it with the target container.
+     * @param targetConnector The target connector to finalize the migration with.
+     * @param options The options to control how the migration is finalized.
+     * @param loggingComponentType The optional component type to use for logging.
+     * @returns The final connector pointing at the original container id.
+     */
+    async finalizeMigration(targetConnector, options, loggingComponentType) {
+        // There is no rename operation in DynamoDB so we have to create a new table with the original name and copy the data over
+        // Teardown the existing table with the original name to free up the name for the new table
+        await this.teardown(loggingComponentType);
+        // Create a new connector with the original table name but with the new schema
+        // and copy the data from the migration table to the new table using batch operations
+        const finalConnector = new CosmosDbEntityStorageConnector({
+            entitySchema: targetConnector._entitySchemaName,
+            config: this._config,
+            partitionContextIds: this._partitionContextIds
+        });
+        if (await finalConnector.bootstrap(loggingComponentType)) {
+            // Since there is no rename, we need to copy the data from the migration table to the new table
+            const partitions = await targetConnector.getPartitionContextIds();
+            const batchSize = options?.batchSize ?? CosmosDbEntityStorageConnector._DEFAULT_LIMIT;
+            await this.bulkCopy(targetConnector, finalConnector, partitions, batchSize);
+            await targetConnector.teardown(loggingComponentType);
+            return finalConnector;
+        }
+        throw new GeneralError(CosmosDbEntityStorageConnector.CLASS_NAME, "finalizeMigrationFailedBootstrap");
+    }
+    /**
+     * Cleanup the migration if a migration fails or needs to be aborted.
+     * @param targetConnector The target connector to cleanup.
+     * @param options The options to control how the migration is cleaned up.
+     * @param loggingComponentType The optional component type to use for logging.
+     */
+    async cleanupMigration(targetConnector, options, loggingComponentType) {
+        // If something failed the only thing to cleanup is the migration table
+        await targetConnector?.teardown?.(loggingComponentType);
+    }
+    /**
+     * Copy all entities from sourceConnector to destConnector, paging through each partition.
+     * @param sourceConnector The connector to read entities from.
+     * @param destConnector The connector to write entities to.
+     * @param partitions The partition list returned by getPartitionContextIds.
+     * @param batchSize The number of entities to read per page.
+     * @internal
+     */
+    async bulkCopy(sourceConnector, destConnector, partitions, batchSize) {
+        let partitionList;
+        if (Is.arrayValue(partitions)) {
+            partitionList = partitions;
+        }
+        else if (Is.arrayValue(sourceConnector._partitionContextIds)) {
+            partitionList = [];
+        }
+        else {
+            partitionList = [{}];
+        }
+        for (let i = 0; i < partitionList.length; i++) {
+            const partitionKey = ContextIdHelper.combinedContextKey(partitionList[i], sourceConnector._partitionContextIds) ?? CosmosDbEntityStorageConnector._PARTITION_KEY_VALUE;
+            let continuationToken;
+            do {
+                const feedOptions = { maxItemCount: batchSize, continuationToken };
+                const { resources, continuationToken: nextToken } = await sourceConnector._container.items
+                    .query({
+                    query: `SELECT * FROM c WHERE c.${CosmosDbEntityStorageConnector._PARTITION_KEY} = @partitionId`,
+                    parameters: [{ name: "@partitionId", value: partitionKey }]
+                }, feedOptions)
+                    .fetchNext();
+                continuationToken = nextToken;
+                if (Is.arrayValue(resources)) {
+                    const operations = resources.map(({ _rid: rid, _self: self, _ts: ts, _etag: etag, _attachments: attachments, ...rest }) => ({
+                        operationType: BulkOperationType.Upsert,
+                        partitionKey,
+                        resourceBody: rest
+                    }));
+                    await destConnector._container.items.executeBulkOperations(operations);
+                }
+            } while (Is.stringValue(continuationToken));
         }
     }
     /**
@@ -450,7 +754,7 @@ export class CosmosDbEntityStorageConnector {
      * @param objectPath The prefix to use for the condition.
      * @param comparator The operator to map.
      * @param type The type of the property.
-     * @param attributeValues The attribute values to use in the query.
+     * @param attributeNames The attribute names to use in the query.
      * @returns The comparison expression.
      * @throws GeneralError if the comparison operator is not supported.
      * @internal
@@ -476,6 +780,10 @@ export class CosmosDbEntityStorageConnector {
         }
         else if (Is.array(comparator.value)) {
             const dbValues = comparator.value.map(v => this.propertyToDbValue(v, type));
+            if (dbValues.length === 0 && comparator.comparison === ComparisonOperator.In) {
+                // CosmosDB rejects `IN ()` — return always-false sentinel (#141).
+                return "1=0";
+            }
             const arrAttributeNames = [];
             for (let i = 0; i < dbValues.length; i++) {
                 const arrAttributeName = `${propName}${i}`;
@@ -485,7 +793,27 @@ export class CosmosDbEntityStorageConnector {
             propName = attributeName;
             attributeName = `(${arrAttributeNames.map(name => `@${name}`).join(", ")})`;
         }
+        else if (Is.object(comparator.value) &&
+            (comparator.comparison === ComparisonOperator.Equals ||
+                comparator.comparison === ComparisonOperator.NotEquals)) {
+            // CosmosDB SQL does not support object equality with =; expand to per-property comparisons.
+            const op = comparator.comparison === ComparisonOperator.Equals ? "=" : "<>";
+            const join = comparator.comparison === ComparisonOperator.Equals ? " AND " : " OR ";
+            const clauses = [];
+            for (const [key, val] of Object.entries(comparator.value)) {
+                const paramName = `${propName}${key}`;
+                attributeValues[paramName] = val;
+                clauses.push(`c.${attributeName}.${key} ${op} @${paramName}`);
+            }
+            return clauses.length === 1 ? clauses[0] : `(${clauses.join(join)})`;
+        }
         else {
+            // Avoid parameter name conflicts by ensuring unique parameter names in the query
+            let counter = 1;
+            while (propName in attributeValues) {
+                propName = `${attributeName.replace(/\./g, "").replace(/@/g, "")}${counter}`;
+                counter++;
+            }
             attributeValues[propName] = comparator.value;
         }
         const matches = attributeName.split(".").length;
@@ -514,15 +842,23 @@ export class CosmosDbEntityStorageConnector {
         else if (comparator.comparison === ComparisonOperator.LessThanOrEqual) {
             return `c.${attributeName} <= @${propName}`;
         }
-        else if (typeof attributeValues[propName] === "object" &&
+        else if (Is.object(attributeValues[propName]) &&
             comparator.comparison === ComparisonOperator.Includes) {
-            return `array_contains(c.${attributeName}, @${propName})`;
+            return `ARRAY_CONTAINS(c.${attributeName}, @${propName}, true)`;
+        }
+        else if ((type === "array" || type === "object") &&
+            comparator.comparison === ComparisonOperator.Includes) {
+            return `ARRAY_CONTAINS(c.${attributeName}, @${propName})`;
+        }
+        else if ((type === "array" || type === "object") &&
+            comparator.comparison === ComparisonOperator.NotIncludes) {
+            return `NOT ARRAY_CONTAINS(c.${attributeName}, @${propName})`;
         }
         else if (comparator.comparison === ComparisonOperator.Includes) {
-            return `contains(c.${attributeName}, @${propName})`;
+            return `CONTAINS(c.${attributeName}, @${propName})`;
         }
         else if (comparator.comparison === ComparisonOperator.NotIncludes) {
-            return `notContains(c.${attributeName}, @${propName})`;
+            return `NOT CONTAINS(c.${attributeName}, @${propName})`;
         }
         else if (comparator.comparison === ComparisonOperator.In) {
             return `c.${propName} IN ${attributeName}`;
@@ -550,7 +886,7 @@ export class CosmosDbEntityStorageConnector {
             return `${Coerce.string(value)}`;
         }
         else if (type === "integer" || type === "number") {
-            return Coerce.string(value) ?? "";
+            return Coerce.number(value) ?? 0;
         }
         else if (type === "boolean") {
             return Coerce.boolean(value) ?? false;
@@ -597,6 +933,8 @@ export class CosmosDbEntityStorageConnector {
     /**
      * Verify the conditions for the entity.
      * @param conditions The conditions to verify.
+     * @param obj The object to verify the conditions against.
+     * @returns True if all conditions are met, false otherwise.
      * @internal
      */
     verifyConditions(conditions, obj) {
@@ -609,13 +947,14 @@ export class CosmosDbEntityStorageConnector {
      * @internal
      */
     itemToEntity(item) {
-        ObjectHelper.propertyDelete(item, "partitionId");
-        ObjectHelper.propertyDelete(item, "_attachments");
-        ObjectHelper.propertyDelete(item, "_etag");
-        ObjectHelper.propertyDelete(item, "_rid");
-        ObjectHelper.propertyDelete(item, "_self");
-        ObjectHelper.propertyDelete(item, "_ts");
-        return item;
+        return EntityStorageHelper.unPrepareEntity(item, [
+            CosmosDbEntityStorageConnector._PARTITION_KEY,
+            "_attachments",
+            "_etag",
+            "_rid",
+            "_self",
+            "_ts"
+        ]);
     }
     /**
      * Check if the database exists.
@@ -676,5 +1015,19 @@ export class CosmosDbEntityStorageConnector {
             await new Promise(resolve => setTimeout(resolve, 250));
         }
     }
+    /**
+     * Wait for a container to not exist.
+     * @returns Nothing.
+     * @internal
+     */
+    async waitForContainerNotExists() {
+        for (let attempt = 0; attempt < 20; attempt++) {
+            const containerExists = await this.containerExists();
+            if (!containerExists) {
+                break;
+            }
+            await new Promise(resolve => setTimeout(resolve, 250));
+        }
+    }
 }
 //# sourceMappingURL=cosmosDbEntityStorageConnector.js.map