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

package/src/backend/utils/__tests__/optimisticLock.test.ts

@@ -0,0 +1,126 @@
+import { buildOptimisticLockHeader, extractOptimisticLockConflict } from '../optimisticLock'
+import {
+  OPTIMISTIC_LOCK_CONFLICT_CODE,
+  OPTIMISTIC_LOCK_HEADER_NAME,
+} from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+
+describe('buildOptimisticLockHeader', () => {
+  it('returns the extension header when updatedAt is a non-empty string', () => {
+    expect(buildOptimisticLockHeader('2026-05-25T08:42:18.123Z')).toEqual({
+      [OPTIMISTIC_LOCK_HEADER_NAME]: '2026-05-25T08:42:18.123Z',
+    })
+  })
+
+  it('trims surrounding whitespace', () => {
+    expect(buildOptimisticLockHeader('   2026-05-25T08:42:18.123Z   ')).toEqual({
+      [OPTIMISTIC_LOCK_HEADER_NAME]: '2026-05-25T08:42:18.123Z',
+    })
+  })
+
+  it('returns an empty object for null / undefined / empty / whitespace input', () => {
+    expect(buildOptimisticLockHeader(null)).toEqual({})
+    expect(buildOptimisticLockHeader(undefined)).toEqual({})
+    expect(buildOptimisticLockHeader('')).toEqual({})
+    expect(buildOptimisticLockHeader('   ')).toEqual({})
+  })
+
+  it('returns an empty object for non-string input (defensive)', () => {
+    // @ts-expect-error intentional misuse
+    expect(buildOptimisticLockHeader(12345)).toEqual({})
+    // @ts-expect-error intentional misuse
+    expect(buildOptimisticLockHeader({ updatedAt: '2026' })).toEqual({})
+  })
+})
+
+describe('extractOptimisticLockConflict', () => {
+  it('returns the conflict body when the error has status 409 + optimistic-lock code + both timestamps', () => {
+    const err = {
+      status: 409,
+      body: {
+        error: 'record_modified',
+        code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+        currentUpdatedAt: '2026-05-25T08:42:19.000Z',
+        expectedUpdatedAt: '2026-05-25T08:42:18.000Z',
+      },
+    }
+    expect(extractOptimisticLockConflict(err)).toEqual({
+      error: 'record_modified',
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: '2026-05-25T08:42:19.000Z',
+      expectedUpdatedAt: '2026-05-25T08:42:18.000Z',
+    })
+  })
+
+  it('returns the conflict body when raiseCrudError attached the response fields directly to the error', () => {
+    const err = {
+      status: 409,
+      error: 'record_modified',
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: '2026-05-25T08:42:19.000Z',
+      expectedUpdatedAt: '2026-05-25T08:42:18.000Z',
+    }
+    expect(extractOptimisticLockConflict(err)).toEqual({
+      error: 'record_modified',
+      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+      currentUpdatedAt: '2026-05-25T08:42:19.000Z',
+      expectedUpdatedAt: '2026-05-25T08:42:18.000Z',
+    })
+  })
+
+  it('returns null for non-409 errors', () => {
+    expect(
+      extractOptimisticLockConflict({
+        status: 422,
+        body: { error: 'validation_failed', code: OPTIMISTIC_LOCK_CONFLICT_CODE },
+      }),
+    ).toBeNull()
+  })
+
+  it('returns null for 409 errors that are not optimistic-lock conflicts', () => {
+    expect(
+      extractOptimisticLockConflict({
+        status: 409,
+        body: { error: 'duplicate', code: 'duplicate_resource' },
+      }),
+    ).toBeNull()
+  })
+
+  it('returns null when the conflict body is missing required timestamp fields', () => {
+    expect(
+      extractOptimisticLockConflict({
+        status: 409,
+        body: { error: 'record_modified', code: OPTIMISTIC_LOCK_CONFLICT_CODE },
+      }),
+    ).toBeNull()
+    expect(
+      extractOptimisticLockConflict({
+        status: 409,
+        body: {
+          error: 'record_modified',
+          code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+          currentUpdatedAt: 123,
+          expectedUpdatedAt: '2026-05-25T08:42:18.000Z',
+        },
+      }),
+    ).toBeNull()
+  })
+
+  it('returns null for non-object inputs', () => {
+    expect(extractOptimisticLockConflict(null)).toBeNull()
+    expect(extractOptimisticLockConflict(undefined)).toBeNull()
+    expect(extractOptimisticLockConflict('boom')).toBeNull()
+    expect(extractOptimisticLockConflict(409)).toBeNull()
+  })
+
+  it('falls back to the canonical error token when body.error is missing', () => {
+    const result = extractOptimisticLockConflict({
+      status: 409,
+      body: {
+        code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+        currentUpdatedAt: '2026-05-25T08:42:19.000Z',
+        expectedUpdatedAt: '2026-05-25T08:42:18.000Z',
+      },
+    })
+    expect(result?.error).toBe('record_modified')
+  })
+})

