@object-ui/data-objectstack 11.0.0 → 11.3.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @object-ui/data-objectstack
 
+## 11.3.0
+
+### Patch Changes
+
+- Updated dependencies [d23d6eb]
+  - @object-ui/core@11.3.0
+  - @object-ui/types@11.3.0
+
+## 11.2.0
+
+### Patch Changes
+
+- Updated dependencies [9e7a986]
+- Updated dependencies [1311749]
+  - @object-ui/core@11.2.0
+  - @object-ui/types@11.2.0
+
+## 11.1.0
+
+### Patch Changes
+
+- @object-ui/types@11.1.0
+- @object-ui/core@11.1.0
+
 ## 7.3.0
 
 ### Patch Changes

package/dist/index.cjs

@@ -585,6 +585,7 @@ function createObjectStackUserStateAdapter(options) {
     }
   } = options;
   let cachedRowId = null;
+  let saveChain = Promise.resolve();
   const findExisting = async () => {
     const params = {
       $filter: {
@@ -615,6 +616,42 @@ function createObjectStackUserStateAdapter(options) {
     }
     return [];
   };
+  const upsert = async (items) => {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    if (cachedRowId !== null) {
+      try {
+        await dataSource.update(resource, cachedRowId, { value: items, updated_at: now });
+        return;
+      } catch (updateError) {
+        cachedRowId = null;
+        onError("save", updateError);
+      }
+    }
+    const existing = await findExisting();
+    if (existing && existing.id !== void 0 && 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?.id;
+      if (newId !== void 0 && newId !== null) cachedRowId = newId;
+    } catch (createError) {
+      const recovered = await findExisting();
+      if (recovered && recovered.id !== void 0 && recovered.id !== null) {
+        cachedRowId = recovered.id;
+        await dataSource.update(resource, recovered.id, { value: items, updated_at: now });
+        return;
+      }
+      throw createError;
+    }
+  };
   return {
     async load() {
       try {
@@ -631,40 +668,11 @@ function createObjectStackUserStateAdapter(options) {
       }
     },
     async save(items) {
-      try {
-        const now = (/* @__PURE__ */ new Date()).toISOString();
-        if (cachedRowId !== null) {
-          try {
-            await dataSource.update(resource, cachedRowId, {
-              value: items,
-              updated_at: now
-            });
-            return;
-          } catch (updateError) {
-            cachedRowId = null;
-            onError("save", updateError);
-          }
-        }
-        const existing = await findExisting();
-        if (existing && existing.id !== void 0 && 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?.id;
-        if (newId !== void 0 && newId !== null) cachedRowId = newId;
-      } catch (error) {
+      const run = saveChain.then(() => upsert(items)).catch((error) => {
         onError("save", error);
-      }
+      });
+      saveChain = run;
+      return run;
     }
   };
 }
@@ -2105,6 +2113,53 @@ var ObjectStackAdapter = class {
     }
     return body;
   }
+  /**
+   * Synchronously download a server-streamed export (csv / json / xlsx).
+   *
+   * Hits `GET /api/v1/data/:object/export`, which streams matching rows in the
+   * requested format, formats values for readability (lookup → name, select →
+   * label, boolean → 是/否, dates formatted) and enforces permissions. The
+   * filter / sort are translated the same way as `rawFindWithPopulate` so the
+   * exported file mirrors the active list view. Returns the file as a Blob;
+   * the caller triggers the browser download.
+   */
+  async exportDownload(resource, request = {}) {
+    const queryParams = new URLSearchParams();
+    const format = request.format === "xlsx" ? "xlsx" : request.format === "json" ? "json" : "csv";
+    queryParams.set("format", format);
+    if (request.fields && request.fields.length > 0) {
+      queryParams.set("fields", request.fields.join(","));
+    }
+    if (request.limit && request.limit > 0) {
+      queryParams.set("limit", String(request.limit));
+    }
+    if (request.includeHeaders === false) {
+      queryParams.set("header", "false");
+    }
+    if (request.sort && request.sort.length > 0) {
+      const orderby = request.sort.filter((s) => s && s.field).map((s) => `${s.field}:${s.direction === "desc" ? "desc" : "asc"}`).join(",");
+      if (orderby) queryParams.set("orderby", orderby);
+    }
+    if (request.filter !== void 0 && request.filter !== null) {
+      const translated = translateFilterToAST(request.filter);
+      if (translated !== void 0) {
+        queryParams.set("filter", JSON.stringify(translated));
+      }
+    }
+    const baseUrl = this.baseUrl.replace(/\/$/, "");
+    const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+    const dataPath = hasApiVersionSuffix ? "/data" : "/api/v1/data";
+    const url = `${baseUrl}${dataPath}/${encodeURIComponent(resource)}/export?${queryParams.toString()}`;
+    const headers = { ...this.getAuthHeaders() };
+    const res = await this.fetchImpl(url, { method: "GET", headers, credentials: "include" });
+    if (!res.ok) {
+      const errorBody = await res.json().catch(() => ({ message: res.statusText }));
+      const err = new Error(errorBody?.error?.message || errorBody?.message || res.statusText);
+      err.status = res.status;
+      throw err;
+    }
+    return await res.blob();
+  }
   /**
    * Convert ObjectUI QueryParams to ObjectStack QueryOptions.
    * Maps OData-style conventions to ObjectStack conventions.

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { ObjectStackClient } from '@objectstack/client';
-import { DataSource, QueryParams, QueryResult, FileUploadResult } from '@object-ui/types';
+import { DataSource, QueryParams, QueryResult, ExportDownloadRequest, FileUploadResult } from '@object-ui/types';
 export { FileUploadResult } from '@object-ui/types';
 
 /**
@@ -1443,6 +1443,17 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * to findData({ object, query: req.query }) which processes `populate`.
      */
     private rawFindWithPopulate;
+    /**
+     * Synchronously download a server-streamed export (csv / json / xlsx).
+     *
+     * Hits `GET /api/v1/data/:object/export`, which streams matching rows in the
+     * requested format, formats values for readability (lookup → name, select →
+     * label, boolean → 是/否, dates formatted) and enforces permissions. The
+     * filter / sort are translated the same way as `rawFindWithPopulate` so the
+     * exported file mirrors the active list view. Returns the file as a Blob;
+     * the caller triggers the browser download.
+     */
+    exportDownload(resource: string, request?: ExportDownloadRequest): Promise<Blob>;
     /**
      * Convert ObjectUI QueryParams to ObjectStack QueryOptions.
      * Maps OData-style conventions to ObjectStack conventions.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ObjectStackClient } from '@objectstack/client';
-import { DataSource, QueryParams, QueryResult, FileUploadResult } from '@object-ui/types';
+import { DataSource, QueryParams, QueryResult, ExportDownloadRequest, FileUploadResult } from '@object-ui/types';
 export { FileUploadResult } from '@object-ui/types';
 
 /**
@@ -1443,6 +1443,17 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
      * to findData({ object, query: req.query }) which processes `populate`.
      */
     private rawFindWithPopulate;
+    /**
+     * Synchronously download a server-streamed export (csv / json / xlsx).
+     *
+     * Hits `GET /api/v1/data/:object/export`, which streams matching rows in the
+     * requested format, formats values for readability (lookup → name, select →
+     * label, boolean → 是/否, dates formatted) and enforces permissions. The
+     * filter / sort are translated the same way as `rawFindWithPopulate` so the
+     * exported file mirrors the active list view. Returns the file as a Blob;
+     * the caller triggers the browser download.
+     */
+    exportDownload(resource: string, request?: ExportDownloadRequest): Promise<Blob>;
     /**
      * Convert ObjectUI QueryParams to ObjectStack QueryOptions.
      * Maps OData-style conventions to ObjectStack conventions.

package/dist/index.js

@@ -537,6 +537,7 @@ function createObjectStackUserStateAdapter(options) {
     }
   } = options;
   let cachedRowId = null;
+  let saveChain = Promise.resolve();
   const findExisting = async () => {
     const params = {
       $filter: {
@@ -567,6 +568,42 @@ function createObjectStackUserStateAdapter(options) {
     }
     return [];
   };
+  const upsert = async (items) => {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    if (cachedRowId !== null) {
+      try {
+        await dataSource.update(resource, cachedRowId, { value: items, updated_at: now });
+        return;
+      } catch (updateError) {
+        cachedRowId = null;
+        onError("save", updateError);
+      }
+    }
+    const existing = await findExisting();
+    if (existing && existing.id !== void 0 && 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?.id;
+      if (newId !== void 0 && newId !== null) cachedRowId = newId;
+    } catch (createError) {
+      const recovered = await findExisting();
+      if (recovered && recovered.id !== void 0 && recovered.id !== null) {
+        cachedRowId = recovered.id;
+        await dataSource.update(resource, recovered.id, { value: items, updated_at: now });
+        return;
+      }
+      throw createError;
+    }
+  };
   return {
     async load() {
       try {
@@ -583,40 +620,11 @@ function createObjectStackUserStateAdapter(options) {
       }
     },
     async save(items) {
-      try {
-        const now = (/* @__PURE__ */ new Date()).toISOString();
-        if (cachedRowId !== null) {
-          try {
-            await dataSource.update(resource, cachedRowId, {
-              value: items,
-              updated_at: now
-            });
-            return;
-          } catch (updateError) {
-            cachedRowId = null;
-            onError("save", updateError);
-          }
-        }
-        const existing = await findExisting();
-        if (existing && existing.id !== void 0 && 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?.id;
-        if (newId !== void 0 && newId !== null) cachedRowId = newId;
-      } catch (error) {
+      const run = saveChain.then(() => upsert(items)).catch((error) => {
         onError("save", error);
-      }
+      });
+      saveChain = run;
+      return run;
     }
   };
 }
