@twin.org/entity-storage-connector-mysql 0.0.1-next.18

package/dist/esm/index.mjs

@@ -0,0 +1,506 @@
+import { Guards, BaseError, GeneralError, Is, ObjectHelper } from '@twin.org/core';
+import { EntitySchemaFactory, SortDirection, ComparisonOperator, LogicalOperator, EntitySchemaPropertyType } from '@twin.org/entity';
+import { LoggingConnectorFactory } from '@twin.org/logging-models';
+import { createConnection } from 'mysql2/promise';
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Class for performing entity storage operations using MySql.
+ */
+class MySqlEntityStorageConnector {
+    /**
+     * Limit the number of entities when finding.
+     * @internal
+     */
+    static _PAGE_SIZE = 40;
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "MySqlEntityStorageConnector";
+    /**
+     * The schema for the entity.
+     * @internal
+     */
+    _entitySchema;
+    /**
+     * The configuration for the connector.
+     * @internal
+     */
+    _config;
+    /**
+     * The configuration for the connector.
+     * @internal
+     */
+    _connection;
+    /**
+     * Create a new instance of MySqlEntityStorageConnector.
+     * @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.user", options.config.user);
+        Guards.stringValue(this.CLASS_NAME, "options.config.password", options.config.password);
+        Guards.stringValue(this.CLASS_NAME, "options.config.database", options.config.database);
+        Guards.stringValue(this.CLASS_NAME, "options.config.table", options.config.table);
+        this._entitySchema = EntitySchemaFactory.get(options.entitySchema);
+        this._config = options.config;
+    }
+    /**
+     * Initialize the MySql 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 {
+            const dbConnection = await this.createConnection();
+            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
+            await dbConnection.query(`CREATE DATABASE IF NOT EXISTS \`${this._config.database}\``);
+            await nodeLogging?.log({
+                level: "info",
+                source: this.CLASS_NAME,
+                ts: Date.now(),
+                message: "databaseExists",
+                data: {
+                    database: this._config.database
+                }
+            });
+            await dbConnection.query(`CREATE TABLE IF NOT EXISTS \`${this._config.database}\`.\`${this._config.table}\` (${this.mapMySqlProperties(this._entitySchema)})`);
+            await nodeLogging?.log({
+                level: "info",
+                source: this.CLASS_NAME,
+                ts: Date.now(),
+                message: "tableExists",
+                data: {
+                    table: this._config.table
+                }
+            });
+        }
+        catch (error) {
+            // eslint-disable-next-line no-console
+            console.log("error", 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 MySql.
+     * @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 dbConnection = await this.createConnection();
+            const whereClauses = [];
+            const values = [];
+            if (secondaryIndex) {
+                whereClauses.push(`\`${String(secondaryIndex)}\` = ?`);
+                values.push(id);
+            }
+            else {
+                whereClauses.push("`id` = ?");
+                values.push(id);
+            }
+            if (conditions) {
+                for (const condition of conditions) {
+                    whereClauses.push(`\`${String(condition.property)}\` = ?`);
+                    values.push(condition.value);
+                }
+            }
+            const query = `SELECT * FROM \`${this._config.database}\`.\`${this._config.table}\` WHERE ${whereClauses.join(" AND ")} LIMIT 1`;
+            const [rows] = await dbConnection.query(query, values);
+            if (Array.isArray(rows) && rows.length === 1) {
+                return rows[0];
+            }
+        }
+        catch (err) {
+            throw new 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) {
+        Guards.object(this.CLASS_NAME, "entity", entity);
+        // Validate that the entity matches the schema
+        this.entitySqlVerification(entity);
+        const id = entity["id"];
+        try {
+            if (Is.arrayValue(conditions)) {
+                const itemData = await this.get(id);
+                if (Is.notEmpty(itemData) && !this.verifyConditions(conditions, itemData)) {
+                    return;
+                }
+            }
+            const columns = Object.keys(entity)
+                .map(key => `\`${key}\``)
+                .join(", ");
+            const values = Object.values(entity);
+            const placeholders = values.map(() => "?").join(", ");
+            const dbConnection = await this.createConnection();
+            await dbConnection.query(`INSERT INTO \`${this._config.database}\`.\`${this._config.table}\` (${columns}) VALUES (${placeholders}) ON DUPLICATE KEY UPDATE ${columns
+                .split(", ")
+                .map(col => `${col} = VALUES(${col})`)
+                .join(", ")};`, values.map(value => (typeof value === "object" ? JSON.stringify(value) : value)));
+        }
+        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 dbConnection = await this.createConnection();
+            const itemData = await this.get(id);
+            if (Is.notEmpty(itemData)) {
+                const values = [id];
+                let whereClauses = [];
+                if (Is.arrayValue(conditions)) {
+                    whereClauses = conditions.map(condition => {
+                        values.push(condition.value);
+                        return `\`${String(condition.property)}\` = ?`;
+                    });
+                }
+                const query = `DELETE FROM \`${this._config.database}\`.\`${this._config.table}\` WHERE \`id\` = ?${whereClauses.length > 0 ? ` AND ${whereClauses.join(" AND ")}` : ""}`;
+                await dbConnection.query(query, values);
+            }
+        }
+        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 sql = "";
+        try {
+            const returnSize = pageSize ?? MySqlEntityStorageConnector._PAGE_SIZE;
+            let orderByClause = "";
+            if (Array.isArray(sortProperties)) {
+                const orderClauses = [];
+                for (const sortProperty of sortProperties) {
+                    const direction = sortProperty.sortDirection === SortDirection.Ascending ? "ASC" : "DESC";
+                    orderClauses.push(`\`${String(sortProperty.property)}\` ${direction}`);
+                }
+                orderByClause = `ORDER BY ${orderClauses.join(", ")}`;
+            }
+            const whereClauses = [];
+            const values = [];
+            if (conditions) {
+                this.buildQueryParameters("", conditions, whereClauses, values);
+            }
+            const query = `SELECT ${properties ? properties.map(p => `\`${String(p)}\``).join(", ") : "*"} FROM \`${this._config.database}\`.\`${this._config.table}\` WHERE ${whereClauses.length > 0 ? whereClauses.join(" AND ") : "1"} ${orderByClause} LIMIT ${returnSize} OFFSET ${cursor ? Number(cursor) : 0}`;
+            const dbConnection = await this.createConnection();
+            const [rows] = (await dbConnection?.query(query, values)) ?? [];
+            return {
+                entities: rows,
+                cursor: Array.isArray(rows) && rows.length === returnSize
+                    ? String((cursor ? Number(cursor) : 0) + returnSize)
+                    : undefined
+            };
+        }
+        catch (err) {
+            throw new GeneralError(this.CLASS_NAME, "queryFailed", { sql }, err);
+        }
+    }
+    /**
+     * Drop the table.
+     * @returns Nothing.
+     */
+    async tableDrop() {
+        try {
+            const dbConnection = await this.createConnection();
+            await dbConnection?.query(`DROP TABLE \`${this._config.database}\`.\`${this._config.table}\`;`);
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    /**
+     * Create a new DB connection.
+     * @returns The dynamo db connection.
+     * @internal
+     */
+    async createConnection() {
+        if (this._connection) {
+            return this._connection;
+        }
+        const newConnection = await createConnection(this.createConnectionConfig());
+        this._connection = newConnection;
+        return newConnection;
+    }
+    /**
+     * Create a new DB connection configuration.
+     * @returns The dynamo db connection configuration.
+     * @internal
+     */
+    createConnectionConfig() {
+        return {
+            host: this._config.host,
+            port: this._config.port ?? 3306,
+            user: this._config.user,
+            password: this._config.password
+        };
+    }
+    /**
+     * Create an SQL condition clause.
+     * @param objectPath The path for the nested object.
+     * @param condition The conditions to create the query from.
+     * @param whereClauses The where clauses to use in the query.
+     * @param values The values to use in the query.
+     * @internal
+     */
+    buildQueryParameters(objectPath, condition, whereClauses, values) {
+        if (Is.undefined(condition)) {
+            return;
+        }
+        if ("conditions" in condition) {
+            if (condition.conditions.length === 0) {
+                return;
+            }
+            const joinConditions = condition.conditions.map(c => {
+                const subWhereClauses = [];
+                const subValues = [];
+                this.buildQueryParameters(objectPath, c, subWhereClauses, subValues);
+                values.push(...subValues);
+                return subWhereClauses.join(" AND ");
+            });
+            const logicalOperator = this.mapConditionalOperator(condition.logicalOperator);
+            const queryClause = joinConditions.filter(j => j.length > 0).join(` ${logicalOperator} `);
+            if (queryClause.length > 0) {
+                whereClauses.push(`(${queryClause})`);
+            }
+            return;
+        }
+        const schemaProp = this._entitySchema.properties?.find(p => p.property === condition.property);
+        const comparison = this.mapComparisonOperator(objectPath, condition, schemaProp?.type, values);
+        whereClauses.push(comparison);
+    }
+    /**
+     * Map the framework comparison operators to those in MySQL.
+     * @param objectPath The prefix to use for the condition.
+     * @param comparator The operator to map.
+     * @param type The type of the property.
+     * @param values The values to use in the query.
+     * @returns The comparison expression.
+     * @throws GeneralError if the comparison operator is not supported.
+     * @internal
+     */
+    mapComparisonOperator(objectPath, comparator, type, values) {
+        let prop = objectPath;
+        if (prop.length > 0) {
+            prop += ".";
+        }
+        prop += comparator.property;
+        // prop = prop.replace(/\./g, "->");
+        if (comparator.comparison === ComparisonOperator.In) {
+            const inValues = Array.isArray(comparator.value) ? comparator.value : [comparator.value];
+            values.push(...inValues.map(val => this.propertyToDbValue(val, type)));
+            const placeholders = inValues.map(() => "?").join(", ");
+            return `\`${prop}\` IN (${placeholders})`;
+        }
+        const dbValue = this.propertyToDbValue(comparator.value, type);
+        values.push(dbValue);
+        if (comparator.property.split(".").length > 1) {
+            return `JSON_UNQUOTE(JSON_EXTRACT(\`${comparator.property.split(".")[0]}\`, '$.${comparator.property.split(".").slice(1).join(".")}')) = ?`;
+        }
+        else if (comparator.comparison === ComparisonOperator.Equals) {
+            return `\`${prop}\` = ?`;
+        }
+        else if (comparator.comparison === ComparisonOperator.NotEquals) {
+            return `\`${prop}\` <> ?`;
+        }
+        else if (comparator.comparison === ComparisonOperator.GreaterThan) {
+            return `\`${prop}\` > ?`;
+        }
+        else if (comparator.comparison === ComparisonOperator.LessThan) {
+            return `\`${prop}\` < ?`;
+        }
+        else if (comparator.comparison === ComparisonOperator.GreaterThanOrEqual) {
+            return `\`${prop}\` >= ?`;
+        }
+        else if (comparator.comparison === ComparisonOperator.LessThanOrEqual) {
+            return `\`${prop}\` <= ?`;
+        }
+        else if (comparator.comparison === ComparisonOperator.Includes) {
+            return `JSON_CONTAINS(\`${prop}\`, ?)`;
+        }
+        throw new 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 (Is.object(value)) {
+            return JSON.stringify(value);
+        }
+        if (type === "string") {
+            return String(value);
+        }
+        else if (type === "number") {
+            return Number(value);
+        }
+        else if (type === "boolean") {
+            return Boolean(value);
+        }
+        return value;
+    }
+    /**
+     * Map the framework conditional operators to those in MySQL.
+     * @param operator The operator to map.
+     * @returns The conditional operator.
+     * @throws GeneralError if the conditional operator is not supported.
+     * @internal
+     */
+    mapConditionalOperator(operator) {
+        if ((operator ?? LogicalOperator.And) === LogicalOperator.And) {
+            return "AND";
+        }
+        else if (operator === LogicalOperator.Or) {
+            return "OR";
+        }
+        throw new GeneralError(this.CLASS_NAME, "conditionalNotSupported", { operator });
+    }
+    /**
+     * Verify the conditions for the entity.
+     * @param conditions The conditions to verify.
+     * @internal
+     */
+    verifyConditions(conditions, obj) {
+        return conditions.every(condition => ObjectHelper.propertyGet(obj, condition.property) === condition.value);
+    }
+    /**
+     * Map entity schema properties to SQL properties.
+     * @param entitySchema The schema of the entity.
+     * @returns The SQL properties as a string.
+     * @throws GeneralError if the entity properties do not exist.
+     */
+    mapMySqlProperties(entitySchema) {
+        const sqlTypeMap = {
+            [EntitySchemaPropertyType.String]: "LONGTEXT",
+            [EntitySchemaPropertyType.Number]: "FLOAT",
+            [EntitySchemaPropertyType.Integer]: "INT",
+            [EntitySchemaPropertyType.Object]: "JSON",
+            [EntitySchemaPropertyType.Array]: "JSON",
+            [EntitySchemaPropertyType.Boolean]: "TINYINT(1)"
+        };
+        if (!entitySchema.properties) {
+            throw new GeneralError(this.CLASS_NAME, "entitySchemaPropertiesUndefined");
+        }
+        const primaryKeys = [];
+        const columnDefinitions = entitySchema.properties
+            .map(prop => {
+            const sqlType = sqlTypeMap[prop.type] || "TEXT";
+            const columnName = String(prop.property);
+            const nullable = prop.optional ? " NULL" : " NOT NULL";
+            if (prop.isPrimary) {
+                if (sqlType === "LONGTEXT" || sqlType === "TEXT") {
+                    primaryKeys.push(`${columnName}(255)`);
+                }
+                else {
+                    primaryKeys.push(columnName);
+                }
+            }
+            return `${columnName} ${sqlType}${nullable}`;
+        })
+            .join(", ");
+        const primaryKeyDefinition = primaryKeys.length > 0 ? `, PRIMARY KEY (${primaryKeys.join(", ")})` : "";
+        return columnDefinitions + primaryKeyDefinition;
+    }
+    /**
+     * Validate that the entity matches the schema.
+     * @param entity The entity to validate.
+     * @throws GeneralError if the entity schema properties are undefined or if the entity does not match the schema.
+     */
+    entitySqlVerification(entity) {
+        // Validate that the entity matches the schema
+        if (!this._entitySchema.properties) {
+            throw new GeneralError(this.CLASS_NAME, "entitySchemaPropertiesUndefined");
+        }
+        for (const prop of this._entitySchema.properties) {
+            const value = entity[prop.property];
+            if (value === undefined || value === null) {
+                if (!prop.optional) {
+                    throw new GeneralError(this.CLASS_NAME, "invalidEntity", {
+                        entity,
+                        entitySchema: this._entitySchema
+                    });
+                }
+            }
+            else if (typeof value !== prop.type && (prop.type !== "array" || !Is.array(value))) {
+                throw new GeneralError(this.CLASS_NAME, "invalidEntity", {
+                    entity,
+                    entitySchema: this._entitySchema
+                });
+            }
+        }
+    }
+}
+
+export { MySqlEntityStorageConnector };

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./mysqlEntityStorageConnector";
+export * from "./models/IMySqlEntityStorageConnectorConfig";
+export * from "./models/IMySqlEntityStorageConnectorConstructorOptions";

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

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

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

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

package/dist/types/mysqlEntityStorageConnector.d.ts

@@ -0,0 +1,94 @@
+import { type EntityCondition, type IEntitySchema, SortDirection } from "@twin.org/entity";
+import type { IEntityStorageConnector } from "@twin.org/entity-storage-models";
+import type { IMySqlEntityStorageConnectorConstructorOptions } from "./models/IMySqlEntityStorageConnectorConstructorOptions";
+/**
+ * Class for performing entity storage operations using MySql.
+ */
+export declare class MySqlEntityStorageConnector<T = unknown> implements IEntityStorageConnector<T> {
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of MySqlEntityStorageConnector.
+     * @param options The options for the connector.
+     */
+    constructor(options: IMySqlEntityStorageConnectorConstructorOptions);
+    /**
+     * Initialize the MySql 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 MySql.
+     * @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 table.
+     * @returns Nothing.
+     */
+    tableDrop(): Promise<void>;
+    /**
+     * Map entity schema properties to SQL properties.
+     * @param entitySchema The schema of the entity.
+     * @returns The SQL properties as a string.
+     * @throws GeneralError if the entity properties do not exist.
+     */
+    private mapMySqlProperties;
+    /**
+     * Validate that the entity matches the schema.
+     * @param entity The entity to validate.
+     * @throws GeneralError if the entity schema properties are undefined or if the entity does not match the schema.
+     */
+    private entitySqlVerification;
+}

package/docs/changelog.md

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

package/docs/examples.md

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