@object-ui/data-objectstack 11.3.0 → 11.5.0

package/src/index.ts

@@ -7,7 +7,22 @@
  */
 
 import { ObjectStackClient, type QueryOptions as ObjectStackQueryOptions } from '@objectstack/client';
-import type { DataSource, QueryParams, QueryResult, FileUploadResult, ExportDownloadRequest } from '@object-ui/types';
+import type {
+  DataSource,
+  MutationEvent,
+  QueryParams,
+  QueryResult,
+  FileUploadResult,
+  ExportDownloadRequest,
+  ImportRequestOptions,
+  ImportRecordsResult,
+  CreateImportJobResult,
+  ImportJobProgressInfo,
+  ImportJobResultsInfo,
+  ImportJobSummaryInfo,
+  ImportJobUndoResult,
+  ListImportJobsOptions,
+} from '@object-ui/types';
 import { convertFiltersToAST } from '@object-ui/core';
 import { MetadataCache } from './cache/MetadataCache';
 import {
@@ -389,6 +404,11 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   // so optional collections like sys_presence don't hammer the server with
   // failing requests on every record open / panel render.
   private missingResources = new Set<string>();
+  // Subscribers registered via onMutation(). Emitted after each successful
+  // create/update/delete so data-bound views (ListView, ObjectView, kanban,
+  // calendar) auto-refresh — the interface ListView relies on to reflect
+  // inline-edit "Save All" writes without a manual reload.
+  private mutationListeners = new Set<(event: MutationEvent<T>) => void>();
 
   constructor(config: {
     baseUrl: string;
@@ -692,9 +712,37 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   /**
    * Create a new record.
    */
+  /**
+   * Notify all mutation subscribers. A throwing listener must not break the
+   * mutation or starve the other subscribers, so each is isolated.
+   */
+  private emitMutation(event: MutationEvent<T>): void {
+    for (const listener of this.mutationListeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        console.warn('ObjectStackAdapter: mutation listener error', err);
+      }
+    }
+  }
+
+  /**
+   * Subscribe to create/update/delete events on any resource. Returns an
+   * unsubscribe function. Data-bound views use this to auto-refresh after a
+   * mutation (e.g. inline-edit "Save All", which writes through `update` and
+   * must repaint the list without a manual reload).
+   */
+  onMutation(callback: (event: MutationEvent<T>) => void): () => void {
+    this.mutationListeners.add(callback);
+    return () => {
+      this.mutationListeners.delete(callback);
+    };
+  }
+
   async create(resource: string, data: Partial<T>): Promise<T> {
     await this.connect();
     const result = await this.client.data.create<T>(resource, data);
+    this.emitMutation({ type: 'create', resource, record: { ...result.record } });
     return result.record;
   }
 
@@ -723,6 +771,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         data,
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : undefined,
       );
+      this.emitMutation({ type: 'update', resource, id, record: { ...result.record } });
       return result.record;
     } catch (err) {
       throw normaliseClientError(err);
@@ -748,6 +797,9 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         String(id),
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : undefined,
       );
+      if (result.deleted) {
+        this.emitMutation({ type: 'delete', resource, id });
+      }
       return result.deleted;
     } catch (err) {
       throw normaliseClientError(err);
@@ -778,6 +830,13 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     if (!ids || ids.length === 0) return 0;
     const records = ids.map((id) => ({ id: String(id), data: patch as any }));
 
+    // Notify subscribers once for the whole batch (not per-id) so a single
+    // "mark all read"/"archive selected" refreshes bound views exactly once.
+    const emitBulk = (count: number): number => {
+      if (count > 0) this.emitMutation({ type: 'update', resource });
+      return count;
+    };
+
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const updateMany = (this.client.data as any).updateMany;
     if (typeof updateMany === 'function') {
@@ -786,10 +845,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         // 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;
+          return emitBulk((res as any).succeeded as number);
         }
-        if (Array.isArray(res)) return (res as any[]).length;
-        return ids.length;
+        if (Array.isArray(res)) return emitBulk((res as any[]).length);
+        return emitBulk(ids.length);
       } catch (err) {
         throw normaliseClientError(err);
       }
@@ -805,7 +864,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         // continueOnError semantics — swallow per-row errors
       }
     }
