@futdevpro/nts-dynamo 1.15.118 → 1.15.119

package/src/_services/core/migration-runner.service.ts

@@ -0,0 +1,106 @@
+import { DyFM_Error, DyFM_Log } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_SingletonService } from '../base/singleton.service';
+import { DyNTS_DataService } from '../base/data.service';
+import {
+  DyNTS_SchemaMigration, dyNTS_schemaMigration_dataParams,
+} from '../../_models/data-models/schema-migration.data-model';
+import { DyNTS_MigrationEntry } from '../../_models/interfaces/migration-entry.interface';
+
+/** A `runPending` összesítő eredménye. */
+export interface DyNTS_MigrationRunResult {
+  applied: number;
+  skipped: number;
+  failed: number;
+}
+
+/**
+ * **Deploy-integrált migráció-futtató** — bedrock, újrahasználható. Az app a `app.server.postProcess()`-
+ * ből hívja: `DyNTS_Migration_Runner.getInstance().runPending(ALL_MIGRATIONS, appVersion)`.
+ *
+ * Mechanizmus (kanon `deploy-integrated-migrations.md`):
+ *  - Boot-on lekéri a `DyNTS_SchemaMigration` ledgerből a MÁR-alkalmazott `migrationId`-kat.
+ *  - A **pending** (még nem alkalmazott) entry-ket **sorrendben, egyszer** lefuttatja.
+ *  - Mindegyik után egy ledger-sort rögzít (`migrationId` + `appliedAt` + `appliedVersion` + `notes`).
+ *  - **RUN-ONCE:** a `migrationId` unique-index → re-boot / párhuzamos instance esetén skip (duplicate-key).
+ *  - **Boot-safe:** egy hibás migráció NEM állítja meg a boot-ot (catch + notes; a runner tovább megy).
+ */
+export class DyNTS_Migration_Runner extends DyNTS_SingletonService {
+
+  static getInstance(): DyNTS_Migration_Runner {
+    return DyNTS_Migration_Runner.getSingletonInstance();
+  }
+
+  /**
+   * TISZTA pending-szelekció (DB nélkül tesztelhető): azok az entry-k, amiknek az `id`-ja NINCS az
+   * `appliedIds`-ban. A regisztráció sorrendje megőrződik (a bővítés a tömb VÉGÉRE).
+   */
+  static selectPending(
+    migrations: DyNTS_MigrationEntry[],
+    appliedIds: Set<string>,
+  ): DyNTS_MigrationEntry[] {
+    return (migrations ?? []).filter((migration: DyNTS_MigrationEntry): boolean => !appliedIds.has(migration.id));
+  }
+
+  /** A ledger-DataService előállítása. `protected` → a spec felül tudja írni (mock-hoz). */
+  protected createLedgerDataService(issuer: string): DyNTS_DataService<DyNTS_SchemaMigration> {
+    return new DyNTS_DataService<DyNTS_SchemaMigration>(
+      new DyNTS_SchemaMigration(),
+      dyNTS_schemaMigration_dataParams,
+      issuer,
+    );
+  }
+
+  /**
+   * A pending migrációk lefuttatása + rögzítése.
+   *
+   * @param migrations - az app registry-je (`DyNTS_MigrationEntry[]`)
+   * @param appVersion - az app aktuális verziója (a ledger `appliedVersion`-jébe)
+   * @param issuer - opcionális issuer-cimke (default `DyNTS_Migration_Runner`)
+   */
+  async runPending(
+    migrations: DyNTS_MigrationEntry[],
+    appVersion: string,
+    issuer: string = 'DyNTS_Migration_Runner',
+  ): Promise<DyNTS_MigrationRunResult> {
+    const result: DyNTS_MigrationRunResult = { applied: 0, skipped: 0, failed: 0 };
+
+    DyFM_Log.info(`[dynts-migration] sweep start — ${migrations?.length ?? 0} migration(s) registered · appVersion=${appVersion}`);
+
+    const ledger_DS: DyNTS_DataService<DyNTS_SchemaMigration> = this.createLedgerDataService(issuer);
+
+    const applied: DyNTS_SchemaMigration[] = await ledger_DS.dataDBService.find({} as never);
+    const appliedIds: Set<string> = new Set(
+      applied.map((record: DyNTS_SchemaMigration): string => record.migrationId ?? ''),
+    );
+
+    const pending: DyNTS_MigrationEntry[] = DyNTS_Migration_Runner.selectPending(migrations, appliedIds);
+    result.skipped = (migrations?.length ?? 0) - pending.length;
+
+    for (const migration of pending) {
+      try {
+        DyFM_Log.info(`[dynts-migration] applying ${migration.id} — ${migration.description}`);
+        const outcome: { touched: number } = await migration.run(issuer);
+
+        // Atomikus claim — a unique-index dob duplicate-ra (race-safe, két párhuzamos instance).
+        ledger_DS.data = new DyNTS_SchemaMigration({
+          migrationId: migration.id,
+          appliedAt: new Date(),
+          appliedVersion: appVersion,
+          notes: `touched=${outcome?.touched ?? 0}`,
+        });
+        await ledger_DS.saveData();
+
+        DyFM_Log.success(`[dynts-migration] applied ${migration.id} (touched=${outcome?.touched ?? 0})`);
+        result.applied++;
+      } catch (error) {
+        // Egy hibás migráció NEM állíthatja meg a boot-ot (catch + log; a következő entry mehet).
+        DyFM_Error.logSimple(`[dynts-migration] FAILED ${migration.id}`, error);
+        result.failed++;
+      }
+    }
+
+    DyFM_Log.info(`[dynts-migration] sweep done — applied=${result.applied} skipped=${result.skipped} failed=${result.failed}`);
+    return result;
+  }
+}

package/src/index.ts

@@ -53,6 +53,7 @@ export * from './_models/interfaces/static-client-settings.interface';
 export * from './_models/interfaces/cors-settings.interface';
 export * from './_models/interfaces/security-headers-settings.interface';
 export * from './_models/interfaces/db-query-options.interface';
+export * from './_models/interfaces/migration-entry.interface';
 export * from './_collections/security-headers.util';
 export * from './_collections/client-safe-error.util';
 export * from './_collections/load-shed.util';
@@ -70,6 +71,9 @@ export * from './_models/control-models/system-control.control-model';
 // models/TYPES
 export * from './_models/types/db-update.type';
 
+// models/DATA-MODELS
+export * from './_models/data-models/schema-migration.data-model';
+
 
 // SERVICES
 // services/CORE
@@ -82,6 +86,7 @@ export * from './_services/core/global.service';
 export * from './_services/core/memory-guard.service';
 
 export * from './_services/core/service-collection.service';
+export * from './_services/core/migration-runner.service';
 
 // services/BASE
 export * from './_services/base/api.service-base';