@strata-sync/next 0.1.0

package/src/bootstrap.ts

@@ -0,0 +1,624 @@
+import type { StorageAdapter } from "@strata-sync/client";
+import type {
+  BootstrapMetadata,
+  ModelRegistrySnapshot,
+  ModelRow,
+  SchemaDefinition,
+} from "@strata-sync/core";
+import {
+  computeSchemaHash,
+  getOrCreateClientId,
+  ModelRegistry,
+} from "@strata-sync/core";
+
+const DEFAULT_PREFETCH_TIMEOUT_MS = 10_000;
+const NDJSON_ACCEPT_HEADER = "application/x-ndjson";
+const TRAILING_SLASH_RE = /\/+$/;
+const KNOWN_SYNC_SUFFIXES = ["/bootstrap", "/batch", "/deltas"];
+
+export interface BootstrapSnapshot {
+  version: 1;
+  schemaHash: string;
+  lastSyncId: number;
+  firstSyncId?: number;
+  groups: string[];
+  rows: ModelRow[];
+  fetchedAt: number;
+  rowCount?: number;
+}
+
+export interface PrefetchBootstrapOptions {
+  endpoint: string;
+  authorization?: string;
+  headers?: Record<string, string>;
+  models?: string[];
+  groups?: string[];
+  schemaHash?: string;
+  timeout?: number;
+}
+
+export async function prefetchBootstrap(
+  options: PrefetchBootstrapOptions
+): Promise<BootstrapSnapshot> {
+  const {
+    endpoint,
+    authorization,
+    headers,
+    models,
+    groups,
+    schemaHash,
+    timeout = DEFAULT_PREFETCH_TIMEOUT_MS,
+  } = options;
+
+  const requestHeaders = buildRequestHeaders(authorization, headers);
+  const params = buildBootstrapParams({ models, groups, schemaHash });
+  const url = buildBootstrapUrl(endpoint, params);
+
+  const response = await fetchBootstrap(url, requestHeaders, timeout);
+  await ensureResponseOk(response);
+
+  const { rows, metadata, rowCount } = await readBootstrapStream(
+    getResponseBody(response)
+  );
+
+  const resolvedMetadata = ensureBootstrapMetadata(metadata);
+  const snapshotSchemaHash = resolveSnapshotSchemaHash(
+    resolvedMetadata,
+    schemaHash
+  );
+
+  return {
+    version: 1,
+    schemaHash: snapshotSchemaHash,
+    lastSyncId: resolvedMetadata.lastSyncId,
+    firstSyncId: resolveFirstSyncId(resolvedMetadata),
+    groups: resolvedMetadata.subscribedSyncGroups,
+    rows,
+    fetchedAt: Date.now(),
+    rowCount,
+  };
+}
+
+function buildRequestHeaders(
+  authorization?: string,
+  headers?: Record<string, string>
+): Record<string, string> {
+  const requestHeaders: Record<string, string> = {
+    Accept: NDJSON_ACCEPT_HEADER,
+    ...headers,
+  };
+
+  if (authorization) {
+    requestHeaders.Authorization = authorization;
+  }
+
+  return requestHeaders;
+}
+
+function buildBootstrapParams(options: {
+  models?: string[];
+  groups?: string[];
+  schemaHash?: string;
+}): URLSearchParams {
+  const params = new URLSearchParams();
+  params.set("type", "full");
+
+  if (options.models?.length) {
+    params.set("onlyModels", options.models.join(","));
+  }
+  if (options.schemaHash) {
+    params.set("schemaHash", options.schemaHash);
+  }
+  if (options.groups?.length) {
+    params.set("syncGroups", options.groups.join(","));
+  }
+
+  return params;
+}
+
+function buildBootstrapUrl(endpoint: string, params: URLSearchParams): string {
+  const baseEndpoint = normalizeSyncEndpoint(endpoint);
+  const url = joinSyncUrl(baseEndpoint, "/bootstrap");
+  return `${url}?${params.toString()}`;
+}
+
+async function fetchBootstrap(
+  url: string,
+  headers: Record<string, string>,
+  timeout: number
+): Promise<Response> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    return await fetch(url, {
+      method: "GET",
+      headers,
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+async function ensureResponseOk(response: Response): Promise<void> {
+  if (response.ok) {
+    return;
+  }
+
+  const text = await response.text();
+  throw new Error(`Bootstrap prefetch failed: ${response.status} ${text}`);
+}
+
+function getResponseBody(response: Response): ReadableStream<Uint8Array> {
+  if (!response.body) {
+    throw new Error("Bootstrap prefetch response has no body");
+  }
+  return response.body;
+}
+
+interface BootstrapParseResult {
+  rows: ModelRow[];
+  metadata: BootstrapMetadata | null;
+  rowCount?: number;
+}
+
+interface BootstrapParseState extends BootstrapParseResult {
+  buffer: string;
+}
+
+async function readBootstrapStream(
+  stream: ReadableStream<Uint8Array>
+): Promise<BootstrapParseResult> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  const state: BootstrapParseState = {
+    rows: [],
+    metadata: null,
+    rowCount: undefined,
+    buffer: "",
+  };
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+
+      state.buffer += decoder.decode(value, { stream: true });
+      state.buffer = drainBootstrapLines(state, state.buffer);
+    }
+
+    flushBootstrapBuffer(state);
+  } finally {
+    reader.releaseLock();
+  }
+
+  return {
+    rows: state.rows,
+    metadata: state.metadata,
+    rowCount: state.rowCount,
+  };
+}
+
+function drainBootstrapLines(
+  state: BootstrapParseState,
+  buffer: string
+): string {
+  const lines = buffer.split("\n");
+  const remaining = lines.pop() ?? "";
+
+  for (const line of lines) {
+    applyBootstrapLine(state, line);
+  }
+
+  return remaining;
+}
+
+function flushBootstrapBuffer(state: BootstrapParseState): void {
+  const trimmed = state.buffer.trim();
+  if (!trimmed) {
+    return;
+  }
+  applyBootstrapLine(state, trimmed);
+}
+
+function applyBootstrapLine(state: BootstrapParseState, line: string): void {
+  const parsed = parseBootstrapLine(line);
+  if (!parsed) {
+    return;
+  }
+
+  if (parsed.type === "meta") {
+    state.metadata = parsed.metadata;
+    return;
+  }
+
+  if (parsed.type === "row") {
+    state.rows.push(parsed.row);
+    return;
+  }
+
+  state.rowCount = parsed.rowCount;
+}
+
+interface ValidatedBootstrapMetadata extends BootstrapMetadata {
+  lastSyncId: number;
+}
+
+function ensureBootstrapMetadata(
+  metadata: BootstrapMetadata | null
+): ValidatedBootstrapMetadata {
+  if (!metadata) {
+    throw new Error("Bootstrap prefetch did not receive metadata");
+  }
+  if (metadata.lastSyncId === undefined) {
+    throw new Error("Bootstrap metadata is missing lastSyncId");
+  }
+  return metadata as ValidatedBootstrapMetadata;
+}
+
+function resolveSnapshotSchemaHash(
+  metadata: BootstrapMetadata,
+  fallback?: string
+): string {
+  return metadata.schemaHash ?? fallback ?? "";
+}
+
+function resolveFirstSyncId(metadata: ValidatedBootstrapMetadata): number {
+  return typeof metadata.raw?.firstSyncId === "number"
+    ? metadata.raw.firstSyncId
+    : metadata.lastSyncId;
+}
+
+export interface BootstrapSnapshotPayload {
+  version: 1;
+  encoding: "json" | "gzip-base64";
+  data: string;
+}
+
+export interface SerializeBootstrapOptions {
+  compress?: boolean;
+}
+
+export async function serializeBootstrapSnapshot(
+  snapshot: BootstrapSnapshot,
+  options: SerializeBootstrapOptions = {}
+): Promise<BootstrapSnapshotPayload> {
+  const json = JSON.stringify(snapshot);
+  const shouldCompress =
+    options.compress !== false && canUseCompressionStreams();
+
+  if (!shouldCompress) {
+    return {
+      version: snapshot.version,
+      encoding: "json",
+      data: json,
+    };
+  }
+
+  const compressed = await compressToBase64(json);
+  return {
+    version: snapshot.version,
+    encoding: "gzip-base64",
+    data: compressed,
+  };
+}
+
+export async function deserializeBootstrapSnapshot(
+  payload: BootstrapSnapshotPayload
+): Promise<BootstrapSnapshot> {
+  if (payload.version !== 1) {
+    throw new Error(
+      `Unsupported bootstrap payload version: ${payload.version}`
+    );
+  }
+
+  if (payload.encoding === "json") {
+    return JSON.parse(payload.data) as BootstrapSnapshot;
+  }
+
+  if (!canUseCompressionStreams()) {
+    throw new Error("DecompressionStream is not available in this runtime");
+  }
+
+  const json = await decompressFromBase64(payload.data);
+  return JSON.parse(json) as BootstrapSnapshot;
+}
+
+export async function encodeBootstrapSnapshot(
+  snapshot: BootstrapSnapshot,
+  options: SerializeBootstrapOptions = {}
+): Promise<string> {
+  const payload = await serializeBootstrapSnapshot(snapshot, options);
+  return JSON.stringify(payload);
+}
+
+export function decodeBootstrapSnapshot(
+  encoded: string
+): Promise<BootstrapSnapshot> {
+  const payload = JSON.parse(encoded) as BootstrapSnapshotPayload;
+  return deserializeBootstrapSnapshot(payload);
+}
+
+export function isBootstrapSnapshotStale(
+  snapshot: BootstrapSnapshot,
+  maxAge = 30_000
+): boolean {
+  return Date.now() - snapshot.fetchedAt > maxAge;
+}
+
+export interface SeedStorageOptions {
+  storage: StorageAdapter;
+  snapshot: BootstrapSnapshot | BootstrapSnapshotPayload | string;
+  dbName?: string;
+  clearExisting?: boolean;
+  validateSchemaHash?: boolean;
+  batchSize?: number;
+  closeAfter?: boolean;
+  schema?: SchemaDefinition | ModelRegistrySnapshot;
+}
+
+export interface SeedStorageResult {
+  applied: boolean;
+  rowCount: number;
+  reason?: "schema_mismatch";
+}
+
+export async function seedStorageFromBootstrap(
+  options: SeedStorageOptions
+): Promise<SeedStorageResult> {
+  const {
+    storage,
+    snapshot,
+    dbName = "sync-db",
+    clearExisting = true,
+    validateSchemaHash = true,
+    batchSize = 500,
+    closeAfter = true,
+    schema,
+  } = options;
+
+  const resolvedSnapshot = await resolveSnapshot(snapshot);
+  const localSchemaHash = computeSchemaHash(schema ?? ModelRegistry.snapshot());
+
+  if (
+    validateSchemaHash &&
+    resolvedSnapshot.schemaHash &&
+    resolvedSnapshot.schemaHash !== localSchemaHash
+  ) {
+    return { applied: false, rowCount: 0, reason: "schema_mismatch" };
+  }
+
+  let opened = false;
+
+  try {
+    await storage.open({ name: dbName, schema });
+    opened = true;
+
+    const existingMeta = await storage.getMeta();
+    const clientId =
+      existingMeta.clientId || getOrCreateClientId(`${dbName}_client_id`);
+
+    if (clearExisting) {
+      await storage.clear();
+    }
+
+    let ops: Array<{
+      type: "put";
+      modelName: string;
+      data: Record<string, unknown>;
+    }> = [];
+
+    for (const row of resolvedSnapshot.rows) {
+      ops.push({ type: "put", modelName: row.modelName, data: row.data });
+
+      if (ops.length >= batchSize) {
+        await storage.writeBatch(ops);
+        ops = [];
+      }
+    }
+
+    if (ops.length > 0) {
+      await storage.writeBatch(ops);
+    }
+
+    await storage.setMeta({
+      schemaHash: localSchemaHash,
+      lastSyncId: resolvedSnapshot.lastSyncId,
+      firstSyncId: resolvedSnapshot.firstSyncId,
+      subscribedSyncGroups: resolvedSnapshot.groups,
+      bootstrapComplete: true,
+      lastSyncAt: resolvedSnapshot.fetchedAt,
+      clientId,
+    });
+
+    return { applied: true, rowCount: resolvedSnapshot.rows.length };
+  } finally {
+    if (closeAfter && opened) {
+      await storage.close();
+    }
+  }
+}
+
+function isPayload(
+  value: BootstrapSnapshot | BootstrapSnapshotPayload | string
+): value is BootstrapSnapshotPayload {
+  return typeof value === "object" && value !== null && "encoding" in value;
+}
+
+function resolveSnapshot(
+  snapshot: BootstrapSnapshot | BootstrapSnapshotPayload | string
+): Promise<BootstrapSnapshot> {
+  if (typeof snapshot === "string") {
+    const parsed = JSON.parse(snapshot) as BootstrapSnapshotPayload;
+    return deserializeBootstrapSnapshot(parsed);
+  }
+
+  if (isPayload(snapshot)) {
+    return deserializeBootstrapSnapshot(snapshot);
+  }
+
+  return Promise.resolve(snapshot);
+}
+
+function canUseCompressionStreams(): boolean {
+  return (
+    typeof CompressionStream !== "undefined" &&
+    typeof DecompressionStream !== "undefined"
+  );
+}
+
+async function compressToBase64(input: string): Promise<string> {
+  const compressedStream = new Blob([input])
+    .stream()
+    .pipeThrough(new CompressionStream("gzip"));
+  const buffer = await new Response(compressedStream).arrayBuffer();
+  return toBase64(new Uint8Array(buffer));
+}
+
+function decompressFromBase64(encoded: string): Promise<string> {
+  const bytes = fromBase64(encoded);
+  const decompressedStream = new Blob([bytes as BlobPart])
+    .stream()
+    .pipeThrough(new DecompressionStream("gzip"));
+  return new Response(decompressedStream).text();
+}
+
+function toBase64(bytes: Uint8Array): string {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+function fromBase64(encoded: string): Uint8Array {
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(encoded, "base64"));
+  }
+
+  const binary = atob(encoded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+type ParsedBootstrapLine =
+  | { type: "meta"; metadata: BootstrapMetadata }
+  | { type: "row"; row: ModelRow }
+  | { type: "end"; rowCount?: number };
+
+function parseBootstrapLine(line: string): ParsedBootstrapLine | null {
+  const trimmed = line.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  if (trimmed.startsWith("_metadata_=")) {
+    const raw = JSON.parse(trimmed.slice("_metadata_=".length)) as Record<
+      string,
+      unknown
+    >;
+    return { type: "meta", metadata: normalizeBootstrapMetadata(raw) };
+  }
+
+  const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+
+  if (typeof parsed._metadata_ === "object" && parsed._metadata_ !== null) {
+    return {
+      type: "meta",
+      metadata: normalizeBootstrapMetadata(
+        parsed._metadata_ as Record<string, unknown>
+      ),
+    };
+  }
+
+  if (isBootstrapMetadata(parsed)) {
+    return { type: "meta", metadata: normalizeBootstrapMetadata(parsed) };
+  }
+
+  if (parsed.type === "end") {
+    return {
+      type: "end",
+      rowCount:
+        typeof parsed.rowCount === "number" ? parsed.rowCount : undefined,
+    };
+  }
+
+  if (typeof parsed.__class !== "string") {
+    throw new Error("Bootstrap row is missing __class");
+  }
+
+  const { __class: modelName, ...data } = parsed;
+  return {
+    type: "row",
+    row: { modelName, data },
+  };
+}
+
+function isBootstrapMetadata(parsed: Record<string, unknown>): boolean {
+  return (
+    "lastSyncId" in parsed ||
+    "subscribedSyncGroups" in parsed ||
+    "returnedModelsCount" in parsed
+  );
+}
+
+function normalizeBootstrapMetadata(
+  parsed: Record<string, unknown>
+): BootstrapMetadata {
+  const lastSyncIdRaw = parsed.lastSyncId;
+  const subscribedSyncGroupsRaw = parsed.subscribedSyncGroups;
+
+  const subscribedSyncGroups = Array.isArray(subscribedSyncGroupsRaw)
+    ? subscribedSyncGroupsRaw.filter(
+        (group): group is string => typeof group === "string"
+      )
+    : [];
+
+  const result: BootstrapMetadata = {
+    subscribedSyncGroups,
+    returnedModelsCount:
+      parsed.returnedModelsCount &&
+      typeof parsed.returnedModelsCount === "object"
+        ? (parsed.returnedModelsCount as Record<string, number>)
+        : undefined,
+    schemaHash:
+      typeof parsed.schemaHash === "string" ? parsed.schemaHash : undefined,
+    databaseVersion:
+      typeof parsed.databaseVersion === "number"
+        ? parsed.databaseVersion
+        : undefined,
+    raw: parsed,
+  };
+
+  if (typeof lastSyncIdRaw === "string" || typeof lastSyncIdRaw === "number") {
+    result.lastSyncId = Number(lastSyncIdRaw);
+  }
+
+  return result;
+}
+
+function normalizeSyncEndpoint(endpoint: string): string {
+  const trimmed = endpoint.replace(TRAILING_SLASH_RE, "");
+  for (const suffix of KNOWN_SYNC_SUFFIXES) {
+    if (trimmed.endsWith(suffix)) {
+      return trimmed.slice(0, -suffix.length);
+    }
+  }
+  return trimmed;
+}
+
+function joinSyncUrl(base: string, path: string): string {
+  const normalizedBase = base.replace(TRAILING_SLASH_RE, "");
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `${normalizedBase}${normalizedPath}`;
+}

package/src/client.ts

@@ -0,0 +1,38 @@
+"use client";
+
+// biome-ignore lint/performance/noBarrelFile: This is the package's public client-side API entry point
+export {
+  useConnectionState,
+  useIsOffline,
+  useModel,
+  useModelSuspense,
+  usePendingCount,
+  useQuery,
+  useQueryAll,
+  useQueryCount,
+  useSync,
+  useSyncClient,
+  useSyncClientInstance,
+  useSyncReady,
+  useSyncState,
+} from "@strata-sync/react";
+export type {
+  BootstrapSnapshot,
+  BootstrapSnapshotPayload,
+  SeedStorageOptions,
+  SeedStorageResult,
+} from "./bootstrap";
+export {
+  decodeBootstrapSnapshot,
+  deserializeBootstrapSnapshot,
+  isBootstrapSnapshotStale,
+  seedStorageFromBootstrap,
+} from "./bootstrap";
+export type {
+  PrefetchedData,
+  PrefetchOptions,
+  PrefetchResult,
+} from "./prefetch";
+export { deserializePrefetchResult, isPrefetchStale } from "./prefetch";
+export type { NextSyncProviderProps } from "./provider";
+export { NextSyncProvider, withSyncProvider } from "./provider";

package/src/index.ts

@@ -0,0 +1,45 @@
+// biome-ignore-all lint/performance/noBarrelFile: This is the package's main entry point
+export type {
+  BootstrapSnapshot,
+  BootstrapSnapshotPayload,
+  NextSyncProviderProps,
+  PrefetchedData,
+  PrefetchOptions,
+  PrefetchResult,
+  SeedStorageOptions,
+  SeedStorageResult,
+} from "./client";
+export {
+  decodeBootstrapSnapshot,
+  deserializeBootstrapSnapshot,
+  deserializePrefetchResult,
+  isBootstrapSnapshotStale,
+  isPrefetchStale,
+  NextSyncProvider,
+  seedStorageFromBootstrap,
+  useConnectionState,
+  useIsOffline,
+  useModel,
+  useModelSuspense,
+  usePendingCount,
+  useQuery,
+  useQueryAll,
+  useQueryCount,
+  useSync,
+  useSyncClient,
+  useSyncClientInstance,
+  useSyncReady,
+  useSyncState,
+  withSyncProvider,
+} from "./client";
+export type {
+  PrefetchBootstrapOptions,
+  SerializeBootstrapOptions,
+} from "./server";
+export {
+  encodeBootstrapSnapshot,
+  prefetchBootstrap,
+  prefetchModels,
+  serializeBootstrapSnapshot,
+  serializePrefetchResult,
+} from "./server";