@weasel-js/labkit 1.4.4 → 1.5.0

package/src/state/document.test.ts

@@ -1,14 +1,15 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { createMemoryAdapter } from './adapters';
 import {
   CURRENT_DOCUMENT_VERSION,
-  deleteLegacyKeys,
+  deleteConfirmed,
   emptyDocument,
   labDocumentKey,
   MIGRATIONS,
   migrateV0toV1,
   migrateV1toV2,
   migrateV2toV3,
+  migrateV3toV4,
   normalizeDocument,
   quarantineDocument,
   quarantineKey,
@@ -83,19 +84,24 @@ describe('runMigrations', () => {
   });
 });
 
+function reader(entries: Record<string, unknown>) {
+  const map = new Map(Object.entries(entries));
+  return async (key: string) => map.get(key);
+}
+
 describe('readLegacyDocument', () => {
-  it('returns null when no legacy key is present', () => {
-    expect(readLegacyDocument(createMemoryAdapter(), 'lab', 'auto')).toBeNull();
+  it('returns null when no legacy key is present', async () => {
+    expect(await readLegacyDocument(reader({}), 'lab', 'auto')).toBeNull();
   });
 
-  it('assembles a version-0 document from the four buckets', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'workspaces'), JSON.stringify([{ id: 'w1' }]));
-    storage.write(labStorageKey('lab', 'saves'), JSON.stringify([{ id: 's1' }]));
-    storage.write(labStorageKey('lab', 'layout'), JSON.stringify({ w1: { h: 4 } }));
-    storage.write(labStorageKey('lab', 'theme'), 'dark');
-
-    expect(readLegacyDocument(storage, 'lab', 'auto')).toEqual({
+  it('assembles a version-0 document from the four buckets, parsed or not', async () => {
+    const read = reader({
+      [labStorageKey('lab', 'workspaces')]: JSON.stringify([{ id: 'w1' }]),
+      [labStorageKey('lab', 'saves')]: [{ id: 's1' }],
+      [labStorageKey('lab', 'layout')]: JSON.stringify({ w1: { h: 4 } }),
+      [labStorageKey('lab', 'theme')]: 'dark',
+    });
+    expect(await readLegacyDocument(read, 'lab', 'auto')).toEqual({
       version: 0,
       workspaces: [{ id: 'w1' }],
       saves: [{ id: 's1' }],
@@ -104,97 +110,54 @@ describe('readLegacyDocument', () => {
     });
   });
 
-  it('survives one unparseable bucket without losing the others', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'workspaces'), '{{{not json');
-    storage.write(labStorageKey('lab', 'saves'), JSON.stringify([{ id: 's1' }]));
-
-    const doc = readLegacyDocument(storage, 'lab', 'auto');
+  it('survives one unparseable bucket without losing the others', async () => {
+    const read = reader({
+      [labStorageKey('lab', 'workspaces')]: '{{{not json',
+      [labStorageKey('lab', 'saves')]: JSON.stringify([{ id: 's1' }]),
+    });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const doc = await readLegacyDocument(read, 'lab', 'auto');
     expect(doc?.workspaces).toEqual([]);
     expect(doc?.saves).toEqual([{ id: 's1' }]);
+    warn.mockRestore();
   });
 
-  it('falls back to fallbackMode when the theme key is absent', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'workspaces'), JSON.stringify([]));
-
-    expect(readLegacyDocument(storage, 'lab', 'dark')?.mode).toBe('dark');
+  it('falls back to fallbackMode when the theme key is absent', async () => {
+    const read = reader({ [labStorageKey('lab', 'workspaces')]: '[]' });
+    expect((await readLegacyDocument(read, 'lab', 'dark'))?.mode).toBe('dark');
   });
 
-  it('falls back to fallbackMode when the theme value is unrecognized', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'theme'), 'chartreuse');
-
-    expect(readLegacyDocument(storage, 'lab', 'dark')?.mode).toBe('dark');
+  it('falls back to fallbackMode when the theme value is unrecognized', async () => {
+    const read = reader({ [labStorageKey('lab', 'theme')]: 'chartreuse' });
+    expect((await readLegacyDocument(read, 'lab', 'dark'))?.mode).toBe('dark');
   });
 
-  it('a valid theme value beats the fallback', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'theme'), 'light');
-
-    expect(readLegacyDocument(storage, 'lab', 'dark')?.mode).toBe('light');
+  it('a valid theme value beats the fallback', async () => {
+    const read = reader({ [labStorageKey('lab', 'theme')]: 'light' });
+    expect((await readLegacyDocument(read, 'lab', 'dark'))?.mode).toBe('light');
   });
 
-  it('passes interstellar through untouched for migrateV0toV1 to coerce', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'theme'), 'interstellar');
-
-    expect(readLegacyDocument(storage, 'lab', 'dark')?.mode).toBe('interstellar');
+  it('passes interstellar through untouched for migrateV0toV1 to coerce', async () => {
+    const read = reader({ [labStorageKey('lab', 'theme')]: 'interstellar' });
+    expect((await readLegacyDocument(read, 'lab', 'dark'))?.mode).toBe('interstellar');
   });
 });
 
