Persistence and sync

import { createPersistedEditor } from '@aionbuilders/nabu';

const engine = await createPersistedEditor({ docId: 'my-document' });

import 'fake-indexeddb/auto'; // tests only: a browser has IndexedDB
import { createPersistedEditor, DocumentPreset } from '@aionbuilders/nabu';

// A long debounce keeps the example free of timers: we save by hand.
const options = { docId: 'guide-quickstart', preset: DocumentPreset, debounce: 3_600_000 };

const first = await createPersistedEditor(options);
expect(first.isNew).toBe(true); // nothing was stored

await first.importMarkdown('# Notes\n\nSaved in the browser.');
await first.saveNow();
expect(first.persistence.status).toBe('saved');
first.persistence.dispose(); // as when the page goes away

// A later session restores it.
const second = await createPersistedEditor(options);
expect(second.isNew).toBe(false);
expect(second.serialize('markdown')).toBe('# Notes\n\nSaved in the browser.');
second.persistence.dispose();

<script>
  let { engine } = $props();
</script>

<span class="save-status" data-status={engine.persistence.status}>
  {engine.persistence.status}
</span>

<script>
  import { onDestroy } from 'svelte';
  import { NabuEditor, createPersistedEditor } from '@aionbuilders/nabu';

  let engine = $state(null);

  createPersistedEditor({ docId: 'article-draft' }).then((created) => {
    engine = created;
  });

  onDestroy(() => engine?.persistence.dispose());
</script>

