create-syncular-app 0.1.3 → 0.2.0

package/template/web/src/frontend/main.ts

@@ -0,0 +1,191 @@
+/**
+ * A single-pane browser todo app: one client core syncing through the server.
+ *
+ * The WHOLE core runs in a Web Worker on a persistent opfs-sahpool database,
+ * driven through the `SyncClientHandle` RPC — the page only sends
+ * query/mutate/subscribe messages and re-renders. This is the real browser
+ * shape; grow your app from here.
+ *
+ * Open two browser windows on the same URL to watch them converge over the
+ * realtime socket. (One core per origin: a second TAB gets a clear not-leader
+ * error — multi-tab followers are a roadmap item. Separate windows/profiles or
+ * the two-window trick show convergence today.)
+ */
+import {
+  ClientSyncError,
+  createSyncClientHandle,
+  NOT_LEADER_CODE,
+  type SqlRow,
+} from '@syncular/client';
+import { schema, todoListSubscription } from '../syncular.generated';
+
+const LIST_ID = 'welcome';
+const WS_PROTO = location.protocol === 'https:' ? 'wss' : 'ws';
+
+interface Todo {
+  id: string;
+  list_id: string;
+  title: string;
+  done: number | boolean;
+  position: number;
+  updated_at_ms: number;
+}
+
+const statusEl = document.getElementById('status') as HTMLElement;
+const listEl = document.getElementById('todos') as HTMLUListElement;
+const outboxEl = document.getElementById('outbox') as HTMLElement;
+const form = document.getElementById('add-form') as HTMLFormElement;
+const input = document.getElementById('add-input') as HTMLInputElement;
+const offlineBtn = document.getElementById('offline-btn') as HTMLButtonElement;
+
+function setStatus(text: string): void {
+  statusEl.textContent = text;
+}
+
+async function main(): Promise<void> {
+  const handle = await createSyncClientHandle({
+    worker: () => new Worker('/worker.js', { type: 'module' }),
+    schema,
+    database: { mode: 'persistent', name: 'app' },
+    endpoints: {
+      syncUrl: '/sync',
+      segmentsUrl: '/segments',
+      realtimeUrl: `${WS_PROTO}://${location.host}/realtime?clientId={clientId}`,
+    },
+    autoSync: true,
+    lockName: 'app-core',
+    onSynced: () => void refresh(),
+  });
+
+  if (!handle.isLeader) {
+    throw new ClientSyncError(
+      NOT_LEADER_CODE,
+      'another tab already owns this app’s core — close it first ' +
+        '(multi-tab followers are a roadmap item).',
+    );
+  }
+
+  await handle.subscribe({
+    id: 'todos',
+    table: 'todos',
+    scopes: todoListSubscription.scopes({ listId: LIST_ID }),
+  });
+
+  // Connect-then-sync (§8.7 reference boot order): the first sync round rides
+  // the socket and registers this connection's subscriptions at round end.
+  try {
+    await handle.connectRealtime();
+  } catch {
+    // HTTP sync still works without the socket.
+  }
+  await handle.syncUntilIdle();
+  setStatus('in sync');
+  await refresh();
+
+  let offline = false;
+  offlineBtn.addEventListener('click', async () => {
+    offline = !offline;
+    await handle.setOffline(offline);
+    offlineBtn.textContent = offline ? 'Go online' : 'Go offline';
+    if (offline) {
+      setStatus('offline — edits queue in the outbox');
+    } else {
+      setStatus('back online — draining outbox…');
+      try {
+        await handle.connectRealtime();
+      } catch {
+        // socket optional
+      }
+      await handle.syncUntilIdle();
+      setStatus('in sync');
+    }
+    await refresh();
+  });
+
+  form.addEventListener('submit', async (event) => {
+    event.preventDefault();
+    const title = input.value.trim();
+    if (title === '') return;
+    input.value = '';
+    const rows = (await handle.query(
+      'SELECT position FROM todos ORDER BY position DESC LIMIT 1',
+    )) as SqlRow[];
+    const top = rows[0]?.position;
+    const position = (typeof top === 'number' ? top : 0) + 1;
+    await handle.mutate([
+      {
+        table: 'todos',
+        op: 'upsert',
+        values: {
+          id: crypto.randomUUID(),
+          list_id: LIST_ID,
+          title,
+          done: false,
+          position,
+          updated_at_ms: Date.now(),
+        },
+      },
+    ]);
+    if (!offline) await handle.syncUntilIdle();
+    await refresh();
+  });
+
+  async function refresh(): Promise<void> {
+    const rows = (await handle.query(
+      'SELECT * FROM todos ORDER BY position ASC, id ASC',
+    )) as unknown as Todo[];
+    const pending = (await handle.pendingCommits()).length;
+    outboxEl.textContent = `outbox ${pending}`;
+    listEl.replaceChildren(...rows.map((row) => renderRow(row)));
+
+    async function toggle(row: Todo): Promise<void> {
+      await handle.mutate([
+        {
+          table: 'todos',
+          op: 'upsert',
+          values: {
+            id: row.id,
+            list_id: row.list_id,
+            title: row.title,
+            done: !row.done,
+            position: row.position,
+            updated_at_ms: Date.now(),
+          },
+        },
+      ]);
+      if (!offline) await handle.syncUntilIdle();
+      await refresh();
+    }
+    async function remove(id: string): Promise<void> {
+      await handle.mutate([{ table: 'todos', op: 'delete', rowId: id }]);
+      if (!offline) await handle.syncUntilIdle();
+      await refresh();
+    }
+
+    function renderRow(row: Todo): HTMLLIElement {
+      const li = document.createElement('li');
+      if (row.done) li.classList.add('done');
+      const checkbox = document.createElement('input');
+      checkbox.type = 'checkbox';
+      checkbox.checked = Boolean(row.done);
+      checkbox.addEventListener('change', () => void toggle(row));
+      const title = document.createElement('span');
+      title.className = 'title';
+      title.textContent = row.title;
+      const del = document.createElement('button');
+      del.textContent = '×';
+      del.title = 'delete';
+      del.addEventListener('click', () => void remove(row.id));
+      li.append(checkbox, title, del);
+      return li;
+    }
+  }
+}
+
+void main().catch((error: unknown) => {
+  const message =
+    error instanceof ClientSyncError
+      ? `${error.code}: ${error.message}`
+      : String(error);
+  setStatus(`failed to start — ${message}`);
+});

