Collaboration and offline work

import {
  createGridFromSnapshot,
  SyncCoordinator,
  type PersistenceAdapter,
  type RemoteOperationSource,
} from "@sheetwrite/core";

const documentId = "workbook-42";
const snapshot = await persistenceAdapter.load(documentId);
const grid = createGridFromSnapshot(document.querySelector("#grid")!, snapshot);
const sync = new SyncCoordinator(grid, persistenceAdapter, {
  documentId,
  serverVersion: snapshot.version ?? 0,
});

sync.on((event) => {
  if (event.type === "acknowledged") {
    console.log(`server version ${event.version} acknowledged ${event.clientMutationId}`);
  } else if (event.type === "conflict") {
    console.error("conflict retained for host recovery", event.mutation);
  }
});

await sync.ready();
const unsubscribeRemote = sync.subscribe(remoteOperationSource);

saveButton.addEventListener("click", () => {
  void sync.flush(); // sends in order; each response acknowledges only its mutation ID
});

// Teardown:
// unsubscribeRemote();
// sync.destroy();
// grid.destroy();

import type {
  PersistenceAdapter,
  PersistenceCommitRequest,
  PersistenceCommitResponse,
  WorkbookSnapshot,
} from "@sheetwrite/core";

async function responseJson<T>(response: Response): Promise<T> {
  if (!response.ok) throw new Error(`Persistence request failed: ${response.status}`);
  return (await response.json()) as T;
}

const persistenceAdapter: PersistenceAdapter = {
  async load(documentId, signal) {
    const response = await fetch(`/api/documents/${encodeURIComponent(documentId)}`, { signal });
    return responseJson<WorkbookSnapshot>(response);
  },
  async commit(request: PersistenceCommitRequest) {
    const { signal, ...body } = request;
    const response = await fetch(
      `/api/documents/${encodeURIComponent(request.documentId)}/operations`,
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify(body),
        signal,
      },
    );
    return responseJson<PersistenceCommitResponse>(response);
  },
};

documents(
  document_id       primary key,
  current_version   integer not null,
  snapshot_version  integer not null,
  snapshot_json     json not null
)

document_operations(
  document_id        not null,
  version            integer not null,
  client_mutation_id text not null,
  operations_json    json not null,
  created_at         server_timestamp not null,
  primary key(document_id, version),
  unique(document_id, client_mutation_id)
)

import { SyncCoordinator } from "@sheetwrite/core";
import { IndexedDbPendingCommitStorage } from "@sheetwrite/core/browser";

const pendingStorage = new IndexedDbPendingCommitStorage({
  databaseName: "my-product-sheetwrite",
});

const sync = new SyncCoordinator(grid, persistenceAdapter, {
  documentId: "workbook-42",
  serverVersion: snapshot.version ?? 0,
  pendingStorage,
  initialConnection: navigator.onLine ? "online" : "offline",
});

await sync.ready();
window.addEventListener("online", () => sync.setOnline(true));
window.addEventListener("offline", () => sync.setOnline(false));

import {
  createGridFromSnapshot,
  rebaseDocumentOperations,
  SyncCoordinator,
  type Grid,
  type PersistenceCommitResponse,
} from "@sheetwrite/core";

type ConflictResponse = Extract<PersistenceCommitResponse, { status: "conflict" }>;
interface SyncSession {
  grid: Grid;
  sync: SyncCoordinator;
  unsubscribeRemote: () => void;
}

async function reloadAfterConflict(
  session: SyncSession,
  response: ConflictResponse,
): Promise<SyncSession> {
  if (!response.operationsSinceBase) {
    console.error("Manual conflict review required: server did not return an operation tail");
    return session;
  }

  const pending = session.sync.pendingCommits();
  const remoteOperations = response.operationsSinceBase.flatMap((entry) => [
    ...entry.operations,
  ]);
  const safeBatches: Array<ReturnType<typeof rebaseDocumentOperations> & {
    status: "rebased";
  }> = [];

  for (const record of pending) {
    const result = rebaseDocumentOperations(record.operations, remoteOperations);
    if (result.status === "conflict") {
      console.error("Manual conflict review required", result.conflict);
      return session; // old queue and grid remain intact
    }
    safeBatches.push(result);
  }

  const latest = response.snapshot ?? (await persistenceAdapter.load(documentId));
  for (const record of pending) {
    await pendingStorage.remove(documentId, record.clientMutationId);
  }

  session.unsubscribeRemote();
  session.sync.destroy();
  session.grid.destroy();

  const grid = createGridFromSnapshot(document.querySelector("#grid")!, latest);
  const sync = new SyncCoordinator(grid, persistenceAdapter, {
    documentId,
    serverVersion: latest.version ?? 0,
    pendingStorage,
  });
  await sync.ready(); // the stale IDs were removed before hydration

  for (const batch of safeBatches) {
    const outcome = grid.applyTransaction({ patches: [...batch.operations] });
    if (outcome.status !== "applied") {
      throw new Error(`Rebased local transaction was not applied: ${outcome.status}`);
    }
  }

  const unsubscribeRemote = sync.subscribe(remoteOperationSource);
  await sync.flush();
  return { grid, sync, unsubscribeRemote };
}