@twin.org/entity-storage-connector-mongodb 0.0.1-next.20

package/dist/esm/index.mjs

@@ -0,0 +1,335 @@
+import { Guards, BaseError, Is, GeneralError } from '@twin.org/core';
+import { EntitySchemaFactory, EntitySchemaHelper, SortDirection, LogicalOperator, ComparisonOperator } from '@twin.org/entity';
+import { LoggingConnectorFactory } from '@twin.org/logging-models';
+import { MongoClient } from 'mongodb';
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Class for performing entity storage operations using MongoDb.
+ */
+class MongoDbEntityStorageConnector {
+    /**
+     * Limit the number of entities when finding.
+     * @internal
+     */
+    static _PAGE_SIZE = 40;
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "MongoDbEntityStorageConnector";
+    /**
+     * The schema for the entity.
+     * @internal
+     */
+    _entitySchema;
+    /**
+     * 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(this.CLASS_NAME, "options", options);
+        Guards.stringValue(this.CLASS_NAME, "options.entitySchema", options.entitySchema);
+        Guards.object(this.CLASS_NAME, "options.config", options.config);
+        Guards.stringValue(this.CLASS_NAME, "options.config.host", options.config.host);
+        Guards.stringValue(this.CLASS_NAME, "options.config.database", options.config.database);
+        Guards.stringValue(this.CLASS_NAME, "options.config.collection", options.config.collection);
+        this._entitySchema = EntitySchemaFactory.get(options.entitySchema);
+        this._config = options.config;
+        this._client = new MongoClient(this.createConnectionConfig());
+    }
+    /**
+     * Initialize the MongoDb environment.
+     * @param nodeLoggingConnectorType Optional type of the logging connector.
+     * @returns A promise that resolves to a boolean indicating success.
+     */
+    async bootstrap(nodeLoggingConnectorType) {
+        const nodeLogging = LoggingConnectorFactory.getIfExists(nodeLoggingConnectorType ?? "node-logging");
+        try {
+            await this._client.connect();
+            await nodeLogging?.log({
+                level: "info",
+                source: this.CLASS_NAME,
+                ts: Date.now(),
+                message: "databaseCreating",
+                data: {
+                    database: this._config.database
+                }
+            });
+            // Create the database if it does not exist
+            this._client.db(this._config.database);
+            await nodeLogging?.log({
+                level: "info",
+                source: this.CLASS_NAME,
+                ts: Date.now(),
+                message: "databaseExists",
+                data: {
+                    database: this._config.database
+                }
+            });
+            await this.getCollection();
+            await nodeLogging?.log({
+                level: "info",
+                source: this.CLASS_NAME,
+                ts: Date.now(),
+                message: "collectionExists",
+                data: {
+                    collection: this._config.collection
+                }
+            });
+        }
+        catch (error) {
+            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: BaseError.fromError(err),
+                    data: {
+                        database: this._config.database
+                    }
+                });
+            }
+            return false;
+        }
+        return true;
+    }
+    /**
+     * 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(this.CLASS_NAME, "id", id);
+        try {
+            const primaryKey = EntitySchemaHelper.getPrimaryKey(this.getSchema());
+            const query = Is.empty(secondaryIndex)
+                ? { [primaryKey.property]: id }
+                : { [secondaryIndex]: id };
+            if (conditions) {
+                for (const condition of conditions) {
+                    query[condition.property] = condition.value;
+                }
+            }
+            const collection = await this.getCollection();
+            const result = await collection.findOne(query);
+            return result;
+        }
+        catch (err) {
+            throw new GeneralError(this.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(this.CLASS_NAME, "entity", entity);
+        const primaryKey = EntitySchemaHelper.getPrimaryKey(this.getSchema());
+        const id = entity[primaryKey.property];
+        try {
+            const filter = { [primaryKey.property]: id };
+            if (Is.arrayValue(conditions)) {
+                for (const condition of conditions) {
+                    filter[condition.property] = condition.value;
+                }
+            }
+            const collection = await this.getCollection();
+            await collection.findOneAndUpdate(filter, { $set: entity }, { upsert: true });
+        }
+        catch (err) {
+            throw new 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) {
+        Guards.stringValue(this.CLASS_NAME, "id", id);
+        try {
+            const primaryKey = EntitySchemaHelper.getPrimaryKey(this.getSchema());
+            const query = { [primaryKey.property]: id };
+            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(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 returnSize = pageSize ?? MongoDbEntityStorageConnector._PAGE_SIZE;
+        const filter = {};
+        if (conditions) {
+            this.buildQueryParameters("", conditions, filter);
+        }
+        const sort = {};
+        if (Array.isArray(sortProperties)) {
+            for (const sortProperty of sortProperties) {
+                const direction = sortProperty.sortDirection === SortDirection.Ascending ? 1 : -1;
+                sort[sortProperty.property] = direction;
+            }
+        }
+        const projection = {};
+        if (properties) {
+            for (const property of properties) {
+                projection[property] = 1;
+            }
+        }
+        const cursorValue = cursor ? Number(cursor) : 0;
+        const collection = await this.getCollection();
+        const entities = await collection
+            ?.find(filter, { projection })
+            .sort(sort)
+            .skip(cursorValue)
+            .limit(returnSize)
+            .toArray();
+        return {
+            entities: entities ?? [],
+            cursor: entities?.length === returnSize ? String(cursorValue + returnSize) : undefined
+        };
+    }
+    /**
+     * Drop the collection.
+     * @returns Nothing.
+     */
+    async collectionDrop() {
+        try {
+            const collection = await this.getCollection();
+            await collection.drop();
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    /**
+     * 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 prop = objectPath ? `${objectPath}.${condition.property}` : String(condition.property);
+            const comparison = this.mapComparisonOperator(condition.comparison, condition.value);
+            filter[prop] = comparison;
+        }
+    }
+    /**
+     * Map the framework comparison operators to those in MongoDB.
+     * @param comparison The comparison operator.
+     * @param value The value to compare.
+     * @returns The MongoDB comparison expression.
+     * @internal
+     */
+    mapComparisonOperator(comparison, value) {
+        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:
+                return { $elemMatch: { $eq: value } };
+            default:
+                throw new GeneralError(this.CLASS_NAME, "unsupportedComparisonOperator", { comparison });
+        }
+    }
+}
+
+export { MongoDbEntityStorageConnector };

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./mongoDbEntityStorageConnector";
+export * from "./models/IMongoDbEntityStorageConnectorConfig";
+export * from "./models/IMongoDbEntityStorageConnectorConstructorOptions";

