@weasel-js/labkit 1.4.3 → 1.5.0

package/src/state/SingletonExperiment.tsx

@@ -1,7 +1,10 @@
-import { type ReactNode, useRef } from 'react';
+import type { ReactNode } from 'react';
+import { defaultStorage } from './adapters';
 import { LabStoreProvider, TrialIdProvider } from './context';
-import { createLabStore, type LabStore } from './store';
+import { openLabStore } from './openLabStore';
+import { PersistenceContext } from './Persistence';
 import type { StorageAdapter } from './types';
+import { useOpenOnce, useWarnIgnoredChange } from './useOpenOnce';
 
 const SINGLETON_INSTRUMENT = '__singleton__';
 
@@ -12,8 +15,11 @@ export interface SingletonExperimentProviderProps<TS, TC> {
   id: string;
   initialConfig: TC;
   initialState: TS;
-  storage: StorageAdapter;
   storageKey: string;
+  /** Default: IndexedDB, or localStorage where IndexedDB will not open. */
+  storage?: StorageAdapter;
+  /** Rendered until the stored experiment has loaded. Default: nothing. */
+  fallback?: ReactNode;
   children: ReactNode;
 }
 
@@ -21,7 +27,8 @@ export interface SingletonExperimentProviderProps<TS, TC> {
  * One-trial `<Lab>` substitute for single-screen experiments. Mounts
  * a `LabStoreProvider` + `TrialIdProvider` with one synthetic
  * trial, so `useTrialState` works without going through the
- * full `<Lab instruments={...}>` runtime.
+ * full `<Lab instruments={...}>` runtime. `storageKey` and `storage` are read
+ * once, at mount.
  */
 export function SingletonExperimentProvider<TS, TC>({
   id,
@@ -29,13 +36,14 @@ export function SingletonExperimentProvider<TS, TC>({
   initialState,
   storage,
   storageKey,
+  fallback = null,
   children,
 }: SingletonExperimentProviderProps<TS, TC>) {
-  const storeRef = useRef<LabStore | null>(null);
-  if (storeRef.current === null) {
-    const store = createLabStore({ storageKey, storage });
-    if (!store.getState().trials.some((w) => w.id === id)) {
-      store.getState().addTrial({
+  useWarnIgnoredChange('<SingletonExperimentProvider>', { storageKey, storage });
+  const opened = useOpenOnce(async () => {
+    const lab = await openLabStore({ storageKey, storage: storage ?? (await defaultStorage()) });
+    if (!lab.store.getState().trials.some((w) => w.id === id)) {
+      lab.store.getState().addTrial({
         id,
         instrumentName: SINGLETON_INSTRUMENT,
         config: initialConfig,
@@ -43,11 +51,14 @@ export function SingletonExperimentProvider<TS, TC>({
         view: { zoom: 1, pan: { x: 0, y: 0 } },
       });
     }
-    storeRef.current = store;
-  }
+    return lab;
+  });
+  if (!opened) return <>{fallback}</>;
   return (
-    <LabStoreProvider store={storeRef.current}>
-      <TrialIdProvider trialId={id}>{children}</TrialIdProvider>
+    <LabStoreProvider store={opened.store}>
+      <PersistenceContext.Provider value={opened.records}>
+        <TrialIdProvider trialId={id}>{children}</TrialIdProvider>
+      </PersistenceContext.Provider>
     </LabStoreProvider>
   );
 }

package/src/state/adapterContract.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest';
+import type { StorageAdapter, StorageChange } from './types';
+
+/** How the contract suite drives one adapter. */
+export interface AdapterHarness {
+  adapter: StorageAdapter;
+  /** Whether a `Uint8Array` survives the round trip unchanged. */
+  binary: boolean;
+  /** Make a change the way another writer would, or omit when the adapter
+   *  has no `subscribe`. */
+  foreign?: {
+    set(key: string, value: unknown): Promise<void> | void;
+    delete(key: string): Promise<void> | void;
+  };
+}
+
+async function until(check: () => boolean, ms = 1000): Promise<void> {
+  const end = Date.now() + ms;
+  while (!check()) {
+    if (Date.now() > end) throw new Error('timed out waiting for a change');
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+const settle = (): Promise<void> => new Promise((r) => setTimeout(r, 50));
+
+/** Every shipped adapter answers to these. `setup` runs once per test. */
+export function describeAdapterContract(name: string, setup: () => AdapterHarness): void {
+  describe(`${name} — the adapter contract`, () => {
+    it('reads back what it stored, as a copy', async () => {
+      const { adapter } = setup();
+      const value = { trial: 'a', nested: { n: 1, list: [1, 'two', null] } };
+      await adapter.set('lk:x:one', value);
+      value.nested.n = 99;
+      expect(await adapter.get('lk:x:one')).toEqual({
+        trial: 'a',
+        nested: { n: 1, list: [1, 'two', null] },
+      });
+    });
+
+    it('answers undefined for a key it never held', async () => {
+      const { adapter } = setup();
+      expect(await adapter.get('lk:x:absent')).toBeUndefined();
+    });
+
+    it('lists only the keys under a prefix', async () => {
+      const { adapter } = setup();
+      await adapter.set('lk:x:a', 1);
+      await adapter.set('lk:x:b', 2);
+      await adapter.set('lk:y:a', 3);
+      const listed = await adapter.list('lk:x:');
+      expect(new Map(listed)).toEqual(
+        new Map<string, unknown>([
+          ['lk:x:a', 1],
+          ['lk:x:b', 2],
+        ]),
+      );
+    });
+
+    it('deletes a key', async () => {
+      const { adapter } = setup();
+      await adapter.set('lk:x:gone', { a: 1 });
+      await adapter.delete('lk:x:gone');
+      expect(await adapter.get('lk:x:gone')).toBeUndefined();
+      expect(await adapter.list('lk:x:')).toEqual([]);
+    });
+
+    it('keeps binary values exactly when it says it can', async () => {
+      const { adapter, binary } = setup();
+      if (!binary) return;
+      await adapter.set('lk:x:bytes', new Uint8Array([1, 2, 255]));
+      const back = await adapter.get('lk:x:bytes');
+      // Not `toBeInstanceOf`: under jsdom, structuredClone hands back Node's
+      // Uint8Array, which is not the test realm's.
+      expect(Object.prototype.toString.call(back)).toBe('[object Uint8Array]');
+      expect([...(back as Uint8Array)]).toEqual([1, 2, 255]);
+    });
+
+    it("reports another writer's changes under its prefix, and nothing else", async () => {
+      const { adapter, foreign } = setup();
+      if (!foreign) {
+        expect(adapter.subscribe).toBeUndefined();
+        return;
+      }
+      if (!adapter.subscribe) throw new Error(`${name} has a foreign writer but no subscribe`);
+      const heard: StorageChange[] = [];
+      const off = adapter.subscribe('lk:x:', (changes) => heard.push(...changes));
+      try {
+        await adapter.set('lk:x:own', 'mine');
+        await foreign.set('lk:y:elsewhere', 'not this prefix');
+        await settle();
+        expect(heard).toEqual([]);
+
+        await foreign.set('lk:x:theirs', { from: 'peer' });
+        await until(() => heard.length > 0);
+        expect(heard).toEqual([['lk:x:theirs', { from: 'peer' }]]);
+
+        await foreign.delete('lk:x:theirs');
+        await until(() => heard.length > 1);
+        expect(heard[1]).toEqual(['lk:x:theirs', undefined]);
+      } finally {
+        off();
+      }
+    });
+
+    it('stops reporting once unsubscribed', async () => {
+      const { adapter, foreign } = setup();
+      if (!foreign || !adapter.subscribe) return;
+      const heard: StorageChange[] = [];
+      adapter.subscribe('lk:x:', (changes) => heard.push(...changes))();
+      await foreign.set('lk:x:late', 1);
+      await settle();
+      expect(heard).toEqual([]);
+    });
+  });
+}

package/src/state/adapters.test.ts

@@ -1,94 +1,146 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import 'fake-indexeddb/auto';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { describeAdapterContract } from './adapterContract';
 import {
+  createIndexedDbAdapter,
   createMemoryAdapter,
+  defaultStorage,
+  indexedDbAdapter,
   localStorageAdapter,
   noneAdapter,
+  resetDefaultStorage,
   sessionStorageAdapter,
   urlHashAdapter,
 } from './adapters';
+import { decodeUrlHash, encodeUrlHash } from './helpers';
 
-describe('localStorageAdapter', () => {
-  beforeEach(() => localStorage.clear());
+describeAdapterContract('createMemoryAdapter', () => {
+  const backing = new Map<string, unknown>();
+  const peer = createMemoryAdapter(backing);
+  return { adapter: createMemoryAdapter(backing), binary: true, foreign: peer };
+});
 
-  it('writes and reads a value', () => {
-    localStorageAdapter.write('k', 'v');
-    expect(localStorageAdapter.read('k')).toBe('v');
-  });
+let database = 0;
+describeAdapterContract('createIndexedDbAdapter', () => {
+  const name = `contract-${database++}`;
+  return {
+    adapter: createIndexedDbAdapter({ database: name }),
+    binary: true,
+    foreign: createIndexedDbAdapter({ database: name }),
+  };
+});
 
-  it('returns null for missing key', () => {
-    expect(localStorageAdapter.read('missing')).toBeNull();
-  });
+/** jsdom has one window, so no `storage` event ever arrives from another tab.
+ *  This writes the key and dispatches the event another tab's write would —
+ *  a stand-in for the browser, not a test of it. */
+function foreignWebStorage(area: Storage) {
+  const fire = (key: string, newValue: string | null): void => {
+    window.dispatchEvent(new StorageEvent('storage', { key, newValue, storageArea: area }));
+  };
+  return {
+    set: (key: string, value: unknown) => {
+      const raw = JSON.stringify(value);
+      area.setItem(key, raw);
+      fire(key, raw);
+    },
+    delete: (key: string) => {
+      area.removeItem(key);
+      fire(key, null);
+    },
+  };
+}
 
-  it('deletes a key', () => {
-    localStorageAdapter.write('k', 'v');
-    localStorageAdapter.delete?.('k');
-    expect(localStorageAdapter.read('k')).toBeNull();
-  });
+describeAdapterContract('localStorageAdapter', () => {
+  localStorage.clear();
+  return { adapter: localStorageAdapter, binary: false, foreign: foreignWebStorage(localStorage) };
+});
 
-  it('handles QuotaExceededError gracefully', () => {
-    vi.spyOn(Storage.prototype, 'setItem').mockImplementationOnce(() => {
-      throw new DOMException('QuotaExceeded', 'QuotaExceededError');
-    });
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    expect(() => localStorageAdapter.write('k', 'v')).not.toThrow();
-    expect(warn).toHaveBeenCalled();
-    warn.mockRestore();
-  });
+describeAdapterContract('sessionStorageAdapter', () => {
+  sessionStorage.clear();
+  return { adapter: sessionStorageAdapter, binary: false };
 });
 
-describe('sessionStorageAdapter', () => {
-  beforeEach(() => sessionStorage.clear());
+function foreignHash() {
+  const edit = (change: (map: Record<string, string>) => void): void => {
+    const raw = decodeUrlHash(window.location.hash.replace(/^#/, ''));
+    const map = raw ? (JSON.parse(raw) as Record<string, string>) : {};
+    change(map);
+    window.location.hash = encodeUrlHash(JSON.stringify(map));
+  };
+  return {
+    set: (key: string, value: unknown) =>
+      edit((map) => {
+        map[key] = JSON.stringify(value);
+      }),
+    delete: (key: string) =>
+      edit((map) => {
+        delete map[key];
+      }),
+  };
+}
 
-  it('writes and reads a value', () => {
-    sessionStorageAdapter.write('k', 'v');
-    expect(sessionStorageAdapter.read('k')).toBe('v');
-  });
+describeAdapterContract('urlHashAdapter', () => {
+  window.history.replaceState(null, '', '#');
+  return { adapter: urlHashAdapter, binary: false, foreign: foreignHash() };
 });
 
-describe('urlHashAdapter', () => {
-  beforeEach(() => {
-    window.location.hash = '';
-  });
+describe('localStorageAdapter', () => {
+  beforeEach(() => localStorage.clear());
 
-  it('writes and reads back through the hash', () => {
-    urlHashAdapter.write('any-key', 'hello world');
-    expect(urlHashAdapter.read('any-key')).toBe('hello world');
+  it('reads a value stored before records existed, raw or JSON', async () => {
+    localStorage.setItem('lk:old:theme', 'dark');
+    localStorage.setItem('lk:old:doc', '{"version":3}');
+    expect(await localStorageAdapter.get('lk:old:theme')).toBe('dark');
+    expect(await localStorageAdapter.get('lk:old:doc')).toEqual({ version: 3 });
   });
 
-  it('returns null when hash is empty', () => {
-    expect(urlHashAdapter.read('any-key')).toBeNull();
+  it('rejects a write that does not land', async () => {
+    vi.spyOn(Storage.prototype, 'setItem').mockImplementationOnce(() => {
+      throw new DOMException('QuotaExceeded', 'QuotaExceededError');
+    });
+    await expect(localStorageAdapter.set('k', 'v')).rejects.toThrow('QuotaExceeded');
   });
 
-  it('uses replaceState (not pushState)', () => {
-    const spy = vi.spyOn(window.history, 'replaceState');
-    urlHashAdapter.write('k', 'v');
-    expect(spy).toHaveBeenCalled();
-    spy.mockRestore();
+  it('warns once per key when JSON would change the value, and stores what JSON keeps', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    await localStorageAdapter.set('lk:w:a', { at: new Set([1]) });
+    await localStorageAdapter.set('lk:w:a', { at: new Set([2]) });
+    await localStorageAdapter.set('lk:w:b', { fine: [1, 'x', null], skipped: undefined });
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(await localStorageAdapter.get('lk:w:a')).toEqual({ at: {} });
+    warn.mockRestore();
   });
 });
 
-describe('createMemoryAdapter', () => {
-  it('two instances are isolated', () => {
-    const a = createMemoryAdapter();
-    const b = createMemoryAdapter();
-    a.write('k', 'from-a');
-    expect(b.read('k')).toBeNull();
+describe('noneAdapter', () => {
+  it('stores nothing', async () => {
+    await noneAdapter.set('k', 'v');
+    expect(await noneAdapter.get('k')).toBeUndefined();
+    expect(await noneAdapter.list('')).toEqual([]);
   });
+});
 
-  it('delete removes the key', () => {
-    const m = createMemoryAdapter();
-    m.write('k', 'v');
-    m.delete?.('k');
-    expect(m.read('k')).toBeNull();
+describe('defaultStorage', () => {
+  afterEach(() => {
+    resetDefaultStorage();
+    vi.unstubAllGlobals();
   });
-});
 
-describe('noneAdapter', () => {
-  it('read always returns null', () => {
-    expect(noneAdapter.read('anything')).toBeNull();
+  it('is IndexedDB where it opens', async () => {
+    expect(await defaultStorage()).toBe(indexedDbAdapter);
   });
 
-  it('write is a no-op', () => {
-    expect(() => noneAdapter.write('k', 'v')).not.toThrow();
+  it('falls back to localStorage, with a warning, where it will not', async () => {
+    vi.stubGlobal('indexedDB', undefined);
+    // The shared adapter may already hold an open database from the case above.
+    vi.resetModules();
+    const fresh = await import('./adapters');
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    expect(await fresh.defaultStorage()).toBe(fresh.localStorageAdapter);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('IndexedDB would not open'),
+      expect.anything(),
+    );
+    warn.mockRestore();
   });
 });