@object-ui/data-objectstack 5.0.2 → 5.2.1

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @object-ui/data-objectstack
 
+## 5.2.1
+
+### Patch Changes
+
+- @object-ui/types@5.2.1
+- @object-ui/core@5.2.1
+
+## 5.2.0
+
+### Minor Changes
+
+- de0c5e6: Add `DataSource.bulkDelete(resource, ids)` as the symmetric counterpart
+  to `bulkUpdate`. Implemented in `data-objectstack` via the client's
+  `deleteMany` primitive with a per-id fallback that emulates
+  `continueOnError` semantics for older clients.
+
+  Extract the bulk-vs-per-row decision into a reusable
+  `executeBulkBatch(input, ops)` helper in `@object-ui/core`:
+  - Single decision tree shared by both update and delete fast paths.
+  - Bulk success → no per-row pass.
+  - Bulk partial-count → aggregate batch error.
+  - Bulk throw → per-row fallback so users still get id-level error detail.
+
+  `useBulkExecutor` in plugin-grid now uses the helper for both `update`
+  and `delete` batches, cutting "delete 500 selected rows" from 500 HTTP
+  requests down to ~3.
+
+- 9997cae: DataSource: add optional `bulkUpdate(resource, ids, patch)` for "same patch, many rows" interactions (Slack "mark all as read", Linear "archive selected"). The ObjectStack adapter routes to `POST /api/v1/data/:object/updateMany` so the client pays one HTTP/auth/RLS round-trip instead of N parallel PATCHes, eliminating mark-all-read jank on inboxes with 50+ unread.
+
+  AppHeader's `markAllRead` now prefers `bulkUpdate`, with a transparent fallback to the per-id loop for adapters that don't implement the helper.
+
+### Patch Changes
+
+- Updated dependencies [de0c5e6]
+- Updated dependencies [9997cae]
+- Updated dependencies [70b5570]
+- Updated dependencies [d1442e3]
+  - @object-ui/types@5.2.0
+  - @object-ui/core@5.2.0
+
+## 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,124 @@ 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);
+    }
+  }
+  /**
+   * Apply the same patch to many records in a single round-trip.
+   *
+   * Sends one `POST /api/v1/data/:object/updateMany` request whose body
+   * is `{ records: ids.map(id => ({id, data: patch})), options: { continueOnError: true }}`.
+   * The server iterates server-side (still N engine writes) but the
+   * client only pays for ONE HTTP/auth/RLS round-trip — the relevant
+   * perf win for inbox / list-toolbar "mark all read" / "archive
+   * selected" interactions where N can easily be in the hundreds.
+   *
+   * Falls back to a sequential per-id loop when the connected client
+   * does not expose `updateMany` (older clients / offline adapters).
+   * In that case `continueOnError` semantics are emulated locally so
+   * callers see the same return shape.
+   */
+  async bulkUpdate(resource, ids, patch) {
+    await this.connect();
+    if (!ids || ids.length === 0) return 0;
+    const records = ids.map((id) => ({ id: String(id), data: patch }));
+    const updateMany = this.client.data.updateMany;
+    if (typeof updateMany === "function") {
+      try {
+        const res = await updateMany(resource, records, { continueOnError: true });
+        if (res && typeof res === "object" && typeof res.succeeded === "number") {
+          return res.succeeded;
+        }
+        if (Array.isArray(res)) return res.length;
+        return ids.length;
+      } catch (err) {
+        throw normaliseClientError(err);
+      }
+    }
+    let succeeded = 0;
+    for (const id of ids) {
+      try {
+        await this.client.data.update(resource, String(id), patch);
+        succeeded++;
+      } catch {
+      }
+    }
+    return succeeded;
+  }
+  /**
+   * Single-call bulk delete. Mirrors the bulkUpdate contract: prefers
+   * the server's `deleteMany` primitive when the client supports it;
+   * otherwise emulates `continueOnError` by looping `delete` per id and
+   * swallowing per-row failures. Returns the count of rows reported
+   * deleted by the server (or successfully deleted in fallback mode).
+   */
+  async bulkDelete(resource, ids) {
+    await this.connect();
+    if (!ids || ids.length === 0) return 0;
+    const strIds = ids.map((id) => String(id));
+    const deleteMany = this.client.data.deleteMany;
+    if (typeof deleteMany === "function") {
+      try {
+        const res = await deleteMany(resource, strIds, { continueOnError: true });
+        if (res && typeof res === "object" && typeof res.succeeded === "number") {
+          return res.succeeded;
+        }
+        if (Array.isArray(res)) return res.length;
+        return strIds.length;
+      } catch (err) {
+        throw normaliseClientError(err);
+      }
+    }
+    let succeeded = 0;
+    for (const id of strIds) {
+      try {
+        await this.client.data.delete(resource, id);
+        succeeded++;
+      } catch {
+      }
+    }
+    return succeeded;
   }
   /**
    * Bulk operations with optimized batch processing and error handling.
@@ -2202,6 +2339,7 @@ function createObjectStackAdapter(config) {
   AuthenticationError,
   BulkOperationError,
   CloudOperations,
+  ConcurrentUpdateError,
   ConnectionError,
   IntegrationManager,
   MetadataNotFoundError,
@@ -2218,8 +2356,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,52 @@ 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, opts?: {
+        ifMatch?: string;
+    }): Promise<boolean>;
+    /**
+     * Apply the same patch to many records in a single round-trip.
+     *
+     * Sends one `POST /api/v1/data/:object/updateMany` request whose body
+     * is `{ records: ids.map(id => ({id, data: patch})), options: { continueOnError: true }}`.
+     * The server iterates server-side (still N engine writes) but the
+     * client only pays for ONE HTTP/auth/RLS round-trip — the relevant
+     * perf win for inbox / list-toolbar "mark all read" / "archive
+     * selected" interactions where N can easily be in the hundreds.
+     *
+     * Falls back to a sequential per-id loop when the connected client
+     * does not expose `updateMany` (older clients / offline adapters).
+     * In that case `continueOnError` semantics are emulated locally so
+     * callers see the same return shape.
+     */
+    bulkUpdate(resource: string, ids: ReadonlyArray<string | number>, patch: Partial<T>): Promise<number>;
+    /**
+     * Single-call bulk delete. Mirrors the bulkUpdate contract: prefers
+     * the server's `deleteMany` primitive when the client supports it;
+     * otherwise emulates `continueOnError` by looping `delete` per id and
+     * swallowing per-row failures. Returns the count of rows reported
+     * deleted by the server (or successfully deleted in fallback mode).
      */
