@memberjunction/metadata-sync 6.1.2 → 6.1.4

package/dist/lib/graph-provider-pool.js

@@ -1,26 +1,61 @@
 /**
- * One independent provider per JSON-root graph for `mj sync push`.
+ * Provider assignment per JSON-root graph for `mj sync push`.
  *
- * Sibling graphs may run in parallel; a root and its nested relatedEntities share
- * one provider so every DB op in that graph uses the same connection. Mixing the
- * host connection with a graph instance in the same tree is a deadlock (child FK
- * waits on an uncommitted parent).
+ * Two modes, fixed when the pool is built. A pool never mixes them.
  *
- * Drain: a graph is released at the end of a batch when (a) it will not appear
- * at a later level, or (b) its TransactionDepth is 0 (Save already committed,
- * so a fresh instance at the next level is safe). Graphs with leftover depth
- * stay live until their last level. Peak live independent instances is therefore
- * bounded by `--parallel-batch-size`, plus any still-open leftover-depth graphs.
+ * - **`host`** (atomic push, the default): every graph uses the host provider, inside the
+ *   push transaction. Nothing commits until the push commits. The host has ONE transaction
+ *   stack, so graphs must run one at a time: `obtain` throws if a second graph asks for the
+ *   host while another graph still holds it. The caller releases a graph with `drainBatch`.
+ *
+ * - **`independent`** (an entity directory using isolated transactions): each graph gets its own instance from
+ *   `CreateIndependentInstance()` (shared pool, own transaction stack), so sibling graphs can
+ *   run in parallel. A root and its nested relatedEntities share one instance, so every DB op
+ *   in that graph uses the same connection. Each `Save()` commits on its own, so this mode is
+ *   NOT atomic: `onGraphSettled` reports which graphs left committed rows behind.
+ *   If `CreateIndependentInstance` fails, `obtain` throws. It never falls back to the host,
+ *   because mixing the host connection with graph instances is a deadlock (child FK waits on
+ *   an uncommitted parent). The caller decides the mode up front (see `probeIndependentInstances`).
+ *
+ * Drain (independent mode): a graph is released at the end of a batch when (a) it will not
+ * appear at a later level, or (b) its TransactionDepth is 0 (Save already committed, so a fresh
+ * instance at the next level is safe). Graphs with leftover depth stay live until their last
+ * level. Peak live independent instances is therefore bounded by the batch size, plus any
+ * still-open leftover-depth graphs.
  */
