@strata-sync/next 0.1.0

package/src/prefetch.ts

@@ -0,0 +1,155 @@
+/**
+ * Prefetch utilities for Next.js Server Components
+ *
+ * Note: The sync engine is primarily designed for client-side usage.
+ * These utilities allow pre-fetching data on the server to pass as
+ * initial state to the client, reducing time-to-interactive.
+ */
+
+export interface PrefetchedData {
+  modelName: string;
+  data: Record<string, unknown>[];
+  fetchedAt: number;
+}
+
+export interface PrefetchResult {
+  data: Map<string, PrefetchedData>;
+  success: boolean;
+  error?: string;
+}
+
+export interface PrefetchOptions {
+  endpoint: string;
+  authorization?: string;
+  /** Models to prefetch */
+  models: Array<{
+    name: string;
+    filter?: Record<string, unknown>;
+    limit?: number;
+  }>;
+  timeout?: number;
+}
+
+/**
+ * Prefetches model data on the server
+ *
+ * This can be used in Server Components to pre-fetch data
+ * that will be passed to the client as initial state.
+ *
+ * @example
+ * ```tsx
+ * // app/dashboard/page.tsx
+ * import { prefetchModels } from '@strata-sync/next/server';
+ *
+ * export default async function DashboardPage() {
+ *   const prefetchedData = await prefetchModels({
+ *     endpoint: process.env.API_URL + '/sync/prefetch',
+ *     authorization: await getServerAuth(),
+ *     models: [
+ *       { name: 'Project', limit: 10 },
+ *       { name: 'Task', filter: { status: 'active' }, limit: 50 },
+ *     ],
+ *   });
+ *
+ *   return (
+ *     <SyncClientProvider initialData={prefetchedData}>
+ *       <Dashboard />
+ *     </SyncClientProvider>
+ *   );
+ * }
+ * ```
+ */
+export async function prefetchModels(
+  options: PrefetchOptions
+): Promise<PrefetchResult> {
+  const { endpoint, authorization, models, timeout = 5000 } = options;
+
+  const result: PrefetchResult = {
+    data: new Map(),
+    success: true,
+  };
+
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    if (authorization) {
+      headers.Authorization = authorization;
+    }
+
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ models }),
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      throw new Error(`Prefetch failed: ${response.status}`);
+    }
+
+    const json = (await response.json()) as {
+      data: Array<{
+        modelName: string;
+        rows: Record<string, unknown>[];
+      }>;
+    };
+
+    for (const item of json.data) {
+      result.data.set(item.modelName, {
+        modelName: item.modelName,
+        data: item.rows,
+        fetchedAt: Date.now(),
+      });
+    }
+  } catch (err) {
+    result.success = false;
+    result.error = err instanceof Error ? err.message : String(err);
+  }
+
+  return result;
+}
+
+/**
+ * Serializes prefetch result for passing through Server Component boundary
+ */
+export function serializePrefetchResult(result: PrefetchResult): string {
+  return JSON.stringify({
+    data: Array.from(result.data.entries()),
+    success: result.success,
+    error: result.error,
+  });
+}
+
+/**
+ * Deserializes prefetch result on the client
+ */
+export function deserializePrefetchResult(serialized: string): PrefetchResult {
+  const parsed = JSON.parse(serialized) as {
+    data: [string, PrefetchedData][];
+    success: boolean;
+    error?: string;
+  };
+
+  return {
+    data: new Map(parsed.data),
+    success: parsed.success,
+    error: parsed.error,
+  };
+}
+
+/**
+ * Checks if prefetched data is stale
+ */
+export function isPrefetchStale(
+  prefetched: PrefetchedData,
+  maxAge = 30_000
+): boolean {
+  return Date.now() - prefetched.fetchedAt > maxAge;
+}

package/src/provider.tsx

