@object-ui/data-objectstack 16.0.0 → 16.1.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { ObjectStackClient } from '@objectstack/client';
-import { DataSource, QueryParams, QueryResult, MutationEvent, ImportRequestOptions, ImportRecordsResult, CreateImportJobResult, ImportJobProgressInfo, ImportJobResultsInfo, ListImportJobsOptions, ImportJobSummaryInfo, ImportJobUndoResult, ExportDownloadRequest, FileUploadResult } from '@object-ui/types';
+import { DataSource, QueryParams, QueryResult, MutationEvent, BatchTransactionOperation, ImportRequestOptions, ImportRecordsResult, CreateImportJobResult, ImportJobProgressInfo, ImportJobResultsInfo, ListImportJobsOptions, ImportJobSummaryInfo, ImportJobUndoResult, ExportDownloadRequest, FileUploadResult } from '@object-ui/types';
 export { FileUploadResult } from '@object-ui/types';
 
 /**
@@ -1182,6 +1182,26 @@ declare function calculateAutoLayout(items: Array<{
 declare function getSharedDiscovery(baseUrl: string, fetcher: () => Promise<unknown>): Promise<unknown>;
 /** Test/dev helper to drop the cache (e.g. on logout or origin change). */
 declare function clearSharedDiscoveryCache(): void;
