@itrocks/mysql-maintainer 0.2.7 → 0.3.0

package/README.md

@@ -68,6 +68,8 @@ composition system's loading rules.
 ## How it works
 
 The package enriches the usual `Mysql` operations with the context required to identify the persistent classes involved.
+Each connection stores that context with `AsyncLocalStorage`, so concurrent operations on different classes cannot
+overwrite one another's maintenance target.
 It intercepts MySQL errors that indicate a missing or outdated table, column, or foreign key, derives the expected
 schema from the object model, applies the required structural changes, and retries the original operation.
 
@@ -82,6 +84,16 @@ For example, a read follows this simplified sequence:
 The exported classes that implement context tracking, error handling, schema updates, and retries are internal
 mechanics of this integration. They are not a separate API that an application needs to call.
 
+Unique indexes declared with `@Unique` are checked before the first insert or update of each persistent class on a
+database connection. This lazy preflight also detects an index added to a class after its table already exists. Writes
+of the same class on the same connection share one preflight, and a new connection performs the check again.
+
+If existing duplicate rows prevent a unique index from being created, the maintainer does not alter or delete those
+rows. It rejects the write with a generic `UniqueIndexMaintenanceError`. Operational logs contain only a fixed event
+name and a driver error code from a closed operational allowlist; they do not contain SQL, parameters, driver messages,
+arbitrary code strings, or stored values. Once an
+operator resolves the duplicates, a later write retries the preflight.
+
 ## Persistent model requirements
 
 Automatic maintenance derives database structure from business classes and their reflection metadata. Those classes

package/cjs/contextual-connection.d.ts

@@ -0,0 +1,20 @@
+import { ObjectOrType } from '@itrocks/class-type';
+import { Type } from '@itrocks/class-type';
+import { Connection } from 'mariadb';
+import { QueryOptions } from 'mariadb';
+import { SqlError } from 'mariadb';
+import { AsyncLocalStorage } from 'node:async_hooks';
+export type Context = ObjectOrType | ObjectOrType[];
+export declare class Contextual implements Partial<Connection> {
+    [x: number]: (() => Promise<void>) | undefined;
+    contextStorage: AsyncLocalStorage<Context>;
+    errorCount: Record<string, Record<string, Array<number>>>;
+    superQuery: <T = any>(sql: string | QueryOptions, values?: any) => Promise<T>;
+    uniqueIndexPromises: WeakMap<Type, Promise<void>>;
+    applyTo(connection: ContextualConnection): Promise<ContextualConnection>;
+    incrementErrorCount(sql: string, error: any): this is Connection;
+    isSqlError(error: any): error is SqlError;
+    query<T = any>(sql: string | QueryOptions, values?: any): Promise<T>;
+    run<T>(context: Context, operation: () => Promise<T>): Promise<T>;
+}
+export type ContextualConnection = Connection & Contextual;

