@twin.org/entity-storage-connector-cosmosdb 0.0.1-next.12

package/dist/cjs/index.cjs

@@ -0,0 +1,597 @@
+'use strict';
+
+var cosmos = require('@azure/cosmos');
+var core = require('@twin.org/core');
+var entity = require('@twin.org/entity');
+var loggingModels = require('@twin.org/logging-models');
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Class for performing entity storage operations using Cosmos DB.
+ */
+class CosmosDbEntityStorageConnector {
+    /**
+     * Limit the number of entities when finding.
+     * @internal
+     */
+    static _PAGE_SIZE = 40;
+    /**
+     * Partition id field name.
+     * @internal
+     */
+    static _PARTITION_ID_NAME = "partitionId";
+    /**
+     * Partition id field path.
+     * @internal
+     */
+    static _PARTITION_ID_PATH = "/partitionId";
+    /**
+     * Partition id field value.
+     * @internal
+     */
+    static _PARTITION_ID_VALUE = "1";
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "CosmosDbEntityStorageConnector";
+    /**
+     * The schema for the entity.
+     * @internal
+     */
+    _entitySchema;
+    /**
+     * The primary key.
+     * @internal
+     */
+    _primaryKey;
+    /**
+     * The configuration for the connector.
+     * @internal
+     */
+    _config;
+    /**
+     * The Cosmos DB client.
+     * @internal
+     */
+    _client;
+    /**
+     * Container user for the data storage.
+     * @internal
+     */
+    _container;
+    /**
+     * Create a new instance of CosmosDbEntityStorageConnector.
+     * @param options The options for the connector.
+     * @param options.entitySchema The schema for the entity.
+     * @param options.loggingConnectorType The type of logging connector to use, defaults to no logging.
+     * @param options.config The configuration for the connector.
+     */
+    constructor(options) {
+        core.Guards.object(this.CLASS_NAME, "options", options);
+        core.Guards.stringValue(this.CLASS_NAME, "options.entitySchema", options.entitySchema);
+        core.Guards.object(this.CLASS_NAME, "options.config", options.config);
+        core.Guards.stringValue(this.CLASS_NAME, "options.config.endpoint", options.config.endpoint);
+        core.Guards.stringValue(this.CLASS_NAME, "options.config.key", options.config.key);
+        core.Guards.stringValue(this.CLASS_NAME, "options.config.databaseId", options.config.databaseId);
+        core.Guards.stringValue(this.CLASS_NAME, "options.config.containerId", options.config.containerId);
+        this._entitySchema = entity.EntitySchemaFactory.get(options.entitySchema);
+        this._primaryKey = entity.EntitySchemaHelper.getPrimaryKey(this._entitySchema);
+        this._config = options.config;
+        this._client = new cosmos.CosmosClient({
+            endpoint: this._config.endpoint,
+            key: this._config.key,
+            diagnosticLevel: cosmos.CosmosDbDiagnosticLevel.debug
+        });
+        this._container = this._client
+            .database(this._config.databaseId)
+            .container(this._config.containerId);
+    }
+    /**
+     * Initialize the Cosmos DB environment.
+     * @param nodeLoggingConnectorType Optional type of the logging connector.
+     * @returns A promise that resolves to a boolean indicating success.
+     */
+    async bootstrap(nodeLoggingConnectorType) {
+        const nodeLogging = loggingModels.LoggingConnectorFactory.getIfExists(nodeLoggingConnectorType ?? "node-logging");
+        // Create the database if it does not exist
+        try {
+            await nodeLogging?.log({
+                level: "info",
+                source: this.CLASS_NAME,
+                ts: Date.now(),
+                message: "databaseCreating",
+                data: {
+                    databaseId: this._config.databaseId
+                }
+            });
+            const { resource: databaseDefinition } = await this._client.databases.createIfNotExists({
+                id: this._config.databaseId
+            });
+            core.Guards.stringValue(this.CLASS_NAME, "databaseDefinition.id", databaseDefinition?.id);
+            await nodeLogging?.log({
+                level: "info",
+                source: this.CLASS_NAME,
+                ts: Date.now(),
+                message: "databaseExists",
+                data: {
+                    databaseId: databaseDefinition.id
+                }
+            });
+        }
+        catch (error) {
+            if (core.BaseError.isErrorCode(error, "Conflict")) {
+                await nodeLogging?.log({
+                    level: "info",
+                    source: this.CLASS_NAME,
+                    ts: Date.now(),
+                    message: "databaseAlreadyExists",
+                    data: {
+                        databaseId: this._config.databaseId
+                    }
+                });
+            }
+            else {
+                const errors = error instanceof AggregateError ? error.errors : [error];
+                for (const err of errors) {
+                    await nodeLogging?.log({
+                        level: "error",
+                        source: this.CLASS_NAME,
+                        ts: Date.now(),
+                        message: "databaseCreateFailed",
+                        error: core.BaseError.fromError(err),
+                        data: {
+                            databaseId: this._config.databaseId
+                        }
+                    });
+                }
+                return false;
+            }
+        }
+        // Create the container if it does not exist
+        try {
+            const { resource: containerDefinition } = await this._client
+                .database(this._config.databaseId)
+                .containers.createIfNotExists({
+                id: this._config.containerId,
+                partitionKey: {
+                    kind: cosmos.PartitionKeyKind.Hash,
+                    paths: [CosmosDbEntityStorageConnector._PARTITION_ID_PATH]
+                }
+            }, { offerThroughput: 400 });
+            if (containerDefinition) {
+                await nodeLogging?.log({
+                    level: "info",
+                    source: this.CLASS_NAME,
+                    ts: Date.now(),
+                    message: "containerExists",
+                    data: {
+                        containerId: this._config.containerId
+                    }
+                });
+            }
+            else {
+                await nodeLogging?.log({
+                    level: "error",
+                    source: this.CLASS_NAME,
+                    ts: Date.now(),
+                    message: "containerNotExisting",
+                    data: {
+                        containerId: this._config.containerId
+                    }
+                });
+                return false;
+            }
+        }
+        catch (error) {
+            await nodeLogging?.log({
+                level: "error",
+                source: this.CLASS_NAME,
+                ts: Date.now(),
+                message: "containerCreateFailed",
+                error: core.BaseError.fromError(error),
+                data: {
+                    containerId: this._config.containerId
+                }
+            });
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Get the schema for the entities.
+     * @returns The schema for the entities.
+     */
+    getSchema() {
+        return this._entitySchema;
+    }
+    /**
+     * Get an entity from Cosmos DB.
+     * @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) {
+        core.Guards.stringValue(this.CLASS_NAME, "id", id);
+        try {
+            // No secondary index or conditions
+            if (core.Is.empty(secondaryIndex) && !core.Is.arrayValue(conditions)) {
+                const { resource: item } = await this._container
+                    .item(id, CosmosDbEntityStorageConnector._PARTITION_ID_VALUE)
+                    .read();
+                return this.itemToEntity(item);
+            }
+            const whereQuery = [
+                `c.${CosmosDbEntityStorageConnector._PARTITION_ID_NAME} = @partitionKey`
+            ];
+            // With a secondary index
+            if (core.Is.stringValue(secondaryIndex)) {
+                const secIndex = secondaryIndex.toString();
+                whereQuery.push(`c.${secIndex} = @id`);
+            }
+            else {
+                whereQuery.push(`c.${this._primaryKey.property} = @id`);
+            }
+            // With conditions
+            if (core.Is.arrayValue(conditions)) {
+                for (const c of conditions) {
+                    const schemaProp = this._entitySchema.properties?.find(p => p.property === c.property);
+                    whereQuery.push(`c.${String(c.property)} = ${this.propertyToDbValue(c.value, schemaProp?.type)}`);
+                }
+            }
+            const query = {
+                query: `SELECT * FROM c WHERE ${whereQuery.join(" AND ")}`,
+                parameters: [
+                    { name: "@id", value: id },
+                    { name: "@partitionKey", value: CosmosDbEntityStorageConnector._PARTITION_ID_VALUE }
+                ]
+            };
+            const { resources: items } = await this._container.items.query(query).fetchAll();
+            if (items.length === 1) {
+                return this.itemToEntity(items[0]);
+            }
+        }
+        catch (err) {
+            if (core.BaseError.isErrorCode(err, "NotFound")) {
+                throw new core.GeneralError(this.CLASS_NAME, "containerDoesNotExist", {
+                    container: this._config.containerId
+                }, err);
+            }
+            throw new core.GeneralError(this.CLASS_NAME, "getFailed", {
+                id
+            }, err);
+        }
+        return undefined;
+    }
+    /**
+     * 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) {
+        core.Guards.object(this.CLASS_NAME, "entity", entity);
+        const id = entity[this._primaryKey.property];
+        try {
+            if (core.Is.arrayValue(conditions)) {
+                const item = await this._container.item(id, CosmosDbEntityStorageConnector._PARTITION_ID_VALUE);
+                const { resource: itemData } = await item.read();
+                if (core.Is.notEmpty(itemData) && !this.verifyConditions(conditions, itemData)) {
+                    return;
+                }
+            }
+            await this._container.items.upsert({
+                id,
+                [CosmosDbEntityStorageConnector._PARTITION_ID_NAME]: CosmosDbEntityStorageConnector._PARTITION_ID_VALUE,
+                ...entity
+            });
+        }
+        catch (err) {
+            if (core.BaseError.isErrorCode(err, "ResourceNotFoundException")) {
+                throw new core.GeneralError(this.CLASS_NAME, "containerDoesNotExist", {
+                    containerId: this._config.containerId
+                }, err);
+            }
+            throw new core.GeneralError(this.CLASS_NAME, "setFailed", {
+                id
+            }, 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) {
+        core.Guards.stringValue(this.CLASS_NAME, "id", id);
+        try {
+            const item = await this._container.item(id, CosmosDbEntityStorageConnector._PARTITION_ID_VALUE);
+            const { resource: itemData } = await item.read();
+            if (core.Is.notEmpty(itemData)) {
+                if (core.Is.arrayValue(conditions) && !this.verifyConditions(conditions, itemData)) {
+                    return;
+                }
+                await item.delete();
+            }
+        }
+        catch (err) {
+            if (core.BaseError.fromError(err) &&
+                core.Is.object(err) &&
+                err.body?.code === "NotFound") {
+                return;
+            }
+            throw new core.GeneralError(this.CLASS_NAME, "removeFailed", {
+                id
+            }, err);
+        }
+    }
+    /**
+     * 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 page of entities.
+     * @param pageSize 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, pageSize) {
+        const sql = "";
+        try {
+            const returnSize = pageSize ?? CosmosDbEntityStorageConnector._PAGE_SIZE;
+            let orderByClause = "";
+            if (Array.isArray(sortProperties)) {
+                if (sortProperties.length > 1) {
+                    throw new core.GeneralError(this.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 core.GeneralError(this.CLASS_NAME, "sortNotIndexed", {
+                            property: sortProperty.property
+                        });
+                    }
+                    const direction = sortProperty.sortDirection === entity.SortDirection.Ascending ? "asc" : "desc";
+                    orderByClause = `ORDER BY c.${String(sortProperty.property)} ${direction}`;
+                }
+            }
+            const attributeNames = {};
+            const attributeValues = {};
+            let queryClause = this.buildQueryParameters("", conditions, attributeNames, attributeValues);
+            if (queryClause.length > 0) {
+                queryClause = ` AND ${queryClause}`;
+            }
+            const querySpecs = {
+                query: `SELECT ${properties ? properties.map(p => `c.${p}`).join(", ") : "*"} FROM c WHERE c.partitionId = @partitionId ${queryClause} ${orderByClause}`,
+                parameters: [
+                    { name: "@partitionId", value: CosmosDbEntityStorageConnector._PARTITION_ID_VALUE },
+                    ...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
+            };
+        }
+        catch (err) {
+            throw new core.GeneralError(this.CLASS_NAME, "queryFailed", { sql }, err);
+        }
+    }
+    /**
+     * Delete the container.
+     * @returns Nothing.
+     */
+    async containerDelete() {
+        try {
+            await this._container.deleteAllItemsForPartitionKey(CosmosDbEntityStorageConnector._PARTITION_ID_VALUE);
+            await this._container.delete();
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    /**
+     * Create an SQL condition clause.
+     * @param objectPath The path for the nested object.
+     * @param condition The conditions to create the query from.
+     * @param attributeNames The attribute names to use in the query.
+     * @param attributeValues The attribute values to use in the query.
+     * @returns The condition clause.
+     * @internal
+     */
+    buildQueryParameters(objectPath, condition, attributeNames, attributeValues) {
+        // If no conditions are defined then return empty string
+        if (core.Is.undefined(condition)) {
+            return "";
+        }
+        if ("conditions" in condition) {
+            if (condition.conditions.length === 0) {
+                return "";
+            }
+            // It's a group of comparisons, so check the individual items and combine with the logical operator
+            const joinConditions = condition.conditions.map(c => this.buildQueryParameters(objectPath, c, attributeNames, attributeValues));
+            const logicalOperator = this.mapConditionalOperator(condition.logicalOperator);
+            const queryClause = joinConditions
+                .filter(j => j.length > 0)
+                .map(j => j)
+                .join(` ${logicalOperator} `);
+            return core.Is.stringValue(queryClause) ? ` (${queryClause}) ` : "";
+        }
+        const schemaProp = this._entitySchema.properties?.find(p => p.property === condition.property);
+        // It's a single value so just create the property comparison for the condition
+        const comparison = this.mapComparisonOperator(objectPath, condition, schemaProp?.type, attributeNames, attributeValues);
+        return comparison;
+    }
+    /**
+     * Map the framework comparison operators to those in CosmosDB.
+     * @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.
+     * @returns The comparison expression.
+     * @throws GeneralError if the comparison operator is not supported.
+     * @internal
+     */
+    mapComparisonOperator(objectPath, comparator, type, attributeNames, attributeValues) {
+        let prop = objectPath;
+        if (prop.length > 0) {
+            prop += ".";
+        }
+        prop += comparator.property;
+        let attributeName = this.populateAttributeNames(prop, attributeNames);
+        let propName = `${attributeName.replace(/\./g, "").replace(/@/g, "")}`;
+        if (core.Is.array(comparator.value)) {
+            const dbValues = comparator.value.map(v => this.propertyToDbValue(v, type));
+            const arrAttributeNames = [];
+            for (let i = 0; i < dbValues.length; i++) {
+                const arrAttributeName = `${propName}${i}`;
+                attributeValues[arrAttributeName] = dbValues[i];
+                arrAttributeNames.push(arrAttributeName);
+            }
+            propName = attributeName;
+            attributeName = `(${arrAttributeNames.map(name => `@${name}`).join(", ")})`;
+        }
+        else {
+            attributeValues[propName] = comparator.value;
+        }
+        const matches = attributeName.split(".").length;
+        if (matches && comparator.comparison === entity.ComparisonOperator.Equals) {
+            attributeName = attributeName
+                .split(".")
+                .map(part => `["${part}"]`)
+                .join("");
+            return `c${attributeName} = @${propName}`;
+        }
+        else if (comparator.comparison === entity.ComparisonOperator.Equals) {
+            return `c.${attributeName} = @${propName}`;
+        }
+        else if (comparator.comparison === entity.ComparisonOperator.NotEquals) {
+            return `c.${attributeName} <> @${propName}`;
+        }
+        else if (comparator.comparison === entity.ComparisonOperator.GreaterThan) {
+            return `c.${attributeName} > @${propName}`;
+        }
+        else if (comparator.comparison === entity.ComparisonOperator.LessThan) {
+            return `c.${attributeName} < @${propName}`;
+        }
+        else if (comparator.comparison === entity.ComparisonOperator.GreaterThanOrEqual) {
+            return `c.${attributeName} >= @${propName}`;
+        }
+        else if (comparator.comparison === entity.ComparisonOperator.LessThanOrEqual) {
+            return `c.${attributeName} <= @${propName}`;
+        }
+        else if (typeof attributeValues[propName] === "object" &&
+            comparator.comparison === entity.ComparisonOperator.Includes) {
+            return `array_contains(c.${attributeName}, @${propName})`;
+        }
+        else if (comparator.comparison === entity.ComparisonOperator.Includes) {
+            return `contains(c.${attributeName}, @${propName})`;
+        }
+        else if (comparator.comparison === entity.ComparisonOperator.NotIncludes) {
+            return `notContains(c.${attributeName}, @${propName})`;
+        }
+        else if (comparator.comparison === entity.ComparisonOperator.In) {
+            return `c.${propName} IN ${attributeName}`;
+        }
+        throw new core.GeneralError(this.CLASS_NAME, "comparisonNotSupported", {
+            comparison: comparator.comparison
+        });
+    }
+    /**
+     * Format a value to insert into DB.
+     * @param value The value to format.
+     * @param type The type for the property.
+     * @returns The value after conversion.
+     * @internal
+     */
+    propertyToDbValue(value, type) {
+        if (core.Is.object(value)) {
+            const map = {};
+            for (const key in value) {
+                map[key] = this.propertyToDbValue(value[key]);
+            }
+            return map;
+        }
+        if (type === "string") {
+            return `${core.Coerce.string(value)}`;
+        }
+        else if (type === "integer" || type === "number") {
+            return core.Coerce.string(value) ?? "";
+        }
+        else if (type === "boolean") {
+            return core.Coerce.boolean(value) ?? false;
+        }
+        return core.Coerce.string(value) ?? "";
+    }
+    /**
+     * Create a unique name for the attribute.
+     * @param name The name to create a unique name for.
+     * @param attributeNames The attribute names to use in the query.
+     * @returns The unique name.
+     * @internal
+     */
+    populateAttributeNames(name, attributeNames) {
+        const parts = name.split(".");
+        const attributeNameParts = [];
+        for (const part of parts) {
+            const hashPart = `${part}`;
+            if (core.Is.empty(attributeNames[hashPart])) {
+                attributeNames[hashPart] = part;
+            }
+            attributeNameParts.push(hashPart);
+        }
+        return attributeNameParts.join(".");
+    }
+    /**
+     * Map the framework conditional operators to those in CosmosDB.
+     * @param operator The operator to map.
+     * @returns The conditional operator.
+     * @throws GeneralError if the conditional operator is not supported.
+     * @internal
+     */
+    mapConditionalOperator(operator) {
+        if ((operator ?? entity.LogicalOperator.And) === entity.LogicalOperator.And) {
+            return "AND";
+        }
+        else if (operator === entity.LogicalOperator.Or) {
+            return "OR";
+        }
+        throw new core.GeneralError(this.CLASS_NAME, "conditionalNotSupported", { operator });
+    }
+    /**
+     * Creates the CosmosDB container to be used if it doesn't exists in the context yet.
+     * @returns The existing container.
+     * @throws GeneralError if the container was not created.
+     * @internal
+     */
+    verifyConditions(conditions, obj) {
+        return conditions.every(condition => core.ObjectHelper.propertyGet(obj, condition.property) === condition.value);
+    }
+    /**
+     * Convert an entity to an item.
+     * @param item The item to convert.
+     * @returns The entity.
+     * @internal
+     */
+    itemToEntity(item) {
+        core.ObjectHelper.propertyDelete(item, "partitionId");
+        core.ObjectHelper.propertyDelete(item, "_attachments");
+        core.ObjectHelper.propertyDelete(item, "_etag");
+        core.ObjectHelper.propertyDelete(item, "_rid");
+        core.ObjectHelper.propertyDelete(item, "_self");
+        core.ObjectHelper.propertyDelete(item, "_ts");
+        return item;
+    }
+}
+
+exports.CosmosDbEntityStorageConnector = CosmosDbEntityStorageConnector;