-describe('deleteLegacyKeys', () => {
-  it('deletes all four legacy buckets when the document matches', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'workspaces'), JSON.stringify([{ id: 'w1' }]));
-    storage.write(labStorageKey('lab', 'saves'), JSON.stringify([{ id: 's1' }]));
-    storage.write(labStorageKey('lab', 'layout'), JSON.stringify({ w1: { h: 4 } }));
-    storage.write(labStorageKey('lab', 'theme'), 'dark');
-    storage.write(labDocumentKey('lab'), 'the-document');
-
-    expect(deleteLegacyKeys(storage, 'lab', 'the-document')).toBe(true);
-
-    expect(storage.read(labStorageKey('lab', 'workspaces'))).toBeNull();
-    expect(storage.read(labStorageKey('lab', 'saves'))).toBeNull();
-    expect(storage.read(labStorageKey('lab', 'layout'))).toBeNull();
-    expect(storage.read(labStorageKey('lab', 'theme'))).toBeNull();
-  });
-
-  it('the document key itself survives deletion', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'workspaces'), JSON.stringify([{ id: 'w1' }]));
-    storage.write(labDocumentKey('lab'), 'the-document');
-
-    deleteLegacyKeys(storage, 'lab', 'the-document');
-
-    expect(storage.read(labDocumentKey('lab'))).toBe('the-document');
-  });
-
-  it('deletes nothing and returns false when the document key is absent', () => {
+describe('deleteConfirmed', () => {
+  it('deletes the keys and confirms they are gone', async () => {
     const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'workspaces'), JSON.stringify([{ id: 'w1' }]));
-
-    expect(deleteLegacyKeys(storage, 'lab', 'the-document')).toBe(false);
-    expect(storage.read(labStorageKey('lab', 'workspaces'))).not.toBeNull();
+    await storage.set('a', 1);
+    await storage.set('b', 2);
+    expect(await deleteConfirmed(storage, ['a', 'b'])).toBe(true);
+    expect(await storage.get('a')).toBeUndefined();
   });
 
-  it('returns false when the adapter cannot delete, and the keys survive', () => {
-    const mem = createMemoryAdapter();
-    const storage = { read: mem.read, write: mem.write };
-    storage.write(labStorageKey('lab', 'workspaces'), JSON.stringify([{ id: 'w1' }]));
-    storage.write(labDocumentKey('lab'), 'the-document');
-
-    expect(deleteLegacyKeys(storage, 'lab', 'the-document')).toBe(false);
-    expect(storage.read(labStorageKey('lab', 'workspaces'))).not.toBeNull();
-  });
-
-  it('deletes nothing and returns false when the document key holds different content', () => {
-    const storage = createMemoryAdapter();
-    storage.write(labStorageKey('lab', 'workspaces'), JSON.stringify([{ id: 'w1' }]));
-    storage.write(labDocumentKey('lab'), 'something-else');
-
-    expect(deleteLegacyKeys(storage, 'lab', 'the-document')).toBe(false);
-    expect(storage.read(labStorageKey('lab', 'workspaces'))).not.toBeNull();
+  it('returns false when a delete silently does nothing', async () => {
+    const memory = createMemoryAdapter();
+    await memory.set('a', 1);
+    const storage = { ...memory, delete: async () => {} };
+    expect(await deleteConfirmed(storage, ['a'])).toBe(false);
+    expect(await memory.get('a')).toBe(1);
   });
 });
 
@@ -303,18 +266,15 @@ describe('MIGRATIONS', () => {
 });
 
 describe('quarantineDocument', () => {
-  it('copies the document aside and confirms it landed', () => {
+  it('copies the document aside and confirms it landed', async () => {
     const storage = createMemoryAdapter();
-
-    expect(quarantineDocument(storage, 'lab', 'the-bytes')).toBe(true);
-    expect(storage.read(quarantineKey('lab'))).toBe('the-bytes');
+    expect(await quarantineDocument(storage, 'lab', 'the-bytes')).toBe(true);
+    expect(await storage.get(quarantineKey('lab'))).toBe('the-bytes');
   });
 
-  it('returns false when the quarantine write silently fails', () => {
-    const storage = createMemoryAdapter();
-    storage.write = () => {};
-
-    expect(quarantineDocument(storage, 'lab', 'the-bytes')).toBe(false);
+  it('returns false when the quarantine write silently fails', async () => {
+    const storage = { ...createMemoryAdapter(), set: async () => {} };
+    expect(await quarantineDocument(storage, 'lab', 'the-bytes')).toBe(false);
   });
 });
 
@@ -390,3 +350,18 @@ describe('version 2 to version 3', () => {
     expect(out.mode).toBe('dark');
   });
 });
+
+describe('version 3 to version 4', () => {
+  it('only restamps the document, whose shape does not change', () => {
+    const doc = {
+      version: 3,
+      trials: [{ id: 'w1' }],
+      saves: [],
+      layout: {},
+      undockedPanels: {},
+      mode: 'auto',
+    };
+    expect(migrateV3toV4(doc)).toEqual({ ...doc, version: 4 });
+    expect(MIGRATIONS[3]).toBe(migrateV3toV4);
+  });
+});

package/src/state/document.ts

@@ -10,11 +10,10 @@ import type {
 import type { UndockedPanels } from './undock';
 
 /** Bumped whenever the persisted shape changes; every bump needs a migration. */
-export const CURRENT_DOCUMENT_VERSION = 3;
+export const CURRENT_DOCUMENT_VERSION = 4;
 
-/** The one key a lab persists under. The `:doc` suffix keeps it out of the
- *  legacy bucket namespace, where a lab named `a:saves` would otherwise write
- *  its document over lab `a`'s saves bucket. */
+/** Where a version-3 lab kept its one document. Read once, to fold it into
+ *  records, then deleted. */
 export function labDocumentKey(storageKey: string): string {
   return `lk:${storageKey}:doc`;
 }
@@ -69,83 +68,92 @@ export function runMigrations(
 
 const LEGACY_BUCKETS = ['workspaces', 'saves', 'layout', 'theme'] as const;
 
-function parseOr<T>(raw: string | null, fallback: T, bucket: string): T {
-  if (raw === null) return fallback;
+/** The four keys a lab used before it was one document. */
+export function legacyKeys(storageKey: string): string[] {
+  return LEGACY_BUCKETS.map((bucket) => labStorageKey(storageKey, bucket));
+}
+
+/** A value some substrate returned for an old key: already parsed, or a JSON
+ *  string from a store that does not parse. `undefined` when it is neither. */
+export function parseStored(value: unknown): unknown {
+  if (typeof value !== 'string') return value;
   try {
-    return JSON.parse(raw) as T;
+    return JSON.parse(value);
   } catch {
-    console.warn(`[labkit] unparseable legacy bucket "${bucket}", dropping it`);
-    return fallback;
+    return undefined;
   }
 }
 
+function bucketOr<T>(value: unknown, fallback: T, bucket: string, shape: 'array' | 'object'): T {
+  if (value === undefined) return fallback;
+  const parsed = parseStored(value);
+  const fits = shape === 'array' ? Array.isArray(parsed) : !!parsed && typeof parsed === 'object';
+  if (fits) return parsed as T;
+  console.warn(`[labkit] unparseable legacy bucket "${bucket}", dropping it`);
+  return fallback;
+}
+
 /** Assemble a version-0 document out of the four pre-document keys, or null
  *  if none of them is present. `fallbackMode` is used when the theme key is
  *  absent or holds something unrecognized; `interstellar` passes through
  *  untouched for `migrateV0toV1` to coerce. */
-export function readLegacyDocument(
-  storage: StorageAdapter,
+export async function readLegacyDocument(
+  read: (key: string) => Promise<unknown>,
   storageKey: string,
   fallbackMode: LabMode,
-): Record<string, unknown> | null {
-  const present = LEGACY_BUCKETS.some((b) => storage.read(labStorageKey(storageKey, b)) !== null);
-  if (!present) return null;
+): Promise<Record<string, unknown> | null> {
+  const [workspaces, saves, layout, theme] = await Promise.all(
+    LEGACY_BUCKETS.map((bucket) => read(labStorageKey(storageKey, bucket))),
+  );
+  if ([workspaces, saves, layout, theme].every((v) => v === undefined)) return null;
 
-  const rawMode = storage.read(labStorageKey(storageKey, 'theme'));
   const mode =
-    rawMode === 'light' || rawMode === 'dark' || rawMode === 'auto' || rawMode === 'interstellar'
-      ? rawMode
+    theme === 'light' || theme === 'dark' || theme === 'auto' || theme === 'interstellar'
+      ? theme
       : fallbackMode;
 
   return {
     version: 0,
-    workspaces: parseOr(storage.read(labStorageKey(storageKey, 'workspaces')), [], 'workspaces'),
-    saves: parseOr(storage.read(labStorageKey(storageKey, 'saves')), [], 'saves'),
-    layout: parseOr(storage.read(labStorageKey(storageKey, 'layout')), {}, 'layout'),
+    workspaces: bucketOr(workspaces, [], 'workspaces', 'array'),
+    saves: bucketOr(saves, [], 'saves', 'array'),
+    layout: bucketOr(layout, {}, 'layout', 'object'),
     mode,
   };
 }
 
-/** Delete the four pre-document keys, but only once `expectedDocument` is
- *  confirmed to be exactly what is stored under the document key — a
- *  read-back, not a trust of the write that produced it. On any mismatch
- *  (write failed, landed partially, or never happened) it deletes nothing,
- *  warns, and returns `false` so the legacy buckets stay as a recoverable
- *  copy. Deletion itself is read back too — `StorageAdapter.delete` is
- *  optional, so an adapter without it leaves the keys in place — and `true`
- *  is returned only once all four are actually gone. */
-export function deleteLegacyKeys(
-  storage: StorageAdapter,
-  storageKey: string,
-  expectedDocument: string,
-): boolean {
-  const actual = storage.read(labDocumentKey(storageKey));
-  if (actual !== expectedDocument) {
-    console.warn(
-      `[labkit] keeping legacy keys for "${storageKey}": could not confirm the migrated document was written`,
-    );
+/** Whether two stored values hold the same data. Stored values are
+ *  structured-clone copies, so identity says nothing. */
+export function sameStored(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/** Delete `keys` and read each back, so an adapter whose delete silently did
+ *  nothing is caught. `true` only once all of them are gone. */
+export async function deleteConfirmed(storage: StorageAdapter, keys: string[]): Promise<boolean> {
+  try {
+    await Promise.all(keys.map((key) => storage.delete(key)));
+    const left = await Promise.all(keys.map((key) => storage.get(key)));
+    return left.every((v) => v === undefined);
+  } catch {
     return false;
   }
-  let allGone = true;
-  for (const bucket of LEGACY_BUCKETS) {
-    const key = labStorageKey(storageKey, bucket);
-    storage.delete?.(key);
-    if (storage.read(key) !== null) allGone = false;
-  }
-  return allGone;
 }
 
-/** Set `raw` aside under the quarantine key, reading it back to confirm it
+/** Set `value` aside under the quarantine key, reading it back to confirm it
  *  landed. Returns `false` when it did not — a full disk is exactly when a
  *  document goes unreadable — so the caller can leave the original alone
  *  rather than overwrite the only copy of it. */
-export function quarantineDocument(
+export async function quarantineDocument(
   storage: StorageAdapter,
   storageKey: string,
-  raw: string,
-): boolean {
-  storage.write(quarantineKey(storageKey), raw);
-  return storage.read(quarantineKey(storageKey)) === raw;
+  value: unknown,
+): Promise<boolean> {
+  try {
+    await storage.set(quarantineKey(storageKey), value);
+    return sameStored(await storage.get(quarantineKey(storageKey)), value);
+  } catch {
+    return false;
+  }
 }
 
 /** Fill in whatever a document is missing or holds the wrong shape of, so a
@@ -202,5 +210,11 @@ export function migrateV2toV3(doc: Record<string, unknown>): Record<string, unkn
   return { ...doc, undockedPanels: {}, version: 3 };
 }
 
+/** Version 3 to version 4: a lab is stored as records under one prefix
+ *  instead of one document. The joined shape does not change. */
+export function migrateV3toV4(doc: Record<string, unknown>): Record<string, unknown> {
+  return { ...doc, version: 4 };
+}
+
 /** Index `i` migrates a version-`i` document to version `i + 1`. */
-export const MIGRATIONS: Migration[] = [migrateV0toV1, migrateV1toV2, migrateV2toV3];
+export const MIGRATIONS: Migration[] = [migrateV0toV1, migrateV1toV2, migrateV2toV3, migrateV3toV4];

package/src/state/helpers.test.ts

@@ -4,8 +4,8 @@ import {
   deserializeTrials,
   emptyUndoStack,
   encodeUrlHash,
-  newId,
   labStorageKey,
+  newId,
   serializeTrials,
 } from './helpers';
 

package/src/state/index.ts

@@ -1,5 +1,8 @@
 export {
+  createIndexedDbAdapter,
   createMemoryAdapter,
+  type IndexedDbAdapterOptions,
+  indexedDbAdapter,
   localStorageAdapter,
   noneAdapter,
   sessionStorageAdapter,
@@ -26,6 +29,9 @@ export {
   labStorageKey,
   serializeTrials,
 } from './helpers';
+export { type OpenedLabStore, type OpenLabStoreOptions, openLabStore } from './openLabStore';
+export { Persistence, type PersistenceProps } from './Persistence';
+export type { RecordCache, RecordChange } from './records';
 export {
   SingletonExperimentProvider,
   type SingletonExperimentProviderProps,
@@ -41,10 +47,12 @@ export type {
   SavedSnapshot,
   SerializedTrial,
   StorageAdapter,
+  StorageChange,
   TrialRecord,
   TrialStateHandle,
   UndoStack,
 } from './types';
 export type { UndockedPanel, UndockedPanels } from './undock';
 export { dockPanel, panelKey, undockPanel } from './undock';
+export { type PersistedStateOptions, usePersistedState } from './usePersistedState';
 export { useTrialState } from './useTrialState';

package/src/state/labRecords.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import { CURRENT_DOCUMENT_VERSION } from './document';
+import {
+  documentOfRecords,
+  labPrefix,
+  parseRecordName,
+  recordsOfDocument,
+  trialRecord,
+  valueRecord,
+} from './labRecords';
+import type { LabDocument } from './types';
+
+const VIEW = { zoom: 1, pan: { x: 0, y: 0 } };
+
+describe('record names', () => {
+  it('encodes the storage key, so no lab prefix contains another', () => {
+    expect(labPrefix('drag-lab')).toBe('lk:drag-lab:');
+    expect(labPrefix('a:trial:x')).toBe('lk:a%3Atrial%3Ax:');
+    expect(labPrefix('a:trial:x').startsWith(labPrefix('a'))).toBe(false);
+  });
+
+  it('round-trips ids holding the separator', () => {
+    expect(parseRecordName(trialRecord('odd:id'))).toEqual({ kind: 'trial', id: 'odd:id' });
+  });
+
+  it('scopes a value to its trial or to the lab', () => {
+    expect(valueRecord('t:1', 'tab')).toBe('value:trial:t%3A1:tab');
+    expect(valueRecord(null, 'tab')).toBe('value:lab:tab');
+    expect(parseRecordName(valueRecord('t:1', 'a:b'))).toEqual({ kind: 'value' });
+  });
+
+  it('answers null for a name no lab writes', () => {
+    for (const name of [
+      'doc',
+      'meta:x',
+      'trial:',
+      'trial:a:b',
+      'value:lab',
+      'value:x:y',
+      'trial:%E0%A4%A',
+    ]) {
+      expect(parseRecordName(name)).toBeNull();
+    }
+  });
+});
+
+describe('documents and records', () => {
+  const doc: LabDocument = {
+    version: CURRENT_DOCUMENT_VERSION,
+    trials: [
+      { id: 'b', instrumentName: 'T', config: {}, state: { n: 2 }, view: VIEW },
+      { id: 'a', instrumentName: 'T', config: {}, state: { n: 1 }, view: VIEW },
+    ],
+    saves: [
+      {
+        id: 's2',
+        name: 'later',
+        trialId: 'a',
+        instrumentName: 'T',
+        config: {},
+        state: {},
+        savedAt: 2,
+      },
+      {
+        id: 's1',
+        name: 'earlier',
+        trialId: 'a',
+        instrumentName: 'T',
+        config: {},
+        state: {},
+        savedAt: 1,
+      },
+    ],
+    layout: { a: { h: 1 } },
+    undockedPanels: {},
+    mode: 'dark',
+  };
+
+  it('writes meta last', () => {
+    const names = recordsOfDocument(doc).map(([name]) => name);
+    expect(names.at(-1)).toBe('meta');
+  });
+
+  it('joins back into the document it came from, trials in stored order', () => {
+    const joined = documentOfRecords(recordsOfDocument(doc).reverse());
+    expect(joined?.doc).toEqual({ ...doc, saves: [doc.saves[1], doc.saves[0]] });
+    expect([...(joined?.orders ?? [])]).toEqual([
+      ['b', 0],
+      ['a', 1],
+    ]);
+  });
+
+  it('breaks an order tie by id', () => {
+    const joined = documentOfRecords([
+      ['meta', { version: 4, mode: 'auto' }],
+      ['trial:z', { instrumentName: 'T', order: 0 }],
+      ['trial:m', { instrumentName: 'T', order: 0 }],
+    ]);
+    expect((joined?.doc.trials as { id: string }[]).map((t) => t.id)).toEqual(['m', 'z']);
+  });
+
+  it('is null without a meta record', () => {
+    expect(documentOfRecords([['trial:a', { instrumentName: 'T', order: 0 }]])).toBeNull();
+  });
+});