@open-mercato/shared 0.6.5-develop.4534.1.b459babe6d → 0.6.5-develop.4559.1.839e136509

package/src/lib/crud/__tests__/optimistic-lock-command.test.ts

@@ -0,0 +1,425 @@
+import {
+  assertOptimisticLock,
+  buildOptimisticLockConflictBody,
+  createCommandOptimisticLockGuardService,
+  enforceCommandOptimisticLock,
+  enforceRecordGoneIsConflict,
+  readOptimisticLockExpected,
+} from '../optimistic-lock-command'
+import { CrudHttpError, isCrudHttpError } from '../errors'
+import {
+  OPTIMISTIC_LOCK_CONFLICT_CODE,
+  OPTIMISTIC_LOCK_CONFLICT_ERROR,
+  OPTIMISTIC_LOCK_HEADER_NAME,
+} from '../optimistic-lock-headers'
+
+const A = '2026-05-25T08:42:18.123Z'
+const B = '2026-05-25T08:42:20.999Z'
+
+function headersWith(token: string | null): Headers {
+  const h = new Headers()
+  if (token != null) h.set(OPTIMISTIC_LOCK_HEADER_NAME, token)
+  return h
+}
+
+describe('readOptimisticLockExpected', () => {
+  it('reads + trims the header from a Headers object', () => {
+    expect(readOptimisticLockExpected(headersWith(`  ${A}  `))).toBe(A)
+  })
+
+  it('reads the header from a Request', () => {
+    const req = new Request('https://example.test/api/sales/order-lines', {
+      method: 'PUT',
+      headers: headersWith(A),
+    })
+    expect(readOptimisticLockExpected(req)).toBe(A)
+  })
+
+  it('returns null when the header is absent / empty / source missing', () => {
+    expect(readOptimisticLockExpected(headersWith(null))).toBeNull()
+    expect(readOptimisticLockExpected(headersWith('   '))).toBeNull()
+    expect(readOptimisticLockExpected(null)).toBeNull()
+    expect(readOptimisticLockExpected(undefined)).toBeNull()
+  })
+})
+
+describe('assertOptimisticLock', () => {
+  it('throws 409 with the structured body on a version mismatch', () => {
+    let caught: unknown
+    try {
+      assertOptimisticLock({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        expected: A,
+        current: B,
+        envValue: 'all',
+      })
+    } catch (err) {
+      caught = err
+    }
+    expect(isCrudHttpError(caught)).toBe(true)
+    const httpError = caught as CrudHttpError
+    expect(httpError.status).toBe(409)
+    expect(httpError.body).toEqual({
+      error: OPTIMISTIC_LOCK_CONFLICT_ERROR,
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: B,
+      expectedUpdatedAt: A,
+    })
+  })
+
+  it('passes when expected matches current (normalized comparison across Date + string)', () => {
+    expect(() =>
+      assertOptimisticLock({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        expected: A,
+        current: new Date(A),
+        envValue: 'all',
+      }),
+    ).not.toThrow()
+  })
+
+  it('is a no-op when no expected token is supplied (strictly additive)', () => {
+    expect(() =>
+      assertOptimisticLock({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        expected: null,
+        current: B,
+        envValue: 'all',
+      }),
+    ).not.toThrow()
+    expect(() =>
+      assertOptimisticLock({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        expected: '   ',
+        current: B,
+        envValue: 'all',
+      }),
+    ).not.toThrow()
+  })
+
+  it('is a no-op when the current version is missing (let the command 404)', () => {
+    expect(() =>
+      assertOptimisticLock({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        expected: A,
+        current: null,
+        envValue: 'all',
+      }),
+    ).not.toThrow()
+  })
+
+  it('is a no-op when expected is an unparseable token', () => {
+    expect(() =>
+      assertOptimisticLock({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        expected: 'not-a-date',
+        current: B,
+        envValue: 'all',
+      }),
+    ).not.toThrow()
+  })
+
+  it('respects OM_OPTIMISTIC_LOCK=off (no 409 even on mismatch)', () => {
+    expect(() =>
+      assertOptimisticLock({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        expected: A,
+        current: B,
+        envValue: 'off',
+      }),
+    ).not.toThrow()
+  })
+
+  it('respects an allow-list that excludes the resourceKind', () => {
+    expect(() =>
+      assertOptimisticLock({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        expected: A,
+        current: B,
+        envValue: 'customers.company',
+      }),
+    ).not.toThrow()
+  })
+
+  it('enforces the check for a resourceKind present in the allow-list', () => {
+    expect(() =>
+      assertOptimisticLock({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        expected: A,
+        current: B,
+        envValue: 'sales.order',
+      }),
+    ).toThrow(CrudHttpError)
+  })
+
+  it('is ON by default (env unset) — mismatch 409s', () => {
+    const prev = process.env.OM_OPTIMISTIC_LOCK
+    delete process.env.OM_OPTIMISTIC_LOCK
+    try {
+      expect(() =>
+        assertOptimisticLock({
+          resourceKind: 'sales.order',
+          resourceId: 'order-1',
+          expected: A,
+          current: B,
+        }),
+      ).toThrow(CrudHttpError)
+    } finally {
+      if (prev !== undefined) process.env.OM_OPTIMISTIC_LOCK = prev
+    }
+  })
+})
+
+describe('enforceCommandOptimisticLock', () => {
+  it('reads the expected token from the request header and 409s on mismatch', () => {
+    const req = new Request('https://example.test/api/sales/order-lines', {
+      method: 'PUT',
+      headers: headersWith(A),
+    })
+    expect(() =>
+      enforceCommandOptimisticLock({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        current: B,
+        request: req,
+        envValue: 'all',
+      }),
+    ).toThrow(CrudHttpError)
+  })
+
+  it('prefers the explicit expected override over the header', () => {
+    const req = new Request('https://example.test/api/sales/order-lines', {
+      method: 'PUT',
+      headers: headersWith(B), // header matches current → would pass if used
+    })
+    expect(() =>
+      enforceCommandOptimisticLock({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        current: B,
+        expected: A, // stale override → must 409
+        request: req,
+        envValue: 'all',
+      }),
+    ).toThrow(CrudHttpError)
+  })
+
+  it('is a no-op when neither override nor header is present', () => {
+    expect(() =>
+      enforceCommandOptimisticLock({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        current: B,
+        request: headersWith(null),
+        envValue: 'all',
+      }),
+    ).not.toThrow()
+  })
+
+  it('passes when the header matches the current version', () => {
+    expect(() =>
+      enforceCommandOptimisticLock({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        current: new Date(A),
+        request: headersWith(A),
+        envValue: 'all',
+      }),
+    ).not.toThrow()
+  })
+})
+
+describe('enforceRecordGoneIsConflict', () => {
+  it('409s when the client opted in (header present) but the record is gone', () => {
+    let caught: unknown
+    try {
+      enforceRecordGoneIsConflict({
+        resourceKind: 'customers.interaction',
+        resourceId: 'int-1',
+        request: headersWith(A),
+        envValue: 'all',
+      })
+    } catch (err) {
+      caught = err
+    }
+    expect(isCrudHttpError(caught)).toBe(true)
+    const httpError = caught as CrudHttpError
+    expect(httpError.status).toBe(409)
+    // No current version exists for a deleted record, so it echoes the expected token.
+    expect(httpError.body).toEqual({
+      error: OPTIMISTIC_LOCK_CONFLICT_ERROR,
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: A,
+      expectedUpdatedAt: A,
+    })
+  })
+
+  it('is a no-op when the client did not opt in (no header → caller 404 fires)', () => {
+    expect(() =>
+      enforceRecordGoneIsConflict({
+        resourceKind: 'customers.interaction',
+        resourceId: 'int-1',
+        request: headersWith(null),
+        envValue: 'all',
+      }),
+    ).not.toThrow()
+  })
+
+  it('prefers an explicit expected override over the header', () => {
+    expect(() =>
+      enforceRecordGoneIsConflict({
+        resourceKind: 'customers.interaction',
+        resourceId: 'int-1',
+        expected: A,
+        request: headersWith(null),
+        envValue: 'all',
+      }),
+    ).toThrow(CrudHttpError)
+  })
+
+  it('is a no-op when the env disables the guard for the resource', () => {
+    expect(() =>
+      enforceRecordGoneIsConflict({
+        resourceKind: 'customers.interaction',
+        resourceId: 'int-1',
+        request: headersWith(A),
+        envValue: 'off',
+      }),
+    ).not.toThrow()
+  })
+
+  it('is a no-op when the expected token is unparseable', () => {
+    expect(() =>
+      enforceRecordGoneIsConflict({
+        resourceKind: 'customers.interaction',
+        resourceId: 'int-1',
+        request: headersWith('not-a-date'),
+        envValue: 'all',
+      }),
+    ).not.toThrow()
+  })
+})
+
+describe('buildOptimisticLockConflictBody', () => {
+  it('shapes the structured conflict body', () => {
+    expect(buildOptimisticLockConflictBody(B, A)).toEqual({
+      error: OPTIMISTIC_LOCK_CONFLICT_ERROR,
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: B,
+      expectedUpdatedAt: A,
+    })
+  })
+})
+
+describe('createCommandOptimisticLockGuardService', () => {
+  it('default service mirrors enforceCommandOptimisticLock (header compare → 409 on mismatch)', async () => {
+    const guard = createCommandOptimisticLockGuardService()
+    let caught: unknown
+    try {
+      await guard.enforce({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        current: B,
+        request: headersWith(A),
+        envValue: 'all',
+      })
+    } catch (err) {
+      caught = err
+    }
+    expect(isCrudHttpError(caught)).toBe(true)
+    expect((caught as CrudHttpError).status).toBe(409)
+  })
+
+  it('default service is a no-op when the client sends no expected token (strictly additive)', async () => {
+    const guard = createCommandOptimisticLockGuardService()
+    await expect(
+      guard.enforce({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        current: B,
+        request: headersWith(null),
+        envValue: 'all',
+      }),
+    ).resolves.toBeUndefined()
+  })
+
+  it('default service is a no-op when the env disables the guard for the resource', async () => {
+    const guard = createCommandOptimisticLockGuardService()
+    await expect(
+      guard.enforce({
+        resourceKind: 'sales.order',
+        resourceId: 'order-1',
+        current: B,
+        request: headersWith(A),
+        envValue: 'off',
+      }),
+    ).resolves.toBeUndefined()
+  })
+
+  it('resolveExpected overrides the header-derived token (enterprise extension point)', async () => {
+    const seen: Array<{ expectedFromHeader: string | null; resourceKind: string; resourceId: string }> = []
+    // Resolver supplies a stale token even though the client header matches `current`,
+    // proving enterprise can drive the expected version from a lock record.
+    const guard = createCommandOptimisticLockGuardService({
+      resolveExpected: (input) => {
+        seen.push(input)
+        return A
+      },
+    })
+    let caught: unknown
+    try {
+      await guard.enforce({
+        resourceKind: 'sales.order',
+        resourceId: 'order-9',
+        current: B,
+        request: headersWith(B),
+        envValue: 'all',
+      })
+    } catch (err) {
+      caught = err
+    }
+    expect(isCrudHttpError(caught)).toBe(true)
+    expect((caught as CrudHttpError).status).toBe(409)
+    expect(seen).toHaveLength(1)
+    expect(seen[0]).toEqual({ expectedFromHeader: B, resourceKind: 'sales.order', resourceId: 'order-9' })
+  })
+
+  it('awaits an async resolveExpected and passes when it returns the current token', async () => {
+    const guard = createCommandOptimisticLockGuardService({
+      resolveExpected: async () => B,
+    })
+    await expect(
+      guard.enforce({
+        resourceKind: 'sales.order',
+        resourceId: 'order-9',
+        current: B,
+        request: headersWith(A),
+        envValue: 'all',
+      }),
+    ).resolves.toBeUndefined()
+  })
+
+  it('resolveExpected returning null skips the check (no expected → additive no-op)', async () => {
+    const guard = createCommandOptimisticLockGuardService({
+      resolveExpected: () => null,
+    })
+    await expect(
+      guard.enforce({
+        resourceKind: 'sales.order',
+        resourceId: 'order-9',
+        current: B,
+        request: headersWith(A),
+        envValue: 'all',
+      }),
+    ).resolves.toBeUndefined()
+  })
+})