package/cjs/contextual-connection.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Contextual = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+const mysql_maintainer_1 = require("./mysql-maintainer");
+const mysql_maintainer_2 = require("./mysql-maintainer");
+const safe_error_code_1 = require("./safe-error-code");
+const MANAGED_ERROR_CODES = ['ER_BAD_FIELD_ERROR', 'ER_CANNOT_ADD_FOREIGN', 'ER_NO_SUCH_TABLE'];
+class Contextual {
+    contextStorage = new node_async_hooks_1.AsyncLocalStorage();
+    errorCount = {};
+    superQuery = () => new Promise(() => { });
+    uniqueIndexPromises = new WeakMap();
+    async applyTo(connection) {
+        connection.contextStorage = new node_async_hooks_1.AsyncLocalStorage();
+        connection.errorCount = {};
+        connection.incrementErrorCount = Contextual.prototype.incrementErrorCount;
+        connection.isSqlError = Contextual.prototype.isSqlError;
+        connection.run = Contextual.prototype.run;
+        connection.superQuery = connection.query;
+        connection.query = Contextual.prototype.query;
+        connection.uniqueIndexPromises = new WeakMap();
+        return connection;
+    }
+    incrementErrorCount(sql, error) {
+        if (!this.errorCount[sql]) {
+            this.errorCount[sql] = {};
+        }
+        if (!this.errorCount[sql][error.message]) {
+            this.errorCount[sql][error.message] = [];
+        }
+        const errors = this.errorCount[sql][error.message];
+        errors.push(new Date().getTime());
+        console.warn('[@itrocks/mysql-maintainer] Schema maintenance attempt', {
+            attempt: errors.length,
+            code: (0, safe_error_code_1.safeDriverErrorCode)(error)
+        });
+        return true;
+    }
+    isSqlError(error) {
+        return (typeof error === 'object') && !!error.code;
+    }
+    async query(sql, values) {
+        try {
+            if (mysql_maintainer_1.DEBUG)
+                console.log(sql, values);
+            return await this.superQuery(sql, values);
+        }
+        catch (error) {
+            if (!this.isSqlError(error) || !MANAGED_ERROR_CODES.includes(error.code)) {
+                if (mysql_maintainer_1.DEBUG)
+                    console.log('MAINTAINER: throw', error);
+                throw error;
+            }
+            sql = (typeof sql === 'object') ? sql.sql : sql;
+            if (this.incrementErrorCount(sql, error)
+                && (this.errorCount[sql][error.message].length < 5)
+                && await new mysql_maintainer_2.MysqlMaintainer(this).manageError(error, this.contextStorage.getStore(), sql, values)) {
+                return this.query(sql, values);
+            }
+            if (mysql_maintainer_1.DEBUG)
+                console.log('MAINTAINER: throw (2)', error);
+            throw error;
+        }
+    }
+    run(context, operation) {
+        return this.contextStorage.run(context, operation);
+    }
+}
+exports.Contextual = Contextual;
+//# sourceMappingURL=contextual-connection.js.map

package/cjs/mysql-maintainer.d.ts

@@ -0,0 +1,18 @@
+import { ObjectOrType } from '@itrocks/class-type';
+import { Type } from '@itrocks/class-type';
+import { Connection } from 'mariadb';
+import { QueryOptions } from 'mariadb';
+import { SqlError } from 'mariadb';
+import { Context } from './contextual-connection';
+export { Mysql, UniqueIndexMaintenanceError } from './mysql';
+export declare const DEBUG = false;
+export declare class MysqlMaintainer {
+    connection: Connection;
+    constructor(connection: Connection);
+    createImplicitTable(type1: ObjectOrType, type2: ObjectOrType): Promise<boolean>;
+    createTable(type: Type): Promise<boolean>;
+    implicitTableName(type1: ObjectOrType, type2: ObjectOrType): string;
+    manageError(error: SqlError, context: Context, _sql: string | QueryOptions, _values: any[]): Promise<boolean>;
+    updateContextTables(context: Context, tableName?: string): Promise<boolean>;
+    updateTable(type: Type): Promise<boolean>;
+}

