@object-ui/data-objectstack 5.0.2 → 5.1.1

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @object-ui/data-objectstack
 
+## 5.1.1
+
+### Patch Changes
+
+- @object-ui/types@5.1.1
+- @object-ui/core@5.1.1
+
+## 5.1.0
+
+### Minor Changes
+
+- 5b80cfd: feat: Optimistic Concurrency Control (OCC) on DataSource writes
+
+  `DataSource.update()` and `DataSource.delete()` now accept an optional fourth /
+  third argument `opts?: { ifMatch?: string }`. When supplied, adapters forward
+  the token to the backend; servers that implement OCC (e.g. ObjectStack
+  `>=4.2.0`) compare it against the record's current `updated_at` and reject
+  with `409 CONCURRENT_UPDATE` on mismatch, preventing silent overwrites in
+  multi-user editing scenarios.
+
+  **`@object-ui/data-objectstack`**
+  - Exports `ConcurrentUpdateError` (carries `currentVersion` and
+    `currentRecord`) and `isConcurrentUpdateError()` type guard.
+  - `update()` / `delete()` accept `opts.ifMatch` and forward it via the
+    `@objectstack/client` data API (header: `If-Match`). Requires
+    `@objectstack/client@>=4.1.2` for the header to reach the server;
+    older clients silently drop the option and fall back to today's
+    "last writer wins" behaviour.
+  - Adapter-level error handling maps a 409 with `code === 'CONCURRENT_UPDATE'`
+    into a typed `ConcurrentUpdateError` so callers can detect and recover
+    from conflicts without parsing the wire format.
+
+  **`@object-ui/core`**
+  - `ApiDataSource.update()` and `.delete()` accept `opts.ifMatch` and emit
+    the `If-Match` HTTP header.
+
+  UI consumers (Detail view, inline cell-edit) will be wired in a follow-up
+  patch to capture `updated_at` at load time, pass it as `ifMatch` on save,
+  and present a Reload / Overwrite / Cancel dialog on conflict.
+
+### Patch Changes
+
+- Updated dependencies [cf30cc2]
+- Updated dependencies [5b80cfd]
+  - @object-ui/types@5.1.0
+  - @object-ui/core@5.1.0
+
 ## 5.0.2
 
 ### Patch Changes

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(index_exports, {
   AuthenticationError: () => AuthenticationError,
   BulkOperationError: () => BulkOperationError,
   CloudOperations: () => CloudOperations,
+  ConcurrentUpdateError: () => ConcurrentUpdateError,
   ConnectionError: () => ConnectionError,
   IntegrationManager: () => IntegrationManager,
   MetadataNotFoundError: () => MetadataNotFoundError,
@@ -41,8 +42,10 @@ __export(index_exports, {
   generateContractManifest: () => generateContractManifest,
   getSharedDiscovery: () => getSharedDiscovery,
   is404Error: () => is404Error,
+  isConcurrentUpdateError: () => isConcurrentUpdateError,
   isErrorType: () => isErrorType,
   isObjectStackError: () => isObjectStackError,
+  normaliseClientError: () => normaliseClientError,
   snapToGrid: () => snapToGrid,
   validatePluginContract: () => validatePluginContract
 });
@@ -1016,6 +1019,35 @@ function is404Error(error) {
   const code = typeof err.code === "string" ? err.code : "";
   return code === "object_not_found" || code === "record_not_found";
 }
+var ConcurrentUpdateError = class extends Error {
+  constructor(opts) {
+    super(opts.message ?? "Record was modified by another user");
+    __publicField(this, "code", "CONCURRENT_UPDATE");
+    __publicField(this, "httpStatus", 409);
+    __publicField(this, "currentVersion");
+    __publicField(this, "currentRecord");
+    this.name = "ConcurrentUpdateError";
+    this.currentVersion = opts.currentVersion;
+    this.currentRecord = opts.currentRecord;
+  }
+};
+function isConcurrentUpdateError(error) {
+  if (!error || typeof error !== "object") return false;
+  const e = error;
+  return e.code === "CONCURRENT_UPDATE" || e.name === "ConcurrentUpdateError";
+}
+function normaliseClientError(error) {
+  if (!error || typeof error !== "object") return error;
+  const e = error;
+  if (e.code !== "CONCURRENT_UPDATE" && e.httpStatus !== 409) return error;
+  if (e.code !== "CONCURRENT_UPDATE") return error;
+  const details = e.details ?? {};
+  return new ConcurrentUpdateError({
+    currentVersion: typeof details.currentVersion === "string" ? details.currentVersion : null,
+    currentRecord: details.currentRecord ?? null,
+    message: typeof e.message === "string" ? e.message : void 0
+  });
+}
 function createQuietHttpLogger() {
   const isExpected404 = (meta) => {
     if (!meta || typeof meta !== "object") return false;
@@ -1293,19 +1325,48 @@ var ObjectStackAdapter = class {
   }
   /**
    * Update an existing record.
+   *
+   * Optional `opts.ifMatch` enables Optimistic Concurrency Control: the
+   * server compares the supplied token (typically the `updated_at` value
+   * the caller previously read) against the record's current version
+   * and throws a {@link ConcurrentUpdateError} on mismatch (HTTP 409).
+   *
+   * Requires `@objectstack/client@>=4.2.0`, which forwards `opts.ifMatch`
+   * as an `If-Match` HTTP header.
    */
-  async update(resource, id, data) {
+  async update(resource, id, data, opts) {
     await this.connect();
-    const result = await this.client.data.update(resource, String(id), data);
-    return result.record;
+    try {
+      const result = await this.client.data.update(
+        resource,
+        String(id),
+        data,
+        opts?.ifMatch ? { ifMatch: opts.ifMatch } : void 0
+      );
+      return result.record;
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
   }
   /**
    * Delete a record.
+   *
+   * Optional `opts.ifMatch` enables Optimistic Concurrency Control —
+   * see {@link update} for details. On 409 the call rejects with
+   * a {@link ConcurrentUpdateError}.
    */
-  async delete(resource, id) {
+  async delete(resource, id, opts) {
     await this.connect();
-    const result = await this.client.data.delete(resource, String(id));
-    return result.deleted;
+    try {
+      const result = await this.client.data.delete(
+        resource,
+        String(id),
+        opts?.ifMatch ? { ifMatch: opts.ifMatch } : void 0
+      );
+      return result.deleted;
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
   }
   /**
    * Bulk operations with optimized batch processing and error handling.
@@ -2202,6 +2263,7 @@ function createObjectStackAdapter(config) {
   AuthenticationError,
   BulkOperationError,
   CloudOperations,
+  ConcurrentUpdateError,
   ConnectionError,
   IntegrationManager,
   MetadataNotFoundError,
@@ -2218,8 +2280,10 @@ function createObjectStackAdapter(config) {
   generateContractManifest,
   getSharedDiscovery,
   is404Error,
+  isConcurrentUpdateError,
   isErrorType,
   isObjectStackError,
+  normaliseClientError,
   snapToGrid,
   validatePluginContract
 });

package/dist/index.d.cts

@@ -737,6 +737,48 @@ declare function clearSharedDiscoveryCache(): void;
  * tripping on the property-name mismatch.
  */
 declare function is404Error(error: unknown): boolean;
+/**
+ * Thrown by `update()` / `delete()` when the server returns
+ * `409 CONCURRENT_UPDATE` — i.e. the record was modified by someone else
+ * between when the caller last read it and when they attempted to write.
+ *
+ * The error carries the current server-side `updated_at` version and the
+ * full latest record so the UI can render an informed conflict-resolution
+ * dialog (typically "Reload latest" / "Overwrite anyway" / "Cancel").
+ *
+ * Mirrors the {@link ConcurrentUpdateError} thrown by
+ * `@objectstack/objectql`'s protocol; the wire shape is:
+ * ```json
+ * { "code": "CONCURRENT_UPDATE",
+ *   "error": "<message>",
+ *   "currentVersion": "<updated_at>",
+ *   "currentRecord": { ...latest... } }
+ * ```
+ */
+declare class ConcurrentUpdateError extends Error {
+    readonly code = "CONCURRENT_UPDATE";
+    readonly httpStatus = 409;
+    readonly currentVersion: string | null;
+    readonly currentRecord: unknown;
+    constructor(opts: {
+        currentVersion: string | null;
+        currentRecord: unknown;
+        message?: string;
+    });
+}
+/**
+ * Detect "concurrent update" errors raised by the platform. The wire
+ * shape is `409` + `code: 'CONCURRENT_UPDATE'`. The client surfaces
+ * extra details on `error.details` (full response body).
+ */
+declare function isConcurrentUpdateError(error: unknown): error is ConcurrentUpdateError;
+/**
+ * Convert any error thrown by the upstream client into a typed
+ * `ConcurrentUpdateError` when it represents a 409 CONCURRENT_UPDATE.
+ * Returns the original error untouched otherwise. Callers can simply
+ * `throw normaliseClientError(err)` from their catch blocks.
+ */
+declare function normaliseClientError(error: unknown): unknown;
 /**
  * Connection state for monitoring
  */
@@ -874,12 +916,28 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     create(resource: string, data: Partial<T>): Promise<T>;
     /**
      * Update an existing record.
+     *
+     * Optional `opts.ifMatch` enables Optimistic Concurrency Control: the
+     * server compares the supplied token (typically the `updated_at` value
+     * the caller previously read) against the record's current version
+     * and throws a {@link ConcurrentUpdateError} on mismatch (HTTP 409).
+     *
+     * Requires `@objectstack/client@>=4.2.0`, which forwards `opts.ifMatch`
+     * as an `If-Match` HTTP header.
      */
-    update(resource: string, id: string | number, data: Partial<T>): Promise<T>;
+    update(resource: string, id: string | number, data: Partial<T>, opts?: {
+        ifMatch?: string;
+    }): Promise<T>;
     /**
      * Delete a record.
+     *
+     * Optional `opts.ifMatch` enables Optimistic Concurrency Control —
+     * see {@link update} for details. On 409 the call rejects with
+     * a {@link ConcurrentUpdateError}.
      */
-    delete(resource: string, id: string | number): Promise<boolean>;
+    delete(resource: string, id: string | number, opts?: {
+        ifMatch?: string;
+    }): Promise<boolean>;
     /**
      * Bulk operations with optimized batch processing and error handling.
      * Emits progress events for tracking operation status.
@@ -1151,4 +1209,4 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     reconnectDelay?: number;
 }): DataSource<T>;
 
-export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, generateContractManifest, getSharedDiscovery, is404Error, isErrorType, isObjectStackError, snapToGrid, validatePluginContract };
+export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConcurrentUpdateError, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, generateContractManifest, getSharedDiscovery, is404Error, isConcurrentUpdateError, isErrorType, isObjectStackError, normaliseClientError, snapToGrid, validatePluginContract };

package/dist/index.d.ts

@@ -737,6 +737,48 @@ declare function clearSharedDiscoveryCache(): void;
  * tripping on the property-name mismatch.
  */
 declare function is404Error(error: unknown): boolean;
+/**
+ * Thrown by `update()` / `delete()` when the server returns
+ * `409 CONCURRENT_UPDATE` — i.e. the record was modified by someone else
+ * between when the caller last read it and when they attempted to write.
+ *
+ * The error carries the current server-side `updated_at` version and the
+ * full latest record so the UI can render an informed conflict-resolution
+ * dialog (typically "Reload latest" / "Overwrite anyway" / "Cancel").
+ *
+ * Mirrors the {@link ConcurrentUpdateError} thrown by
+ * `@objectstack/objectql`'s protocol; the wire shape is:
+ * ```json
+ * { "code": "CONCURRENT_UPDATE",
+ *   "error": "<message>",
+ *   "currentVersion": "<updated_at>",
+ *   "currentRecord": { ...latest... } }
+ * ```
+ */
+declare class ConcurrentUpdateError extends Error {
+    readonly code = "CONCURRENT_UPDATE";
+    readonly httpStatus = 409;
+    readonly currentVersion: string | null;
+    readonly currentRecord: unknown;
+    constructor(opts: {
+        currentVersion: string | null;
+        currentRecord: unknown;
+        message?: string;
+    });
+}
+/**
+ * Detect "concurrent update" errors raised by the platform. The wire
+ * shape is `409` + `code: 'CONCURRENT_UPDATE'`. The client surfaces
+ * extra details on `error.details` (full response body).
+ */
+declare function isConcurrentUpdateError(error: unknown): error is ConcurrentUpdateError;
+/**
+ * Convert any error thrown by the upstream client into a typed
+ * `ConcurrentUpdateError` when it represents a 409 CONCURRENT_UPDATE.
+ * Returns the original error untouched otherwise. Callers can simply
+ * `throw normaliseClientError(err)` from their catch blocks.
+ */
+declare function normaliseClientError(error: unknown): unknown;
 /**
  * Connection state for monitoring
  */
@@ -874,12 +916,28 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     create(resource: string, data: Partial<T>): Promise<T>;
     /**
      * Update an existing record.
+     *
+     * Optional `opts.ifMatch` enables Optimistic Concurrency Control: the
+     * server compares the supplied token (typically the `updated_at` value
+     * the caller previously read) against the record's current version
+     * and throws a {@link ConcurrentUpdateError} on mismatch (HTTP 409).
+     *
+     * Requires `@objectstack/client@>=4.2.0`, which forwards `opts.ifMatch`
+     * as an `If-Match` HTTP header.
      */
-    update(resource: string, id: string | number, data: Partial<T>): Promise<T>;
+    update(resource: string, id: string | number, data: Partial<T>, opts?: {
+        ifMatch?: string;
+    }): Promise<T>;
     /**
      * Delete a record.
+     *
+     * Optional `opts.ifMatch` enables Optimistic Concurrency Control —
+     * see {@link update} for details. On 409 the call rejects with
+     * a {@link ConcurrentUpdateError}.
      */
-    delete(resource: string, id: string | number): Promise<boolean>;
+    delete(resource: string, id: string | number, opts?: {
+        ifMatch?: string;
+    }): Promise<boolean>;
     /**
      * Bulk operations with optimized batch processing and error handling.
      * Emits progress events for tracking operation status.
@@ -1151,4 +1209,4 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     reconnectDelay?: number;
 }): DataSource<T>;
 
-export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, generateContractManifest, getSharedDiscovery, is404Error, isErrorType, isObjectStackError, snapToGrid, validatePluginContract };
+export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConcurrentUpdateError, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, generateContractManifest, getSharedDiscovery, is404Error, isConcurrentUpdateError, isErrorType, isObjectStackError, normaliseClientError, snapToGrid, validatePluginContract };

package/dist/index.js

@@ -972,6 +972,35 @@ function is404Error(error) {
   const code = typeof err.code === "string" ? err.code : "";
   return code === "object_not_found" || code === "record_not_found";
 }
+var ConcurrentUpdateError = class extends Error {
+  constructor(opts) {
+    super(opts.message ?? "Record was modified by another user");
+    __publicField(this, "code", "CONCURRENT_UPDATE");
+    __publicField(this, "httpStatus", 409);
+    __publicField(this, "currentVersion");
+    __publicField(this, "currentRecord");
+    this.name = "ConcurrentUpdateError";
+    this.currentVersion = opts.currentVersion;
+    this.currentRecord = opts.currentRecord;
+  }
+};
+function isConcurrentUpdateError(error) {
+  if (!error || typeof error !== "object") return false;
+  const e = error;
+  return e.code === "CONCURRENT_UPDATE" || e.name === "ConcurrentUpdateError";
+}
+function normaliseClientError(error) {
+  if (!error || typeof error !== "object") return error;
+  const e = error;
+  if (e.code !== "CONCURRENT_UPDATE" && e.httpStatus !== 409) return error;
+  if (e.code !== "CONCURRENT_UPDATE") return error;
+  const details = e.details ?? {};
+  return new ConcurrentUpdateError({
+    currentVersion: typeof details.currentVersion === "string" ? details.currentVersion : null,
+    currentRecord: details.currentRecord ?? null,
+    message: typeof e.message === "string" ? e.message : void 0
+  });
+}
 function createQuietHttpLogger() {
   const isExpected404 = (meta) => {
     if (!meta || typeof meta !== "object") return false;
@@ -1249,19 +1278,48 @@ var ObjectStackAdapter = class {
   }
   /**
    * Update an existing record.
+   *
+   * Optional `opts.ifMatch` enables Optimistic Concurrency Control: the
+   * server compares the supplied token (typically the `updated_at` value
+   * the caller previously read) against the record's current version
+   * and throws a {@link ConcurrentUpdateError} on mismatch (HTTP 409).
+   *
+   * Requires `@objectstack/client@>=4.2.0`, which forwards `opts.ifMatch`
+   * as an `If-Match` HTTP header.
    */
-  async update(resource, id, data) {
+  async update(resource, id, data, opts) {
     await this.connect();
-    const result = await this.client.data.update(resource, String(id), data);
-    return result.record;
+    try {
+      const result = await this.client.data.update(
+        resource,
+        String(id),
+        data,
+        opts?.ifMatch ? { ifMatch: opts.ifMatch } : void 0
+      );
+      return result.record;
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
   }
   /**
    * Delete a record.
+   *
+   * Optional `opts.ifMatch` enables Optimistic Concurrency Control —
+   * see {@link update} for details. On 409 the call rejects with
+   * a {@link ConcurrentUpdateError}.
    */
-  async delete(resource, id) {
+  async delete(resource, id, opts) {
     await this.connect();
-    const result = await this.client.data.delete(resource, String(id));
-    return result.deleted;
+    try {
+      const result = await this.client.data.delete(
+        resource,
+        String(id),
+        opts?.ifMatch ? { ifMatch: opts.ifMatch } : void 0
+      );
+      return result.deleted;
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
   }
   /**
    * Bulk operations with optimized batch processing and error handling.
@@ -2157,6 +2215,7 @@ export {
   AuthenticationError,
   BulkOperationError,
   CloudOperations,
+  ConcurrentUpdateError,
   ConnectionError,
   IntegrationManager,
   MetadataNotFoundError,
@@ -2173,8 +2232,10 @@ export {
   generateContractManifest,
   getSharedDiscovery,
   is404Error,
+  isConcurrentUpdateError,
   isErrorType,
   isObjectStackError,
+  normaliseClientError,
   snapToGrid,
   validatePluginContract
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "5.0.2",
+  "version": "5.1.1",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -22,9 +22,9 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@objectstack/client": "^4.1.1",
-    "@object-ui/core": "5.0.2",
-    "@object-ui/types": "5.0.2"
+    "@objectstack/client": "^4.2.0",
+    "@object-ui/core": "5.1.1",
+    "@object-ui/types": "5.1.1"
   },
   "devDependencies": {
     "tsup": "^8.5.1",

package/src/index.ts

@@ -177,6 +177,67 @@ export function is404Error(error: unknown): boolean {
   return code === 'object_not_found' || code === 'record_not_found';
 }
 
+/**
+ * Thrown by `update()` / `delete()` when the server returns
+ * `409 CONCURRENT_UPDATE` — i.e. the record was modified by someone else
+ * between when the caller last read it and when they attempted to write.
+ *
+ * The error carries the current server-side `updated_at` version and the
+ * full latest record so the UI can render an informed conflict-resolution
+ * dialog (typically "Reload latest" / "Overwrite anyway" / "Cancel").
+ *
+ * Mirrors the {@link ConcurrentUpdateError} thrown by
+ * `@objectstack/objectql`'s protocol; the wire shape is:
+ * ```json
+ * { "code": "CONCURRENT_UPDATE",
+ *   "error": "<message>",
+ *   "currentVersion": "<updated_at>",
+ *   "currentRecord": { ...latest... } }
+ * ```
+ */
+export class ConcurrentUpdateError extends Error {
+  readonly code = 'CONCURRENT_UPDATE';
+  readonly httpStatus = 409;
+  readonly currentVersion: string | null;
+  readonly currentRecord: unknown;
+  constructor(opts: { currentVersion: string | null; currentRecord: unknown; message?: string }) {
+    super(opts.message ?? 'Record was modified by another user');
+    this.name = 'ConcurrentUpdateError';
+    this.currentVersion = opts.currentVersion;
+    this.currentRecord = opts.currentRecord;
+  }
+}
+
+/**
+ * Detect "concurrent update" errors raised by the platform. The wire
+ * shape is `409` + `code: 'CONCURRENT_UPDATE'`. The client surfaces
+ * extra details on `error.details` (full response body).
+ */
+export function isConcurrentUpdateError(error: unknown): error is ConcurrentUpdateError {
+  if (!error || typeof error !== 'object') return false;
+  const e = error as Record<string, unknown>;
+  return e.code === 'CONCURRENT_UPDATE' || e.name === 'ConcurrentUpdateError';
+}
+
+/**
+ * Convert any error thrown by the upstream client into a typed
+ * `ConcurrentUpdateError` when it represents a 409 CONCURRENT_UPDATE.
+ * Returns the original error untouched otherwise. Callers can simply
+ * `throw normaliseClientError(err)` from their catch blocks.
+ */
+export function normaliseClientError(error: unknown): unknown {
+  if (!error || typeof error !== 'object') return error;
+  const e = error as Record<string, unknown>;
+  if (e.code !== 'CONCURRENT_UPDATE' && e.httpStatus !== 409) return error;
+  if (e.code !== 'CONCURRENT_UPDATE') return error;
+  const details = (e.details ?? {}) as Record<string, unknown>;
+  return new ConcurrentUpdateError({
+    currentVersion: typeof details.currentVersion === 'string' ? details.currentVersion : null,
+    currentRecord: details.currentRecord ?? null,
+    message: typeof e.message === 'string' ? e.message : undefined,
+  });
+}
+
 /**
  * Build a Logger compatible with @objectstack/client that demotes expected
  * 404 noise to console.debug. The client logs every non-2xx response with
@@ -635,20 +696,58 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
 
   /**
    * Update an existing record.
+   *
+   * Optional `opts.ifMatch` enables Optimistic Concurrency Control: the
+   * server compares the supplied token (typically the `updated_at` value
+   * the caller previously read) against the record's current version
+   * and throws a {@link ConcurrentUpdateError} on mismatch (HTTP 409).
+   *
+   * Requires `@objectstack/client@>=4.2.0`, which forwards `opts.ifMatch`
+   * as an `If-Match` HTTP header.
    */
-  async update(resource: string, id: string | number, data: Partial<T>): Promise<T> {
+  async update(
+    resource: string,
+    id: string | number,
+    data: Partial<T>,
+    opts?: { ifMatch?: string },
+  ): Promise<T> {
     await this.connect();
-    const result = await this.client.data.update<T>(resource, String(id), data);
-    return result.record;
+    try {
+      const result = await this.client.data.update<T>(
+        resource,
+        String(id),
+        data,
+        opts?.ifMatch ? { ifMatch: opts.ifMatch } : undefined,
+      );
+      return result.record;
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
   }
 
   /**
    * Delete a record.
+   *
+   * Optional `opts.ifMatch` enables Optimistic Concurrency Control —
+   * see {@link update} for details. On 409 the call rejects with
+   * a {@link ConcurrentUpdateError}.
    */
-  async delete(resource: string, id: string | number): Promise<boolean> {
+  async delete(
+    resource: string,
+    id: string | number,
+    opts?: { ifMatch?: string },
+  ): Promise<boolean> {
     await this.connect();
-    const result = await this.client.data.delete(resource, String(id));
-    return result.deleted;
+    try {
+      const result = await this.client.data.delete(
+        resource,
+        String(id),
+        opts?.ifMatch ? { ifMatch: opts.ifMatch } : undefined,
+      );
+      return result.deleted;
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
   }
 
   /**

package/src/occ.test.ts

@@ -0,0 +1,101 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  ConcurrentUpdateError,
+  isConcurrentUpdateError,
+  normaliseClientError,
+} from './index';
+
+describe('Optimistic Concurrency Control errors', () => {
+  describe('ConcurrentUpdateError', () => {
+    it('carries currentVersion + currentRecord and a stable shape', () => {
+      const e = new ConcurrentUpdateError({
+        currentVersion: '2026-05-22T07:14:00.000Z',
+        currentRecord: { id: 'rec_1', name: 'Acme', updated_at: '2026-05-22T07:14:00.000Z' },
+        message: 'stale write',
+      });
+      expect(e).toBeInstanceOf(Error);
+      expect(e.name).toBe('ConcurrentUpdateError');
+      expect(e.code).toBe('CONCURRENT_UPDATE');
+      expect(e.httpStatus).toBe(409);
+      expect(e.currentVersion).toBe('2026-05-22T07:14:00.000Z');
+      expect((e.currentRecord as any).name).toBe('Acme');
+      expect(e.message).toBe('stale write');
+    });
+
+    it('defaults to a generic message when none is supplied', () => {
+      const e = new ConcurrentUpdateError({ currentVersion: null, currentRecord: null });
+      expect(e.message).toMatch(/modified/i);
+    });
+  });
+
+  describe('isConcurrentUpdateError', () => {
+    it('returns true for our typed instances', () => {
+      const e = new ConcurrentUpdateError({ currentVersion: null, currentRecord: null });
+      expect(isConcurrentUpdateError(e)).toBe(true);
+    });
+
+    it('returns true for plain objects with the canonical code', () => {
+      expect(isConcurrentUpdateError({ code: 'CONCURRENT_UPDATE' })).toBe(true);
+    });
+
+    it('returns false for unrelated errors', () => {
+      expect(isConcurrentUpdateError(new Error('boom'))).toBe(false);
+      expect(isConcurrentUpdateError({ code: 'NOT_FOUND' })).toBe(false);
+      expect(isConcurrentUpdateError(null)).toBe(false);
+      expect(isConcurrentUpdateError(undefined)).toBe(false);
+      expect(isConcurrentUpdateError('CONCURRENT_UPDATE')).toBe(false);
+    });
+  });
+
+  describe('normaliseClientError', () => {
+    it('returns the original error when it is not a 409 CONCURRENT_UPDATE', () => {
+      const generic = Object.assign(new Error('not found'), {
+        code: 'NOT_FOUND',
+        httpStatus: 404,
+      });
+      expect(normaliseClientError(generic)).toBe(generic);
+    });
+
+    it('returns the original error for non-object inputs', () => {
+      expect(normaliseClientError(null)).toBe(null);
+      expect(normaliseClientError(undefined)).toBe(undefined);
+      expect(normaliseClientError('boom')).toBe('boom');
+    });
+
+    it('wraps an upstream 409 CONCURRENT_UPDATE into a typed ConcurrentUpdateError', () => {
+      const upstream = Object.assign(new Error('Record was modified by another user'), {
+        code: 'CONCURRENT_UPDATE',
+        httpStatus: 409,
+        details: {
+          currentVersion: '2026-05-22T07:14:00.000Z',
+          currentRecord: { id: 'rec_1', name: 'Acme' },
+        },
+      });
+      const normalised = normaliseClientError(upstream);
+      expect(isConcurrentUpdateError(normalised)).toBe(true);
+      const typed = normalised as ConcurrentUpdateError;
+      expect(typed.currentVersion).toBe('2026-05-22T07:14:00.000Z');
+      expect((typed.currentRecord as any).name).toBe('Acme');
+      expect(typed.message).toBe('Record was modified by another user');
+    });
+
+    it('tolerates a missing details payload', () => {
+      const upstream = Object.assign(new Error('stale'), {
+        code: 'CONCURRENT_UPDATE',
+        httpStatus: 409,
+      });
+      const normalised = normaliseClientError(upstream) as ConcurrentUpdateError;
+      expect(isConcurrentUpdateError(normalised)).toBe(true);
+      expect(normalised.currentVersion).toBeNull();
+      expect(normalised.currentRecord).toBeNull();
+    });
+  });
+});