{#if engine}
  <NabuEditor {engine} />
{/if}

import 'fake-indexeddb/auto';
import { createPersistedEditor, DocumentPreset } from '@aionbuilders/nabu';

const options = { docId: 'guide-clear', preset: DocumentPreset, debounce: 3_600_000 };

const engine = await createPersistedEditor(options);
await engine.importMarkdown('Throw me away');
await engine.saveNow();

await engine.clearPersistence();
engine.persistence.dispose();

const fresh = await createPersistedEditor(options);
expect(fresh.isNew).toBe(true);
fresh.persistence.dispose();

import 'fake-indexeddb/auto';
import { createPersistedEditor, DocumentPreset } from '@aionbuilders/nabu';

const options = { docId: 'guide-recover', preset: DocumentPreset, debounce: 3_600_000 };

// Two saves, so that a backup exists.
const a = await createPersistedEditor(options);
await a.importMarkdown('First version');
await a.saveNow();
await a.importMarkdown('Second version');
await a.saveNow();
a.persistence.dispose();

// Simulate a corrupted record (the storage layout is documented in the reference at the end of the page).
const db = await new Promise((resolve, reject) => {
  const request = indexedDB.open('nabu');
  request.onsuccess = () => resolve(request.result);
  request.onerror = () => reject(request.error);
});
await new Promise((resolve, reject) => {
  const tx = db.transaction('snapshots', 'readwrite');
  tx.objectStore('snapshots').put({ docId: options.docId, snapshot: new Uint8Array([1, 2, 3]), savedAt: Date.now() });
  tx.oncomplete = resolve;
  tx.onerror = () => reject(tx.error);
});
db.close();

let recovery = null;
const b = await createPersistedEditor({ ...options, onRecover: (info) => { recovery = info; } });

expect(recovery.kind).toBe('backup');            // restored from the previous save
expect(b.persistence.recovery).toBe(recovery);   // also kept on the instance
expect(recovery.quarantinedKey).toMatch(/^guide-recover@/);
expect(b.serialize('markdown')).toBe('First version');
b.persistence.dispose();

const engine = await createPersistedEditor({
  docId: 'article-draft',
  onSaveError: (error) => showToast('Your last changes are not saved yet.')
});

import 'fake-indexeddb/auto';
import { createPersistedEditor, DocumentPreset } from '@aionbuilders/nabu';

const options = { docId: 'guide-tabs', preset: DocumentPreset, debounce: 3_600_000, sync: false };

// A first session creates the document, so that both tabs start from the same history.
const seed = await createPersistedEditor(options);
await seed.importMarkdown('Shared');
await seed.saveNow();
seed.persistence.dispose();

const tabA = await createPersistedEditor(options);
const tabB = await createPersistedEditor(options);
expect(tabA.persistence.sync).toBe(false); // live sync is off here; the merge at save time is not

tabA.insert('paragraph', { text: 'written in A' });
await tabA.commit();
await tabA.saveNow();

tabB.insert('paragraph', { text: 'written in B' });
await tabB.commit();
await tabB.saveNow(); // merges what A stored, then writes

expect(tabB.serialize('markdown')).toContain('written in A');
expect(tabB.serialize('markdown')).toContain('written in B');

tabA.persistence.dispose();
tabB.persistence.dispose();

const reopened = await createPersistedEditor(options);
expect(reopened.serialize('markdown')).toContain('written in A');
expect(reopened.serialize('markdown')).toContain('written in B');
reopened.persistence.dispose();

// Default: the complete history. Nothing is ever compacted, trimmed or deleted.
await createPersistedEditor({ docId: 'book' }); // same as history: 'full'

// Opt-in: compact when the document is opened, keeping 30 days of history.
await createPersistedEditor({
  docId: 'notes',
  history: {
    mode: 'compact',
    retain: '30d',                              // ms, '12h', '30d', '2w'... or 0 = no past history
    onBeforeCompact: async (fullSnapshot) => {  // a Uint8Array: the COMPLETE snapshot
      await archive(fullSnapshot);              // if this throws, the compaction is cancelled
    }
  }
});

import 'fake-indexeddb/auto';
import { createPersistedEditor, DocumentPreset } from '@aionbuilders/nabu';

// A mistake in `history` fails loudly, before anything is read or written.
await expect(
  createPersistedEditor({ docId: 'guide-history', preset: DocumentPreset, history: { mode: 'compact' } })
).rejects.toThrow(/retain/);
await expect(
  createPersistedEditor({ docId: 'guide-history', preset: DocumentPreset, history: 'forever' })
).rejects.toThrow(/history/);

import 'fake-indexeddb/auto';
import { createPersistedEditor, DocumentPreset } from '@aionbuilders/nabu';

const engine = await createPersistedEditor({ docId: 'guide-compact', preset: DocumentPreset, debounce: 3_600_000 });
await engine.importMarkdown('Draft one');
await engine.saveNow();
await engine.importMarkdown('Draft two');

// Unsaved changes: refused, nothing was dropped.
const refused = await engine.compact({ retain: 0 });
expect(refused).toMatchObject({ compacted: false, reason: 'unsaved-changes' });

await engine.saveNow();
let archived = null;
const result = await engine.compact({ retain: 0, onBeforeCompact: (snapshot) => { archived = snapshot; } });

expect(result.compacted).toBe(true);
expect(archived).toBeInstanceOf(Uint8Array);         // the complete history, before anything was dropped
expect(result.bytesAfter).toBeLessThanOrEqual(result.bytesBefore);
expect(engine.serialize('markdown')).toBe('Draft two'); // the content is untouched
engine.persistence.dispose();

await createPersistedEditor({
  docId: 'article',
  history: { mode: 'compact', retain: '30d' },
  files: {
    onBeforePersist: async (file, { signal, onProgress }) => ({ ref: await uploadToMyServer(file, signal, onProgress) }),
    onAssetReleased: async (url) => { await deleteFromMyServer(url); }
  }
});

import { createDocumentEditor } from '@aionbuilders/nabu';

// Both peers start from the same history (a snapshot): independently created
// documents each have their own first paragraph.
const a = createDocumentEditor();
await a.importMarkdown('Hello');
const b = createDocumentEditor({ snapshot: a.doc.export({ mode: 'snapshot' }) });

// The "network": here, a direct call each way. Yours is a WebSocket, a fetch...
const stopA = a.doc.subscribeLocalUpdates((bytes) => b.importRemote(bytes));
const stopB = b.doc.subscribeLocalUpdates((bytes) => a.importRemote(bytes));

a.insert('paragraph', { text: 'from a' });
await a.commit();
b.insert('paragraph', { text: 'from b' });
await b.commit();
await new Promise((resolve) => setTimeout(resolve)); // Loro delivers events asynchronously

// Both converge, in the same order, whoever typed first.
expect(a.serialize('markdown')).toBe(b.serialize('markdown'));
expect(a.serialize('markdown')).toContain('from a');
expect(a.serialize('markdown')).toContain('from b');

stopA();
stopB();