package/cjs/mysql-maintainer.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MysqlMaintainer = exports.DEBUG = exports.UniqueIndexMaintenanceError = exports.Mysql = void 0;
+const class_type_1 = require("@itrocks/class-type");
+const mysql_1 = require("@itrocks/mysql");
+const mysql_to_schema_1 = require("@itrocks/mysql-to-schema");
+const reflect_to_schema_1 = require("@itrocks/reflect-to-schema");
+const schema_diff_1 = require("@itrocks/schema-diff");
+const schema_diff_mysql_1 = require("@itrocks/schema-diff-mysql");
+const schema_to_mysql_1 = require("@itrocks/schema-to-mysql");
+const store_1 = require("@itrocks/store");
+var mysql_2 = require("./mysql");
+Object.defineProperty(exports, "Mysql", { enumerable: true, get: function () { return mysql_2.Mysql; } });
+Object.defineProperty(exports, "UniqueIndexMaintenanceError", { enumerable: true, get: function () { return mysql_2.UniqueIndexMaintenanceError; } });
+exports.DEBUG = false;
+const DELETION = false;
+class MysqlMaintainer {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    async createImplicitTable(type1, type2) {
+        const joinTable = this.implicitTableName(type1, type2);
+        const table1 = (0, store_1.storeOf)(type1);
+        const table2 = (0, store_1.storeOf)(type2);
+        const query = `CREATE TABLE \`${joinTable}\` (
+${table1}_id int unsigned NOT NULL,
+${table2}_id int unsigned NOT NULL,
+PRIMARY KEY (${table1}_id, ${table2}_id),
+CONSTRAINT \`${joinTable}.${table1}_id\` FOREIGN KEY (${table1}_id) REFERENCES \`${table1}\` (id) ON DELETE CASCADE ON UPDATE CASCADE,
+CONSTRAINT \`${joinTable}.${table2}_id\` FOREIGN KEY (${table2}_id) REFERENCES \`${table2}\` (id) ON DELETE CASCADE ON UPDATE CASCADE
+)`;
+        await this.connection.query(query);
+        return true;
+    }
+    async createTable(type) {
+        const tableName = (0, store_1.storeOf)(type);
+        if (!tableName) {
+            throw 'No table name for type';
+        }
+        const tableSchema = new reflect_to_schema_1.ReflectToTable().convert(type);
+        const schemaToMysql = new schema_to_mysql_1.SchemaToMysql();
+        const sql = schemaToMysql.sql(tableSchema);
+        await this.connection.query(sql);
+        return true;
+    }
+    implicitTableName(type1, type2) {
+        const table1 = (0, store_1.storeOf)(type1);
+        const table2 = (0, store_1.storeOf)(type2);
+        if (!table1 || !table2) {
+            throw 'Collection objects are not stored';
+        }
+        return (0, mysql_1.joinTableName)(table1, table2);
+    }
+    async manageError(error, context, _sql, _values) {
+        if (exports.DEBUG)
+            console.log('MAINTAINER: manageError', error);
+        switch (error.code) {
+            case 'ER_BAD_FIELD_ERROR':
+            case 'ER_CANNOT_ADD_FOREIGN':
+                return this.updateContextTables(context);
+            case 'ER_NO_SUCH_TABLE':
+                const tableName = /Table '.*?\.(.*?)'/.exec(error.message)?.[1];
+                return this.updateContextTables(context, tableName);
+        }
+        return false;
+    }
+    async updateContextTables(context, tableName) {
+        let result = false;
+        const contexts = Array.isArray(context) ? context : [context];
+        for (const context of contexts) {
+            const type = (0, class_type_1.typeOf)(context);
+            const tableName = (0, store_1.storeOf)(type);
+            if (!tableName) {
+                throw 'No table name for type';
+            }
+            const exists = (await this.connection.query('SHOW TABLES LIKE ?', tableName));
+            result ||= await (exists.length ? this.updateTable(type) : this.createTable(type));
+        }
+        if ((contexts.length === 2) && (this.implicitTableName(contexts[0], contexts[1]) === tableName)) {
+            result ||= await this.createImplicitTable(contexts[0], contexts[1]);
+        }
+        return result;
+    }
+    async updateTable(type) {
+        const tableName = (0, store_1.storeOf)(type);
+        if (!tableName) {
+            throw 'No table name for type';
+        }
+        const classTable = new reflect_to_schema_1.ReflectToTable().convert(type);
+        new mysql_to_schema_1.MysqlToTable(this.connection).normalize(classTable);
+        const mysqlTable = await ((new mysql_to_schema_1.MysqlToTable(this.connection)).convert(tableName));
+        const schemaDiff = new schema_diff_1.TableDiff(mysqlTable, classTable);
+        if (!schemaDiff.additions.length
+            && !schemaDiff.changes.length
+            && (!schemaDiff.deletions.length || !DELETION)
+            && !schemaDiff.tableChanges()) {
+            return false;
+        }
+        const schemaDiffMysql = new schema_diff_mysql_1.SchemaDiffMysql();
+        const sql = schemaDiffMysql.sql(schemaDiff, DELETION);
+        await this.connection.query(sql);
+        return true;
+    }
+}
+exports.MysqlMaintainer = MysqlMaintainer;
+//# sourceMappingURL=mysql-maintainer.js.map

package/cjs/mysql.d.ts