@@ -2057,6 +2065,53 @@ var ObjectStackAdapter = class {
     }
     return body;
   }
+  /**
+   * Synchronously download a server-streamed export (csv / json / xlsx).
+   *
+   * Hits `GET /api/v1/data/:object/export`, which streams matching rows in the
+   * requested format, formats values for readability (lookup → name, select →
+   * label, boolean → 是/否, dates formatted) and enforces permissions. The
+   * filter / sort are translated the same way as `rawFindWithPopulate` so the
+   * exported file mirrors the active list view. Returns the file as a Blob;
+   * the caller triggers the browser download.
+   */
+  async exportDownload(resource, request = {}) {
+    const queryParams = new URLSearchParams();
+    const format = request.format === "xlsx" ? "xlsx" : request.format === "json" ? "json" : "csv";
+    queryParams.set("format", format);
+    if (request.fields && request.fields.length > 0) {
+      queryParams.set("fields", request.fields.join(","));
+    }
+    if (request.limit && request.limit > 0) {
+      queryParams.set("limit", String(request.limit));
+    }
+    if (request.includeHeaders === false) {
+      queryParams.set("header", "false");
+    }
+    if (request.sort && request.sort.length > 0) {
+      const orderby = request.sort.filter((s) => s && s.field).map((s) => `${s.field}:${s.direction === "desc" ? "desc" : "asc"}`).join(",");
+      if (orderby) queryParams.set("orderby", orderby);
+    }
+    if (request.filter !== void 0 && request.filter !== null) {
+      const translated = translateFilterToAST(request.filter);
+      if (translated !== void 0) {
+        queryParams.set("filter", JSON.stringify(translated));
+      }
+    }
+    const baseUrl = this.baseUrl.replace(/\/$/, "");
+    const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+    const dataPath = hasApiVersionSuffix ? "/data" : "/api/v1/data";
+    const url = `${baseUrl}${dataPath}/${encodeURIComponent(resource)}/export?${queryParams.toString()}`;
+    const headers = { ...this.getAuthHeaders() };
+    const res = await this.fetchImpl(url, { method: "GET", headers, credentials: "include" });
+    if (!res.ok) {
+      const errorBody = await res.json().catch(() => ({ message: res.statusText }));
+      const err = new Error(errorBody?.error?.message || errorBody?.message || res.statusText);
+      err.status = res.status;
+      throw err;
+    }
+    return await res.blob();
+  }
   /**
    * Convert ObjectUI QueryParams to ObjectStack QueryOptions.
    * Maps OData-style conventions to ObjectStack conventions.

package/package.json

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

package/src/exportDownload.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 an adapter whose fetch is a spy returning the given Response. */
+function makeDS(fetchImpl: any) {
+  const ds: any = new ObjectStackAdapter({ baseUrl: 'http://test.local', fetch: fetchImpl });
+  ds.connected = true;
+  ds.connectionState = 'connected';
+  return ds;
+}
+
+function csvResponse(body = 'ID,Name\n1,Acme') {
+  return new Response(body, { status: 200, headers: { 'Content-Type': 'text/csv' } });
+}
+
+describe('ObjectStackAdapter.exportDownload', () => {
+  it('GETs the /export route with format, fields, orderby, header and limit', async () => {
+    const fetchImpl = vi.fn(async () => csvResponse());
+    const ds = makeDS(fetchImpl);
+
+    const blob = await ds.exportDownload('task', {
+      format: 'xlsx',
+      fields: ['title', 'owner'],
+      sort: [{ field: 'title', direction: 'desc' }, { field: 'owner' }],
+      includeHeaders: false,
+      limit: 5000,
+    });
+
+    expect(blob).toBeInstanceOf(Blob);
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchImpl.mock.calls[0];
+    const parsed = new URL(url);
+    expect(parsed.pathname).toBe('/api/v1/data/task/export');
+    expect(parsed.searchParams.get('format')).toBe('xlsx');
+    expect(parsed.searchParams.get('fields')).toBe('title,owner');
+    // direction defaults to asc when omitted.
+    expect(parsed.searchParams.get('orderby')).toBe('title:desc,owner:asc');
+    expect(parsed.searchParams.get('header')).toBe('false');
+    expect(parsed.searchParams.get('limit')).toBe('5000');
+    expect(init.method).toBe('GET');
+    expect(init.credentials).toBe('include');
+  });
+
+  it('defaults to csv and omits optional params when not provided', async () => {
+    const fetchImpl = vi.fn(async () => csvResponse());
+    const ds = makeDS(fetchImpl);
+
+    await ds.exportDownload('task', {});
+
+    const [url] = fetchImpl.mock.calls[0];
+    const parsed = new URL(url);
+    expect(parsed.searchParams.get('format')).toBe('csv');
+    expect(parsed.searchParams.get('fields')).toBeNull();
+    expect(parsed.searchParams.get('orderby')).toBeNull();
+    expect(parsed.searchParams.get('header')).toBeNull();
+    expect(parsed.searchParams.get('limit')).toBeNull();
+  });
+
+  it('serializes the filter to a JSON AST query param', async () => {
+    const fetchImpl = vi.fn(async () => csvResponse());
+    const ds = makeDS(fetchImpl);
+
+    await ds.exportDownload('task', { filter: [['status', '=', 'open']] });
+
+    const [url] = fetchImpl.mock.calls[0];
+    const raw = new URL(url).searchParams.get('filter');
+    expect(raw).toBeTruthy();
+    expect(JSON.parse(raw!)).toEqual([['status', '=', 'open']]);
+  });
+
+  it('throws an error carrying the server message and status on failure', async () => {
+    const fetchImpl = vi.fn(async () =>
+      new Response(JSON.stringify({ error: { message: 'Permission denied' } }), {
+        status: 403,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    const ds = makeDS(fetchImpl);
+
+    await expect(ds.exportDownload('task', { format: 'csv' })).rejects.toMatchObject({
+      message: 'Permission denied',
+      status: 403,
+    });
+  });
+});

package/src/getObjectSchema.test.ts

@@ -74,4 +74,40 @@ describe('ObjectStackAdapter.getObjectSchema', () => {
     expect(schema.name).toBe('account');
     expect(Object.keys(schema.fields)).toEqual(['x']);
   });
+
+  it('preserves `validations` (incl. state_machine transitions) — the seam the inline editor depends on', async () => {
+    // Inert-metadata regression guard. The inline select editor filters its
+    // options by the object's `state_machine` validation (objectui#2110). That
+    // feature only works because `getObjectSchema` passes the served
+    // `validations` through untouched — the server enforces the same rule. If a
+    // future change here started stripping or reshaping top-level metadata, the
+    // filter would silently no-op (valid-but-inert) with no error. Pin the
+    // pass-through so the data path can't go dark unnoticed.
+    const { fetchImpl } = makeFetch({
+      name: 'showcase_task',
+      fields: { status: { type: 'select', options: [{ value: 'done', label: 'Done' }] } },
+      validations: [
+        {
+          type: 'state_machine',
+          field: 'status',
+          transitions: { in_review: ['done', 'in_progress'], done: ['in_progress'] },
+        },
+      ],
+    });
+    const adapter = new ObjectStackAdapter({
+      baseUrl: 'http://localhost:3000',
+      autoReconnect: false,
+      fetch: fetchImpl as any,
+    });
+
+    const schema: any = await adapter.getObjectSchema('showcase_task');
+
+    const sm = (schema.validations ?? []).find((v: any) => v?.type === 'state_machine');
+    expect(sm).toBeTruthy();
+    expect(sm.field).toBe('status');
+    // The exact map the consumer filters on — `done` only transitions to
+    // `in_progress` (so the editor must not offer `in_review`).
+    expect(sm.transitions.done).toEqual(['in_progress']);
+    expect(sm.transitions.in_review).toEqual(['done', 'in_progress']);
+  });
 });

package/src/index.ts

@@ -7,7 +7,7 @@
  */
 
 import { ObjectStackClient, type QueryOptions as ObjectStackQueryOptions } from '@objectstack/client';
-import type { DataSource, QueryParams, QueryResult, FileUploadResult } from '@object-ui/types';
+import type { DataSource, QueryParams, QueryResult, FileUploadResult, ExportDownloadRequest } from '@object-ui/types';
 import { convertFiltersToAST } from '@object-ui/core';
 import { MetadataCache } from './cache/MetadataCache';
 import {
@@ -1182,6 +1182,66 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     return body;
   }
 
+  /**
+   * Synchronously download a server-streamed export (csv / json / xlsx).
+   *
+   * Hits `GET /api/v1/data/:object/export`, which streams matching rows in the
+   * requested format, formats values for readability (lookup → name, select →
+   * label, boolean → 是/否, dates formatted) and enforces permissions. The
+   * filter / sort are translated the same way as `rawFindWithPopulate` so the
+   * exported file mirrors the active list view. Returns the file as a Blob;
+   * the caller triggers the browser download.
+   */
+  async exportDownload(resource: string, request: ExportDownloadRequest = {}): Promise<Blob> {
+    const queryParams = new URLSearchParams();
+
+    const format = request.format === 'xlsx' ? 'xlsx' : request.format === 'json' ? 'json' : 'csv';
+    queryParams.set('format', format);
+
+    if (request.fields && request.fields.length > 0) {
+      queryParams.set('fields', request.fields.join(','));
+    }
+    if (request.limit && request.limit > 0) {
+      queryParams.set('limit', String(request.limit));
+    }
+    if (request.includeHeaders === false) {
+      queryParams.set('header', 'false');
+    }
+    // Sort → server `orderby` shorthand: "field:dir,field2:dir".
+    if (request.sort && request.sort.length > 0) {
+      const orderby = request.sort
+        .filter(s => s && s.field)
+        .map(s => `${s.field}:${s.direction === 'desc' ? 'desc' : 'asc'}`)
+        .join(',');
+      if (orderby) queryParams.set('orderby', orderby);
+    }
+    // Filter → AST tuples, same translation the list GET path uses.
+    if (request.filter !== undefined && request.filter !== null) {
+      const translated = translateFilterToAST(request.filter);
+      if (translated !== undefined) {
+        queryParams.set('filter', JSON.stringify(translated));
+      }
+    }
+
+    const baseUrl = this.baseUrl.replace(/\/$/, '');
+    // Avoid doubling /api/v1 if baseUrl already includes the version suffix.
+    const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+    const dataPath = hasApiVersionSuffix ? '/data' : '/api/v1/data';
+    const url = `${baseUrl}${dataPath}/${encodeURIComponent(resource)}/export?${queryParams.toString()}`;
+
+    const headers: Record<string, string> = { ...this.getAuthHeaders() };
+    // `credentials: 'include'` carries the session cookie for the browser
+    // console (which authenticates by cookie, not a bearer token).
+    const res = await this.fetchImpl(url, { method: 'GET', headers, credentials: 'include' });
+    if (!res.ok) {
+      const errorBody = await res.json().catch(() => ({ message: res.statusText }));
+      const err = new Error(errorBody?.error?.message || errorBody?.message || res.statusText) as any;
+      err.status = res.status;
+      throw err;
+    }
+    return await res.blob();
+  }
+
   /**
    * Convert ObjectUI QueryParams to ObjectStack QueryOptions.
    * Maps OData-style conventions to ObjectStack conventions.

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;
     },
   };
 }