package/template/web/src/frontend/worker.ts

@@ -0,0 +1,9 @@
+/**
+ * The sync worker: the whole client core (SyncClient + transports + sqlite-wasm
+ * on opfs-sahpool) runs here — the page only talks RPC. Built as its own
+ * bundle (`/worker.js`) because module workers do not inherit the page's import
+ * map.
+ */
+import { startSyncWorker } from '@syncular/client/worker';
+
+startSyncWorker();

package/template/web/src/server.ts

@@ -0,0 +1,183 @@
+/**
+ * The whole app in one Bun process:
+ * - POST /sync + GET /segments/:id via the server-hono adapter,
+ * - GET /realtime as a WebSocket wired to the server's RealtimeHub (§8.7),
+ * - the static frontend: TWO bundles built with Bun.build at startup —
+ *   /app.js (the page) and /worker.js (the sync worker running the whole
+ *   client core on opfs-sahpool). Module workers do not inherit the page's
+ *   import map, so the sqlite-wasm bare specifier is rewritten to the served
+ *   vendor path in both bundles.
+ *
+ * Storage is bun:sqlite (in-memory by default; set DB_PATH=path for a file).
+ *
+ * EDIT FIRST: `resolveScopes` + `authenticate` below are the whole
+ * authorization story — they run in YOUR backend next to YOUR auth.
+ */
+import { dirname, join } from 'node:path';
+import {
+  createRealtimeHub,
+  MemorySegmentStore,
+  type RealtimeSession,
+  SqliteServerStorage,
+  type SyncServerConfig,
+} from '@syncular/server';
+import { createSyncularHono } from '@syncular/server-hono';
+import { schema } from './syncular.generated';
+
+const PORT = Number(process.env.PORT ?? 8787);
+const PARTITION = 'demo';
+const ACTOR_ID = 'demo-user';
+
+// -- sync server ------------------------------------------------------------
+
+const storage = new SqliteServerStorage(process.env.DB_PATH ?? ':memory:');
+const segments = new MemorySegmentStore();
+/** Demo authorization: the single actor may see every list. Replace with the
+ * scope values the authenticated actor is allowed to see. */
+const resolveScopes = () => ({ list_id: ['*'] });
+
+const hub = createRealtimeHub({ schema, storage, resolveScopes, segments });
+const config: SyncServerConfig = {
+  schema,
+  storage,
+  segments,
+  resolveScopes,
+  realtime: hub,
+};
+const hono = createSyncularHono({
+  config,
+  // Replace with your real auth: return { actorId, partition } or null (401).
+  authenticate: async () => ({ actorId: ACTOR_ID, partition: PARTITION }),
+});
+
+// -- frontend build + static assets ------------------------------------------
+
+const build = await Bun.build({
+  entrypoints: [
+    join(import.meta.dir, 'frontend', 'main.ts'),
+    join(import.meta.dir, 'frontend', 'worker.ts'),
+  ],
+  target: 'browser',
+  sourcemap: 'inline',
+  external: ['@sqlite.org/sqlite-wasm'],
+});
+async function bundleText(basename: string): Promise<string> {
+  const artifact = build.outputs.find((output) =>
+    output.path.endsWith(`/${basename}`),
+  );
+  if (artifact === undefined) {
+    throw new Error(`frontend build produced no ${basename}`);
+  }
+  // Both bundles import sqlite-wasm from the served vendor path. An import map
+  // would only cover the page, never the module worker, so the external bare
+  // specifier is rewritten in the emitted JS instead.
+  const text = await artifact.text();
+  return text.replaceAll(
+    /(["'])@sqlite\.org\/sqlite-wasm\1/g,
+    '"/vendor/sqlite-wasm/index.mjs"',
+  );
+}
+const appJs = await bundleText('main.js');
+const workerJs = await bundleText('worker.js');
+const indexHtml = await Bun.file(
+  join(import.meta.dir, 'frontend', 'index.html'),
+).text();
+
+const wasmDir = dirname(
+  Bun.resolveSync('@sqlite.org/sqlite-wasm', import.meta.dir),
+);
+/** Only the files the sqlite-wasm ESM entry actually references. */
+const WASM_FILES: Record<string, string> = {
+  'index.mjs': 'text/javascript',
+  'sqlite3.wasm': 'application/wasm',
+  'sqlite3-opfs-async-proxy.js': 'text/javascript',
+  'sqlite3-worker1.mjs': 'text/javascript',
+};
+
+/** COOP/COEP so OPFS-capable contexts get cross-origin isolation (not
+ * required by opfs-sahpool, but harmless and future-proof). */
+const STATIC_HEADERS = {
+  'Cross-Origin-Opener-Policy': 'same-origin',
+  'Cross-Origin-Embedder-Policy': 'require-corp',
+  'Cache-Control': 'no-store',
+};
+
+function staticResponse(body: string | Uint8Array, type: string): Response {
+  return new Response(body as BodyInit, {
+    headers: { ...STATIC_HEADERS, 'Content-Type': type },
+  });
+}
+
+// -- one process, one port ----------------------------------------------------
+
+interface SocketData {
+  clientId: string;
+  session?: RealtimeSession;
+}
+
+const server = Bun.serve<SocketData, never>({
+  port: PORT,
+  async fetch(request, bunServer) {
+    const url = new URL(request.url);
+    const path = url.pathname;
+
+    if (path === '/realtime') {
+      const clientId = url.searchParams.get('clientId') ?? crypto.randomUUID();
+      if (bunServer.upgrade(request, { data: { clientId } })) {
+        return undefined as unknown as Response;
+      }
+      return new Response('expected a websocket upgrade', { status: 400 });
+    }
+    if (path === '/sync' || path.startsWith('/segments/')) {
+      return hono.fetch(request);
+    }
+    if (path === '/' || path === '/index.html') {
+      return staticResponse(indexHtml, 'text/html; charset=utf-8');
+    }
+    if (path === '/app.js') {
+      return staticResponse(appJs, 'text/javascript; charset=utf-8');
+    }
+    if (path === '/worker.js') {
+      return staticResponse(workerJs, 'text/javascript; charset=utf-8');
+    }
+    if (path.startsWith('/vendor/sqlite-wasm/')) {
+      const name = path.slice('/vendor/sqlite-wasm/'.length);
+      const type = WASM_FILES[name];
+      if (type !== undefined) {
+        const bytes = await Bun.file(join(wasmDir, name)).bytes();
+        return staticResponse(bytes, type);
+      }
+    }
+    return new Response('not found', { status: 404 });
+  },
+  websocket: {
+    open(ws) {
+      hub
+        .connect({
+          partition: PARTITION,
+          actorId: ACTOR_ID,
+          clientId: ws.data.clientId,
+          send: (data) => {
+            ws.send(data);
+          },
+          closeSocket: () => ws.close(1008, 'protocol violation (§8.7)'),
+        })
+        .then((session) => {
+          ws.data.session = session;
+        })
+        .catch(() => ws.close(1011, 'realtime connect failed'));
+    },
+    message(ws, message) {
+      if (typeof message === 'string') {
+        ws.data.session?.handleMessage(message);
+      } else {
+        ws.data.session?.handleBinary(new Uint8Array(message));
+      }
+    },
+    close(ws) {
+      ws.data.session?.close();
+    },
+  },
+});
+
+console.log(`app: http://localhost:${server.port}`);

package/template/web/src/smoke.test.ts

@@ -0,0 +1,91 @@
+/**
+ * The web template's smoke test. The browser frontend (worker + OPFS) can't
+ * run headless in `bun test`, so this proves the piece that CAN rot silently:
+ * the server config + generated schema this scaffold ships actually sync. It
+ * boots the same server core config as `src/server.ts` on an ephemeral port
+ * and drives two bun:sqlite client cores through real HTTP to convergence.
+ *
+ * The frontend itself is covered by `tsc` (typecheck) and by the demo app /
+ * conformance suite in the syncular tree, which exercise the identical
+ * worker + OPFS + realtime path.
+ */
+import { afterAll, beforeAll, expect, test } from 'bun:test';
+import {
+  httpSegmentDownloader,
+  httpSyncTransport,
+  SyncClient,
+} from '@syncular/client';
+import { openBunDatabase } from '@syncular/client/bun';
+import {
+  MemorySegmentStore,
+  SqliteServerStorage,
+  type SyncServerConfig,
+} from '@syncular/server';
+import { createSyncularHono } from '@syncular/server-hono';
+import { schema, todoListSubscription } from './syncular.generated';
+
+let server: ReturnType<typeof Bun.serve>;
+let baseUrl: string;
+
+beforeAll(() => {
+  const config: SyncServerConfig = {
+    schema,
+    storage: new SqliteServerStorage(':memory:'),
+    segments: new MemorySegmentStore(),
+    resolveScopes: () => ({ list_id: ['*'] }),
+  };
+  const app = createSyncularHono({
+    config,
+    authenticate: async () => ({ actorId: 'demo-user', partition: 'demo' }),
+  });
+  server = Bun.serve({ port: 0, fetch: app.fetch });
+  baseUrl = `http://localhost:${server.port}`;
+});
+
+afterAll(() => {
+  server.stop(true);
+});
+
+function makeClient(clientId: string): SyncClient {
+  return new SyncClient({
+    database: openBunDatabase(),
+    schema,
+    clientId,
+    transport: httpSyncTransport(`${baseUrl}/sync`),
+    segments: httpSegmentDownloader(`${baseUrl}/segments`),
+  });
+}
+
+test('two clients converge through the scaffolded server config', async () => {
+  const a = makeClient('client-a');
+  const b = makeClient('client-b');
+  await a.start();
+  await b.start();
+
+  const scopes = todoListSubscription.scopes({ listId: 'welcome' });
+  a.subscribe({ id: 'todos', table: 'todos', scopes });
+  b.subscribe({ id: 'todos', table: 'todos', scopes });
+
+  a.mutate([
+    {
+      table: 'todos',
+      op: 'upsert',
+      values: {
+        id: 'todo-1',
+        list_id: 'welcome',
+        title: 'Buy milk',
+        done: false,
+        position: 1,
+        updated_at_ms: Date.now(),
+      },
+    },
+  ]);
+  await a.syncUntilIdle();
+  await b.syncUntilIdle();
+
+  const rows = b.query('SELECT id, title, done FROM todos ORDER BY id');
+  expect(rows).toEqual([{ id: 'todo-1', title: 'Buy milk', done: 0 }]);
+
+  await a.close();
+  await b.close();
+});

package/template/web/src/syncular.generated.ts

@@ -0,0 +1,74 @@
+// Generated by @syncular/typegen — DO NOT EDIT.
+// irVersion: 1
+// irHash: sha256:2ffc5b70cb96cd546326de9c06868bd988c9fa3459fb3bac8428a81dcc85fca0
+
+/** ServerSchema-compatible schema object (SPEC §2.4, §3.1). */
+export const schema = {
+  version: 1,
+  tables: [
+    {
+      name: 'todos',
+      columns: [
+        { name: 'id', type: 'string', nullable: false },
+        { name: 'list_id', type: 'string', nullable: false },
+        { name: 'title', type: 'string', nullable: false },
+        { name: 'done', type: 'boolean', nullable: false },
+        { name: 'position', type: 'integer', nullable: false },
+        { name: 'updated_at_ms', type: 'integer', nullable: false },
+      ],
+      primaryKey: 'id',
+      scopes: [
+        { pattern: 'list:{list_id}', column: 'list_id' },
+      ],
+    },
+  ],
+} as const;
+
+/** One todos row (§2.4 column order). */
+export interface TodosRow {
+  id: string;
+  list_id: string;
+  title: string;
+  done: boolean;
+  position: number;
+  updated_at_ms: number;
+}
+
+/** Insert shape: nullable columns may be omitted. */
+export interface TodosInsert {
+  id: string;
+  list_id: string;
+  title: string;
+  done: boolean;
+  position: number;
+  updated_at_ms: number;
+}
+
+/** Update shape: primary key required, all other columns optional. */
+export interface TodosUpdate {
+  id: string;
+  list_id?: string;
+  title?: string;
+  done?: boolean;
+  position?: number;
+  updated_at_ms?: number;
+}
+
+/** Kysely `Database` interface (table → Row); the generic for
+ *  @syncular/kysely's SyncularDialect. */
+export interface Database {
+  todos: TodosRow;
+}
+
+export interface TodoListParams {
+  listId: string;
+}
+
+/** Requested-scope template for the 'todoList' subscription. */
+export const todoListSubscription = {
+  name: 'todoList',
+  table: 'todos',
+  scopes: (params: TodoListParams): Record<string, string[]> => ({
+    list_id: [params.listId],
+  }),
+} as const;

package/template/web/syncular.ir.json

@@ -0,0 +1,76 @@
+{
+  "irVersion": 1,
+  "schemaVersion": 1,
+  "schemaVersions": [
+    {
+      "version": 1,
+      "migrations": [
+        "0001_initial"
+      ]
+    }
+  ],
+  "tables": [
+    {
+      "name": "todos",
+      "primaryKey": "id",
+      "columns": [
+        {
+          "name": "id",
+          "type": "string",
+          "nullable": false
+        },
+        {
+          "name": "list_id",
+          "type": "string",
+          "nullable": false
+        },
+        {
+          "name": "title",
+          "type": "string",
+          "nullable": false
+        },
+        {
+          "name": "done",
+          "type": "boolean",
+          "nullable": false
+        },
+        {
+          "name": "position",
+          "type": "integer",
+          "nullable": false
+        },
+        {
+          "name": "updated_at_ms",
+          "type": "integer",
+          "nullable": false
+        }
+      ],
+      "scopes": [
+        {
+          "pattern": "list:{list_id}",
+          "variable": "list_id",
+          "column": "list_id"
+        }
+      ],
+      "extensions": {}
+    }
+  ],
+  "subscriptions": [
+    {
+      "name": "todoList",
+      "table": "todos",
+      "scopes": [
+        {
+          "variable": "list_id",
+          "values": [
+            {
+              "kind": "parameter",
+              "name": "listId"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "extensions": {}
+}

package/template/web/syncular.json

@@ -0,0 +1,17 @@
+{
+  "manifestVersion": 1,
+  "migrations": "./migrations",
+  "output": {
+    "ir": "./syncular.ir.json",
+    "module": "./src/syncular.generated.ts"
+  },
+  "schemaVersions": [{ "version": 1, "through": "0001_initial" }],
+  "tables": [{ "name": "todos", "scopes": ["list:{list_id}"] }],
+  "subscriptions": [
+    {
+      "name": "todoList",
+      "table": "todos",
+      "scopes": { "list_id": ["{listId}"] }
+    }
+  ]
+}

package/template/web/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "types": ["bun"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}