@open-mercato/shared 0.6.4-develop.4217.1.c9aa050183 → 0.6.4-develop.4236.1.9fa6806b34

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

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

@@ -0,0 +1,233 @@
+// Core-free building blocks for the custom-field definition index.
+//
+// This module intentionally has ZERO dependency on `@open-mercato/core` (no ORM
+// entity imports) so that infrastructure code such as the query engine can build
+// the same definition index that `custom-fields.ts` produces via MikroORM, without
+// pulling a domain package into the query layer.
+
+export type CustomFieldDefinitionSummary = {
+  key: string
+  label: string | null
+  kind: string | null
+  multi: boolean
+  dictionaryId?: string | null
+  organizationId?: string | null
+  tenantId?: string | null
+  priority: number
+  updatedAt: number
+}
+
+export type CustomFieldDefinitionIndex = Map<string, CustomFieldDefinitionSummary[]>
+
+// Plain-row representation of a `custom_field_defs` record. Both the ORM-backed
+// loader (`custom-fields.ts`) and the Kysely-backed query engine map their native
+// rows into this shape before building an index, so the two paths stay in lockstep.
+export type CustomFieldDefinitionRow = {
+  key: string
+  entityId: string
+  kind: string | null
+  configJson: unknown
+  organizationId: string | null
+  tenantId: string | null
+  deletedAt: Date | string | number | null
+  updatedAt: Date | string | number | null
+}
+
+// The resolved definition index the query engine threads onto its result so the
+// CRUD factory can decorate list rows without reloading definitions (issue #2133).
+export type ResolvedCustomFieldDefinitions = {
+  index: CustomFieldDefinitionIndex
+  entityIds: string[]
+  tenantId: string | null
+  organizationIds: string[]
+}
+
+export function normalizeDefinitionKey(key: unknown): string {
+  if (typeof key !== 'string') return ''
+  const trimmed = key.trim()
+  return trimmed.length ? trimmed.toLowerCase() : ''
+}
+
+export function normalizeDefinitionConfig(raw: unknown): Record<string, any> {
+  if (!raw) return {}
+  if (typeof raw === 'string') {
+    try {
+      const parsed = JSON.parse(raw)
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return { ...(parsed as Record<string, any>) }
+      }
+      return {}
+    } catch {
+      return {}
+    }
+  }
+  if (typeof raw === 'object' && !Array.isArray(raw)) {
+    return { ...(raw as Record<string, any>) }
+  }
+  return {}
+}
+
+export function normalizeFieldsetFilter(input?: string | string[] | null): Set<string | null> | null {
+  if (input == null) return null
+  const values = Array.isArray(input) ? input : [input]
+  const normalized = new Set<string | null>()
+  for (const raw of values) {
+    if (raw == null) continue
+    const trimmed = String(raw).trim()
+    if (!trimmed) {
+      normalized.add(null)
+    } else {
+      normalized.add(trimmed)
+    }
+  }
+  return normalized.size ? normalized : null
+}
+
+function toTimeMs(value: Date | string | number | null | undefined): number {
+  if (value == null) return 0
+  if (value instanceof Date) return value.getTime()
+  const parsed = new Date(value as any).getTime()
+  return Number.isNaN(parsed) ? 0 : parsed
+}
+
+export function summarizeDefinitionRow(row: CustomFieldDefinitionRow): CustomFieldDefinitionSummary | null {
+  const normalizedKey = normalizeDefinitionKey(row.key)
+  if (!normalizedKey) return null
+  const cfg = normalizeDefinitionConfig(row.configJson)
+  const label =
+    typeof cfg.label === 'string' && cfg.label.trim().length
+      ? cfg.label.trim()
+      : row.key
+  const dictionaryId =
+    typeof cfg.dictionaryId === 'string' && cfg.dictionaryId.trim().length
+      ? cfg.dictionaryId.trim()
+      : null
+  const multi = cfg.multi !== undefined ? Boolean(cfg.multi) : false
+  const priority = typeof cfg.priority === 'number' ? cfg.priority : 0
+  return {
+    key: row.key,
+    label,
+    kind: typeof row.kind === 'string' ? row.kind : null,
+    multi,
+    dictionaryId,
+    organizationId: row.organizationId ?? null,
+    tenantId: row.tenantId ?? null,
+    priority,
+    updatedAt: toTimeMs(row.updatedAt),
+  }
+}
+
+export function sortDefinitionSummaries(defs: CustomFieldDefinitionSummary[]): CustomFieldDefinitionSummary[] {
+  return [...defs].sort((a, b) => {
+    const priorityDiff = (a.priority ?? 0) - (b.priority ?? 0)
+    if (priorityDiff !== 0) return priorityDiff
+    const updatedDiff = (b.updatedAt ?? 0) - (a.updatedAt ?? 0)
+    if (updatedDiff !== 0) return updatedDiff
+    return a.key.localeCompare(b.key)
+  })
+}
+
+export function selectDefinitionForRecord(
+  defs: CustomFieldDefinitionSummary[],
+  organizationId: string | null,
+  tenantId: string | null,
+): CustomFieldDefinitionSummary | null {
+  if (!defs.length) return null
+  const prioritizedForOrg = defs.filter(
+    (def) => def.organizationId && organizationId && def.organizationId === organizationId,
+  )
+  if (prioritizedForOrg.length) return sortDefinitionSummaries(prioritizedForOrg)[0]
+  const prioritizedForTenant = defs.filter(
+    (def) => def.tenantId && tenantId && def.tenantId === tenantId && !def.organizationId,
+  )
+  if (prioritizedForTenant.length) return sortDefinitionSummaries(prioritizedForTenant)[0]
+  const global = defs.filter((def) => !def.organizationId)
+  if (global.length) return sortDefinitionSummaries(global)[0]
+  return sortDefinitionSummaries(defs)[0] ?? null
+}
+
+// Resolve the effective list of organization candidates for a definition index
+// lookup, mirroring `loadCustomFieldDefinitionIndex`: when explicit org ids are
+// present they win, otherwise the fallback (selected org) is used. Null/empty
+// entries are dropped — the null-org branch is always allowed by the index filter.
+export function resolveCfDefIndexOrgCandidates(
+  organizationIds: Array<string | null | undefined> | null | undefined,
+  fallbackOrganizationId: string | null | undefined,
+): string[] {
+  const source = Array.isArray(organizationIds) && organizationIds.length
+    ? organizationIds
+    : [fallbackOrganizationId ?? null]
+  return source
+    .map((id) => (typeof id === 'string' ? id.trim() : id))
+    .filter((id): id is string => typeof id === 'string' && id.length > 0)
+}
+
+function matchesFieldset(configJson: unknown, fieldsetFilter: Set<string | null>): boolean {
+  const config = normalizeDefinitionConfig(configJson)
+  const fieldsets = Array.isArray(config.fieldsets)
+    ? config.fieldsets
+        .filter((entry: unknown): entry is string => typeof entry === 'string')
+        .map((entry: string) => entry.trim())
+        .filter((entry: string) => entry.length > 0)
+    : []
+  const fieldset = typeof config.fieldset === 'string' && config.fieldset.trim().length > 0
+    ? config.fieldset.trim()
+    : null
+  return fieldsets.length > 0
+    ? fieldsets.some((entry: string) => fieldsetFilter.has(entry))
+    : fieldsetFilter.has(fieldset)
+}
+
+// Build the grouped + sorted definition index from plain rows. Callers must
+// pre-filter rows by tenant + is_active (both the ORM loader and the query engine
+// already do so in SQL); this function additionally applies the org candidate
+// filter, the soft-delete guard, and the optional fieldset filter so its output is
+// byte-for-byte identical to the ORM-backed loader for the same logical scope.
+export function buildCustomFieldDefinitionIndexFromRows(
+  rows: CustomFieldDefinitionRow[],
+  opts: { organizationIds?: string[] | null; fieldset?: string | string[] | null } = {},
+): CustomFieldDefinitionIndex {
+  const orgCandidates = opts.organizationIds ?? []
+  const fieldsetFilter = normalizeFieldsetFilter(opts.fieldset)
+  const index: CustomFieldDefinitionIndex = new Map()
+  for (const row of rows) {
+    if (row.deletedAt != null) continue
+    const org = row.organizationId ?? null
+    if (org !== null && !(orgCandidates.length > 0 && orgCandidates.includes(org))) continue
+    if (fieldsetFilter && !matchesFieldset(row.configJson, fieldsetFilter)) continue
+    const summary = summarizeDefinitionRow(row)
+    if (!summary) continue
+    const normalizedKey = normalizeDefinitionKey(summary.key)
+    if (!normalizedKey) continue
+    if (!index.has(normalizedKey)) index.set(normalizedKey, [])
+    index.get(normalizedKey)!.push(summary)
+  }
+  index.forEach((entries, key) => {
+    index.set(key, sortDefinitionSummaries(entries))
+  })
+  return index
+}
+
+function sameStringSet(a: readonly string[], b: readonly string[]): boolean {
+  const left = new Set(a)
+  const right = new Set(b)
+  if (left.size !== right.size) return false
+  for (const value of left) {
+    if (!right.has(value)) return false
+  }
+  return true
+}
+
+// Decide whether a precomputed definition index from a QueryEngine result can be
+// reused for a decoration request. Reuse is only safe when the engine resolved
+// definitions for exactly the same entity-id set, tenant, and org candidates.
+export function canReuseCustomFieldDefinitions(
+  resolved: ResolvedCustomFieldDefinitions | null | undefined,
+  request: { entityIds: string[]; tenantId: string | null; organizationIds: string[] },
+): boolean {
+  if (!resolved) return false
+  if ((resolved.tenantId ?? null) !== (request.tenantId ?? null)) return false
+  if (!sameStringSet(resolved.entityIds.map(String), request.entityIds.map(String))) return false
+  if (!sameStringSet(resolved.organizationIds, request.organizationIds)) return false
+  return true
+}