-    delete(resource: string, id: string | number): Promise<boolean>;
+    bulkDelete(resource: string, ids: ReadonlyArray<string | number>): Promise<number>;
     /**
      * Bulk operations with optimized batch processing and error handling.
      * Emits progress events for tracking operation status.
@@ -1151,4 +1233,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,52 @@ 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, opts?: {
+        ifMatch?: string;
+    }): Promise<boolean>;
+    /**
+     * Apply the same patch to many records in a single round-trip.
+     *
+     * Sends one `POST /api/v1/data/:object/updateMany` request whose body
+     * is `{ records: ids.map(id => ({id, data: patch})), options: { continueOnError: true }}`.
+     * The server iterates server-side (still N engine writes) but the
+     * client only pays for ONE HTTP/auth/RLS round-trip — the relevant
+     * perf win for inbox / list-toolbar "mark all read" / "archive
+     * selected" interactions where N can easily be in the hundreds.
+     *
+     * Falls back to a sequential per-id loop when the connected client
+     * does not expose `updateMany` (older clients / offline adapters).
+     * In that case `continueOnError` semantics are emulated locally so
+     * callers see the same return shape.
+     */
+    bulkUpdate(resource: string, ids: ReadonlyArray<string | number>, patch: Partial<T>): Promise<number>;
+    /**
+     * Single-call bulk delete. Mirrors the bulkUpdate contract: prefers
+     * the server's `deleteMany` primitive when the client supports it;
+     * otherwise emulates `continueOnError` by looping `delete` per id and
+     * swallowing per-row failures. Returns the count of rows reported
+     * deleted by the server (or successfully deleted in fallback mode).
      */