package/dist/types/models/IMongoDbEntityStorageConnectorConfig.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Configuration for the MongoDb Entity Storage Connector.
+ */
+export interface IMongoDbEntityStorageConnectorConfig {
+    /**
+     * The host for the MongoDb instance.
+     */
+    host: string;
+    /**
+     * The port for the MongoDb instance.
+     */
+    port?: number;
+    /**
+     * The user for the MongoDb instance.
+     */
+    user?: string;
+    /**
+     * The password for the MongoDb instance.
+     */
+    password?: string;
+    /**
+     * The name of the database to be used.
+     */
+    database: string;
+    /**
+     * The name of the collection to be used.
+     */
+    collection: string;
+}

package/dist/types/models/IMongoDbEntityStorageConnectorConstructorOptions.d.ts

@@ -0,0 +1,19 @@
+import type { IMongoDbEntityStorageConnectorConfig } from "./IMongoDbEntityStorageConnectorConfig";
+/**
+ * The options for the MongoDb entity storage connector constructor.
+ */
+export interface IMongoDbEntityStorageConnectorConstructorOptions {
+    /**
+     * The schema for the entity.
+     */
+    entitySchema: string;
+    /**
+     * The type of logging connector to use.
+     * @default logging
+     */
+    loggingConnectorType?: string;
+    /**
+     * The configuration for the connector.
+     */
+    config: IMongoDbEntityStorageConnectorConfig;
+}

package/dist/types/mongoDbEntityStorageConnector.d.ts

@@ -0,0 +1,81 @@
+import { type EntityCondition, type IEntitySchema, SortDirection } from "@twin.org/entity";
+import type { IEntityStorageConnector } from "@twin.org/entity-storage-models";
+import type { IMongoDbEntityStorageConnectorConstructorOptions } from "./models/IMongoDbEntityStorageConnectorConstructorOptions";
+/**
+ * Class for performing entity storage operations using MongoDb.
+ */
+export declare class MongoDbEntityStorageConnector<T = unknown> implements IEntityStorageConnector<T> {
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of MongoDbEntityStorageConnector.
+     * @param options The options for the connector.
+     */
+    constructor(options: IMongoDbEntityStorageConnectorConstructorOptions);
+    /**
+     * Initialize the MongoDb environment.
+     * @param nodeLoggingConnectorType Optional type of the logging connector.
+     * @returns A promise that resolves to a boolean indicating success.
+     */
+    bootstrap(nodeLoggingConnectorType?: string): Promise<boolean>;
+    /**
+     * Get the schema for the entities.
+     * @returns The schema for the entities.
+     */
+    getSchema(): IEntitySchema;
+    /**
+     * 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.
+     */
+    get(id: string, secondaryIndex?: keyof T, conditions?: {
+        property: keyof T;
+        value: unknown;
+    }[]): Promise<T | 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.
+     */
+    set(entity: T, conditions?: {
+        property: keyof T;
+        value: unknown;
+    }[]): Promise<void>;
+    /**
+     * Remove the entity.
+     * @param id The id of the entity to remove.
+     * @param conditions The optional conditions to match for the entities.
+     * @returns Nothing.
+     */
+    remove(id: string, conditions?: {
+        property: keyof T;
+        value: unknown;
+    }[]): Promise<void>;
+    /**
+     * 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.
+     */
+    query(conditions?: EntityCondition<T>, sortProperties?: {
+        property: keyof T;
+        sortDirection: SortDirection;
+    }[], properties?: (keyof T)[], cursor?: string, pageSize?: number): Promise<{
+        entities: Partial<T>[];
+        cursor?: string;
+    }>;
+    /**
+     * Drop the collection.
+     * @returns Nothing.
+     */
+    collectionDrop(): Promise<void>;
+}

package/docs/changelog.md

@@ -0,0 +1,5 @@
+# @twin.org/entity-storage-connector-mongodb - Changelog
+
+## v0.0.1-next.20
+
+- Initial Release

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/entity-storage-connector-mongodb - Examples