@object-ui/data-objectstack 17.5.0 → 17.7.0

package/src/userState.test.ts

@@ -1,315 +0,0 @@
-/**
- * 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, beforeEach } from 'vitest';
-import { createObjectStackUserStateAdapter } from './userState';
-import type { DataSource } from '@object-ui/types';
-
-function mockDataSource(overrides: Partial<DataSource<any>> = {}): DataSource<any> {
-  return {
-    find: vi.fn().mockResolvedValue({ data: [] }),
-    findOne: vi.fn().mockResolvedValue(null),
-    create: vi.fn().mockResolvedValue({}),
-    update: vi.fn().mockResolvedValue({}),
-    delete: vi.fn().mockResolvedValue(true),
-    ...overrides,
-  } as unknown as DataSource<any>;
-}
-
-describe('createObjectStackUserStateAdapter', () => {
-  beforeEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  describe('load', () => {
-    it('returns [] when no row exists for the (user, key) pair', async () => {
-      const ds = mockDataSource();
-      const adapter = createObjectStackUserStateAdapter({
-        dataSource: ds,
-        userId: 'u1',
-        key: 'ui.favorites',
-      });
-
-      const items = await adapter.load();
-
-      expect(items).toEqual([]);
-      expect(ds.find).toHaveBeenCalledWith('sys_user_preference', {
-        $filter: { user_id: 'u1', key: 'ui.favorites' },
-        $top: 1,
-      });
-    });
-
-    it('returns parsed value when row exists (array value)', async () => {
-      const value = [{ id: 'object:contact', label: 'Contact' }];
-      const ds = mockDataSource({
-        find: vi.fn().mockResolvedValue({
-          data: [{ id: 'row-1', user_id: 'u1', key: 'ui.recent', value }],
-        }) as any,
-      });
-
-      const adapter = createObjectStackUserStateAdapter({
-        dataSource: ds,
-        userId: 'u1',
-        key: 'ui.recent',
-      });
-
-      await expect(adapter.load()).resolves.toEqual(value);
-    });
-
-    it('parses string-encoded JSON values', async () => {
-      const items = [{ id: 'a' }, { id: 'b' }];
-      const ds = mockDataSource({
-        find: vi.fn().mockResolvedValue({
-          data: [{ id: 1, value: JSON.stringify(items) }],
-        }) as any,
-      });
-
-      const adapter = createObjectStackUserStateAdapter({
-        dataSource: ds,
-        userId: 'u',
-        key: 'k',
-      });
-
-      await expect(adapter.load()).resolves.toEqual(items);
-    });
-
-    it('returns [] when value is malformed JSON', async () => {
-      const ds = mockDataSource({
-        find: vi.fn().mockResolvedValue({
-          data: [{ id: 1, value: '{not json' }],
-        }) as any,
-      });
-      const adapter = createObjectStackUserStateAdapter({
-        dataSource: ds,
-        userId: 'u',
-        key: 'k',
-      });
-
-      await expect(adapter.load()).resolves.toEqual([]);
-    });
-
-    it('swallows errors and returns [] when find() throws', async () => {
-      const onError = vi.fn();
-      const ds = mockDataSource({
-        find: vi.fn().mockRejectedValue(new Error('boom')) as any,
-      });
-
-      const adapter = createObjectStackUserStateAdapter({
-        dataSource: ds,
-        userId: 'u',
-        key: 'k',
-        onError,
-      });
-
-      await expect(adapter.load()).resolves.toEqual([]);
-      expect(onError).toHaveBeenCalledWith('load', expect.any(Error));
-    });
-
-    it('uses a custom resource name when provided', async () => {
-      const ds = mockDataSource();
-      const adapter = createObjectStackUserStateAdapter({
-        dataSource: ds,
-        userId: 'u',
-        key: 'k',
-        resource: 'my_prefs',
-      });
-
-      await adapter.load();
-
-      expect(ds.find).toHaveBeenCalledWith('my_prefs', expect.any(Object));
-    });
-  });
-
-  describe('save', () => {
-    it('creates a new row when none exists', async () => {
-      const created = { id: 'new-row' };
-      const ds = mockDataSource({
-        create: vi.fn().mockResolvedValue(created) as any,
-      });
-
-      const adapter = createObjectStackUserStateAdapter({
-        dataSource: ds,
-        userId: 'u1',
-        key: 'ui.favorites',
-      });
-
-      await adapter.save([{ id: 'a' } as any]);
-
-      expect(ds.create).toHaveBeenCalledWith('sys_user_preference', {
-        user_id: 'u1',
-        key: 'ui.favorites',
-        value: [{ id: 'a' }],
-      });
-    });
-
-    it('updates the existing row when one exists', async () => {
-      const ds = mockDataSource({
-        find: vi.fn().mockResolvedValue({
-          data: [{ id: 'row-99', user_id: 'u', key: 'k', value: [] }],
-        }) as any,
-      });
-
-      const adapter = createObjectStackUserStateAdapter({
-        dataSource: ds,
-        userId: 'u',
-        key: 'k',
-      });
-
-      await adapter.save([{ id: 'x' } as any]);
-
-      expect(ds.update).toHaveBeenCalledWith('sys_user_preference', 'row-99', {
-        value: [{ id: 'x' }],
-      });
-      expect(ds.create).not.toHaveBeenCalled();
-    });
-
-    // #3794 — `updated_at` is server-managed. A caller-supplied value is
-    // stripped (framework #2948) and reported back as a dropped field, which
-    // the console turns into a "Some fields were not saved" toast. Stamping it
-    // here fired that warning on every recents/favorites write, about a field
-    // no user ever touched — noise on the exact surface that is supposed to
-    // tell a user their edit did not land.
-    it('never sends the server-managed updated_at column', async () => {
-      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 adapter.save([{ id: 'a' } as any]);
-      await adapter.save([{ id: 'b' } as any]);
-
-      for (const call of [...(ds.create as any).mock.calls, ...(ds.update as any).mock.calls]) {
-        expect(call[call.length - 1]).not.toHaveProperty('updated_at');
-      }
-    });
-
-    it('uses the cached row id from a previous load on subsequent saves', async () => {
-      const ds = mockDataSource({
-        find: vi.fn().mockResolvedValue({
-          data: [{ id: 'row-42', value: [] }],
-        }) as any,
-      });
-
-      const adapter = createObjectStackUserStateAdapter({
-        dataSource: ds,
-        userId: 'u',
-        key: 'k',
-      });
-
-      await adapter.load();
-      (ds.find as any).mockClear();
-
-      await adapter.save([{ id: 'b' } as any]);
-
-      // No second find() — went straight to update via cached id.
-      expect(ds.find).not.toHaveBeenCalled();
-      expect(ds.update).toHaveBeenCalledWith('sys_user_preference', 'row-42', expect.any(Object));
-    });
-
-    it('falls back to insert when cached row update fails (row deleted server-side)', async () => {
-      const ds = mockDataSource({
-        find: vi.fn()
-          .mockResolvedValueOnce({ data: [{ id: 'stale', value: [] }] })
-          .mockResolvedValueOnce({ data: [] }) as any,
-        update: vi.fn().mockRejectedValue(new Error('not found')) as any,
-        create: vi.fn().mockResolvedValue({ id: 'new' }) as any,
-      });
-      const onError = vi.fn();
-
-      const adapter = createObjectStackUserStateAdapter({
-        dataSource: ds,
-        userId: 'u',
-        key: 'k',
-        onError,
-      });
-
-      await adapter.load(); // primes cachedRowId = 'stale'
-      await adapter.save([{ id: 'z' } as any]);
-
-      expect(ds.update).toHaveBeenCalledTimes(1);
-      expect(ds.create).toHaveBeenCalledWith('sys_user_preference', expect.objectContaining({
-        user_id: 'u',
-        key: 'k',
-        value: [{ id: 'z' }],
-      }));
-    });
-
-    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' }],
-      });
-    });
-
-    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' }],
-      });
-    });
-
-    it('swallows errors when save() throws', async () => {
-      const onError = vi.fn();
-      const ds = mockDataSource({
-        find: vi.fn().mockRejectedValue(new Error('network down')) as any,
-      });
-
-      const adapter = createObjectStackUserStateAdapter({
-        dataSource: ds,
-        userId: 'u',
-        key: 'k',
-        onError,
-      });
-
-      await expect(adapter.save([{ id: 'a' } as any])).resolves.toBeUndefined();
-      expect(onError).toHaveBeenCalledWith('save', expect.any(Error));
-    });
-  });
-});

package/src/userState.ts

@@ -1,238 +0,0 @@
-/**
- * ObjectStack-backed `UserDataAdapter` factory.
- *
- * Persists arbitrary per-user UI state (favorites, recently-accessed items, …)
- * as a single JSON blob per `(user_id, key)` row in the **unified per-user
- * KV store** — the `sys_user_preference` object shipped by every
- * `@objectstack/plugin-auth`-enabled environment.
- *
- * Using the existing `sys_user_preference` table (rather than a parallel
- * `user_app_state` table) keeps things consistent with the platform's
- * "one KV store per scope" pattern:
- *
- *   - `sys_setting`         ← tenant / env scope
- *   - `sys_user_preference` ← per-user scope  ← we live here
- *
- * Callers are encouraged to namespace their keys (e.g. `ui.favorites`,
- * `ui.recent`, `ui.grid.account.state`) so explicit settings (`theme`,
- * `locale`) and machine-written UI traces stay easy to tell apart.
- *
- * ## Schema this adapter expects
- *
- * The canonical `sys_user_preference` schema (from
- * `@objectstack/platform-objects`):
- *
- * ```yaml
- * object: sys_user_preference
- * fields:
- *   user_id:    lookup(sys_user)  # indexed
- *   key:        string            # indexed  (e.g. "ui.favorites")
- *   value:      json              # the serialised list
- *   updated_at: datetime          # auto-managed
- * unique: [user_id, key]
- * ```
- *
- * ## Failure modes
- *
- * The adapter is designed to **degrade silently**. Any error — missing
- * schema, 4xx/5xx, network — is caught:
- *
- * - `load()` returns `[]`, so the hosting provider keeps its localStorage state.
- * - `save()` resolves without throwing, so UI mutations never surface a toast.
- *
- * As soon as the backend supports `sys_user_preference`, persistence
- * "lights up" with no code change.
- *
- * @module
- */
-
-import type { DataSource, QueryParams } from '@object-ui/types';
-
-export interface ObjectStackUserStateAdapterOptions {
-  /** Connected data source (usually the one provided by `<AdapterProvider>`). */
-  dataSource: DataSource<any>;
-  /** Authenticated user id. */
-  userId: string;
-  /**
-   * Storage key. Should be a dotted, namespaced string so UI traces
-   * don't collide with user-facing preferences. Examples:
-   * `ui.favorites`, `ui.recent`, `ui.grid.account.state`.
-   */
-  key: string;
-  /** Override the storage object name. Defaults to `"sys_user_preference"`. */
-  resource?: string;
-  /**
-   * Optional console logger for development diagnostics. Defaults to noop so
-   * production builds stay quiet.
-   */
-  onError?: (where: 'load' | 'save', error: unknown) => void;
-}
-
-export interface UserDataAdapter<T> {
-  load(): Promise<T[]>;
-  save(items: T[]): Promise<void>;
-}
-
-interface UserPreferenceRecord {
-  id?: string | number;
-  user_id: string;
-  key: string;
-  value: unknown;
-  updated_at?: string;
-}
-
-const DEFAULT_RESOURCE = 'sys_user_preference';
-
-/**
- * Build a `UserDataAdapter<T>` backed by ObjectStack.
- *
- * Each adapter instance is bound to a single `(user, key)` pair; create
- * one per slot you want to persist.
- */
-export function createObjectStackUserStateAdapter<T = unknown>(
-  options: ObjectStackUserStateAdapterOptions,
-): UserDataAdapter<T> {
-  const {
-    dataSource,
-    userId,
-    key,
-    resource = DEFAULT_RESOURCE,
-    onError = () => {},
-  } = options;
-
-  // Cache the row id between load() and save() so we can update in place
-  // 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
-    // `convertQueryParams` layer, which then returns *any* row in the
-    // `sys_user_preference` table — that caused the Favorites adapter to load
-    // the Recents row (and vice-versa), so clicked items leaked into Starred.
-    const params: QueryParams = {
-      $filter: {
-        user_id: userId,
-        key,
-      },
-      $top: 1,
-    };
-    const result = await dataSource.find(resource, params);
-    const rows = (result?.data ?? []) as UserPreferenceRecord[];
-    // Defensive: if the backend ignored our predicate and returned mixed
-    // rows, only accept ones tagged for this (user, key) pair. Rows that
-    // omit those metadata fields entirely are trusted (covers mocks and
-    // backends that strip metadata from the projection).
-    const match = rows.find(r => {
-      if (!r) return false;
-      const userMismatch = r.user_id !== undefined && r.user_id !== userId;
-      const keyMismatch = r.key !== undefined && r.key !== key;
-      return !userMismatch && !keyMismatch;
-    });
-    return match ?? null;
-  };
-
-  const decodeValue = (value: unknown): T[] => {
-    // The server may return the JSON column already parsed, or as a string.
-    if (Array.isArray(value)) return value as T[];
-    if (typeof value === 'string') {
-      try {
-        const parsed = JSON.parse(value);
-        return Array.isArray(parsed) ? (parsed as T[]) : [];
-      } catch {
-        return [];
-      }
-    }
-    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.
-  //
-  // Deliberately does NOT stamp `updated_at`: the column is server-managed, and
-  // a non-system caller's write to it is stripped (framework #2948) and reported
-  // back as a dropped field — which the console surfaces as a "Some fields were
-  // not saved" toast (#3431). Sending it made every recents/favorites write pop
-  // a scary warning about a field the user never touched, drowning the real
-  // signal the toast exists for (#3794). The server stamps it either way.
-  const upsert = async (items: T[]): Promise<void> => {
-    // Fast path: we already know the row id from a previous load/save.
-    if (cachedRowId !== null) {
-      try {
-        await dataSource.update(resource, cachedRowId, { value: items });
-        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 });
-      return;
-    }
-
-    try {
-      const created = await dataSource.create(resource, {
-        user_id: userId,
-        key,
-        value: items,
-      });
-      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 });
-        return;
-      }
-      throw createError;
-    }
-  };
-
-  return {
-    async load(): Promise<T[]> {
-      try {
-        const row = await findExisting();
-        if (!row) {
-          cachedRowId = null;
-          return [];
-        }
-        if (row.id !== undefined && row.id !== null) cachedRowId = row.id;
-        return decodeValue(row.value);
-      } catch (error) {
-        onError('load', error);
-        return [];
-      }
-    },
-
-    async save(items: T[]): Promise<void> {
-      // 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;
-    },
-  };
-}