@itrocks/mysql-maintainer 0.2.8 → 0.3.1

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

@@ -1,16 +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;
-    contexts: Context[];
+    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

@@ -1,20 +1,25 @@
 "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 {
-    contexts = [];
+    contextStorage = new node_async_hooks_1.AsyncLocalStorage();
     errorCount = {};
     superQuery = () => new Promise(() => { });
+    uniqueIndexPromises = new WeakMap();
     async applyTo(connection) {
-        connection.contexts = [];
+        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) {
@@ -24,8 +29,12 @@ class Contextual {
         if (!this.errorCount[sql][error.message]) {
             this.errorCount[sql][error.message] = [];
         }
-        this.errorCount[sql][error.message].push(new Date().getTime());
-        console.log('incremented', this.errorCount[sql][error.message].length, ':', 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) {
@@ -46,7 +55,7 @@ class Contextual {
             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.contexts[this.contexts.length - 1], sql, values)) {
+                && await new mysql_maintainer_2.MysqlMaintainer(this).manageError(error, this.contextStorage.getStore(), sql, values)) {
                 return this.query(sql, values);
             }
             if (mysql_maintainer_1.DEBUG)
@@ -54,6 +63,9 @@ class Contextual {
             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

@@ -4,7 +4,7 @@ import { Connection } from 'mariadb';
 import { QueryOptions } from 'mariadb';
 import { SqlError } from 'mariadb';
 import { Context } from './contextual-connection';
-export { Mysql } from './mysql';
+export { Mysql, UniqueIndexMaintenanceError } from './mysql';
 export declare const DEBUG = false;
 export declare class MysqlMaintainer {
     connection: Connection;

package/cjs/mysql-maintainer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MysqlMaintainer = exports.DEBUG = exports.Mysql = void 0;
+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");
@@ -11,6 +11,7 @@ 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 {

package/cjs/mysql.d.ts

@@ -3,24 +3,30 @@ import { Type } from '@itrocks/class-type';
 import { Mysql as M } from '@itrocks/mysql';
 import { Entity } from '@itrocks/storage';
 import { Identifier } from '@itrocks/storage';
-import { MayEntity } 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>[]>;
-    save<T extends object>(object: MayEntity<T>): 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

@@ -1,91 +1,100 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Mysql = void 0;
+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') {
-        const contexts = (this.connection ?? await this.connect()).contexts;
-        contexts.push(type);
-        const result = await super.deleteId(type, id, property);
-        contexts.pop();
-        return result;
+        return this.withContext(type, () => super.deleteId(type, id, property));
     }
     async deleteRelatedId(object, property, id) {
-        const contexts = (this.connection ?? await this.connect()).contexts;
-        contexts.push(object);
-        const result = await super.deleteRelatedId(object, property, id);
-        contexts.pop();
-        return result;
+        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) {
-        const contexts = (this.connection ?? await this.connect()).contexts;
-        contexts.push(object);
-        const result = await super.insert(object);
-        contexts.pop();
-        return result;
+        return this.withContext(object, async () => {
+            await this.ensureUniqueIndexes((0, class_type_1.typeOf)(object));
+            return super.insert(object);
+        });
     }
     async insertRelatedId(object, property, id) {
-        const contexts = (this.connection ?? await this.connect()).contexts;
-        contexts.push(object);
-        const result = await super.insertRelatedId(object, property, id);
-        contexts.pop();
-        return result;
+        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) {
-        const contexts = (this.connection ?? await this.connect()).contexts;
-        contexts.push(type);
-        const result = await super.read(type, id);
-        contexts.pop();
-        return result;
+        return this.withContext(type, () => super.read(type, id));
     }
     async readCollection(object, property, type) {
-        type ??= new reflect_1.ReflectProperty(object, property).collectionType.elementType.type;
-        const contexts = (this.connection ?? await this.connect()).contexts;
-        contexts.push([object, type]);
-        const result = await super.readCollection(object, property, type);
-        contexts.pop();
-        return result;
+        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_1.ReflectProperty(object, property).collectionType.elementType.type;
-        const contexts = (this.connection ?? await this.connect()).contexts;
-        contexts.push([object, type]);
-        const result = await super.readCollectionIds(object, property, type);
-        contexts.pop();
-        return result;
+        type ??= new reflect_2.ReflectProperty(object, property).collectionType.elementType.type;
+        return this.withContext([object, type], () => super.readCollectionIds(object, property, type));
     }
     async readMultiple(type, ids) {
-        const contexts = (this.connection ?? await this.connect()).contexts;
-        contexts.push(type);
-        const result = await super.readMultiple(type, ids);
-        contexts.pop();
-        return result;
-    }
-    async save(object) {
-        const contexts = (this.connection ?? await this.connect()).contexts;
-        contexts.push(object);
-        const result = await super.save(object);
-        contexts.pop();
-        return result;
+        return this.withContext(type, () => super.readMultiple(type, ids));
     }
     async search(type, search = {}, options) {
-        const contexts = (this.connection ?? await this.connect()).contexts;
-        contexts.push(type);
-        const result = await super.search(type, search, options);
-        contexts.pop();
-        return result;
+        return this.withContext(type, () => super.search(type, search, options));
     }
     async update(object) {
-        const contexts = (this.connection ?? await this.connect()).contexts;
-        contexts.push(object);
-        const result = await super.update(object);
-        contexts.pop();
-        return result;
+        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;

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.8"
+	"version": "0.3.1"
 }