-    delete(resource: string, id: string | number): Promise<boolean>;
+    bulkDelete(resource: string, ids: ReadonlyArray<string | number>): Promise<number>;
     /**
      * Bulk operations with optimized batch processing and error handling.
      * Emits progress events for tracking operation status.
@@ -1151,4 +1233,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,124 @@ 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);
+    }
+  }
+  /**
+   * Apply the same patch to many records in a single round-trip.
+   *
+   * Sends one `POST /api/v1/data/:object/updateMany` request whose body
+   * is `{ records: ids.map(id => ({id, data: patch})), options: { continueOnError: true }}`.
+   * The server iterates server-side (still N engine writes) but the
+   * client only pays for ONE HTTP/auth/RLS round-trip — the relevant
+   * perf win for inbox / list-toolbar "mark all read" / "archive
+   * selected" interactions where N can easily be in the hundreds.
+   *
+   * Falls back to a sequential per-id loop when the connected client
+   * does not expose `updateMany` (older clients / offline adapters).
+   * In that case `continueOnError` semantics are emulated locally so
+   * callers see the same return shape.
+   */
+  async bulkUpdate(resource, ids, patch) {
+    await this.connect();
+    if (!ids || ids.length === 0) return 0;
+    const records = ids.map((id) => ({ id: String(id), data: patch }));
+    const updateMany = this.client.data.updateMany;
+    if (typeof updateMany === "function") {
+      try {
+        const res = await updateMany(resource, records, { continueOnError: true });
+        if (res && typeof res === "object" && typeof res.succeeded === "number") {
+          return res.succeeded;
+        }
+        if (Array.isArray(res)) return res.length;
+        return ids.length;
+      } catch (err) {
+        throw normaliseClientError(err);
+      }
+    }
+    let succeeded = 0;
+    for (const id of ids) {
+      try {
+        await this.client.data.update(resource, String(id), patch);
+        succeeded++;
+      } catch {
+      }
+    }
+    return succeeded;
+  }
+  /**
+   * Single-call bulk delete. Mirrors the bulkUpdate contract: prefers
+   * the server's `deleteMany` primitive when the client supports it;
+   * otherwise emulates `continueOnError` by looping `delete` per id and
+   * swallowing per-row failures. Returns the count of rows reported
+   * deleted by the server (or successfully deleted in fallback mode).
+   */
+  async bulkDelete(resource, ids) {
+    await this.connect();
+    if (!ids || ids.length === 0) return 0;
+    const strIds = ids.map((id) => String(id));
+    const deleteMany = this.client.data.deleteMany;
+    if (typeof deleteMany === "function") {
+      try {
+        const res = await deleteMany(resource, strIds, { continueOnError: true });
+        if (res && typeof res === "object" && typeof res.succeeded === "number") {
+          return res.succeeded;
+        }
+        if (Array.isArray(res)) return res.length;
+        return strIds.length;
+      } catch (err) {
+        throw normaliseClientError(err);
+      }
+    }
+    let succeeded = 0;
+    for (const id of strIds) {
+      try {
+        await this.client.data.delete(resource, id);
+        succeeded++;
+      } catch {
+      }
+    }
+    return succeeded;
   }
   /**
    * Bulk operations with optimized batch processing and error handling.
@@ -2157,6 +2291,7 @@ export {
   AuthenticationError,
   BulkOperationError,
   CloudOperations,
+  ConcurrentUpdateError,
   ConnectionError,
   IntegrationManager,
   MetadataNotFoundError,
@@ -2173,8 +2308,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.2.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.2.1",
+    "@object-ui/types": "5.2.1"
   },
   "devDependencies": {
     "tsup": "^8.5.1",

package/src/bulkDelete.test.ts

@@ -0,0 +1,75 @@
+/**
+ * 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, vi } from 'vitest';
+import { ObjectStackAdapter } from './index';
+
+function makeDS(stub: { deleteMany?: any; delete?: any }) {
+  const ds: any = new ObjectStackAdapter({
+    baseUrl: 'http://test.local',
+    fetch: vi.fn(async () => {
+      const body = { success: true, data: { capabilities: {}, routes: {} } };
+      return new Response(JSON.stringify(body), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }),
+  });
+  ds.connected = true;
+  ds.connectionState = 'connected';
+  ds.client = { data: stub };
+  return ds;
+}
+
+describe('ObjectStackDataSource.bulkDelete', () => {
+  it('returns 0 and skips network when ids is empty', async () => {
+    const deleteMany = vi.fn();
+    const ds = makeDS({ deleteMany });
+    const n = await ds.bulkDelete('sys_notification', []);
+    expect(n).toBe(0);
+    expect(deleteMany).not.toHaveBeenCalled();
+  });
+
+  it('issues a single deleteMany call with the id list', async () => {
+    const deleteMany = vi.fn().mockResolvedValue({ succeeded: 3, failed: 0 });
+    const ds = makeDS({ deleteMany });
+    const n = await ds.bulkDelete('task', ['a', 'b', 'c']);
+    expect(n).toBe(3);
+    expect(deleteMany).toHaveBeenCalledTimes(1);
+    const [resource, ids, opts] = deleteMany.mock.calls[0];
+    expect(resource).toBe('task');
+    expect(ids).toEqual(['a', 'b', 'c']);
+    expect(opts).toEqual({ continueOnError: true });
+  });
+
+  it('returns ids.length when deleteMany returns void (older clients)', async () => {
+    const deleteMany = vi.fn().mockResolvedValue(undefined);
+    const ds = makeDS({ deleteMany });
+    const n = await ds.bulkDelete('task', ['a', 'b']);
+    expect(n).toBe(2);
+  });
+
+  it('falls back to per-id delete loop when deleteMany is missing', async () => {
+    const del = vi.fn(async (_: string, id: string) => {
+      if (id === 'b') throw new Error('FK violation');
+    });
+    const ds = makeDS({ delete: del });
+    const n = await ds.bulkDelete('task', ['a', 'b', 'c']);
+    // continueOnError-emulated: b throws, a + c succeed.
+    expect(n).toBe(2);
+    expect(del).toHaveBeenCalledTimes(3);
+  });
+
+  it('coerces non-string ids before sending', async () => {
+    const deleteMany = vi.fn().mockResolvedValue({ succeeded: 2 });
+    const ds = makeDS({ deleteMany });
+    await ds.bulkDelete('task', [1, 2]);
+    const [, ids] = deleteMany.mock.calls[0];
+    expect(ids).toEqual(['1', '2']);
+  });
+});

package/src/bulkUpdate.test.ts

@@ -0,0 +1,93 @@
+/**
+ * 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, vi } from 'vitest';
+import { ObjectStackAdapter } from './index';
+
+/**
+ * Build a DataSource instance with a stubbed `fetch` that satisfies the
+ * one-shot discovery probe inside `connect()`. The client object is then
+ * swapped out for a lightweight mock so we can assert directly against
+ * the `updateMany` / `update` calls without spinning real HTTP.
+ */
+function makeDS(stub: { updateMany?: any; update?: any }) {
+  const ds: any = new ObjectStackAdapter({
+    baseUrl: 'http://test.local',
+    fetch: vi.fn(async (_url: any, _init: any) => {
+      const body = { success: true, data: { capabilities: {}, routes: {} } };
+      return new Response(JSON.stringify(body), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }),
+  });
+  // Pre-mark connected so connect() short-circuits without hitting fetch.
+  ds.connected = true;
+  ds.connectionState = 'connected';
+  ds.client = { data: stub };
+  return ds;
+}
+
+describe('ObjectStackDataSource.bulkUpdate', () => {
+  it('returns 0 and skips network when ids is empty', async () => {
+    const updateMany = vi.fn();
+    const ds = makeDS({ updateMany });
+    const n = await ds.bulkUpdate('sys_notification', [], { is_read: true });
+    expect(n).toBe(0);
+    expect(updateMany).not.toHaveBeenCalled();
+  });
+
+  it('issues a single updateMany call with the per-id record shape', async () => {
+    const updateMany = vi.fn().mockResolvedValue({ succeeded: 3, failed: 0, results: [] });
+    const ds = makeDS({ updateMany });
+    const n = await ds.bulkUpdate('sys_notification', ['a', 'b', 'c'], {
+      is_read: true,
+      read_at: '2026-05-23T05:00:00.000Z',
+    });
+    expect(n).toBe(3);
+    expect(updateMany).toHaveBeenCalledTimes(1);
+    const [resource, records, opts] = updateMany.mock.calls[0];
+    expect(resource).toBe('sys_notification');
+    expect(opts).toEqual({ continueOnError: true });
+    expect(records).toEqual([
+      { id: 'a', data: { is_read: true, read_at: '2026-05-23T05:00:00.000Z' } },
+      { id: 'b', data: { is_read: true, read_at: '2026-05-23T05:00:00.000Z' } },
+      { id: 'c', data: { is_read: true, read_at: '2026-05-23T05:00:00.000Z' } },
+    ]);
+  });
+
+  it('honors server-reported partial success counts', async () => {
+    const updateMany = vi.fn().mockResolvedValue({ succeeded: 2, failed: 1, results: [] });
+    const ds = makeDS({ updateMany });
+    const n = await ds.bulkUpdate('sys_notification', ['a', 'b', 'c'], { is_read: true });
+    expect(n).toBe(2);
+  });
+
+  it('falls back to per-id updates when client.data.updateMany is missing', async () => {
+    const update = vi.fn().mockResolvedValue({ record: {} });
+    const ds = makeDS({ update });
+    const n = await ds.bulkUpdate('sys_notification', ['a', 'b'], { is_read: true });
+    expect(n).toBe(2);
+    expect(update).toHaveBeenCalledTimes(2);
+    expect(update.mock.calls[0][0]).toBe('sys_notification');
+    expect(update.mock.calls[0][1]).toBe('a');
+    expect(update.mock.calls[0][2]).toEqual({ is_read: true });
+  });
+
+  it('fallback path tolerates per-row failures (continueOnError semantics)', async () => {
+    const update = vi
+      .fn()
+      .mockResolvedValueOnce({ record: {} })
+      .mockRejectedValueOnce(new Error('row 2 failed'))
+      .mockResolvedValueOnce({ record: {} });
+    const ds = makeDS({ update });
+    const n = await ds.bulkUpdate('sys_notification', ['a', 'b', 'c'], { is_read: true });
+    expect(n).toBe(2);
+    expect(update).toHaveBeenCalledTimes(3);
+  });
+});

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,156 @@ 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);
+    }
+  }
+
+  /**
+   * Apply the same patch to many records in a single round-trip.
+   *
+   * Sends one `POST /api/v1/data/:object/updateMany` request whose body
+   * is `{ records: ids.map(id => ({id, data: patch})), options: { continueOnError: true }}`.
+   * The server iterates server-side (still N engine writes) but the
+   * client only pays for ONE HTTP/auth/RLS round-trip — the relevant
+   * perf win for inbox / list-toolbar "mark all read" / "archive
+   * selected" interactions where N can easily be in the hundreds.
+   *
+   * Falls back to a sequential per-id loop when the connected client
+   * does not expose `updateMany` (older clients / offline adapters).
+   * In that case `continueOnError` semantics are emulated locally so
+   * callers see the same return shape.
+   */
+  async bulkUpdate(
+    resource: string,
+    ids: ReadonlyArray<string | number>,
+    patch: Partial<T>,
+  ): Promise<number> {
+    await this.connect();
+    if (!ids || ids.length === 0) return 0;
+    const records = ids.map((id) => ({ id: String(id), data: patch as any }));
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const updateMany = (this.client.data as any).updateMany;
+    if (typeof updateMany === 'function') {
+      try {
+        const res = await updateMany(resource, records, { continueOnError: true });
+        // The server returns BatchUpdateResponse { succeeded, failed, ... };
+        // fall back to ids.length on adapters that return a bare array.
+        if (res && typeof res === 'object' && typeof (res as any).succeeded === 'number') {
+          return (res as any).succeeded as number;
+        }
+        if (Array.isArray(res)) return (res as any[]).length;
+        return ids.length;
+      } catch (err) {
+        throw normaliseClientError(err);
+      }
+    }
+
+    // Fallback: sequential per-id updates, tolerating failures.
+    let succeeded = 0;
+    for (const id of ids) {
+      try {
+        await this.client.data.update<T>(resource, String(id), patch);
+        succeeded++;
+      } catch {
+        // continueOnError semantics — swallow per-row errors
+      }
+    }
+    return succeeded;
+  }
+
+  /**
+   * Single-call bulk delete. Mirrors the bulkUpdate contract: prefers
+   * the server's `deleteMany` primitive when the client supports it;
+   * otherwise emulates `continueOnError` by looping `delete` per id and
+   * swallowing per-row failures. Returns the count of rows reported
+   * deleted by the server (or successfully deleted in fallback mode).
+   */
+  async bulkDelete(
+    resource: string,
+    ids: ReadonlyArray<string | number>,
+  ): Promise<number> {
+    await this.connect();
+    if (!ids || ids.length === 0) return 0;
+    const strIds = ids.map((id) => String(id));
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const deleteMany = (this.client.data as any).deleteMany;
+    if (typeof deleteMany === 'function') {
+      try {
+        const res = await deleteMany(resource, strIds, { continueOnError: true });
+        if (res && typeof res === 'object' && typeof (res as any).succeeded === 'number') {
+          return (res as any).succeeded as number;
+        }
+        if (Array.isArray(res)) return (res as any[]).length;
+        // deleteMany historically returns void on success — assume all hit.
+        return strIds.length;
+      } catch (err) {
+        throw normaliseClientError(err);
+      }
+    }
+
+    // Fallback: sequential per-id deletes, tolerating failures.
+    let succeeded = 0;
+    for (const id of strIds) {
+      try {
+        await this.client.data.delete(resource, id);
+        succeeded++;
+      } catch {
+        // continueOnError semantics — swallow per-row errors
+      }
+    }
+    return succeeded;
   }
 
   /**

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