+/**
+ * Checks once whether the host can create independent instances. Used to pick the pool mode
+ * before any graph runs, so a push never discovers mid-file that it has to switch topology.
+ * @returns `undefined` when independent instances work, otherwise the reason they do not.
+ */
+export async function probeIndependentInstances(host) {
+    let instance;
+    try {
+        instance = await host.CreateIndependentInstance();
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+    try {
+        await instance.ReleaseIndependentInstance();
+    }
+    catch {
+        /* the probe instance did no work; a failed release changes nothing */
+    }
+    return undefined;
+}
 export class GraphProviderPool {
-    constructor(host, log = () => undefined) {
+    constructor(host, options) {
         this.host = host;
-        this.log = log;
         this.providers = new Map();
         this.lastLevelByGraph = new Map();
-        this.independentUnavailable = false;
-        this.unavailableLogged = false;
         this.anyFailed = false;
+        this.mode = options.mode;
+        this.log = options.log ?? (() => undefined);
+        this.onGraphSettled = options.onGraphSettled;
+    }
+    get Mode() {
+        return this.mode;
     }
     /**
      * Record, per graphId, the highest dependency-level index it occupies so we
@@ -41,54 +76,44 @@ export class GraphProviderPool {
     get hasFailed() {
         return this.anyFailed;
     }
-    /**
-     * Provider for this graph. Never returns a mix: either every graph in the
-     * file gets its own independent instance, or (if the *first*
-     * CreateIndependentInstance fails) every graph uses the host.
-     *
-     * If independent instances already exist and a later CreateIndependentInstance
-     * throws, this throws rather than handing the rest of the file to the host.
-     * Mid-file topology change is the deadlock this pool exists to prevent.
-     *
-     * The host itself is never stored in the map, so release cannot
-     * RollbackTransaction the global push TX.
-     */
+    /** Provider for this graph. See the class comment for the per-mode rules. */
     async obtain(graphId) {
+        if (this.mode === 'host') {
+            return this.obtainHost(graphId);
+        }
         const existing = this.providers.get(graphId);
         if (existing)
             return existing;
-        if (this.independentUnavailable)
-            return this.host;
         try {
             const created = await this.host.CreateIndependentInstance();
             this.providers.set(graphId, created);
             return created;
         }
         catch (e) {
-            const reason = e.message;
-            if (this.providers.size > 0) {
-                throw new Error(`CreateIndependentInstance failed after ${this.providers.size} graph(s) already had independent instances (${reason}). ` +
-                    `Refusing mixed host + independent topology in one file.`);
-            }
-            this.independentUnavailable = true;
-            if (!this.unavailableLogged) {
-                this.unavailableLogged = true;
-                this.log(`⚠️  CreateIndependentInstance unavailable (${reason}); ` +
-                    `ALL graphs in this file use the host provider (inside the push transaction). ` +
-                    `Mixing host + independent instances in one file is a deadlock — we refuse that topology.`);
-            }
-            return this.host;
+            const reason = e instanceof Error ? e.message : String(e);
+            throw new Error(`CreateIndependentInstance failed for graph ${graphId} (${reason}). ` +
+                `Refusing to run this graph on the host provider: mixing host and independent instances is a deadlock.`);
         }
     }
+    obtainHost(graphId) {
+        if (this.hostHolder !== undefined && this.hostHolder !== graphId) {
+            throw new Error(`Graph ${graphId} asked for the host provider while graph ${this.hostHolder} still holds it. ` +
+                `In atomic mode graphs share one transaction stack and must run one at a time.`);
+        }
+        this.hostHolder = graphId;
+        return this.host;
+    }
     /**
-     * Commit-or-rollback + release graphs in this batch that are done:
-     * their last level is `levelIndex`, or TransactionDepth is already 0
-     * (Save settled; a fresh instance at a later level is safe).
-     * Leftover-depth graphs that still appear later stay live.
-     * Returns the first settle error so the caller cannot report success
-     * with uncommitted rows.
+     * Release graphs in this batch that are done. Host mode: frees the host for the next graph
+     * (the push transaction settles it later). Independent mode: commit-or-rollback + release the
+     * graphs whose last level is `levelIndex`, or whose TransactionDepth is already 0.
+     * Returns the first settle error so the caller cannot report success with uncommitted rows.
      */
     async drainBatch(graphIds, levelIndex) {
+        if (this.mode === 'host') {
+            this.releaseHost(graphIds);
+            return undefined;
+        }
         const ending = graphIds.filter((id) => {
             const last = this.lastLevelByGraph.get(id) ?? levelIndex;
             if (last === levelIndex)
@@ -98,52 +123,79 @@ export class GraphProviderPool {
         });
         return this.releaseGraphs(ending);
     }
-    /** Release every remaining independent instance. Safe to call from `finally`. */
+    /** Release every remaining graph. Safe to call from `finally`. */
     async releaseAll() {
+        if (this.mode === 'host') {
+            this.hostHolder = undefined;
+            return undefined;
+        }
         return this.releaseGraphs([...this.providers.keys()]);
     }
+    releaseHost(graphIds) {
+        if (this.hostHolder !== undefined && graphIds.includes(this.hostHolder)) {
+            this.hostHolder = undefined;
+        }
+    }
     async releaseGraphs(ids) {
         let settleError;
         for (const id of ids) {
             const provider = this.providers.get(id);
             this.providers.delete(id);
-            if (!provider || provider === this.host)
+            if (!provider)
                 continue;
+            const error = await this.settleAndRelease(id, provider);
+            settleError ??= error;
+        }
+        return settleError;
+    }
+    /** Settle one independent instance, report the outcome, and always release it. */
+    async settleAndRelease(id, provider) {
+        try {
+            const outcome = await this.settle(provider);
+            this.onGraphSettled?.(id, outcome);
+            return undefined;
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            this.anyFailed = true;
+            this.log(`Failed to settle graph ${id} transaction: ${error.message}`);
+            await this.rollbackQuietly(provider);
+            this.onGraphSettled?.(id, 'rolledBack');
+            return error;
+        }
+        finally {
             try {
-                if (provider.TransactionDepth > 0) {
-                    if (this.anyFailed) {
-                        // Explicit rollback at the call site — do not rely on
-                        // ReleaseIndependentInstance's implicit leftover-depth rollback.
-                        await provider.RollbackTransaction();
-                    }
-                    else {
-                        await provider.CommitTransaction();
-                    }
-                }
+                await provider.ReleaseIndependentInstance();
             }
-            catch (e) {
-                this.anyFailed = true;
-                settleError ??= e;
-                this.log(`Failed to settle graph ${id} transaction: ${e.message}`);
-                try {
-                    if (provider.TransactionDepth > 0) {
-                        await provider.RollbackTransaction();
-                    }
-                }
-                catch {
-                    /* still release */
-                }
+            catch {
+                /* pool-safe: handle already dropped */
             }
-            finally {
-                try {
-                    await provider.ReleaseIndependentInstance();
-                }
-                catch {
-                    /* pool-safe: handle already dropped */
-                }
+        }
+    }
+    /**
+     * Depth 0: every Save on this instance already committed. Leftover depth: commit it, or
+     * roll it back explicitly when the file failed (do not rely on ReleaseIndependentInstance).
+     */
+    async settle(provider) {
+        if (provider.TransactionDepth === 0) {
+            return 'committed';
+        }
+        if (this.anyFailed) {
+            await provider.RollbackTransaction();
+            return 'rolledBack';
+        }
+        await provider.CommitTransaction();
+        return 'committed';
+    }
+    async rollbackQuietly(provider) {
+        try {
+            if (provider.TransactionDepth > 0) {
+                await provider.RollbackTransaction();
             }
         }
-        return settleError;
+        catch {
+            /* still release */
+        }
     }
 }
 //# sourceMappingURL=graph-provider-pool.js.map

package/dist/lib/graph-provider-pool.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-provider-pool.js","sourceRoot":"","sources":["../../src/lib/graph-provider-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAUH,MAAM,OAAO,iBAAiB;IAO5B,YACmB,IAAuB,EACvB,MAAiC,GAAG,EAAE,CAAC,SAAS;QADhD,SAAI,GAAJ,IAAI,CAAmB;QACvB,QAAG,GAAH,GAAG,CAA6C;QARlD,cAAS,GAAG,IAAI,GAAG,EAA6B,CAAC;QACjD,qBAAgB,GAAG,IAAI,GAAG,EAAkB,CAAC;QACtD,2BAAsB,GAAG,KAAK,CAAC;QAC/B,sBAAiB,GAAG,KAAK,CAAC;QAC1B,cAAS,GAAG,KAAK,CAAC;IAKvB,CAAC;IAEJ;;;OAGG;IACH,UAAU,CAAC,MAAyC;QAClD,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC;QAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC5B,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC;IACH,CAAC;IAED,iFAAiF;IACjF,UAAU;QACR,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAM,CAAC,OAAe;QAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,IAAI,IAAI,CAAC,sBAAsB;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC;QAElD,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,yBAAyB,EAAE,CAAC;YAC5D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACrC,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,MAAM,GAAI,CAAW,CAAC,OAAO,CAAC;YACpC,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CACb,0CAA0C,IAAI,CAAC,SAAS,CAAC,IAAI,gDAAgD,MAAM,KAAK;oBACtH,yDAAyD,CAC5D,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,sBAAsB,GAAG,IAAI,CAAC;YACnC,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBAC5B,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC;gBAC9B,IAAI,CAAC,GAAG,CACN,8CAA8C,MAAM,KAAK;oBACvD,+EAA+E;oBAC/E,0FAA0F,CAC7F,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,CAAC,IAAI,CAAC;QACnB,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,UAAU,CAAC,QAAkB,EAAE,UAAkB;QACrD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE;YACpC,MAAM,IAAI,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,UAAU,CAAC;YACzD,IAAI,IAAI,KAAK,UAAU;gBAAE,OAAO,IAAI,CAAC;YACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACxC,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC,gBAAgB,KAAK,CAAC,CAAC;QACtD,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAED,iFAAiF;IACjF,KAAK,CAAC,UAAU;QACd,OAAO,IAAI,CAAC,aAAa,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACxD,CAAC;IAEO,KAAK,CAAC,aAAa,CAAC,GAAa;QACvC,IAAI,WAA8B,CAAC;QACnC,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;YACrB,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACxC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC1B,IAAI,CAAC,QAAQ,IAAI,QAAQ,KAAK,IAAI,CAAC,IAAI;gBAAE,SAAS;YAElD,IAAI,CAAC;gBACH,IAAI,QAAQ,CAAC,gBAAgB,GAAG,CAAC,EAAE,CAAC;oBAClC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;wBACnB,sDAAsD;wBACtD,iEAAiE;wBACjE,MAAM,QAAQ,CAAC,mBAAmB,EAAE,CAAC;oBACvC,CAAC;yBAAM,CAAC;wBACN,MAAM,QAAQ,CAAC,iBAAiB,EAAE,CAAC;oBACrC,CAAC;gBACH,CAAC;YACH,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;gBACtB,WAAW,KAAK,CAAU,CAAC;gBAC3B,IAAI,CAAC,GAAG,CAAC,0BAA0B,EAAE,iBAAkB,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC9E,IAAI,CAAC;oBACH,IAAI,QAAQ,CAAC,gBAAgB,GAAG,CAAC,EAAE,CAAC;wBAClC,MAAM,QAAQ,CAAC,mBAAmB,EAAE,CAAC;oBACvC,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC;oBACP,mBAAmB;gBACrB,CAAC;YACH,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC;oBACH,MAAM,QAAQ,CAAC,0BAA0B,EAAE,CAAC;gBAC9C,CAAC;gBAAC,MAAM,CAAC;oBACP,uCAAuC;gBACzC,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC;CACF"}
+{"version":3,"file":"graph-provider-pool.js","sourceRoot":"","sources":["../../src/lib/graph-provider-pool.ts"],"names":[],"mappings":"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"}

package/dist/lib/push-outcome.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview What a failed `mj sync push` left behind, and how to say so.
+ * @module push-outcome
+ */
+import type { PushWriteMode } from './push-write-mode.js';
+/** A create or update committed outside the push transaction (an isolated directory only). */
+export interface CommittedWrite {
+    /** Absolute path of the metadata file the record came from. */
+    filePath: string;
+    entityName: string;
+    /** Position of the record inside the file, e.g. `MJ: Actions[3]/MJ: Action Params[0]`. */
+    recordPath: string;
+    status: 'created' | 'updated';
+}
+/** What a push had done when it failed. Same shape as the successful result's counts. */
+export interface PushPartialTotals {
+    created: number;
+    updated: number;
+    unchanged: number;
+    deleted: number;
+    skipped: number;
+    deferred: number;
+    errors: number;
+}
+export interface PushAbortedDetails {
+    /** The write modes the directories processed so far were using. */
+    modes: PushWriteMode[];
+    /** Whether the push transaction was rolled back (or was never opened, as in a dry run). */
+    rolledBack: boolean;
+    /** Rows that are still in the database even though the push failed. */
+    committedWrites: CommittedWrite[];
+    /** Counts as far as the push got. Reported so a failed run is still machine-readable. */
+    totals: PushPartialTotals;
+    /** The SQL log for this run, when one was being written. Most wanted on a failure. */
+    sqlLogPath?: string;
+    cause: unknown;
+}
+/**
+ * Thrown by `PushService.push()` whenever a push fails after it started writing.
+ * The message is the original failure's message, so existing callers keep working;
+ * the extra fields let a caller say exactly what is and is not in the database.
+ */
+export declare class PushAbortedError extends Error {
+    /** The write modes in play when the push failed, e.g. `['shared']` or `['shared','isolated']`. */
+    readonly modes: PushWriteMode[];
+    readonly rolledBack: boolean;
+    readonly committedWrites: CommittedWrite[];
+    readonly totals: PushPartialTotals;
+    readonly sqlLogPath?: string;
+    constructor(details: PushAbortedDetails);
+    /** True only when nothing from this push is left in the database. */
+    get NothingCommitted(): boolean;
+}
+/**
+ * The lines that tell the user how a failed push ended. The first line is the summary;
+ * any further lines list the committed records, grouped by file.
+ */
+export declare function describeRollbackOutcome(rolledBack: boolean, committedWrites: CommittedWrite[], cwd: string): string[];
+/** One line per file, then one indented line per committed record. */
+export declare function describeCommittedWrites(committedWrites: CommittedWrite[], cwd: string): string[];
+/**
+ * Message for a failed COMMIT. On PostgreSQL, deferred foreign keys are checked at commit, so
+ * the failure is about the transaction as a whole and cannot be tied to one record.
+ */
+export declare function describeCommitFailure(cause: unknown, platform: string | undefined): string;
+//# sourceMappingURL=push-outcome.d.ts.map

package/dist/lib/push-outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-outcome.d.ts","sourceRoot":"","sources":["../../src/lib/push-outcome.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;CAC/B;AAED,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,2FAA2F;IAC3F,UAAU,EAAE,OAAO,CAAC;IACpB,uEAAuE;IACvE,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,yFAAyF;IACzF,MAAM,EAAE,iBAAiB,CAAC;IAC1B,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,kGAAkG;IAClG,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,cAAc,EAAE,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,kBAAkB;IAUvC,qEAAqE;IACrE,IAAI,gBAAgB,IAAI,OAAO,CAE9B;CACF;AAMD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBrH;AAED,sEAAsE;AACtE,wBAAgB,uBAAuB,CAAC,eAAe,EAAE,cAAc,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAehG;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAS1F"}

package/dist/lib/push-outcome.js

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview What a failed `mj sync push` left behind, and how to say so.
+ * @module push-outcome
+ */
+import path from 'path';
+/**
+ * Thrown by `PushService.push()` whenever a push fails after it started writing.
+ * The message is the original failure's message, so existing callers keep working;
+ * the extra fields let a caller say exactly what is and is not in the database.
+ */
+export class PushAbortedError extends Error {
+    constructor(details) {
+        super(messageOf(details.cause), { cause: details.cause });
+        this.name = 'PushAbortedError';
+        this.modes = details.modes;
+        this.rolledBack = details.rolledBack;
+        this.committedWrites = details.committedWrites;
+        this.totals = details.totals;
+        this.sqlLogPath = details.sqlLogPath;
+    }
+    /** True only when nothing from this push is left in the database. */
+    get NothingCommitted() {
+        return this.rolledBack && this.committedWrites.length === 0;
+    }
+}
+function messageOf(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * The lines that tell the user how a failed push ended. The first line is the summary;
+ * any further lines list the committed records, grouped by file.
+ */
+export function describeRollbackOutcome(rolledBack, committedWrites, cwd) {
+    if (!rolledBack) {
+        return [
+            '❌ Database transaction rollback failed. Check the database before pushing again: ' +
+                'rows written by this push may still be locked or present.',
+            ...describeCommittedWrites(committedWrites, cwd),
+        ];
+    }
+    if (committedWrites.length === 0) {
+        return ['✓ Database transaction rolled back successfully. Nothing from this push was saved.'];
+    }
+    return [
+        `⚠️  The push transaction was rolled back, but ${committedWrites.length} created or updated ` +
+            `record${committedWrites.length === 1 ? '' : 's'} in directories using isolated transactions ` +
+            `${committedWrites.length === 1 ? 'was' : 'were'} already committed and ` +
+            `${committedWrites.length === 1 ? 'is' : 'are'} still in the database. Their files keep the pushed contents.`,
+        ...describeCommittedWrites(committedWrites, cwd),
+    ];
+}
+/** One line per file, then one indented line per committed record. */
+export function describeCommittedWrites(committedWrites, cwd) {
+    const byFile = new Map();
+    for (const write of committedWrites) {
+        const list = byFile.get(write.filePath) ?? [];
+        list.push(write);
+        byFile.set(write.filePath, list);
+    }
+    const lines = [];
+    for (const [filePath, writes] of byFile) {
+        lines.push(`   ${path.relative(cwd, filePath) || filePath}: ${writes.length} committed`);
+        for (const write of writes) {
+            lines.push(`      ${write.status} ${write.entityName} at ${write.recordPath}`);
+        }
+    }
+    return lines;
+}
+/**
+ * Message for a failed COMMIT. On PostgreSQL, deferred foreign keys are checked at commit, so
+ * the failure is about the transaction as a whole and cannot be tied to one record.
+ */
+export function describeCommitFailure(cause, platform) {
+    const base = `The database rejected the commit of the push transaction, so the transaction was not saved: ${messageOf(cause)}`;
+    if (platform === 'postgresql') {
+        return (`${base}. PostgreSQL checks deferred foreign-key constraints when the transaction commits, ` +
+            `so this error is not tied to a single record in the metadata files.`);
+    }
+    return base;
+}
+//# sourceMappingURL=push-outcome.js.map

package/dist/lib/push-outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-outcome.js","sourceRoot":"","sources":["../../src/lib/push-outcome.ts"],"names":[],"mappings":"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"}

package/dist/lib/push-write-mode.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview How `mj sync push` writes the creates and updates of one entity directory.
+ * @module push-write-mode
+ *
+ * - `shared` (default): every save runs on the host provider inside the push transaction, one
+ *   JSON-root graph at a time. A failure anywhere rolls back everything that directory wrote,
+ *   along with every other shared directory in the push.
+ * - `isolated` (`isolatedTransactions: true`, or `--isolated-transactions`): sibling graphs run in
+ *   parallel, each on its own provider instance and therefore its own connection and transaction.
+ *   Each save commits on its own, so a failure does NOT roll those creates and updates back.
+ *
+ * Isolation is chosen **per entity directory**, because entities differ: metadata is simple and
+ * wants atomicity, while an entity that manages its own transaction scopes (an order with journal
+ * entries and payments) may want the parallelism. It cannot be finer than a directory: mixing the
+ * host connection with per-graph connections inside one file is the deadlock the graph pool exists
+ * to prevent.
+ */
+/** How one entity directory's creates and updates are written. */
+export type PushWriteMode = 'shared' | 'isolated';
+/** Default number of JSON-root graphs run at once in an isolated directory. */
+export declare const DEFAULT_PARALLEL_BATCH_SIZE = 10;
+export interface PushWriteModeInput {
+    /** CLI `--isolated-transactions` / `--no-isolated-transactions`. Undefined when not passed. */
+    isolatedFlag?: boolean;
+    /** `push.isolatedTransactions` from this directory's `.mj-sync.json`. */
+    entityIsolated?: boolean;
+    /** `push.isolatedTransactions` from the root `.mj-sync.json`. */
+    rootIsolated?: boolean;
+}
+/** Where a directory's mode came from, for the log line. */
+export type PushWriteModeSource = 'flag' | 'entity' | 'root' | 'default';
+export interface PushDirectoryMode {
+    mode: PushWriteMode;
+    source: PushWriteModeSource;
+}
+/**
+ * The mode for one entity directory. The CLI flag wins over every file, so a run can force either
+ * mode without editing metadata; then the directory's own config, then the root's, then shared.
+ */
+export declare function resolveDirectoryMode(input: PushWriteModeInput): PushDirectoryMode;
+/** Graphs to run at once in a directory of this mode. */
+export declare function graphBatchSizeFor(mode: PushWriteMode, parallelBatchSize?: number): number;
+/** The warning shown once per push that writes any isolated directory to the database. */
+export declare function isolatedModeWarning(directories: string[], graphBatchSize: number): string;
+/** Told once when `--parallel-batch-size` cannot apply, so the flag does not look effective. */
+export declare function unusedBatchSizeWarning(size: number): string;
+//# sourceMappingURL=push-write-mode.d.ts.map

package/dist/lib/push-write-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-write-mode.d.ts","sourceRoot":"","sources":["../../src/lib/push-write-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,kEAAkE;AAClE,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,CAAC;AAElD,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IACjC,+FAA+F;IAC/F,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yEAAyE;IACzE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iEAAiE;IACjE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,4DAA4D;AAC5D,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAEzE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,iBAAiB,CAWjF;AAED,yDAAyD;AACzD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzF;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAOzF;AAED,gGAAgG;AAChG,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM3D"}

package/dist/lib/push-write-mode.js

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview How `mj sync push` writes the creates and updates of one entity directory.
+ * @module push-write-mode
+ *
+ * - `shared` (default): every save runs on the host provider inside the push transaction, one
+ *   JSON-root graph at a time. A failure anywhere rolls back everything that directory wrote,
+ *   along with every other shared directory in the push.
+ * - `isolated` (`isolatedTransactions: true`, or `--isolated-transactions`): sibling graphs run in
+ *   parallel, each on its own provider instance and therefore its own connection and transaction.
+ *   Each save commits on its own, so a failure does NOT roll those creates and updates back.
+ *
+ * Isolation is chosen **per entity directory**, because entities differ: metadata is simple and
+ * wants atomicity, while an entity that manages its own transaction scopes (an order with journal
+ * entries and payments) may want the parallelism. It cannot be finer than a directory: mixing the
+ * host connection with per-graph connections inside one file is the deadlock the graph pool exists
+ * to prevent.
+ */
+/** Default number of JSON-root graphs run at once in an isolated directory. */
+export const DEFAULT_PARALLEL_BATCH_SIZE = 10;
+/**
+ * The mode for one entity directory. The CLI flag wins over every file, so a run can force either
+ * mode without editing metadata; then the directory's own config, then the root's, then shared.
+ */
+export function resolveDirectoryMode(input) {
+    if (input.isolatedFlag !== undefined) {
+        return { mode: input.isolatedFlag ? 'isolated' : 'shared', source: 'flag' };
+    }
+    if (input.entityIsolated !== undefined) {
+        return { mode: input.entityIsolated ? 'isolated' : 'shared', source: 'entity' };
+    }
+    if (input.rootIsolated !== undefined) {
+        return { mode: input.rootIsolated ? 'isolated' : 'shared', source: 'root' };
+    }
+    return { mode: 'shared', source: 'default' };
+}
+/** Graphs to run at once in a directory of this mode. */
+export function graphBatchSizeFor(mode, parallelBatchSize) {
+    return mode === 'isolated' ? parallelBatchSize ?? DEFAULT_PARALLEL_BATCH_SIZE : 1;
+}
+/** The warning shown once per push that writes any isolated directory to the database. */
+export function isolatedModeWarning(directories, graphBatchSize) {
+    const list = directories.join(', ');
+    return (`Isolated transactions (${graphBatchSize} graphs in parallel) for: ${list}. ` +
+        `Each create and update in those directories is committed as soon as it is saved. If the push fails, ` +
+        `those records stay in the database; only the shared directories, the deletes and the deferred records roll back.`);
+}
+/** Told once when `--parallel-batch-size` cannot apply, so the flag does not look effective. */
+export function unusedBatchSizeWarning(size) {
+    return (`--parallel-batch-size=${size} is ignored: no entity directory in this push uses isolated transactions, ` +
+        `so records are saved one graph at a time in a single transaction. ` +
+        `Set push.isolatedTransactions on an entity's .mj-sync.json, or pass --isolated-transactions, to run graphs in parallel.`);
+}
+//# sourceMappingURL=push-write-mode.js.map

package/dist/lib/push-write-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-write-mode.js","sourceRoot":"","sources":["../../src/lib/push-write-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAmB9C;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAyB;IAC5D,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC9E,CAAC;IACD,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACvC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAClF,CAAC;IACD,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC9E,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC/C,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,iBAAiB,CAAC,IAAmB,EAAE,iBAA0B;IAC/E,OAAO,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,iBAAiB,IAAI,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAAC;AACpF,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,mBAAmB,CAAC,WAAqB,EAAE,cAAsB;IAC/E,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,CACL,0BAA0B,cAAc,6BAA6B,IAAI,IAAI;QAC7E,sGAAsG;QACtG,kHAAkH,CACnH,CAAC;AACJ,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,CACL,yBAAyB,IAAI,4EAA4E;QACzG,oEAAoE;QACpE,yHAAyH,CAC1H,CAAC;AACJ,CAAC"}

package/dist/lib/record-primary-key.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Primary-key extraction for pulled records.
+ *
+ * Pull must key every database record by its real primary-key value: the key decides whether a
+ * record updates an existing file entry or is appended as a new one. Reading the key through the
+ * entity's typed property (`record.ID`) only works when the entity's generated subclass is
+ * registered in this process. When it is not — an Open App whose server package did not load, a
+ * host's generated entities package missing from the CLI — the ClassFactory hands back a bare
+ * `BaseEntity`, which has no typed properties, so every record read `undefined`. All records then
+ * shared one key, each overwrote the last in the write batch, and a pull of N new records wrote
+ * exactly one, with an empty `primaryKey` that duplicated on the next pull (#3415).
+ *
+ * `BaseEntity.Get()` is metadata-driven and works on a bare `BaseEntity` as well as on a subclass.
+ */
+import type { BaseEntity, EntityInfo } from '@memberjunction/core';
+import type { RecordData } from './sync-engine.js';
+/** Primary-key values keyed by field name — the shape `RecordData.primaryKey` carries. */
+export type PrimaryKeyValues = NonNullable<RecordData['primaryKey']>;
+/**
+ * Reads every primary-key field of `record` through `BaseEntity.Get()`.
+ *
+ * @throws when a key field has no value. A record without its key cannot be matched to a file
+ *         entry and would overwrite other records, so refusing is the only safe outcome.
+ */
+export declare function extractPrimaryKeyValues(record: BaseEntity, entityInfo: EntityInfo): PrimaryKeyValues;
+/** True when `primaryKey` has at least one field and every field holds a value. */
+export declare function hasCompletePrimaryKey(primaryKey: RecordData['primaryKey']): boolean;
+/**
+ * Builds the string pull uses to match a database record to a file entry: `field:value` segments,
+ * sorted by field name, joined by `|`. `\` and `|` inside a value are escaped, so a value that
+ * contains the separator can't make two different keys produce the same string. The string is only
+ * ever compared in memory — never parsed or persisted.
+ */
+export declare function createPrimaryKeyLookup(primaryKey: RecordData['primaryKey']): string;
+//# sourceMappingURL=record-primary-key.d.ts.map

package/dist/lib/record-primary-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-primary-key.d.ts","sourceRoot":"","sources":["../../src/lib/record-primary-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,0FAA0F;AAC1F,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC;AAErE;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,GAAG,gBAAgB,CAapG;AAUD,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,UAAU,CAAC,YAAY,CAAC,GAAG,OAAO,CAGnF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,UAAU,CAAC,YAAY,CAAC,GAAG,MAAM,CAMnF"}