package/src/lib/crud/__tests__/optimistic-lock-store.test.ts

@@ -0,0 +1,194 @@
+import {
+  clearOptimisticLockReadersForTests,
+  getAllOptimisticLockReaders,
+  registerOptimisticLockReaderIfAbsent,
+  registerOptimisticLockReaders,
+} from '../optimistic-lock-store'
+import { createOptimisticLockGuardService } from '../optimistic-lock'
+import {
+  OPTIMISTIC_LOCK_CONFLICT_CODE,
+  OPTIMISTIC_LOCK_HEADER_NAME,
+} from '../optimistic-lock-headers'
+import type { CrudMutationGuardValidateInput } from '../mutation-guard'
+
+describe('optimistic-lock-store', () => {
+  beforeEach(() => {
+    clearOptimisticLockReadersForTests()
+  })
+
+  afterAll(() => {
+    clearOptimisticLockReadersForTests()
+  })
+
+  it('starts empty', () => {
+    expect(getAllOptimisticLockReaders()).toEqual({})
+  })
+
+  it('registers a single reader', () => {
+    const reader = async () => '2026-01-01T00:00:00.000Z'
+    registerOptimisticLockReaders({ 'customers.company': reader })
+    expect(Object.keys(getAllOptimisticLockReaders())).toEqual(['customers.company'])
+    expect(getAllOptimisticLockReaders()['customers.company']).toBe(reader)
+  })
+
+  it('merges multiple registrations across modules', () => {
+    const a = async () => '2026-01-01T00:00:00.000Z'
+    const b = async () => '2026-02-02T00:00:00.000Z'
+    registerOptimisticLockReaders({ 'customers.company': a })
+    registerOptimisticLockReaders({ 'sales.order': b })
+    const all = getAllOptimisticLockReaders()
+    expect(Object.keys(all).sort()).toEqual(['customers.company', 'sales.order'])
+    expect(all['customers.company']).toBe(a)
+    expect(all['sales.order']).toBe(b)
+  })
+
+  it('later registration overrides earlier for the same key', () => {
+    const v1 = async () => 'v1'
+    const v2 = async () => 'v2'
+    registerOptimisticLockReaders({ 'customers.company': v1 })
+    registerOptimisticLockReaders({ 'customers.company': v2 })
+    expect(getAllOptimisticLockReaders()['customers.company']).toBe(v2)
+  })
+})
+
+describe('registerOptimisticLockReaderIfAbsent', () => {
+  beforeEach(() => {
+    clearOptimisticLockReadersForTests()
+  })
+
+  afterAll(() => {
+    clearOptimisticLockReadersForTests()
+  })
+
+  it('writes readers for keys that have no entry yet', () => {
+    const reader = async () => '2026-05-26T07:00:00.000Z'
+    const written = registerOptimisticLockReaderIfAbsent({ 'customers.deal': reader })
+    expect(written).toEqual(['customers.deal'])
+    expect(getAllOptimisticLockReaders()['customers.deal']).toBe(reader)
+  })
+
+  it('skips keys that already have a reader (hand-wired wins)', () => {
+    const handWired = async () => 'hand-wired'
+    const generic = async () => 'generic'
+    registerOptimisticLockReaders({ 'customers.company': handWired })
+    const written = registerOptimisticLockReaderIfAbsent({ 'customers.company': generic })
+    expect(written).toEqual([])
+    expect(getAllOptimisticLockReaders()['customers.company']).toBe(handWired)
+  })
+
+  it('handles a mixed batch — keeps the hand-wired one, writes the new one', () => {
+    const handWired = async () => 'hand-wired'
+    const genericDeal = async () => 'deal'
+    const genericQuote = async () => 'quote'
+    registerOptimisticLockReaders({ 'customers.company': handWired })
+    const written = registerOptimisticLockReaderIfAbsent({
+      'customers.company': async () => 'no-op',
+      'customers.deal': genericDeal,
+      'sales.quote': genericQuote,
+    })
+    expect(written.sort()).toEqual(['customers.deal', 'sales.quote'])
+    const all = getAllOptimisticLockReaders()
+    expect(all['customers.company']).toBe(handWired)
+    expect(all['customers.deal']).toBe(genericDeal)
+    expect(all['sales.quote']).toBe(genericQuote)
+  })
+
+  it('does not touch global state when every key is already taken', () => {
+    const handWired = async () => 'hand-wired'
+    registerOptimisticLockReaders({ 'customers.company': handWired })
+    const before = getAllOptimisticLockReaders()
+    const written = registerOptimisticLockReaderIfAbsent({ 'customers.company': async () => 'x' })
+    expect(written).toEqual([])
+    const after = getAllOptimisticLockReaders()
+    expect(after['customers.company']).toBe(handWired)
+    expect(Object.keys(after)).toEqual(Object.keys(before))
+  })
+
+  it('repeated calls are idempotent — second invocation writes nothing', () => {
+    const generic = async () => 'generic'
+    expect(registerOptimisticLockReaderIfAbsent({ 'customers.deal': generic })).toEqual([
+      'customers.deal',
+    ])
+    expect(registerOptimisticLockReaderIfAbsent({ 'customers.deal': async () => 'x' })).toEqual([])
+    expect(getAllOptimisticLockReaders()['customers.deal']).toBe(generic)
+  })
+})
+
+describe('createOptimisticLockGuardService — store-backed fallback', () => {
+  beforeEach(() => {
+    clearOptimisticLockReadersForTests()
+  })
+
+  afterAll(() => {
+    clearOptimisticLockReadersForTests()
+  })
+
+  function makeInput(overrides: Partial<CrudMutationGuardValidateInput> = {}): CrudMutationGuardValidateInput {
+    const headers = overrides.requestHeaders ?? new Headers()
+    return {
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+      userId: 'user-1',
+      resourceKind: 'customers.company',
+      resourceId: 'company-1',
+      operation: 'update',
+      requestMethod: 'PUT',
+      requestHeaders: headers,
+      mutationPayload: null,
+      ...overrides,
+      requestHeaders: headers,
+    }
+  }
+
+  it('pulls readers from the store when opts.readers is omitted', async () => {
+    registerOptimisticLockReaders({
+      'customers.company': async () => '2026-05-25T08:00:00.000Z',
+    })
+    const headers = new Headers()
+    headers.set(OPTIMISTIC_LOCK_HEADER_NAME, '2026-05-25T08:00:00.000Z')
+    const service = createOptimisticLockGuardService({
+      getEm: () => ({} as never),
+      envValue: 'all',
+    })
+    const result = await service.validateMutation(makeInput({ requestHeaders: headers }))
+    expect(result).toEqual({ ok: true, shouldRunAfterSuccess: false })
+  })
+
+  it('returns 409 when the store-backed reader reports a different current value', async () => {
+    registerOptimisticLockReaders({
+      'customers.company': async () => '2026-05-25T08:00:05.000Z',
+    })
+    const headers = new Headers()
+    headers.set(OPTIMISTIC_LOCK_HEADER_NAME, '2026-05-25T08:00:00.000Z')
+    const service = createOptimisticLockGuardService({
+      getEm: () => ({} as never),
+      envValue: 'all',
+    })
+    const result = await service.validateMutation(makeInput({ requestHeaders: headers }))
+    expect(result.ok).toBe(false)
+    if (result.ok) throw new Error('expected failure')
+    expect(result.status).toBe(409)
+    expect(result.body).toMatchObject({
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: '2026-05-25T08:00:05.000Z',
+      expectedUpdatedAt: '2026-05-25T08:00:00.000Z',
+    })
+  })
+
+  it('explicit opts.readers wins over the store for the same key', async () => {
+    registerOptimisticLockReaders({
+      'customers.company': async () => 'from-store',
+    })
+    const headers = new Headers()
+    headers.set(OPTIMISTIC_LOCK_HEADER_NAME, '2026-05-25T08:00:00.000Z')
+    const service = createOptimisticLockGuardService({
+      getEm: () => ({} as never),
+      envValue: 'all',
+      readers: {
+        'customers.company': async () => '2026-05-25T08:00:00.000Z', // matches client header
+      },
+    })
+    const result = await service.validateMutation(makeInput({ requestHeaders: headers }))
+    expect(result).toEqual({ ok: true, shouldRunAfterSuccess: false })
+  })
+})