@object-ui/data-objectstack 11.2.0 → 11.4.0

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

package/src/userState.test.ts

@@ -221,6 +221,59 @@ describe('createObjectStackUserStateAdapter', () => {
       }));
     });
 
+    it('recovers from a UNIQUE(user_id, key) insert failure by updating in place', async () => {
+      // First findExisting() (no cached id) misses; create() loses the race and
+      // throws; the recovery findExisting() now sees the row → update.
+      const ds = mockDataSource({
+        find: vi.fn()
+          .mockResolvedValueOnce({ data: [] })
+          .mockResolvedValueOnce({ data: [{ id: 'row-7', user_id: 'u', key: 'k', value: [] }] }) as any,
+        create: vi.fn().mockRejectedValue(new Error('UNIQUE constraint failed')) as any,
+      });
+
+      const adapter = createObjectStackUserStateAdapter({
+        dataSource: ds,
+        userId: 'u',
+        key: 'k',
+      });
+
+      await adapter.save([{ id: 'q' } as any]);
+
+      expect(ds.create).toHaveBeenCalledTimes(1);
+      expect(ds.update).toHaveBeenCalledWith('sys_user_preference', 'row-7', {
+        value: [{ id: 'q' }],
+        updated_at: expect.any(String),
+      });
+    });
+
+    it('serializes concurrent saves so only one insert happens', async () => {
+      // Both saves start before either resolves. Without serialization both
+      // would findExisting()→[]→create() and the second would trip the
+      // UNIQUE constraint. With the save chain, the second waits, sees the
+      // cached row id from the first, and updates.
+      const ds = mockDataSource({
+        find: vi.fn().mockResolvedValue({ data: [] }) as any,
+        create: vi.fn().mockResolvedValue({ id: 'row-1' }) as any,
+      });
+
+      const adapter = createObjectStackUserStateAdapter({
+        dataSource: ds,
+        userId: 'u',
+        key: 'ui.recent',
+      });
+
+      await Promise.all([
+        adapter.save([{ id: 'a' } as any]),
+        adapter.save([{ id: 'a' }, { id: 'b' }] as any),
+      ]);
+
+      expect(ds.create).toHaveBeenCalledTimes(1);
+      expect(ds.update).toHaveBeenCalledWith('sys_user_preference', 'row-1', {
+        value: [{ id: 'a' }, { id: 'b' }],
+        updated_at: expect.any(String),
+      });
+    });
+
     it('swallows errors when save() throws', async () => {
       const onError = vi.fn();
       const ds = mockDataSource({

package/src/userState.ts

@@ -104,6 +104,14 @@ export function createObjectStackUserStateAdapter<T = unknown>(
   // without re-querying. Reset on every successful load.
   let cachedRowId: string | number | null = null;
 
+  // Serializes overlapping save() calls. A fresh adapter is created whenever
+  // the data source / user changes (see UserStateBridge), so its cachedRowId
+  // starts null; rapid navigations then fire debounced flushes that can race —
+  // two saves each findExisting()→null→create() and the second trips the
+  // UNIQUE(user_id, key) constraint. Chaining writes means the second save
+  // sees the cachedRowId the first one set and updates instead of inserting.
+  let saveChain: Promise<void> = Promise.resolve();
+
   const findExisting = async (): Promise<UserPreferenceRecord | null> => {
     // NOTE: `QueryParams` uses OData-style `$`-prefixed keys. Using the bare
     // names (`filter`, `limit`) silently drops the predicate at the
@@ -146,6 +154,55 @@ export function createObjectStackUserStateAdapter<T = unknown>(
     return [];
   };
 
+  // Upsert by (user_id, key): update in place when the row is known/found,
+  // otherwise insert — and if the insert loses a UNIQUE(user_id, key) race
+  // (a concurrent writer created the row, or the backend dropped our find
+  // predicate), recover by re-finding and updating rather than surfacing the
+  // failed insert.
+  const upsert = async (items: T[]): Promise<void> => {
+    const now = new Date().toISOString();
+
+    // Fast path: we already know the row id from a previous load/save.
+    if (cachedRowId !== null) {
+      try {
+        await dataSource.update(resource, cachedRowId, { value: items, updated_at: now });
+        return;
+      } catch (updateError) {
+        // Row may have been deleted server-side — fall through to find/insert.
+        cachedRowId = null;
+        onError('save', updateError);
+      }
+    }
+
+    const existing = await findExisting();
+    if (existing && existing.id !== undefined && existing.id !== null) {
+      cachedRowId = existing.id;
+      await dataSource.update(resource, existing.id, { value: items, updated_at: now });
+      return;
+    }
+
+    try {
+      const created = await dataSource.create(resource, {
+        user_id: userId,
+        key,
+        value: items,
+        updated_at: now,
+      });
+      const newId = (created as UserPreferenceRecord | undefined)?.id;
+      if (newId !== undefined && newId !== null) cachedRowId = newId;
+    } catch (createError) {
+      // The row already exists (UNIQUE(user_id, key) violation) — re-find and
+      // update in place. This turns the insert into a real upsert.
+      const recovered = await findExisting();
+      if (recovered && recovered.id !== undefined && recovered.id !== null) {
+        cachedRowId = recovered.id;
+        await dataSource.update(resource, recovered.id, { value: items, updated_at: now });
+        return;
+      }
+      throw createError;
+    }
+  };
+
   return {
     async load(): Promise<T[]> {
       try {
@@ -163,45 +220,15 @@ export function createObjectStackUserStateAdapter<T = unknown>(
     },
 
     async save(items: T[]): Promise<void> {
-      try {
-        const now = new Date().toISOString();
-        // Fast path: we already know the row id from a previous load/save.
-        if (cachedRowId !== null) {
-          try {
-            await dataSource.update(resource, cachedRowId, {
-              value: items,
-              updated_at: now,
-            });
-            return;
-          } catch (updateError) {
-            // Row may have been deleted server-side — fall through to insert.
-            cachedRowId = null;
-            onError('save', updateError);
-          }
-        }
-
-        const existing = await findExisting();
-        if (existing && existing.id !== undefined && existing.id !== null) {
-          cachedRowId = existing.id;
-          await dataSource.update(resource, existing.id, {
-            value: items,
-            updated_at: now,
-          });
-          return;
-        }
-
-        const created = await dataSource.create(resource, {
-          user_id: userId,
-          key,
-          value: items,
-          updated_at: now,
-        });
-        const newId = (created as UserPreferenceRecord | undefined)?.id;
-        if (newId !== undefined && newId !== null) cachedRowId = newId;
-      } catch (error) {
+      // Chain onto any in-flight save so concurrent flushes upsert serially
+      // rather than racing into two inserts (see `saveChain` above). Each link
+      // catches its own errors so one failure never poisons the chain.
+      const run = saveChain.then(() => upsert(items)).catch(error => {
         onError('save', error);
         // Swallow — provider falls back to localStorage as source of truth.
-      }
+      });
+      saveChain = run;
+      return run;
     },
   };
 }