@@ -0,0 +1,32 @@
+import { ObjectOrType } from '@itrocks/class-type';
+import { Type } from '@itrocks/class-type';
+import { Mysql as M } from '@itrocks/mysql';
+import { Entity } from '@itrocks/storage';
+import { Identifier } from '@itrocks/storage';
+import { Options } from '@itrocks/storage';
+import { SearchType } from '@itrocks/storage';
+import { ContextualConnection } from './contextual-connection';
+export declare class UniqueIndexMaintenanceError extends Error {
+    readonly code = "SCHEMA_UNIQUE_INDEX_MAINTENANCE_FAILED";
+    constructor();
+}
+export declare class Mysql extends M {
+    connection?: ContextualConnection;
+    connect(): Promise<ContextualConnection>;
+    deleteId<T extends object>(type: ObjectOrType<T>, id: any, property?: keyof Entity<T>): Promise<void>;
+    deleteRelatedId<T extends Entity>(object: T, property: keyof T, id: Identifier): Promise<void>;
+    ensureUniqueIndexes(type: Type): Promise<void>;
+    private hasUniqueIndexes;
+    insert<T extends object>(object: T): Promise<Entity<T>>;
+    insertRelatedId<T extends Entity>(object: T, property: keyof T, id: Identifier): Promise<void>;
+    protected maintainUniqueIndexes(type: Type, connection: ContextualConnection): Promise<void>;
+    read<T extends object>(type: Type<T>, id: Identifier): Promise<Entity<T>>;
+    readCollection<T extends object, PT extends object>(object: Entity<T>, property: keyof T, type?: Type<PT>): Promise<Awaited<PT & {
+        id: Identifier;
+    }>[]>;
+    readCollectionIds<T extends object, PT extends object>(object: Entity<T>, property: keyof T, type?: Type<PT>): Promise<Identifier[]>;
+    readMultiple<T extends object>(type: Type<T>, ids: Identifier[]): Promise<Entity<T>[]>;
+    search<T extends object>(type: Type<T>, search?: SearchType<T>, options?: Options): Promise<Entity<T>[]>;
+    update<T extends object>(object: Entity<T>): Promise<Entity<T>>;
+    private withContext;
+}