@@ -0,0 +1,156 @@
+"use client";
+
+import type { SyncClient } from "@strata-sync/client";
+import { SyncProvider as BaseSyncProvider } from "@strata-sync/react";
+import { type ReactNode, useEffect, useState } from "react";
+
+/**
+ * Props for the Next.js sync provider
+ */
+export interface NextSyncProviderProps {
+  /** Sync client instance or factory function */
+  client: SyncClient | (() => SyncClient);
+  /** Children to render */
+  children: ReactNode;
+  /** Loading component to show while client initializes */
+  loading?: ReactNode;
+  /** Error component to show if initialization fails */
+  error?: (error: Error) => ReactNode;
+  /** Callback when client is ready */
+  onReady?: () => void;
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Next.js App Router compatible sync provider
+ *
+ * This provider:
+ * - Only renders on the client (uses 'use client' directive)
+ * - Handles client initialization lifecycle
+ * - Provides loading and error states
+ *
+ * @example
+ * ```tsx
+ * // app/providers.tsx
+ * 'use client';
+ *
+ * import { NextSyncProvider } from '@strata-sync/next';
+ * import { createSyncClient } from '@strata-sync/client';
+ * import { createIndexedDbStorage } from '@strata-sync/storage-idb';
+ * import { createGraphQLTransport } from '@strata-sync/transport-graphql';
+ * import { createMobXReactivity } from '@strata-sync/mobx';
+ * import { schema } from './schema';
+ *
+ * const client = createSyncClient({
+ *   schema,
+ *   storage: createIndexedDbStorage(),
+ *   transport: createGraphQLTransport({
+ *     endpoint: 'https://api.example.com/graphql',
+ *     syncEndpoint: 'https://api.example.com/sync',
+ *     wsEndpoint: 'wss://api.example.com/sync',
+ *     auth: {
+ *       getAccessToken: async () => 'token',
+ *     },
+ *     mutationBuilder: (tx) => ({
+ *       mutation: `issueUpdate(id: "${tx.modelId}", input: $input) { syncId }`,
+ *       variables: { input: tx.payload },
+ *       variableTypes: { input: 'IssueUpdateInput!' },
+ *     }),
+ *   }),
+ *   reactivity: createMobXReactivity(),
+ * });
+ *
+ * export function Providers({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <NextSyncProvider
+ *       client={client}
+ *       loading={<div>Loading...</div>}
+ *     >
+ *       {children}
+ *     </NextSyncProvider>
+ *   );
+ * }
+ * ```
+ */
+export function NextSyncProvider({
+  client,
+  children,
+  loading = null,
+  error: errorComponent,
+  onReady,
+  onError,
+}: NextSyncProviderProps): ReactNode {
+  const [syncClient, setSyncClient] = useState<SyncClient | null>(null);
+  const [isInitializing, setIsInitializing] = useState(true);
+  const [initError, setInitError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    let mounted = true;
+
+    const initClient = async () => {
+      try {
+        const resolvedClient = typeof client === "function" ? client() : client;
+
+        await resolvedClient.start();
+
+        if (mounted) {
+          setSyncClient(resolvedClient);
+          setIsInitializing(false);
+          onReady?.();
+        }
+      } catch (err) {
+        if (mounted) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          setInitError(error);
+          setIsInitializing(false);
+          onError?.(error);
+        }
+      }
+    };
+
+    initClient();
+
+    return () => {
+      mounted = false;
+      // Note: We don't stop the client on unmount as it might be reused
+    };
+  }, [client, onReady, onError]);
+
+  if (isInitializing) {
+    return <>{loading}</>;
+  }
+
+  if (initError) {
+    if (errorComponent) {
+      return <>{errorComponent(initError)}</>;
+    }
+    throw initError; // Let error boundary handle it
+  }
+
+  if (!syncClient) {
+    return null;
+  }
+
+  return (
+    <BaseSyncProvider autoStart={false} autoStop={false} client={syncClient}>
+      {children}
+    </BaseSyncProvider>
+  );
+}
+
+/**
+ * HOC to wrap a component with the sync provider
+ */
+export function withSyncProvider<P extends object>(
+  Component: React.ComponentType<P>,
+  providerProps: Omit<NextSyncProviderProps, "children">
+): React.ComponentType<P> {
+  return function WrappedComponent(props: P) {
+    return (
+      <NextSyncProvider {...providerProps}>
+        <Component {...props} />
+      </NextSyncProvider>
+    );
+  };
+}