+/**
+ * Read the cross-object atomic-batch capability from a `discovery` document
+ * (framework #3298 / objectui #2693). The server advertises it hierarchically
+ * under `capabilities.transactionalBatch.enabled`; the published
+ * `@objectstack/client` also accepts the flat `capabilities.transactionalBatch:
+ * boolean` form and normalizes the two — mirror that here so the adapter reads
+ * the same bit regardless of which shape reaches it.
+ *
+ * Returns:
+ *   - `true`  — the backend GUARANTEES an atomic `/batch` (declared === enforced,
+ *     i.e. the route is mounted AND the runtime can honour a transaction): the
+ *     client may drop its non-atomic fallback and treat any batch failure as a
+ *     real error.
+ *   - `false` — the backend explicitly does NOT (route absent, or a runtime that
+ *     can't open a transaction).
+ *   - `undefined` — the capability is absent, i.e. the backend predates #3298;
+ *     the caller must keep the legacy runtime-probe fallback (we can't tell
+ *     whether `/batch` exists without trying it).
+ */
+declare function readTransactionalBatchCapability(discovery: unknown): boolean | undefined;
 /**
  * Detect "missing resource" errors regardless of where they originate.
  *
@@ -1311,6 +1331,8 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private fetchImpl;
     private inflightFinds;
     private missingResources;
+    private batchUnsupported;
+    private atomicBatchCapability;
     private mutationListeners;
     constructor(config: {
         baseUrl: string;
@@ -1440,19 +1462,53 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @returns Promise resolving to array of results
      */
     /**
-     * Cross-object transactional batch (ObjectStack #1604). Runs the operations
-     * in ONE server transaction — commit all or roll back all. A field value of
-     * `{ $ref: <earlier op index> }` resolves to that op's created id, so a child
-     * can reference its parent created earlier in the same batch (master-detail).
-     */
-    batchTransaction(operations: Array<{
-        object: string;
-        action?: 'create' | 'update' | 'delete';
-        data?: any;
-        id?: string;
-    }>): Promise<{
+     * Cross-object transactional batch (ObjectStack #1604 / ADR-0034 item 4).
+     * Runs the operations in ONE server transaction — commit all or roll back
+     * all. A field value of `{ $ref: <earlier op index> }` resolves to that op's
+     * created id, so a child can reference its parent created earlier in the same
+     * batch (master-detail).
+     *
+     * Transport: the published `@objectstack/client` SDK method
+     * `data.batchTransaction` (framework #3271; shipped since client v16, our
+     * dependency floor). Per AGENTS.md §7 data always flows through the client —
+     * never a hand-rolled `fetch('/api/v1/batch')`.
+     *
+     * Fallback decision — declarative capability negotiation (framework #3298 /
+     * objectui #2693). At connect() we read `capabilities.transactionalBatch`
+     * from discovery:
+     *   - Declared `true` → the backend GUARANTEES atomicity (declared ===
+     *     enforced). We TRUST it: any batch failure — including 404/405/501 —
+     *     surfaces as a real error. No non-atomic client-side compensation. This
+     *     is the path modern backends take.
+     *   - Declared `false`, or ABSENT (backend predates #3298) → we can't rely on
+     *     server atomicity, so we keep the legacy behaviour: on 404/405 (no
+     *     endpoint) or 501 (runtime without transactions) degrade to the
+     *     client-side, NON-atomic {@link emulateBatchTransaction} so a save is
+     *     still possible. Removing that here would regress older backends from
+     *     "saves, less safe" to "no save path" (#2679 compatibility constraint).
+     *     The non-atomic fallback stays isolated to THIS adapter.
+     */
+    batchTransaction(operations: BatchTransactionOperation[]): Promise<{
         results: any[];
     }>;
+    /** True for statuses that mean "this backend can't do a transactional batch". */
+    private batchStatusUnsupported;
+    /** Best-effort HTTP status extraction from a thrown SDK/client error. */
+    private errorStatusOf;
+    /** Mark the endpoint unsupported (warn once) and serve via emulation. */
+    private fallbackToEmulation;
+    /**
+     * Emit one MutationEvent per committed operation so the invalidation bus
+     * (#2269) sees writes that went through /batch exactly like single
+     * create/update/delete calls — master-detail ModalForm saves otherwise leave
+     * related lists and count badges stale (#2582). `results` is index-aligned
+     * with `operations`; creates take id/record from the server echo.
+     *
+     * Only called on the server-committed paths. The emulation branch drives the
+     * adapter's own create/update/delete primitives, which already emit — so it
+     * must NOT be routed through here, or events would double-fire.
+     */
+    private emitBatchMutations;
     bulk(resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]>;
     /**
      * Bulk-import raw spreadsheet rows in a single server round-trip via
@@ -1640,7 +1696,16 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * Filters by `data.object === objectName` (or top-level `object`)
      * client-side because the metadata index is name-only, not field-typed.
      */
-    listViews(objectName: string): Promise<any[]>;
+    listViews(objectName: string, options?: {
+        previewDrafts?: boolean;
+    }): Promise<any[]>;
+    /**
+     * Build a {@link MetadataClient} bound to this adapter's server + auth. Used
+     * by draft-aware reads (`listViews({ previewDrafts })`) so the `/meta` route,
+     * `?preview=draft` flag, and environment scoping live in the SDK rather than
+     * being hand-assembled at each call site (#2767 P3).
+     */
+    private metadataClient;
     /**
      * List registered import `mapping` artifacts targeting a given object
      * (framework #2611). Reads the `mapping` metadata kind via the overlay API
@@ -1873,4 +1938,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, 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, type MetadataAuditEntry, type MetadataAuditResponse, MetadataClient, type MetadataClientConfig, type MetadataDeleteOptions, type MetadataDiagnostics, type MetadataDiagnosticsEntry, type MetadataDiagnosticsOptions, type MetadataDiagnosticsSummary, type MetadataDraftHeader, type MetadataError, type MetadataGetOptions, type MetadataHistoryOptions, type MetadataLayered, type MetadataListOptions, MetadataNotFoundError, type MetadataReference, type MetadataSaveOptions, type MetadataValidationIssue, 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 };
+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, type MetadataAuditEntry, type MetadataAuditResponse, MetadataClient, type MetadataClientConfig, type MetadataDeleteOptions, type MetadataDiagnostics, type MetadataDiagnosticsEntry, type MetadataDiagnosticsOptions, type MetadataDiagnosticsSummary, type MetadataDraftHeader, type MetadataError, type MetadataGetOptions, type MetadataHistoryOptions, type MetadataLayered, type MetadataListOptions, MetadataNotFoundError, type MetadataReference, type MetadataSaveOptions, type MetadataValidationIssue, 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, readTransactionalBatchCapability, snapToGrid, validatePluginContract };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ObjectStackClient } from '@objectstack/client';
-import { DataSource, QueryParams, QueryResult, MutationEvent, ImportRequestOptions, ImportRecordsResult, CreateImportJobResult, ImportJobProgressInfo, ImportJobResultsInfo, ListImportJobsOptions, ImportJobSummaryInfo, ImportJobUndoResult, ExportDownloadRequest, FileUploadResult } from '@object-ui/types';
+import { DataSource, QueryParams, QueryResult, MutationEvent, BatchTransactionOperation, ImportRequestOptions, ImportRecordsResult, CreateImportJobResult, ImportJobProgressInfo, ImportJobResultsInfo, ListImportJobsOptions, ImportJobSummaryInfo, ImportJobUndoResult, ExportDownloadRequest, FileUploadResult } from '@object-ui/types';
 export { FileUploadResult } from '@object-ui/types';
 
 /**
@@ -1182,6 +1182,26 @@ declare function calculateAutoLayout(items: Array<{
 declare function getSharedDiscovery(baseUrl: string, fetcher: () => Promise<unknown>): Promise<unknown>;
 /** Test/dev helper to drop the cache (e.g. on logout or origin change). */
 declare function clearSharedDiscoveryCache(): void;
+/**
+ * Read the cross-object atomic-batch capability from a `discovery` document
+ * (framework #3298 / objectui #2693). The server advertises it hierarchically
+ * under `capabilities.transactionalBatch.enabled`; the published
+ * `@objectstack/client` also accepts the flat `capabilities.transactionalBatch:
+ * boolean` form and normalizes the two — mirror that here so the adapter reads
+ * the same bit regardless of which shape reaches it.
+ *
+ * Returns:
+ *   - `true`  — the backend GUARANTEES an atomic `/batch` (declared === enforced,
+ *     i.e. the route is mounted AND the runtime can honour a transaction): the
+ *     client may drop its non-atomic fallback and treat any batch failure as a
+ *     real error.
+ *   - `false` — the backend explicitly does NOT (route absent, or a runtime that
+ *     can't open a transaction).
+ *   - `undefined` — the capability is absent, i.e. the backend predates #3298;
+ *     the caller must keep the legacy runtime-probe fallback (we can't tell
+ *     whether `/batch` exists without trying it).
+ */
+declare function readTransactionalBatchCapability(discovery: unknown): boolean | undefined;
 /**
  * Detect "missing resource" errors regardless of where they originate.
  *
@@ -1311,6 +1331,8 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     private fetchImpl;
     private inflightFinds;
     private missingResources;
+    private batchUnsupported;
+    private atomicBatchCapability;
     private mutationListeners;
     constructor(config: {
         baseUrl: string;
@@ -1440,19 +1462,53 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * @returns Promise resolving to array of results
      */
     /**
-     * Cross-object transactional batch (ObjectStack #1604). Runs the operations
-     * in ONE server transaction — commit all or roll back all. A field value of
-     * `{ $ref: <earlier op index> }` resolves to that op's created id, so a child
-     * can reference its parent created earlier in the same batch (master-detail).
-     */
-    batchTransaction(operations: Array<{
-        object: string;
-        action?: 'create' | 'update' | 'delete';
-        data?: any;
-        id?: string;
-    }>): Promise<{
+     * Cross-object transactional batch (ObjectStack #1604 / ADR-0034 item 4).
+     * Runs the operations in ONE server transaction — commit all or roll back
+     * all. A field value of `{ $ref: <earlier op index> }` resolves to that op's
+     * created id, so a child can reference its parent created earlier in the same
+     * batch (master-detail).
+     *
+     * Transport: the published `@objectstack/client` SDK method
+     * `data.batchTransaction` (framework #3271; shipped since client v16, our
+     * dependency floor). Per AGENTS.md §7 data always flows through the client —
+     * never a hand-rolled `fetch('/api/v1/batch')`.
+     *
+     * Fallback decision — declarative capability negotiation (framework #3298 /
+     * objectui #2693). At connect() we read `capabilities.transactionalBatch`
+     * from discovery:
+     *   - Declared `true` → the backend GUARANTEES atomicity (declared ===
+     *     enforced). We TRUST it: any batch failure — including 404/405/501 —
+     *     surfaces as a real error. No non-atomic client-side compensation. This
+     *     is the path modern backends take.
+     *   - Declared `false`, or ABSENT (backend predates #3298) → we can't rely on
+     *     server atomicity, so we keep the legacy behaviour: on 404/405 (no
+     *     endpoint) or 501 (runtime without transactions) degrade to the
+     *     client-side, NON-atomic {@link emulateBatchTransaction} so a save is
+     *     still possible. Removing that here would regress older backends from
+     *     "saves, less safe" to "no save path" (#2679 compatibility constraint).
+     *     The non-atomic fallback stays isolated to THIS adapter.
+     */
+    batchTransaction(operations: BatchTransactionOperation[]): Promise<{
         results: any[];
     }>;
+    /** True for statuses that mean "this backend can't do a transactional batch". */
+    private batchStatusUnsupported;
+    /** Best-effort HTTP status extraction from a thrown SDK/client error. */
+    private errorStatusOf;
+    /** Mark the endpoint unsupported (warn once) and serve via emulation. */
+    private fallbackToEmulation;
+    /**
+     * Emit one MutationEvent per committed operation so the invalidation bus
+     * (#2269) sees writes that went through /batch exactly like single
+     * create/update/delete calls — master-detail ModalForm saves otherwise leave
+     * related lists and count badges stale (#2582). `results` is index-aligned
+     * with `operations`; creates take id/record from the server echo.
+     *
+     * Only called on the server-committed paths. The emulation branch drives the
+     * adapter's own create/update/delete primitives, which already emit — so it
+     * must NOT be routed through here, or events would double-fire.
+     */
+    private emitBatchMutations;
     bulk(resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]>;
     /**
      * Bulk-import raw spreadsheet rows in a single server round-trip via
@@ -1640,7 +1696,16 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * Filters by `data.object === objectName` (or top-level `object`)
      * client-side because the metadata index is name-only, not field-typed.
      */
-    listViews(objectName: string): Promise<any[]>;
+    listViews(objectName: string, options?: {
+        previewDrafts?: boolean;
+    }): Promise<any[]>;
+    /**
+     * Build a {@link MetadataClient} bound to this adapter's server + auth. Used
+     * by draft-aware reads (`listViews({ previewDrafts })`) so the `/meta` route,
+     * `?preview=draft` flag, and environment scoping live in the SDK rather than
+     * being hand-assembled at each call site (#2767 P3).
+     */
+    private metadataClient;
     /**
      * List registered import `mapping` artifacts targeting a given object
      * (framework #2611). Reads the `mapping` metadata kind via the overlay API
@@ -1873,4 +1938,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, 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, type MetadataAuditEntry, type MetadataAuditResponse, MetadataClient, type MetadataClientConfig, type MetadataDeleteOptions, type MetadataDiagnostics, type MetadataDiagnosticsEntry, type MetadataDiagnosticsOptions, type MetadataDiagnosticsSummary, type MetadataDraftHeader, type MetadataError, type MetadataGetOptions, type MetadataHistoryOptions, type MetadataLayered, type MetadataListOptions, MetadataNotFoundError, type MetadataReference, type MetadataSaveOptions, type MetadataValidationIssue, 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 };
+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, type MetadataAuditEntry, type MetadataAuditResponse, MetadataClient, type MetadataClientConfig, type MetadataDeleteOptions, type MetadataDiagnostics, type MetadataDiagnosticsEntry, type MetadataDiagnosticsOptions, type MetadataDiagnosticsSummary, type MetadataDraftHeader, type MetadataError, type MetadataGetOptions, type MetadataHistoryOptions, type MetadataLayered, type MetadataListOptions, MetadataNotFoundError, type MetadataReference, type MetadataSaveOptions, type MetadataValidationIssue, 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, readTransactionalBatchCapability, snapToGrid, validatePluginContract };