-    return succeeded;
+    return emitBulk(succeeded);
   }
 
   /**
@@ -823,17 +882,23 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     if (!ids || ids.length === 0) return 0;
     const strIds = ids.map((id) => String(id));
 
+    // Notify subscribers once for the whole batch (see bulkUpdate).
+    const emitBulk = (count: number): number => {
+      if (count > 0) this.emitMutation({ type: 'delete', resource });
+      return count;
+    };
+
     // 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;
+          return emitBulk((res as any).succeeded as number);
         }
-        if (Array.isArray(res)) return (res as any[]).length;
+        if (Array.isArray(res)) return emitBulk((res as any[]).length);
         // deleteMany historically returns void on success — assume all hit.
-        return strIds.length;
+        return emitBulk(strIds.length);
       } catch (err) {
         throw normaliseClientError(err);
       }
@@ -849,7 +914,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         // continueOnError semantics — swallow per-row errors
       }
     }
-    return succeeded;
+    return emitBulk(succeeded);
   }
 
   /**
@@ -1047,6 +1112,183 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * Bulk-import raw spreadsheet rows in a single server round-trip via
+   * `POST /api/v1/data/:object/import`. The server performs all value coercion
+   * (booleans, numbers, dates→ISO, select label→code, lookup name→id) from the
+   * object's field metadata, so this method forwards the request verbatim and
+   * returns the aggregate + per-row result untouched.
+   *
+   * Requires `@objectstack/client` with `data.import` (server `/import` route).
+   * Callers should feature-detect (`typeof dataSource.importRecords`) and fall
+   * back to a per-row `create` loop when unavailable.
+   */
+  async importRecords(
+    resource: string,
+    request: ImportRequestOptions,
+  ): Promise<ImportRecordsResult> {
+    await this.connect();
+    const importFn = (this.client.data as { import?: unknown }).import;
+    if (typeof importFn !== 'function') {
+      throw new ObjectStackError(
+        'The connected @objectstack/client does not support data.import(). ' +
+          'Upgrade the client, or import via a per-row create fallback.',
+        'UNSUPPORTED_OPERATION',
+        400,
+      );
+    }
+    try {
+      const result = await (importFn as (
+        object: string,
+        req: ImportRequestOptions,
+      ) => Promise<ImportRecordsResult>).call(this.client.data, resource, request);
+      return result;
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
+  }
+
+  /**
+   * Feature-detect the async import-job API on the connected client. Older
+   * clients/servers lack these routes; callers fall back to {@link importRecords}.
+   */
+  private importJobApi(): {
+    createImportJob: (object: string, req: ImportRequestOptions) => Promise<CreateImportJobResult>;
+    getImportJobProgress: (jobId: string) => Promise<ImportJobProgressInfo>;
+    getImportJobResults: (jobId: string) => Promise<ImportJobResultsInfo>;
+    listImportJobs: (query: ListImportJobsOptions) => Promise<ImportJobSummaryInfo[]>;
+    cancelImportJob: (jobId: string) => Promise<{ success: boolean }>;
+    undoImportJob: (jobId: string) => Promise<ImportJobUndoResult>;
+  } | undefined {
+    const d = this.client.data as Record<string, unknown>;
+    if (typeof d.createImportJob !== 'function') return undefined;
+    return d as any;
+  }
+
+  /**
+   * Start an asynchronous import job — the large-file counterpart to
+   * {@link importRecords}. Posts the whole payload once; the server processes
+   * rows in the background. Requires an `@objectstack/client` new enough to
+   * expose `data.createImportJob` (server `/import/jobs` route). Callers should
+   * feature-detect (`typeof dataSource.createImportJob`) and fall back to the
+   * synchronous path when unavailable.
+   */
+  async createImportJob(
+    resource: string,
+    request: ImportRequestOptions,
+  ): Promise<CreateImportJobResult> {
+    await this.connect();
+    const api = this.importJobApi();
+    if (!api) {
+      throw new ObjectStackError(
+        'The connected @objectstack/client does not support async import jobs (data.createImportJob). ' +
+          'Upgrade the client, or use the synchronous importRecords() path.',
+        'UNSUPPORTED_OPERATION',
+        400,
+      );
+    }
+    try {
+      return await api.createImportJob.call(this.client.data, resource, request);
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
+  }
+
+  /** Poll an import job's progress. Requires {@link createImportJob} support. */
+  async getImportJobProgress(jobId: string): Promise<ImportJobProgressInfo> {
+    await this.connect();
+    const api = this.importJobApi();
+    if (!api) {
+      throw new ObjectStackError(
+        'The connected @objectstack/client does not support async import jobs.',
+        'UNSUPPORTED_OPERATION',
+        400,
+      );
+    }
+    try {
+      return await api.getImportJobProgress.call(this.client.data, jobId);
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
+  }
+
+  /** Fetch an import job's capped per-row results. */
+  async getImportJobResults(jobId: string): Promise<ImportJobResultsInfo> {
+    await this.connect();
+    const api = this.importJobApi();
+    if (!api) {
+      throw new ObjectStackError(
+        'The connected @objectstack/client does not support async import jobs.',
+        'UNSUPPORTED_OPERATION',
+        400,
+      );
+    }
+    try {
+      return await api.getImportJobResults.call(this.client.data, jobId);
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
+  }
+
+  /** List recent import jobs (history), newest first. */
+  async listImportJobs(options: ListImportJobsOptions = {}): Promise<ImportJobSummaryInfo[]> {
+    await this.connect();
+    const api = this.importJobApi();
+    if (!api) {
+      throw new ObjectStackError(
+        'The connected @objectstack/client does not support async import jobs.',
+        'UNSUPPORTED_OPERATION',
+        400,
+      );
+    }
+    try {
+      return await api.listImportJobs.call(this.client.data, options);
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
+  }
+
+  /** Cancel a pending/running import job (cooperative). */
+  async cancelImportJob(jobId: string): Promise<void> {
+    await this.connect();
+    const api = this.importJobApi();
+    if (!api) {
+      throw new ObjectStackError(
+        'The connected @objectstack/client does not support async import jobs.',
+        'UNSUPPORTED_OPERATION',
+        400,
+      );
+    }
+    try {
+      await api.cancelImportJob.call(this.client.data, jobId);
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
+  }
+
+  /**
+   * Logically roll back a finished import job — delete the records it created
+   * and restore the records it updated to their pre-import values. Requires an
+   * `@objectstack/client` new enough to expose `data.undoImportJob`, and a job
+   * the server captured an undo log for (see {@link ImportJobProgressInfo.undoable}).
+   */
+  async undoImportJob(jobId: string): Promise<ImportJobUndoResult> {
+    await this.connect();
+    const api = this.importJobApi();
+    if (!api || typeof (api as { undoImportJob?: unknown }).undoImportJob !== 'function') {
+      throw new ObjectStackError(
+        'The connected @objectstack/client does not support undoing import jobs (data.undoImportJob).',
+        'UNSUPPORTED_OPERATION',
+        400,
+      );
+    }
+    try {
+      return await api.undoImportJob.call(this.client.data, jobId);
+    } catch (err) {
+      throw normaliseClientError(err);
+    }
+  }
+
   /**
    * Normalize the result from data.find() or data.query() into a consistent QueryResult.
    */
@@ -1647,6 +1889,28 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * List registered import `mapping` artifacts targeting a given object
+   * (framework #2611). Reads the `mapping` metadata kind via the overlay API
+   * and filters by `targetObject` client-side (the metadata index is
+   * name-only). Feeds the import wizard's "saved mapping" selector; a failure
+   * (older server without the `mapping` kind) degrades to an empty list, so
+   * the selector simply doesn't appear.
+   */
+  async listImportMappings(objectName: string): Promise<any[]> {
+    await this.connect();
+    try {
+      const result: any = await this.client.meta.getItems('mapping');
+      const items: any[] = Array.isArray(result?.items)
+        ? result.items
+        : Array.isArray(result) ? result : [];
+      return items.filter((m: any) => m && m.targetObject === objectName);
+    } catch (err) {
+      console.warn('[OBJECTSTACKDataSource] listImportMappings failed:', err);
+      return [];
+    }
+  }
+
   /**
    * Create a new overlay view for an object. The view's `name` is the
    * stable identifier — must be unique within the project scope. Returns
@@ -2394,6 +2658,7 @@ export type {
   MetadataDeleteOptions,
   MetadataHistoryOptions,
   MetadataError,
+  MetadataValidationIssue,
   MetadataLayered,
   MetadataReference,
   MetadataDiagnostics,

package/src/metadata-client.test.ts

@@ -122,6 +122,36 @@ describe('MetadataClient', () => {
     });
   });
 
+  it('extracts message, code + field-anchored issues from the dispatcher error shape', async () => {
+    // The dispatcher sends `error` as an OBJECT { message, code, details:{ code, issues } }.
+    // Reading `.message` (not String(object) → "[object Object]") and surfacing
+    // `details.issues` is what lets the Studio point at the offending field.
+    const c = new MetadataClient({
+      baseUrl: 'http://localhost:3000',
+      fetch: mockFetch(async () =>
+        new Response(
+          JSON.stringify({
+            success: false,
+            error: {
+              message: '[invalid_metadata] object/bad failed spec validation: label: Required',
+              code: 422,
+              details: {
+                code: 'invalid_metadata',
+                issues: [{ path: 'label', message: 'Required', code: 'invalid_type' }],
+              },
+            },
+          }),
+          { status: 422, headers: { 'content-type': 'application/json' } },
+        )),
+    });
+    await expect(c.save('object', 'bad', {})).rejects.toMatchObject({
+      status: 422,
+      code: 'invalid_metadata',
+      message: '[invalid_metadata] object/bad failed spec validation: label: Required',
+      issues: [{ path: 'label', message: 'Required', code: 'invalid_type' }],
+    });
+  });
+
   it('listDrafts requests /meta/_drafts with packageId + type and parses {drafts}', async () => {
     const seen: string[] = [];
     const c = new MetadataClient({

package/src/metadata-client.ts

@@ -278,10 +278,20 @@ export interface MetadataHistoryOptions {
   limit?: number;
 }
 
+/** A single field-anchored spec-validation issue (server `error.details.issues`). */
+export interface MetadataValidationIssue {
+  /** Dot-path to the offending field, e.g. `fields.amount.type` (`''` = root). */
+  path: string;
+  message: string;
+  code?: string;
+}
+
 export interface MetadataError extends Error {
   status: number;
   code?: string;
   body?: unknown;
+  /** Structured spec-validation issues, when the failure was a validation error. */
+  issues?: MetadataValidationIssue[];
 }
 
 const META_PREFIX = '/meta';
@@ -310,16 +320,36 @@ async function parseError(res: Response): Promise<MetadataError> {
   } catch {
     body = await res.text().catch(() => undefined);
   }
+  const bodyObj = body && typeof body === 'object' ? (body as Record<string, any>) : undefined;
+  // The dispatcher error shape is `{ success:false, error:{ message, code,
+  // details:{ code, issues } } }` — `error` is an OBJECT. Older/other surfaces
+  // send `error` as a plain string or a top-level `message`. Accept all three
+  // (reading `.message` off the object case, not `String(object)` which yields
+  // "[object Object]").
+  const errNode = bodyObj?.error;
   const message =
-    (body && typeof body === 'object' && 'error' in (body as Record<string, unknown>)
-      ? String((body as Record<string, unknown>).error)
-      : undefined) ?? `Metadata request failed: ${res.status} ${res.statusText}`;
-  const err = new Error(message) as MetadataError;
+    (errNode && typeof errNode === 'object' ? errNode.message : errNode) ??
+    bodyObj?.message ??
+    `Metadata request failed: ${res.status} ${res.statusText}`;
+  const err = new Error(String(message)) as MetadataError;
   err.status = res.status;
   err.body = body;
-  if (body && typeof body === 'object' && 'code' in (body as Record<string, unknown>)) {
-    err.code = String((body as Record<string, unknown>).code);
-  }
+  // Field-anchored spec-validation issues. Two live server shapes carry them:
+  // the REST server puts them at top-level `body.issues` (with `error` a string),
+  // the HTTP dispatcher nests them under `error.details.issues` (with `error` an
+  // object). Accept both (plus a defensive `error.issues`) so the caller can
+  // point at the offending field regardless of which transport served the error.
+  const details = errNode && typeof errNode === 'object' ? errNode.details : undefined;
+  const issues =
+    details?.issues ??
+    (errNode && typeof errNode === 'object' ? errNode.issues : undefined) ??
+    bodyObj?.issues;
+  if (Array.isArray(issues)) err.issues = issues as MetadataValidationIssue[];
+  const code =
+    details?.code ??
+    (errNode && typeof errNode === 'object' ? errNode.code : undefined) ??
+    bodyObj?.code;
+  if (code != null) err.code = String(code);
   return err;
 }
 

package/src/onMutation.test.ts

@@ -0,0 +1,125 @@
+/**
+ * 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.
+ */
+
+/**
+ * Regression: ObjectStackAdapter must implement `onMutation` and emit an event
+ * after every successful create/update/delete (and bulk variant).
+ *
+ * Real-world symptom (framework app-showcase): inline-edit a grid cell, click
+ * "全部保存" (Save All) — the write persisted but the list did NOT auto-refresh.
+ * ListView auto-refreshes by subscribing to `dataSource.onMutation`; the
+ * ObjectStack adapter never implemented it, so the per-row `update` writes
+ * issued by ObjectGrid's default batch-save were silent and the grid kept
+ * showing stale rows until a manual reload.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { ObjectStackAdapter } from './index';
+import type { MutationEvent } from '@object-ui/types';
+
+function makeDS(stub: Record<string, 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('ObjectStackAdapter.onMutation', () => {
+  it('emits an update event after a successful update (the inline-edit save path)', async () => {
+    const update = vi
+      .fn()
+      .mockResolvedValue({ record: { id: 'r1', account: 'acc-1' } });
+    const ds = makeDS({ update });
+
+    const events: MutationEvent[] = [];
+    const unsub = ds.onMutation((e: MutationEvent) => events.push(e));
+
+    await ds.update('showcase_project', 'r1', { account: 'acc-1' });
+
+    expect(events).toEqual([
+      { type: 'update', resource: 'showcase_project', id: 'r1', record: { id: 'r1', account: 'acc-1' } },
+    ]);
+
+    // Unsubscribe stops delivery.
+    unsub();
+    await ds.update('showcase_project', 'r1', { account: 'acc-2' });
+    expect(events).toHaveLength(1);
+  });
+
+  it('emits a create event with the new record', async () => {
+    const create = vi.fn().mockResolvedValue({ record: { id: 'new', name: 'X' } });
+    const ds = makeDS({ create });
+    const events: MutationEvent[] = [];
+    ds.onMutation((e: MutationEvent) => events.push(e));
+
+    await ds.create('showcase_project', { name: 'X' });
+
+    expect(events).toEqual([
+      { type: 'create', resource: 'showcase_project', record: { id: 'new', name: 'X' } },
+    ]);
+  });
+
+  it('emits a delete event only when the server confirms deletion', async () => {
+    const del = vi
+      .fn()
+      .mockResolvedValueOnce({ deleted: true })
+      .mockResolvedValueOnce({ deleted: false });
+    const ds = makeDS({ delete: del });
+    const events: MutationEvent[] = [];
+    ds.onMutation((e: MutationEvent) => events.push(e));
+
+    await ds.delete('showcase_project', 'r1');
+    await ds.delete('showcase_project', 'r2');
+
+    expect(events).toEqual([
+      { type: 'delete', resource: 'showcase_project', id: 'r1' },
+    ]);
+  });
+
+  it('emits a single bulk event per bulkUpdate call (not per id)', async () => {
+    const updateMany = vi.fn().mockResolvedValue({ succeeded: 3, failed: 0, results: [] });
+    const ds = makeDS({ updateMany });
+    const events: MutationEvent[] = [];
+    ds.onMutation((e: MutationEvent) => events.push(e));
+
+    await ds.bulkUpdate('showcase_project', ['a', 'b', 'c'], { archived: true });
+
+    expect(events).toEqual([{ type: 'update', resource: 'showcase_project' }]);
+  });
+
+  it('does not emit when a bulk operation affected zero rows', async () => {
+    const updateMany = vi.fn().mockResolvedValue({ succeeded: 0, failed: 0, results: [] });
+    const ds = makeDS({ updateMany });
+    const events: MutationEvent[] = [];
+    ds.onMutation((e: MutationEvent) => events.push(e));
+
+    await ds.bulkUpdate('showcase_project', ['a'], { archived: true });
+
+    expect(events).toEqual([]);
+  });
+
+  it('isolates a throwing listener so the mutation still resolves and others fire', async () => {
+    const update = vi.fn().mockResolvedValue({ record: { id: 'r1' } });
+    const ds = makeDS({ update });
+    const good = vi.fn();
+    ds.onMutation(() => { throw new Error('boom'); });
+    ds.onMutation(good);
+
+    await expect(ds.update('showcase_project', 'r1', { x: 1 })).resolves.toBeTruthy();
+    expect(good).toHaveBeenCalledTimes(1);
+  });
+});