Documentation

src/db/repositories/circuit.repository.ts

@@ -141,6 +141,8 @@ export class CircuitRepository {
     if (updates.length === 0) {
       return;
     }
+    // better-sqlite3 transactions are synchronous callbacks. Do not make this callback
+    // async or return a Promise, otherwise statements may run outside the transaction scope.
     db.transaction((tx) => {
       const ids = updates.map((entry) => entry.id);
       const existing = tx
@@ -152,6 +154,10 @@ export class CircuitRepository {
         throw new Error("One or more circuit ids are invalid for circuit list.");
       }
 
+      // Direct identifier swaps can violate UNIQUE(circuit_list_id, equipment_identifier)
+      // mid-update (for example A->B while B->A). Two-phase strategy prevents that:
+      // 1) assign unique temporary identifiers for all affected circuits
+      // 2) assign final user-visible identifiers
       const stamp = Date.now();
       for (let index = 0; index < updates.length; index += 1) {
         const entry = updates[index];