@weasel-js/labkit 1.0.3 → 1.1.0

package/src/state/document.test.ts

@@ -0,0 +1,369 @@
+import { describe, expect, it } from 'vitest';
+import { createMemoryAdapter } from './adapters';
+import {
+  CURRENT_DOCUMENT_VERSION,
+  deleteLegacyKeys,
+  emptyDocument,
+  labDocumentKey,
+  MIGRATIONS,
+  migrateV0toV1,
+  migrateV1toV2,
+  normalizeDocument,
+  quarantineDocument,
+  quarantineKey,
+  readLegacyDocument,
+  runMigrations,
+} from './document';
+import { labStorageKey } from './helpers';
+
+describe('document keys', () => {
+  it('namespaces the document key by storageKey', () => {
+    expect(labDocumentKey('mylab')).toBe('lk:mylab:doc');
+  });
+
+  it('namespaces the quarantine key by storageKey', () => {
+    expect(quarantineKey('mylab')).toBe('lk:mylab:quarantine');
+  });
+
+  it('cannot collide with a legacy bucket key of another lab', () => {
+    for (const bucket of ['workspaces', 'saves', 'layout', 'theme'] as const) {
+      expect(labDocumentKey(`a:${bucket}`)).not.toBe(labStorageKey('a', bucket));
+      expect(labDocumentKey('a')).not.toBe(labStorageKey('a', bucket));
+    }
+  });
+
+  it('cannot collide with a quarantine key of another lab', () => {
+    expect(labDocumentKey('a:quarantine')).not.toBe(quarantineKey('a'));
+  });
+});
+
+describe('emptyDocument', () => {
+  it('is stamped at the current version with the given mode', () => {
+    const doc = emptyDocument('light');
+    expect(doc.version).toBe(CURRENT_DOCUMENT_VERSION);
+    expect(doc.mode).toBe('light');
+    expect(doc.trials).toEqual([]);
+    expect(doc.saves).toEqual([]);
+    expect(doc.layout).toEqual({});
+  });
+});
+
+const bump = (to: number) => (doc: Record<string, unknown>) => ({ ...doc, version: to });
+
+describe('runMigrations', () => {
+  it('returns a current-version document untouched', () => {
+    const doc = { version: 2, a: 1 };
+    const out = runMigrations(doc, [bump(1), bump(2)], 2);
+    expect(out).toEqual({ ok: true, doc: { version: 2, a: 1 }, migrated: false });
+  });
+
+  it('runs every migration from the stored version to the current one', () => {
+    const out = runMigrations({ version: 0 }, [bump(1), bump(2)], 2);
+    expect(out).toEqual({ ok: true, doc: { version: 2 }, migrated: true });
+  });
+
+  it('refuses a document from a future version', () => {
+    const out = runMigrations({ version: 9 }, [bump(1)], 1);
+    expect(out).toEqual({ ok: false, reason: 'future' });
+  });
+
+  it('reports a throwing migration as failed', () => {
+    const boom = () => {
+      throw new Error('nope');
+    };
+    const out = runMigrations({ version: 0 }, [boom], 1);
+    expect(out.ok).toBe(false);
+    if (!out.ok) expect(out.reason).toBe('failed');
+  });
+
+  it('treats a document with no version as version 0', () => {
+    const out = runMigrations({}, [bump(1)], 1);
+    expect(out).toEqual({ ok: true, doc: { version: 1 }, migrated: true });
+  });
+});
+
+describe('readLegacyDocument', () => {
+  it('returns null when no legacy key is present', () => {
+    expect(readLegacyDocument(createMemoryAdapter(), '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({
+      version: 0,
+      workspaces: [{ id: 'w1' }],
+      saves: [{ id: 's1' }],
+      layout: { w1: { h: 4 } },
+      mode: 'dark',
+    });
+  });
+
+  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');
+    expect(doc?.workspaces).toEqual([]);
+    expect(doc?.saves).toEqual([{ id: 's1' }]);
+  });
+
+  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 value is unrecognized', () => {
+    const storage = createMemoryAdapter();
+    storage.write(labStorageKey('lab', 'theme'), 'chartreuse');
+
+    expect(readLegacyDocument(storage, '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('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');
+  });
+});
+
+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', () => {
+    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();
+  });
+
+  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();
+  });
+});
+
+describe('migrateV0toV1', () => {
+  it('stamps version 1', () => {
+    expect(migrateV0toV1({ version: 0 }).version).toBe(1);
+  });
+
+  it('renames the old interstellar mode to dark', () => {
+    expect(migrateV0toV1({ version: 0, mode: 'interstellar' }).mode).toBe('dark');
+  });
+
+  it('replaces an unrecognized mode with auto', () => {
+    expect(migrateV0toV1({ version: 0, mode: 'chartreuse' }).mode).toBe('auto');
+  });
+
+  it.each(['light', 'dark', 'auto'] as const)('passes mode %s through unchanged', (mode) => {
+    expect(migrateV0toV1({ version: 0, mode }).mode).toBe(mode);
+  });
+
+  it('fills in every missing section', () => {
+    expect(migrateV0toV1({ version: 0 })).toEqual({
+      version: 1,
+      workspaces: [],
+      saves: [],
+      layout: {},
+      mode: 'auto',
+    });
+  });
+
+  it('preserves a populated workspaces array', () => {
+    const workspaces = [{ id: 'w1', instrumentName: 'osc' }];
+    expect(migrateV0toV1({ version: 0, workspaces }).workspaces).toEqual(workspaces);
+  });
+
+  it('preserves a populated saves array', () => {
+    const saves = [{ id: 's1', name: 'my save' }];
+    expect(migrateV0toV1({ version: 0, saves }).saves).toEqual(saves);
+  });
+
+  it('preserves a populated layout object', () => {
+    const layout = { w1: { h: 4 } };
+    expect(migrateV0toV1({ version: 0, layout }).layout).toEqual(layout);
+  });
+
+  it('falls back layout to {} and workspaces/saves to [] without swapping them', () => {
+    const out = migrateV0toV1({ version: 0, workspaces: 'nope', saves: 'nope', layout: 'nope' });
+    expect(out.workspaces).toEqual([]);
+    expect(out.saves).toEqual([]);
+    expect(out.layout).toEqual({});
+  });
+});
+
+describe('migrateV1toV2', () => {
+  it('stamps version 2', () => {
+    expect(migrateV1toV2({ version: 1, workspaces: [] }).version).toBe(2);
+  });
+
+  it('renames workspaces to trials, record for record', () => {
+    const records = [{ id: 'w1', instrumentName: 'osc', state: { n: 1 } }];
+    const out = migrateV1toV2({ version: 1, workspaces: records });
+    expect(out.trials).toEqual(records);
+    expect(out).not.toHaveProperty('workspaces');
+  });
+
+  it('leaves the other sections alone', () => {
+    const out = migrateV1toV2({
+      version: 1,
+      workspaces: [],
+      saves: [{ id: 's1' }],
+      layout: { w1: { h: 4 } },
+      mode: 'dark',
+    });
+    expect(out.saves).toEqual([{ id: 's1' }]);
+    expect(out.layout).toEqual({ w1: { h: 4 } });
+    expect(out.mode).toBe('dark');
+  });
+
+  it('falls back to an empty trials list when workspaces is the wrong shape', () => {
+    expect(migrateV1toV2({ version: 1, workspaces: 'nope' }).trials).toEqual([]);
+  });
+});
+
+describe('MIGRATIONS', () => {
+  it('has one entry per version below the current one', () => {
+    expect(MIGRATIONS).toHaveLength(CURRENT_DOCUMENT_VERSION);
+  });
+
+  it('indexes migrateV0toV1 at position 0', () => {
+    expect(MIGRATIONS[0]).toBe(migrateV0toV1);
+  });
+
+  it('indexes migrateV1toV2 at position 1', () => {
+    expect(MIGRATIONS[1]).toBe(migrateV1toV2);
+  });
+
+  it('walks a version-0 document all the way to trials', () => {
+    const outcome = runMigrations(
+      { version: 0, workspaces: [{ id: 'w1' }] },
+      MIGRATIONS,
+      CURRENT_DOCUMENT_VERSION,
+    );
+    expect(outcome).toMatchObject({ ok: true, migrated: true });
+    expect(outcome.ok && outcome.doc.trials).toEqual([{ id: 'w1' }]);
+  });
+});
+
+describe('quarantineDocument', () => {
+  it('copies the document aside and confirms it landed', () => {
+    const storage = createMemoryAdapter();
+
+    expect(quarantineDocument(storage, 'lab', 'the-bytes')).toBe(true);
+    expect(storage.read(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);
+  });
+});
+
+describe('normalizeDocument', () => {
+  it('fills in every missing section', () => {
+    expect(normalizeDocument({ version: CURRENT_DOCUMENT_VERSION }, 'auto')).toEqual({
+      version: CURRENT_DOCUMENT_VERSION,
+      trials: [],
+      saves: [],
+      layout: {},
+      mode: 'auto',
+    });
+  });
+
+  it('uses the fallback mode when the document has none', () => {
+    expect(normalizeDocument({ version: CURRENT_DOCUMENT_VERSION }, 'light').mode).toBe('light');
+  });
+
+  it('uses the fallback mode when the stored mode is unrecognized', () => {
+    expect(
+      normalizeDocument({ version: CURRENT_DOCUMENT_VERSION, mode: 'chartreuse' }, 'light').mode,
+    ).toBe('light');
+  });
+
+  it('keeps a stored mode over the fallback', () => {
+    expect(
+      normalizeDocument({ version: CURRENT_DOCUMENT_VERSION, mode: 'dark' }, 'light').mode,
+    ).toBe('dark');
+  });
+
+  it('preserves populated sections', () => {
+    const trials = [{ id: 'w1' }];
+    const saves = [{ id: 's1' }];
+    const layout = { w1: { h: 4 } };
+    const out = normalizeDocument(
+      { version: CURRENT_DOCUMENT_VERSION, trials, saves, layout },
+      'auto',
+    );
+    expect(out.trials).toEqual(trials);
+    expect(out.saves).toEqual(saves);
+    expect(out.layout).toEqual(layout);
+  });
+
+  it('replaces wrong-shaped sections without swapping them', () => {
+    const out = normalizeDocument(
+      { version: CURRENT_DOCUMENT_VERSION, trials: 'nope', saves: 'nope', layout: 'nope' },
+      'auto',
+    );
+    expect(out.trials).toEqual([]);
+    expect(out.saves).toEqual([]);
+    expect(out.layout).toEqual({});
+  });
+});

package/src/state/document.ts

@@ -0,0 +1,194 @@
+import { labStorageKey } from './helpers';
+import type {
+  LabDocument,
+  LabMode,
+  Migration,
+  SavedSnapshot,
+  SerializedTrial,
+  StorageAdapter,
+} from './types';
+
+/** Bumped whenever the persisted shape changes; every bump needs a migration. */
+export const CURRENT_DOCUMENT_VERSION = 2;
+
+/** 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. */
+export function labDocumentKey(storageKey: string): string {
+  return `lk:${storageKey}:doc`;
+}
+
+/** Where a document that failed to migrate is set aside, so a bad migration
+ *  loses state loudly rather than silently. */
+export function quarantineKey(storageKey: string): string {
+  return `lk:${storageKey}:quarantine`;
+}
+
+/** A fresh document at the current version. */
+export function emptyDocument(mode: LabMode): LabDocument {
+  return {
+    version: CURRENT_DOCUMENT_VERSION,
+    trials: [],
+    saves: [],
+    layout: {},
+    mode,
+  };
+}
+
+/** What a migration run produced: the migrated document, or why it refused. */
+export type MigrationOutcome =
+  | { ok: true; doc: Record<string, unknown>; migrated: boolean }
+  | { ok: false; reason: 'future' | 'failed'; error?: unknown };
+
+/** Walk a document forward to `target`, one migration at a time. A version
+ *  above `target` is refused rather than parsed under a shape it may not
+ *  have. */
+export function runMigrations(
+  raw: Record<string, unknown>,
+  migrations: Migration[],
+  target: number,
+): MigrationOutcome {
+  const from = typeof raw.version === 'number' ? raw.version : 0;
+  if (from > target) return { ok: false, reason: 'future' };
+  if (from === target) return { ok: true, doc: raw, migrated: false };
+
+  let doc = raw;
+  try {
+    for (let v = from; v < target; v++) {
+      const migration = migrations[v];
+      if (!migration) throw new Error(`[labkit] no migration from version ${v}`);
+      doc = migration(doc);
+    }
+  } catch (error) {
+    return { ok: false, reason: 'failed', error };
+  }
+  return { ok: true, doc, migrated: true };
+}
+
+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;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    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,
+  storageKey: string,
+  fallbackMode: LabMode,
+): Record<string, unknown> | null {
+  const present = LEGACY_BUCKETS.some((b) => storage.read(labStorageKey(storageKey, b)) !== null);
+  if (!present) return null;
+
+  const rawMode = storage.read(labStorageKey(storageKey, 'theme'));
+  const mode =
+    rawMode === 'light' || rawMode === 'dark' || rawMode === 'auto' || rawMode === 'interstellar'
+      ? rawMode
+      : 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'),
+    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`,
+    );
+    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
+ *  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(
+  storage: StorageAdapter,
+  storageKey: string,
+  raw: string,
+): boolean {
+  storage.write(quarantineKey(storageKey), raw);
+  return storage.read(quarantineKey(storageKey)) === raw;
+}
+
+/** Fill in whatever a document is missing or holds the wrong shape of, so a
+ *  hydrated store never sees `undefined` where a section should be. Applied to
+ *  every document, migrated or already current. */
+export function normalizeDocument(
+  doc: Record<string, unknown>,
+  fallbackMode: LabMode,
+): LabDocument {
+  const mode =
+    doc.mode === 'light' || doc.mode === 'dark' || doc.mode === 'auto' ? doc.mode : fallbackMode;
+  return {
+    version: CURRENT_DOCUMENT_VERSION,
+    trials: Array.isArray(doc.trials) ? (doc.trials as SerializedTrial[]) : [],
+    saves: Array.isArray(doc.saves) ? (doc.saves as SavedSnapshot[]) : [],
+    layout:
+      doc.layout && typeof doc.layout === 'object' ? (doc.layout as Record<string, unknown>) : {},
+    mode,
+  };
+}
+
+/** Version 0 (four loose keys) to version 1 (one document). Normalizes the
+ *  mode, including `interstellar` — the dark mode's name back when it was a
+ *  theme. Coerces against version 1's own field names rather than reusing
+ *  `normalizeDocument`, which produces the current shape and would drop
+ *  `workspaces` from a document it labels version 1. */
+export function migrateV0toV1(doc: Record<string, unknown>): Record<string, unknown> {
+  const raw = doc.mode === 'interstellar' ? 'dark' : doc.mode;
+  const mode = raw === 'light' || raw === 'dark' || raw === 'auto' ? raw : 'auto';
+  return {
+    version: 1,
+    workspaces: Array.isArray(doc.workspaces) ? doc.workspaces : [],
+    saves: Array.isArray(doc.saves) ? doc.saves : [],
+    layout: doc.layout && typeof doc.layout === 'object' ? doc.layout : {},
+    mode,
+  };
+}
+
+/** Version 1 to version 2: the vocabulary refresh renamed a tile from
+ *  workspace to trial. Only the records field moves; a record's own fields are
+ *  unchanged. */
+export function migrateV1toV2(doc: Record<string, unknown>): Record<string, unknown> {
+  const { workspaces, ...rest } = doc;
+  return { ...rest, trials: Array.isArray(workspaces) ? workspaces : [], version: 2 };
+}
+
+/** Index `i` migrates a version-`i` document to version `i + 1`. */
+export const MIGRATIONS: Migration[] = [migrateV0toV1, migrateV1toV2];