package/cjs/mysql.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Mysql = exports.UniqueIndexMaintenanceError = void 0;
+const class_type_1 = require("@itrocks/class-type");
+const mysql_1 = require("@itrocks/mysql");
+const reflect_1 = require("@itrocks/reflect");
+const reflect_2 = require("@itrocks/reflect");
+const store_1 = require("@itrocks/store");
+const contextual_connection_1 = require("./contextual-connection");
+const mysql_maintainer_1 = require("./mysql-maintainer");
+const safe_error_code_1 = require("./safe-error-code");
+const UNIQUE_INDEX_ERROR_CODE = 'SCHEMA_UNIQUE_INDEX_MAINTENANCE_FAILED';
+class UniqueIndexMaintenanceError extends Error {
+    code = UNIQUE_INDEX_ERROR_CODE;
+    constructor() {
+        super('Unique index maintenance failed');
+        this.name = 'UniqueIndexMaintenanceError';
+    }
+}
+exports.UniqueIndexMaintenanceError = UniqueIndexMaintenanceError;
+class Mysql extends mysql_1.Mysql {
+    async connect() {
+        return contextual_connection_1.Contextual.prototype.applyTo(await super.connect());
+    }
+    async deleteId(type, id, property = 'id') {
+        return this.withContext(type, () => super.deleteId(type, id, property));
+    }
+    async deleteRelatedId(object, property, id) {
+        return this.withContext(object, () => super.deleteRelatedId(object, property, id));
+    }
+    async ensureUniqueIndexes(type) {
+        if (!this.hasUniqueIndexes(type))
+            return;
+        const connection = this.connection ?? await this.connect();
+        const promises = connection.uniqueIndexPromises;
+        const current = promises.get(type);
+        if (current)
+            return current;
+        let maintenance;
+        maintenance = Promise.resolve()
+            .then(() => this.maintainUniqueIndexes(type, connection))
+            .catch(error => {
+            if (promises.get(type) === maintenance)
+                promises.delete(type);
+            console.warn('[@itrocks/mysql-maintainer] Unique index maintenance failed', {
+                code: (0, safe_error_code_1.safeDriverErrorCode)(error),
+                event: 'unique-index-preflight'
+            });
+            throw new UniqueIndexMaintenanceError();
+        });
+        promises.set(type, maintenance);
+        return maintenance;
+    }
+    hasUniqueIndexes(type) {
+        return new reflect_1.ReflectClass(type).properties.some(property => (0, store_1.uniqueOf)(type, property.name) !== false);
+    }
+    async insert(object) {
+        return this.withContext(object, async () => {
+            await this.ensureUniqueIndexes((0, class_type_1.typeOf)(object));
+            return super.insert(object);
+        });
+    }
+    async insertRelatedId(object, property, id) {
+        return this.withContext(object, () => super.insertRelatedId(object, property, id));
+    }
+    async maintainUniqueIndexes(type, connection) {
+        const originalConnection = Object.create(connection);
+        originalConnection.query = ((sql, values) => {
+            return connection.superQuery(sql, values);
+        });
+        await new mysql_maintainer_1.MysqlMaintainer(originalConnection).updateContextTables(type);
+    }
+    async read(type, id) {
+        return this.withContext(type, () => super.read(type, id));
+    }
+    async readCollection(object, property, type) {
+        type ??= new reflect_2.ReflectProperty(object, property).collectionType.elementType.type;
+        return this.withContext([object, type], () => super.readCollection(object, property, type));
+    }
+    async readCollectionIds(object, property, type) {
+        type ??= new reflect_2.ReflectProperty(object, property).collectionType.elementType.type;
+        return this.withContext([object, type], () => super.readCollectionIds(object, property, type));
+    }
+    async readMultiple(type, ids) {
+        return this.withContext(type, () => super.readMultiple(type, ids));
+    }
+    async search(type, search = {}, options) {
+        return this.withContext(type, () => super.search(type, search, options));
+    }
+    async update(object) {
+        return this.withContext(object, async () => {
+            await this.ensureUniqueIndexes((0, class_type_1.typeOf)(object));
+            return super.update(object);
+        });
+    }
+    async withContext(context, operation) {
+        return (this.connection ?? await this.connect()).run(context, operation);
+    }
+}
+exports.Mysql = Mysql;
+//# sourceMappingURL=mysql.js.map

package/cjs/safe-error-code.d.ts

@@ -0,0 +1 @@
+export declare function safeDriverErrorCode(error: unknown): string;

package/cjs/safe-error-code.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeDriverErrorCode = safeDriverErrorCode;
+const SAFE_DRIVER_ERROR_CODES = new Set([
+    'ER_BAD_FIELD_ERROR',
+    'ER_CANNOT_ADD_FOREIGN',
+    'ER_DUP_ENTRY',
+    'ER_NO_SUCH_TABLE'
+]);
+function safeDriverErrorCode(error) {
+    const code = (typeof error === 'object') && error && ('code' in error)
+        ? error.code
+        : undefined;
+    return (typeof code === 'string') && SAFE_DRIVER_ERROR_CODES.has(code) ? code : 'UNKNOWN';
+}
+//# sourceMappingURL=safe-error-code.js.map

package/package.json

@@ -17,6 +17,9 @@
 	},
 	"description": "Reactively maintains database structure by updating schema and retrying on MySQL errors",
 	"devDependencies": {
+		"@itrocks/class-file": "latest",
+		"@itrocks/rename": "latest",
+		"@types/node": "^24.10",
 		"typescript": "^7.0"
 	},
 	"engines": {
@@ -49,7 +52,9 @@
 		"url": "git+https://github.com/itrocks-ts/mysql-maintainer.git"
 	},
 	"scripts": {
-		"build": "tsc"
+		"build": "tsc",
+		"test": "npm run build && node --test \"test/**/*.test.mjs\"",
+		"test:integration": "npm run build && node --test \"test/**/*.integration.mjs\""
 	},
-	"version": "0.2.7"
+	"version": "0.3.0"
 }