package/src/server.ts

@@ -0,0 +1,29 @@
+// biome-ignore-all lint/performance/noBarrelFile: This is the package's public server-side API entry point
+export type {
+  BootstrapSnapshot,
+  BootstrapSnapshotPayload,
+  PrefetchBootstrapOptions,
+  SeedStorageOptions,
+  SeedStorageResult,
+  SerializeBootstrapOptions,
+} from "./bootstrap";
+export {
+  decodeBootstrapSnapshot,
+  deserializeBootstrapSnapshot,
+  encodeBootstrapSnapshot,
+  isBootstrapSnapshotStale,
+  prefetchBootstrap,
+  seedStorageFromBootstrap,
+  serializeBootstrapSnapshot,
+} from "./bootstrap";
+export type {
+  PrefetchedData,
+  PrefetchOptions,
+  PrefetchResult,
+} from "./prefetch";
+export {
+  deserializePrefetchResult,
+  isPrefetchStale,
+  prefetchModels,
+  serializePrefetchResult,
+} from "./prefetch";

package/tests/bootstrap.test.ts

@@ -0,0 +1,377 @@
+import type { StorageAdapter, StorageMeta } from "@strata-sync/client";
+import type {
+  ModelRegistrySnapshot,
+  SchemaDefinition,
+  SyncAction,
+  Transaction,
+} from "@strata-sync/core";
+import { computeSchemaHash } from "@strata-sync/core";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  decodeBootstrapSnapshot,
+  deserializeBootstrapSnapshot,
+  encodeBootstrapSnapshot,
+  isBootstrapSnapshotStale,
+  prefetchBootstrap,
+  seedStorageFromBootstrap,
+  serializeBootstrapSnapshot,
+} from "../src/bootstrap";
+
+interface BatchOp {
+  type: "put" | "delete";
+  modelName: string;
+  id?: string;
+  data?: Record<string, unknown>;
+}
+
+class MemoryStorage implements StorageAdapter {
+  meta: StorageMeta;
+  opened = false;
+  closed = false;
+  cleared = false;
+  openOptions: {
+    name?: string;
+    userId?: string;
+    version?: number;
+    userVersion?: number;
+    schema?: SchemaDefinition | ModelRegistrySnapshot;
+  } | null = null;
+  batches: BatchOp[][] = [];
+
+  constructor(meta: StorageMeta) {
+    this.meta = meta;
+  }
+
+  open(options: {
+    name?: string;
+    userId?: string;
+    version?: number;
+    userVersion?: number;
+    schema?: SchemaDefinition | ModelRegistrySnapshot;
+  }): Promise<void> {
+    this.opened = true;
+    this.openOptions = options;
+    return Promise.resolve();
+  }
+
+  close(): Promise<void> {
+    this.closed = true;
+    return Promise.resolve();
+  }
+
+  get<T>(_modelName: string, _id: string): Promise<T | null> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  getAll<T>(_modelName: string): Promise<T[]> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  put<T extends Record<string, unknown>>(
+    _modelName: string,
+    _row: T
+  ): Promise<void> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  delete(_modelName: string, _id: string): Promise<void> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  getByIndex<T>(
+    _modelName: string,
+    _indexName: string,
+    _key: string
+  ): Promise<T[]> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  writeBatch(ops: BatchOp[]): Promise<void> {
+    this.batches.push(ops);
+    return Promise.resolve();
+  }
+
+  getMeta(): Promise<StorageMeta> {
+    return Promise.resolve(this.meta);
+  }
+
+  setMeta(meta: Partial<StorageMeta>): Promise<void> {
+    this.meta = { ...this.meta, ...meta };
+    return Promise.resolve();
+  }
+
+  getModelPersistence(
+    _modelName: string
+  ): ReturnType<StorageAdapter["getModelPersistence"]> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  setModelPersistence(_modelName: string, _persisted: boolean): Promise<void> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  getOutbox(): Promise<Transaction[]> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  addToOutbox(_tx: Transaction): Promise<void> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  removeFromOutbox(_clientTxId: string): Promise<void> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  updateOutboxTransaction(
+    _clientTxId: string,
+    _updates: Partial<Transaction>
+  ): Promise<void> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  hasPartialIndex(
+    _modelName: string,
+    _indexedKey: string,
+    _keyValue: string
+  ): Promise<boolean> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  setPartialIndex(
+    _modelName: string,
+    _indexedKey: string,
+    _keyValue: string
+  ): Promise<void> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  addSyncActions(_actions: SyncAction[]): Promise<void> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  getSyncActions(
+    _afterSyncId?: number,
+    _limit?: number
+  ): Promise<SyncAction[]> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  clearSyncActions(): Promise<void> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+
+  clear(): Promise<void> {
+    this.cleared = true;
+    return Promise.resolve();
+  }
+
+  count(_modelName: string): Promise<number> {
+    return Promise.reject(new Error("Not implemented"));
+  }
+}
+
+const encoder = new TextEncoder();
+
+function createNdjsonResponse(lines: string[], status = 200): Response {
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const line of lines) {
+        controller.enqueue(encoder.encode(`${line}\n`));
+      }
+      controller.close();
+    },
+  });
+
+  return new Response(stream, { status });
+}
+
+function stubFetch(lines: string[], status = 200) {
+  const fetchMock = vi
+    .fn()
+    .mockResolvedValue(createNdjsonResponse(lines, status));
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+describe("prefetchBootstrap", () => {
+  it("uses firstSyncId from metadata and normalizes lastSyncId", async () => {
+    const metadataLine = JSON.stringify({
+      _metadata_: {
+        lastSyncId: "101",
+        firstSyncId: 99,
+        subscribedSyncGroups: ["alpha"],
+      },
+    });
+
+    stubFetch([metadataLine]);
+
+    const snapshot = await prefetchBootstrap({
+      endpoint: "https://api.example.com/sync",
+      schemaHash: "schema-from-option",
+    });
+
+    expect(snapshot.lastSyncId).toBe(101);
+    expect(snapshot.firstSyncId).toBe(99);
+    expect(snapshot.schemaHash).toBe("schema-from-option");
+  });
+
+  it("throws when metadata is missing", async () => {
+    const rowLine = JSON.stringify({ __class: "Issue", id: "issue-1" });
+    stubFetch([rowLine]);
+
+    await expect(
+      prefetchBootstrap({ endpoint: "https://api.example.com/sync" })
+    ).rejects.toThrow("Bootstrap prefetch did not receive metadata");
+  });
+
+  it("normalizes sync endpoints and query params", async () => {
+    const rowLine = JSON.stringify({ __class: "Issue", id: "issue-1" });
+    const metadataLine = `_metadata_=${JSON.stringify({
+      lastSyncId: 1,
+      subscribedSyncGroups: [],
+    })}`;
+    const endLine = JSON.stringify({ type: "end", rowCount: 1 });
+
+    const endpoints = [
+      "https://api.example.com/sync",
+      "https://api.example.com/sync/bootstrap",
+      "https://api.example.com/sync/batch",
+      "https://api.example.com/sync/deltas",
+    ];
+
+    for (const endpoint of endpoints) {
+      const fetchMock = stubFetch([rowLine, metadataLine, endLine]);
+
+      await prefetchBootstrap({
+        endpoint,
+        models: ["Issue", "Project"],
+        groups: ["group-a", "group-b"],
+        schemaHash: "schema-hash",
+      });
+
+      const url = new URL(fetchMock.mock.calls[0][0] as string);
+      expect(url.pathname).toBe("/sync/bootstrap");
+      expect(url.searchParams.get("type")).toBe("full");
+      expect(url.searchParams.get("onlyModels")).toBe("Issue,Project");
+      expect(url.searchParams.get("syncGroups")).toBe("group-a,group-b");
+      expect(url.searchParams.get("schemaHash")).toBe("schema-hash");
+    }
+  });
+});
+
+describe("bootstrap snapshot utilities", () => {
+  it("roundtrips snapshot payloads without compression", async () => {
+    const snapshot = {
+      version: 1,
+      schemaHash: "schema-hash",
+      lastSyncId: 10,
+      firstSyncId: 5,
+      groups: ["group-a"],
+      rows: [{ modelName: "Issue", data: { id: "issue-1" } }],
+      fetchedAt: 1_700_000_000_000,
+      rowCount: 1,
+    };
+
+    const payload = await serializeBootstrapSnapshot(snapshot, {
+      compress: false,
+    });
+    expect(payload.encoding).toBe("json");
+
+    const parsed = await deserializeBootstrapSnapshot(payload);
+    expect(parsed).toEqual(snapshot);
+
+    const encoded = await encodeBootstrapSnapshot(snapshot, {
+      compress: false,
+    });
+    const decoded = await decodeBootstrapSnapshot(encoded);
+    expect(decoded).toEqual(snapshot);
+  });
+
+  it("flags stale snapshots using maxAge", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2025-01-01T00:00:30.000Z"));
+
+    const snapshot = {
+      version: 1 as const,
+      schemaHash: "schema-hash",
+      lastSyncId: 10,
+      groups: [],
+      rows: [],
+      fetchedAt: Date.now() - 31_000,
+    };
+
+    expect(isBootstrapSnapshotStale(snapshot, 30_000)).toBe(true);
+  });
+});
+
+describe("seedStorageFromBootstrap", () => {
+  it("short-circuits on schema mismatch", async () => {
+    const schema: SchemaDefinition = { models: { Issue: { name: "Issue" } } };
+    const storage = new MemoryStorage({ lastSyncId: 0, clientId: "client-1" });
+
+    const result = await seedStorageFromBootstrap({
+      storage,
+      schema,
+      snapshot: {
+        version: 1,
+        schemaHash: "mismatched",
+        lastSyncId: 1,
+        groups: [],
+        rows: [],
+        fetchedAt: 1,
+      },
+    });
+
+    const localSchemaHash = computeSchemaHash(schema);
+    expect(localSchemaHash).not.toBe("mismatched");
+    expect(result).toEqual({
+      applied: false,
+      rowCount: 0,
+      reason: "schema_mismatch",
+    });
+    expect(storage.opened).toBe(false);
+  });
+
+  it("writes rows and metadata when schema matches", async () => {
+    const schema: SchemaDefinition = { models: { Issue: { name: "Issue" } } };
+    const schemaHash = computeSchemaHash(schema);
+    const storage = new MemoryStorage({ lastSyncId: 0, clientId: "client-1" });
+
+    const result = await seedStorageFromBootstrap({
+      storage,
+      schema,
+      batchSize: 2,
+      snapshot: {
+        version: 1,
+        schemaHash,
+        lastSyncId: 10,
+        firstSyncId: 4,
+        groups: ["group-a"],
+        rows: [
+          { modelName: "Issue", data: { id: "issue-1" } },
+          { modelName: "Issue", data: { id: "issue-2" } },
+          { modelName: "Issue", data: { id: "issue-3" } },
+        ],
+        fetchedAt: 1_700_000_000_000,
+      },
+    });
+
+    expect(result).toEqual({ applied: true, rowCount: 3 });
+    expect(storage.opened).toBe(true);
+    expect(storage.cleared).toBe(true);
+    expect(storage.batches.length).toBe(2);
+    expect(storage.meta.schemaHash).toBe(schemaHash);
+    expect(storage.meta.lastSyncId).toBe(10);
+    expect(storage.meta.firstSyncId).toBe(4);
+    expect(storage.meta.subscribedSyncGroups).toEqual(["group-a"]);
+    expect(storage.meta.bootstrapComplete).toBe(true);
+    expect(storage.meta.lastSyncAt).toBe(1_700_000_000_000);
+    expect(storage.meta.clientId).toBe("client-1");
+    expect(storage.closed).toBe(true);
+  });
+});