@open-mercato/shared 0.6.4-develop.4210.1.d412061cfe → 0.6.4-develop.4217.1.c9aa050183

package/dist/lib/commands/flush.js

@@ -6,21 +6,26 @@ async function withAtomicFlush(em, phases, options) {
     }
     await em.flush();
   };
-  if (options?.transaction) {
-    await em.begin();
+  if (!options?.transaction) {
+    await runPhasesAndFlush();
+    return;
+  }
+  const isInTransaction = em.isInTransaction;
+  if (typeof isInTransaction === "function" && isInTransaction.call(em)) {
+    await runPhasesAndFlush();
+    return;
+  }
+  await em.begin(options.isolationLevel ? { isolationLevel: options.isolationLevel } : void 0);
+  try {
+    await runPhasesAndFlush();
+    await em.commit();
+  } catch (err) {
     try {
-      await runPhasesAndFlush();
-      await em.commit();
-    } catch (err) {
-      try {
-        await em.rollback();
-      } catch {
-      }
-      throw err;
+      await em.rollback();
+    } catch {
     }
-    return;
+    throw err;
   }
-  await runPhasesAndFlush();
 }
 export {
   withAtomicFlush

package/dist/lib/commands/flush.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/commands/flush.ts"],
-  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\n\n/**\n * Wraps multiple mutation phases in a single atomic flush.\n *\n * Prevents partial commits when a command mutates entities across\n * multiple phases (e.g., scalar mutations + relation syncs).\n * Each phase function runs sequentially; a single `em.flush()`\n * commits all changes at the end on the same `EntityManager` the\n * phases mutate, so closures over `em` stay valid.\n *\n * When `options.transaction` is true, the whole sequence runs\n * inside a database transaction (`em.begin()` / `em.commit()` /\n * `em.rollback()`) for all-or-nothing semantics. The outer `em`\n * stays bound to the transaction, so phases that close over `em`\n * participate in the same transaction.\n *\n * When `phases` is empty the call is a true no-op \u2014 no flush,\n * no transaction. Callers that need an explicit commit should\n * pass at least one phase.\n *\n * Keep side-effect emissions (`emitCrudSideEffects` etc.) OUTSIDE\n * the `withAtomicFlush` block \u2014 they should only fire after commit.\n */\nexport async function withAtomicFlush(\n  em: EntityManager,\n  phases: Array<() => void | Promise<void>>,\n  options?: { transaction?: boolean },\n): Promise<void> {\n  if (phases.length === 0) return\n\n  const runPhasesAndFlush = async () => {\n    for (const phase of phases) {\n      await phase()\n    }\n    await em.flush()\n  }\n\n  if (options?.transaction) {\n    await em.begin()\n    try {\n      await runPhasesAndFlush()\n      await em.commit()\n    } catch (err) {\n      try {\n        await em.rollback()\n      } catch {\n        // rollback failure should not mask the original error; intentionally swallowed\n      }\n      throw err\n    }\n    return\n  }\n\n  await runPhasesAndFlush()\n}\n"],
-  "mappings": "AAwBA,eAAsB,gBACpB,IACA,QACA,SACe;AACf,MAAI,OAAO,WAAW,EAAG;AAEzB,QAAM,oBAAoB,YAAY;AACpC,eAAW,SAAS,QAAQ;AAC1B,YAAM,MAAM;AAAA,IACd;AACA,UAAM,GAAG,MAAM;AAAA,EACjB;AAEA,MAAI,SAAS,aAAa;AACxB,UAAM,GAAG,MAAM;AACf,QAAI;AACF,YAAM,kBAAkB;AACxB,YAAM,GAAG,OAAO;AAAA,IAClB,SAAS,KAAK;AACZ,UAAI;AACF,cAAM,GAAG,SAAS;AAAA,MACpB,QAAQ;AAAA,MAER;AACA,YAAM;AAAA,IACR;AACA;AAAA,EACF;AAEA,QAAM,kBAAkB;AAC1B;",
+  "sourcesContent": ["import type { EntityManager } from '@mikro-orm/postgresql'\nimport type { IsolationLevel } from '@mikro-orm/core'\n\n/**\n * Options controlling how {@link withAtomicFlush} executes its phases.\n */\nexport type AtomicFlushOptions = {\n  /**\n   * When true, the whole sequence runs inside a database transaction for\n   * all-or-nothing semantics. Default: false (a single `em.flush()` commits\n   * all phases at the end \u2014 no transaction).\n   */\n  transaction?: boolean\n  /**\n   * Optional transaction isolation level, forwarded to `em.begin()`. Only\n   * honoured when this call opens a new top-level transaction (i.e.\n   * `transaction: true` and the EntityManager is not already inside a\n   * transaction). Ignored when joining an ambient transaction.\n   */\n  isolationLevel?: IsolationLevel\n  /**\n   * Optional label for diagnostics. Currently informational only.\n   */\n  label?: string\n}\n\n/**\n * Wraps multiple mutation phases in a single atomic flush.\n *\n * Prevents partial commits when a command mutates entities across\n * multiple phases (e.g., scalar mutations + relation syncs).\n * Each phase function runs sequentially; a single `em.flush()`\n * commits all changes at the end on the same `EntityManager` the\n * phases mutate, so closures over `em` stay valid.\n *\n * When `options.transaction` is true, the whole sequence runs\n * inside a database transaction for all-or-nothing semantics.\n *\n * ## Re-entrancy / composability\n *\n * `withAtomicFlush({ transaction: true })` is safe to nest. If the\n * supplied `EntityManager` is **already inside a transaction**, this\n * call does NOT open a second one (raw `em.begin()` would clobber the\n * active `#transactionContext` and orphan the outer transaction \u2014 unlike\n * `em.transactional()`, MikroORM's `em.begin()` does not check\n * `isInTransaction()`). Instead it joins the ambient transaction: the\n * phases run and flush within it, and the outermost caller owns the final\n * `commit()` / `rollback()`. A phase error therefore rolls back the entire\n * enclosing transaction (all-or-nothing across the whole nest).\n *\n * This mirrors the contract every command relies on: each command forks\n * the request `EntityManager` first, so the common case opens a fresh\n * top-level transaction; nesting only happens when one transactional unit\n * is composed inside another on the same `em`.\n *\n * When `phases` is empty the call is a true no-op \u2014 no flush,\n * no transaction. Callers that need an explicit commit should\n * pass at least one phase.\n *\n * Keep side-effect emissions (`emitCrudSideEffects` etc.) OUTSIDE\n * the `withAtomicFlush` block \u2014 they should only fire after commit.\n */\nexport async function withAtomicFlush(\n  em: EntityManager,\n  phases: Array<() => void | Promise<void>>,\n  options?: AtomicFlushOptions,\n): Promise<void> {\n  if (phases.length === 0) return\n\n  const runPhasesAndFlush = async () => {\n    for (const phase of phases) {\n      await phase()\n    }\n    await em.flush()\n  }\n\n  if (!options?.transaction) {\n    await runPhasesAndFlush()\n    return\n  }\n\n  // Re-entrancy guard: never open a nested transaction with raw begin/commit.\n  // If a transaction is already active on this EntityManager, join it \u2014 the\n  // outermost caller owns commit/rollback. A phase error propagates and rolls\n  // back the whole enclosing transaction.\n  //\n  // Guard the probe: real MikroORM EntityManagers always implement\n  // `isInTransaction()`, but partial / mock EMs may not. A missing method is\n  // treated as \"not in a transaction\", so this call opens its own top-level\n  // transaction via the begin/commit path below (which those EMs do support).\n  const isInTransaction = (em as { isInTransaction?: () => boolean }).isInTransaction\n  if (typeof isInTransaction === 'function' && isInTransaction.call(em)) {\n    await runPhasesAndFlush()\n    return\n  }\n\n  await em.begin(options.isolationLevel ? { isolationLevel: options.isolationLevel } : undefined)\n  try {\n    await runPhasesAndFlush()\n    await em.commit()\n  } catch (err) {\n    try {\n      await em.rollback()\n    } catch {\n      // rollback failure should not mask the original error; intentionally swallowed\n    }\n    throw err\n  }\n}\n"],
+  "mappings": "AA8DA,eAAsB,gBACpB,IACA,QACA,SACe;AACf,MAAI,OAAO,WAAW,EAAG;AAEzB,QAAM,oBAAoB,YAAY;AACpC,eAAW,SAAS,QAAQ;AAC1B,YAAM,MAAM;AAAA,IACd;AACA,UAAM,GAAG,MAAM;AAAA,EACjB;AAEA,MAAI,CAAC,SAAS,aAAa;AACzB,UAAM,kBAAkB;AACxB;AAAA,EACF;AAWA,QAAM,kBAAmB,GAA2C;AACpE,MAAI,OAAO,oBAAoB,cAAc,gBAAgB,KAAK,EAAE,GAAG;AACrE,UAAM,kBAAkB;AACxB;AAAA,EACF;AAEA,QAAM,GAAG,MAAM,QAAQ,iBAAiB,EAAE,gBAAgB,QAAQ,eAAe,IAAI,MAAS;AAC9F,MAAI;AACF,UAAM,kBAAkB;AACxB,UAAM,GAAG,OAAO;AAAA,EAClB,SAAS,KAAK;AACZ,QAAI;AACF,YAAM,GAAG,SAAS;AAAA,IACpB,QAAQ;AAAA,IAER;AACA,UAAM;AAAA,EACR;AACF;",
   "names": []
 }

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.6.4-develop.4210.1.d412061cfe";
+const APP_VERSION = "0.6.4-develop.4217.1.c9aa050183";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.4-develop.4210.1.d412061cfe'\nexport const appVersion = APP_VERSION\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.4-develop.4217.1.c9aa050183'\nexport const appVersion = APP_VERSION\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.4-develop.4210.1.d412061cfe",
+  "version": "0.6.4-develop.4217.1.c9aa050183",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -92,7 +92,7 @@
     "@mikro-orm/core": "^7.1.1",
     "@mikro-orm/decorators": "^7.1.1",
     "@mikro-orm/postgresql": "^7.1.1",
-    "@open-mercato/cache": "0.6.4-develop.4210.1.d412061cfe",
+    "@open-mercato/cache": "0.6.4-develop.4217.1.c9aa050183",
     "dotenv": "^17.4.2",
     "rate-limiter-flexible": "^11.1.0",
     "re2js": "2.8.3",

package/src/lib/commands/__tests__/flush.test.ts

@@ -2,17 +2,19 @@ import { withAtomicFlush } from '../flush'
 
 type FakeEntityManager = {
   flush: jest.Mock<Promise<void>, []>
-  begin: jest.Mock<Promise<void>, []>
+  begin: jest.Mock<Promise<void>, [unknown?]>
   commit: jest.Mock<Promise<void>, []>
   rollback: jest.Mock<Promise<void>, []>
+  isInTransaction: jest.Mock<boolean, []>
 }
 
-function createFakeEm(): FakeEntityManager {
+function createFakeEm(overrides?: { inTransaction?: boolean }): FakeEntityManager {
   return {
     flush: jest.fn().mockResolvedValue(undefined),
     begin: jest.fn().mockResolvedValue(undefined),
     commit: jest.fn().mockResolvedValue(undefined),
     rollback: jest.fn().mockResolvedValue(undefined),
+    isInTransaction: jest.fn().mockReturnValue(overrides?.inTransaction ?? false),
   }
 }
 
@@ -163,4 +165,78 @@ describe('withAtomicFlush', () => {
 
     expect(em.rollback).toHaveBeenCalledTimes(1)
   })
+
+  it('joins an ambient transaction instead of clobbering it (re-entrancy)', async () => {
+    const em = createFakeEm({ inTransaction: true })
+    const phase = jest.fn()
+
+    await withAtomicFlush(em as any, [phase], { transaction: true })
+
+    // Must NOT open/commit a nested transaction — the outermost caller owns it.
+    expect(em.begin).not.toHaveBeenCalled()
+    expect(em.commit).not.toHaveBeenCalled()
+    expect(em.rollback).not.toHaveBeenCalled()
+    expect(phase).toHaveBeenCalledTimes(1)
+    expect(em.flush).toHaveBeenCalledTimes(1)
+  })
+
+  it('propagates a phase error when joining an ambient transaction (no local rollback)', async () => {
+    const em = createFakeEm({ inTransaction: true })
+    const failure = new Error('nested-phase-failure')
+
+    await expect(
+      withAtomicFlush(em as any, [
+        () => {
+          throw failure
+        },
+      ], { transaction: true }),
+    ).rejects.toBe(failure)
+
+    // The enclosing transaction owns rollback; this call must not commit or rollback.
+    expect(em.begin).not.toHaveBeenCalled()
+    expect(em.commit).not.toHaveBeenCalled()
+    expect(em.rollback).not.toHaveBeenCalled()
+    expect(em.flush).not.toHaveBeenCalled()
+  })
+
+  it('forwards isolationLevel to begin when opening a top-level transaction', async () => {
+    const em = createFakeEm()
+
+    await withAtomicFlush(em as any, [() => {}], {
+      transaction: true,
+      isolationLevel: 'serializable' as any,
+    })
+
+    expect(em.begin).toHaveBeenCalledTimes(1)
+    expect(em.begin).toHaveBeenCalledWith({ isolationLevel: 'serializable' })
+    expect(em.commit).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not pass options to begin when no isolationLevel is set', async () => {
+    const em = createFakeEm()
+
+    await withAtomicFlush(em as any, [() => {}], { transaction: true })
+
+    expect(em.begin).toHaveBeenCalledWith(undefined)
+  })
+
+  it('opens its own transaction when the EM does not implement isInTransaction (partial/mock EM)', async () => {
+    // Many command unit tests mock an EntityManager with begin/commit/rollback/flush
+    // but no isInTransaction. The re-entrancy probe must not throw on such EMs — it
+    // treats the missing method as "not in a transaction" and opens its own.
+    const begin = jest.fn().mockResolvedValue(undefined)
+    const commit = jest.fn().mockResolvedValue(undefined)
+    const flush = jest.fn().mockResolvedValue(undefined)
+    const partialEm = { begin, commit, rollback: jest.fn(), flush }
+    const phase = jest.fn()
+
+    await expect(
+      withAtomicFlush(partialEm as any, [phase], { transaction: true }),
+    ).resolves.toBeUndefined()
+
+    expect(begin).toHaveBeenCalledTimes(1)
+    expect(phase).toHaveBeenCalledTimes(1)
+    expect(flush).toHaveBeenCalledTimes(1)
+    expect(commit).toHaveBeenCalledTimes(1)
+  })
 })

package/src/lib/commands/flush.ts

@@ -1,4 +1,28 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
+import type { IsolationLevel } from '@mikro-orm/core'
+
+/**
+ * Options controlling how {@link withAtomicFlush} executes its phases.
+ */
+export type AtomicFlushOptions = {
+  /**
+   * When true, the whole sequence runs inside a database transaction for
+   * all-or-nothing semantics. Default: false (a single `em.flush()` commits
+   * all phases at the end — no transaction).
+   */
+  transaction?: boolean
+  /**
+   * Optional transaction isolation level, forwarded to `em.begin()`. Only
+   * honoured when this call opens a new top-level transaction (i.e.
+   * `transaction: true` and the EntityManager is not already inside a
+   * transaction). Ignored when joining an ambient transaction.
+   */
+  isolationLevel?: IsolationLevel
+  /**
+   * Optional label for diagnostics. Currently informational only.
+   */
+  label?: string
+}
 
 /**
  * Wraps multiple mutation phases in a single atomic flush.
@@ -10,10 +34,24 @@ import type { EntityManager } from '@mikro-orm/postgresql'
  * phases mutate, so closures over `em` stay valid.
  *
  * When `options.transaction` is true, the whole sequence runs
- * inside a database transaction (`em.begin()` / `em.commit()` /
- * `em.rollback()`) for all-or-nothing semantics. The outer `em`
- * stays bound to the transaction, so phases that close over `em`
- * participate in the same transaction.
+ * inside a database transaction for all-or-nothing semantics.
+ *
+ * ## Re-entrancy / composability
+ *
+ * `withAtomicFlush({ transaction: true })` is safe to nest. If the
+ * supplied `EntityManager` is **already inside a transaction**, this
+ * call does NOT open a second one (raw `em.begin()` would clobber the
+ * active `#transactionContext` and orphan the outer transaction — unlike
+ * `em.transactional()`, MikroORM's `em.begin()` does not check
+ * `isInTransaction()`). Instead it joins the ambient transaction: the
+ * phases run and flush within it, and the outermost caller owns the final
+ * `commit()` / `rollback()`. A phase error therefore rolls back the entire
+ * enclosing transaction (all-or-nothing across the whole nest).
+ *
+ * This mirrors the contract every command relies on: each command forks
+ * the request `EntityManager` first, so the common case opens a fresh
+ * top-level transaction; nesting only happens when one transactional unit
+ * is composed inside another on the same `em`.
  *
  * When `phases` is empty the call is a true no-op — no flush,
  * no transaction. Callers that need an explicit commit should
@@ -25,7 +63,7 @@ import type { EntityManager } from '@mikro-orm/postgresql'
 export async function withAtomicFlush(
   em: EntityManager,
   phases: Array<() => void | Promise<void>>,
-  options?: { transaction?: boolean },
+  options?: AtomicFlushOptions,
 ): Promise<void> {
   if (phases.length === 0) return
 
@@ -36,21 +74,36 @@ export async function withAtomicFlush(
     await em.flush()
   }
 
-  if (options?.transaction) {
-    await em.begin()
-    try {
-      await runPhasesAndFlush()
-      await em.commit()
-    } catch (err) {
-      try {
-        await em.rollback()
-      } catch {
-        // rollback failure should not mask the original error; intentionally swallowed
-      }
-      throw err
-    }
+  if (!options?.transaction) {
+    await runPhasesAndFlush()
+    return
+  }
+
+  // Re-entrancy guard: never open a nested transaction with raw begin/commit.
+  // If a transaction is already active on this EntityManager, join it — the
+  // outermost caller owns commit/rollback. A phase error propagates and rolls
+  // back the whole enclosing transaction.
+  //
+  // Guard the probe: real MikroORM EntityManagers always implement
+  // `isInTransaction()`, but partial / mock EMs may not. A missing method is
+  // treated as "not in a transaction", so this call opens its own top-level
+  // transaction via the begin/commit path below (which those EMs do support).
+  const isInTransaction = (em as { isInTransaction?: () => boolean }).isInTransaction
+  if (typeof isInTransaction === 'function' && isInTransaction.call(em)) {
+    await runPhasesAndFlush()
     return
   }
 
-  await runPhasesAndFlush()
+  await em.begin(options.isolationLevel ? { isolationLevel: options.isolationLevel } : undefined)
+  try {
+    await runPhasesAndFlush()
+    await em.commit()
+  } catch (err) {
+    try {
+      await em.rollback()
+    } catch {
+      // rollback failure should not mask the original error; intentionally swallowed
+    }
+    throw err
+  }
 }