@open-mercato/shared 0.6.4-develop.4210.1.d412061cfe → 0.6.4-develop.4236.1.9fa6806b34

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
+  }
 }

package/src/lib/crud/__tests__/crud-factory.test.ts

@@ -4,8 +4,17 @@ jest.mock('@open-mercato/cache', () => ({
 
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { registerApiInterceptors } from '@open-mercato/shared/lib/crud/interceptor-registry'
+import { loadCustomFieldDefinitionIndex } from '@open-mercato/shared/lib/crud/custom-fields'
 import { z } from 'zod'
 
+// Keep the real custom-field helpers but spy on the definition loader so we can
+// assert the factory skips the second DB round-trip when the query engine has
+// already resolved definitions (issue #2133).
+jest.mock('@open-mercato/shared/lib/crud/custom-fields', () => {
+  const actual = jest.requireActual('@open-mercato/shared/lib/crud/custom-fields')
+  return { ...actual, loadCustomFieldDefinitionIndex: jest.fn(async () => new Map()) }
+})
+
 // ---- Mocks ----
 const mockEventBus = { emitEvent: jest.fn() }
 const defaultOrganizationId = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
@@ -25,6 +34,16 @@ let crudMutationGuardService: { validateMutation: jest.Mock; afterMutationSucces
 let mockOrganizationScopeOverride: MockOrganizationScope | null
 
 const em = {
+  transactional: async (cb: () => any) => {
+    const snapshot = Object.fromEntries(Object.entries(db).map(([key, value]) => [key, { ...value }]))
+    try {
+      return await cb()
+    } catch (error) {
+      for (const key of Object.keys(db)) delete db[key]
+      Object.assign(db, snapshot)
+      throw error
+    }
+  },
   create: (_cls: any, data: any) => ({ ...data, id: `id-${idSeq++}` }),
   persist(entity: Rec) {
     db[entity.id] = { ...(db[entity.id] || {} as any), ...entity }
@@ -241,6 +260,64 @@ describe('CRUD Factory', () => {
     }))
   })
 
+  const makeDecoratedRoute = () => makeCrudRoute({
+    metadata: { GET: { requireAuth: true } },
+    orm: { entity: Todo, idField: 'id', orgField: 'organizationId', tenantField: 'tenantId', softDeleteField: 'deletedAt' },
+    indexer: { entityType: 'example.todo' },
+    list: {
+      schema: querySchema,
+      entityId: 'example.todo',
+      fields: ['id', 'title'],
+      buildFilters: () => ({} as any),
+      decorateCustomFields: { entityIds: 'example.todo' },
+    },
+  })
+
+  const colorDefinitionIndex = () => new Map([
+    ['color', [{ key: 'color', label: 'Color', kind: 'text', multi: false, dictionaryId: null, organizationId: null, tenantId: null, priority: 0, updatedAt: 0 }]],
+  ])
+
+  it('reuses query engine custom-field definitions and skips the second DB load (#2133)', async () => {
+    const loadIndexMock = loadCustomFieldDefinitionIndex as unknown as jest.Mock
+    const cfRoute = makeDecoratedRoute()
+    queryEngine.query.mockResolvedValueOnce({
+      items: [{ id: 'id-1', title: 'A', cf_color: 'blue', organization_id: defaultOrganizationId, tenant_id: defaultTenantId }],
+      total: 1,
+      customFieldDefinitions: {
+        index: colorDefinitionIndex(),
+        entityIds: ['example.todo'],
+        tenantId: defaultTenantId,
+        organizationIds: [defaultOrganizationId],
+      },
+    })
+
+    const res = await cfRoute.GET(new Request('http://x/api/example/todos?page=1&pageSize=10&sortField=id&sortDir=asc'))
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(loadIndexMock).not.toHaveBeenCalled()
+    expect(body.items[0].customValues).toEqual({ color: 'blue' })
+  })
+
+  it('falls back to loading definitions when the engine index does not cover the scope', async () => {
+    const loadIndexMock = loadCustomFieldDefinitionIndex as unknown as jest.Mock
+    loadIndexMock.mockResolvedValueOnce(colorDefinitionIndex())
+    const cfRoute = makeDecoratedRoute()
+    queryEngine.query.mockResolvedValueOnce({
+      items: [{ id: 'id-1', title: 'A', cf_color: 'blue', organization_id: defaultOrganizationId, tenant_id: defaultTenantId }],
+      total: 1,
+      customFieldDefinitions: {
+        index: new Map(),
+        entityIds: ['example.todo'],
+        tenantId: defaultTenantId,
+        organizationIds: ['some-other-org'],
+      },
+    })
+
+    const res = await cfRoute.GET(new Request('http://x/api/example/todos?page=1&pageSize=10&sortField=id&sortDir=asc'))
+    expect(res.status).toBe(200)
+    expect(loadIndexMock).toHaveBeenCalledTimes(1)
+  })
+
   it('GET applies ids query filter in query engine path', async () => {
     const idA = '550e8400-e29b-41d4-a716-446655440001'
     const idB = '550e8400-e29b-41d4-a716-446655440002'
@@ -472,6 +549,28 @@ describe('CRUD Factory', () => {
     expect(db[created.id].title).toBe('X2')
   })
 
+  it('POST rolls back the created entity when the custom field write fails', async () => {
+    setRecordCustomFields.mockImplementationOnce(async () => { throw new Error('cf write failed') })
+    const res = await route.POST(new Request('http://x/api/example/todos', { method: 'POST', body: JSON.stringify({ title: 'Atomic', is_done: true, cf_priority: 3 }), headers: { 'content-type': 'application/json' } }))
+    expect(res.status).toBe(500)
+    // Entity write was rolled back together with the failed custom field write
+    expect(Object.values(db)).toHaveLength(0)
+    // No created event/index is emitted for a rolled-back create
+    expect(mockDataEngine.emitOrmEntityEvent).not.toHaveBeenCalled()
+  })
+
+  it('PUT rolls back the entity update when the custom field write fails', async () => {
+    const created = em.create(Todo, { title: 'Before', organizationId: defaultOrganizationId, tenantId: defaultTenantId }) as Rec
+    created.id = '123e4567-e89b-12d3-a456-426614174003'
+    await em.persist(created).flush()
+    setRecordCustomFields.mockImplementationOnce(async () => { throw new Error('cf write failed') })
+    const res = await route.PUT(new Request('http://x/api/example/todos', { method: 'PUT', body: JSON.stringify({ id: created.id, title: 'After', cf_priority: 5 }), headers: { 'content-type': 'application/json' } }))
+    expect(res.status).toBe(500)
+    // The scalar update was rolled back together with the failed custom field write
+    expect(db[created.id].title).toBe('Before')
+    expect(mockDataEngine.emitOrmEntityEvent).not.toHaveBeenCalled()
+  })
+
   it('DELETE soft-deletes entity and emits deleted event', async () => {
     const created = em.create(Todo, { title: 'Y', organizationId: defaultOrganizationId, tenantId: defaultTenantId }) as Rec
     created.id = '123e4567-e89b-12d3-a456-426614174002'

package/src/lib/crud/__tests__/custom-field-definition-index.test.ts

@@ -0,0 +1,136 @@
+import {
+  buildCustomFieldDefinitionIndexFromRows,
+  canReuseCustomFieldDefinitions,
+  resolveCfDefIndexOrgCandidates,
+  type CustomFieldDefinitionRow,
+} from '../custom-field-definition-index'
+
+const row = (overrides: Partial<CustomFieldDefinitionRow> & Pick<CustomFieldDefinitionRow, 'key' | 'entityId'>): CustomFieldDefinitionRow => ({
+  kind: 'text',
+  configJson: {},
+  organizationId: null,
+  tenantId: null,
+  deletedAt: null,
+  updatedAt: null,
+  ...overrides,
+})
+
+describe('buildCustomFieldDefinitionIndexFromRows', () => {
+  it('groups summaries by normalized key and summarizes config', () => {
+    const index = buildCustomFieldDefinitionIndexFromRows([
+      row({ key: 'Color', entityId: 'demo:entity', configJson: { label: 'Colour', multi: true, priority: 2 }, kind: 'select' }),
+    ])
+    expect(Array.from(index.keys())).toEqual(['color'])
+    const summaries = index.get('color')!
+    expect(summaries).toHaveLength(1)
+    expect(summaries[0]).toMatchObject({ key: 'Color', label: 'Colour', kind: 'select', multi: true, priority: 2 })
+  })
+
+  it('sorts summaries within a key by priority, then recency, then key', () => {
+    const index = buildCustomFieldDefinitionIndexFromRows([
+      row({ key: 'color', entityId: 'demo:entity', tenantId: 't1', organizationId: 'o1', configJson: { priority: 5 } }),
+      row({ key: 'color', entityId: 'demo:entity', tenantId: 't1', organizationId: 'o2', configJson: { priority: 1 } }),
+    ], { organizationIds: ['o1', 'o2'] })
+    const summaries = index.get('color')!
+    expect(summaries.map((s) => s.organizationId)).toEqual(['o2', 'o1'])
+  })
+
+  it('excludes soft-deleted rows', () => {
+    const index = buildCustomFieldDefinitionIndexFromRows([
+      row({ key: 'color', entityId: 'demo:entity', deletedAt: new Date('2026-01-01T00:00:00Z') }),
+      row({ key: 'size', entityId: 'demo:entity' }),
+    ])
+    expect(Array.from(index.keys()).sort()).toEqual(['size'])
+  })
+
+  it('keeps null-org rows and rows whose org is a candidate, drops foreign-org rows', () => {
+    const index = buildCustomFieldDefinitionIndexFromRows([
+      row({ key: 'global_field', entityId: 'demo:entity', organizationId: null }),
+      row({ key: 'scoped_field', entityId: 'demo:entity', organizationId: 'org-allowed' }),
+      row({ key: 'foreign_field', entityId: 'demo:entity', organizationId: 'org-other' }),
+    ], { organizationIds: ['org-allowed'] })
+    expect(Array.from(index.keys()).sort()).toEqual(['global_field', 'scoped_field'])
+  })
+
+  it('drops all explicit-org rows when no candidates are supplied', () => {
+    const index = buildCustomFieldDefinitionIndexFromRows([
+      row({ key: 'global_field', entityId: 'demo:entity', organizationId: null }),
+      row({ key: 'scoped_field', entityId: 'demo:entity', organizationId: 'org-allowed' }),
+    ], { organizationIds: [] })
+    expect(Array.from(index.keys()).sort()).toEqual(['global_field'])
+  })
+
+  it('filters by fieldset membership', () => {
+    const index = buildCustomFieldDefinitionIndexFromRows([
+      row({ key: 'a', entityId: 'demo:entity', configJson: { fieldset: 'pack' } }),
+      row({ key: 'b', entityId: 'demo:entity', configJson: { fieldsets: ['pack', 'other'] } }),
+      row({ key: 'c', entityId: 'demo:entity', configJson: { fieldset: 'other' } }),
+    ], { fieldset: 'pack' })
+    expect(Array.from(index.keys()).sort()).toEqual(['a', 'b'])
+  })
+})
+
+describe('resolveCfDefIndexOrgCandidates', () => {
+  it('prefers explicit organization ids and drops blanks', () => {
+    expect(resolveCfDefIndexOrgCandidates(['o1', '', null, 'o2'], 'fallback')).toEqual(['o1', 'o2'])
+  })
+
+  it('falls back to the singleton when no explicit ids are given', () => {
+    expect(resolveCfDefIndexOrgCandidates(null, 'fallback')).toEqual(['fallback'])
+    expect(resolveCfDefIndexOrgCandidates([], 'fallback')).toEqual(['fallback'])
+  })
+
+  it('returns an empty list when neither ids nor fallback resolve', () => {
+    expect(resolveCfDefIndexOrgCandidates(null, null)).toEqual([])
+    expect(resolveCfDefIndexOrgCandidates([], undefined)).toEqual([])
+  })
+})
+
+describe('canReuseCustomFieldDefinitions', () => {
+  const resolved = {
+    index: new Map(),
+    entityIds: ['demo:a', 'demo:b'],
+    tenantId: 't1',
+    organizationIds: ['o1'],
+  }
+
+  it('reuses when entity set, tenant, and org candidates all match (order-insensitive)', () => {
+    expect(canReuseCustomFieldDefinitions(resolved, {
+      entityIds: ['demo:b', 'demo:a'],
+      tenantId: 't1',
+      organizationIds: ['o1'],
+    })).toBe(true)
+  })
+
+  it('does not reuse when tenant differs', () => {
+    expect(canReuseCustomFieldDefinitions(resolved, {
+      entityIds: ['demo:a', 'demo:b'],
+      tenantId: 't2',
+      organizationIds: ['o1'],
+    })).toBe(false)
+  })
+
+  it('does not reuse when entity set differs', () => {
+    expect(canReuseCustomFieldDefinitions(resolved, {
+      entityIds: ['demo:a'],
+      tenantId: 't1',
+      organizationIds: ['o1'],
+    })).toBe(false)
+  })
+
+  it('does not reuse when org candidates differ', () => {
+    expect(canReuseCustomFieldDefinitions(resolved, {
+      entityIds: ['demo:a', 'demo:b'],
+      tenantId: 't1',
+      organizationIds: ['o2'],
+    })).toBe(false)
+  })
+
+  it('does not reuse when nothing was precomputed', () => {
+    expect(canReuseCustomFieldDefinitions(undefined, {
+      entityIds: ['demo:a'],
+      tenantId: 't1',
+      organizationIds: ['o1'],
+    })).toBe(false)
+  })
+})