package/src/backend/utils/optimisticLock.ts

@@ -0,0 +1,70 @@
+/**
+ * Client-side helpers for the OSS opt-in optimistic-locking guard
+ * (spec: .ai/specs/2026-05-25-oss-optimistic-locking.md).
+ *
+ * These are deliberately small and dependency-light so they can be wired
+ * into any backend page without touching the shared CrudForm / useGuardedMutation
+ * components. A future PR may pull them into CrudForm directly once the
+ * reference rollout is broader.
+ */
+import {
+  OPTIMISTIC_LOCK_CONFLICT_CODE,
+  OPTIMISTIC_LOCK_HEADER_NAME,
+  type OptimisticLockConflictBody,
+} from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+
+/**
+ * Build the extension-header bag for an `apiCall` request. Pass into
+ * `withScopedApiRequestHeaders(buildOptimisticLockHeader(updatedAt), ...)`
+ * when issuing a `PUT`/`PATCH`/`DELETE` for a record that exposes
+ * `updatedAt`. Returns an empty object when the input is missing/empty so
+ * the call site stays unconditional:
+ *
+ * ```ts
+ * await withScopedApiRequestHeaders(
+ *   buildOptimisticLockHeader(record.updatedAt),
+ *   () => updateCrud('customers/companies', id, { ... }),
+ * )
+ * ```
+ */
+export function buildOptimisticLockHeader(
+  updatedAt: string | null | undefined,
+): Record<string, string> {
+  if (typeof updatedAt !== 'string') return {}
+  const trimmed = updatedAt.trim()
+  if (!trimmed) return {}
+  return { [OPTIMISTIC_LOCK_HEADER_NAME]: trimmed }
+}
+
+/**
+ * Detect whether an error thrown by `raiseCrudError`/`apiCallOrThrow` is an
+ * optimistic-lock conflict (HTTP 409 with `code: 'optimistic_lock_conflict'`).
+ *
+ * Returns the typed conflict body when matched so the caller can show a
+ * UI that includes the server's `currentUpdatedAt`, or `null` otherwise.
+ */
+export function extractOptimisticLockConflict(
+  err: unknown,
+): OptimisticLockConflictBody | null {
+  if (!err || typeof err !== 'object') return null
+  const candidate = err as Record<string, unknown>
+  const status = candidate.status
+  if (status !== 409) return null
+  const body = candidate.body && typeof candidate.body === 'object'
+    ? candidate.body
+    : candidate
+  if (!body || typeof body !== 'object') return null
+  const bodyRecord = body as Record<string, unknown>
+  if (bodyRecord.code !== OPTIMISTIC_LOCK_CONFLICT_CODE) return null
+  const currentUpdatedAt = bodyRecord.currentUpdatedAt
+  const expectedUpdatedAt = bodyRecord.expectedUpdatedAt
+  if (typeof currentUpdatedAt !== 'string' || typeof expectedUpdatedAt !== 'string') return null
+  return {
+    error: typeof bodyRecord.error === 'string'
+      ? (bodyRecord.error as OptimisticLockConflictBody['error'])
+      : 'record_modified',
+    code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+    currentUpdatedAt,
+    expectedUpdatedAt,
+  }
+}