create-syncular-app 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-syncular-app",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Scaffold a new Syncular app: `create-syncular-app`",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -49,6 +49,6 @@
     "!dist/**/*.test.d.ts"
   ],
   "devDependencies": {
-    "@syncular/typegen": "0.3.1"
+    "@syncular/typegen": "0.5.0"
   }
 }

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

@@ -2,6 +2,20 @@
 // irVersion: 1
 // irHash: sha256:e2e39c94ce6c13720e1f1579e2523d460fd6bb3fea2f8eaaa114305b7aa332ba
 
+/** Structural descriptor consumed by renderer bindings; phantom type
+ * fields make row/insert/update/id inference available without imports. */
+export interface SyncTable<Row, Insert, Update, Id> {
+  readonly name: string;
+  /** Language-facing key used in generated row and mutation types. */
+  readonly primaryKey: keyof Row & string;
+  /** Physical SQLite/wire primary-key column. */
+  readonly physicalPrimaryKey: string;
+  readonly __row?: Row;
+  readonly __insert?: Insert;
+  readonly __update?: Update;
+  readonly __id?: Id;
+}
+
 /** ServerSchema-compatible schema object (SPEC §2.4, §3.1). */
 export const schema = {
   version: 1,
@@ -46,6 +60,13 @@ export interface NotesUpdate {
   updatedAtMs?: number;
 }
 
+/** Typed mutation/resource descriptor for 'notes'. */
+export const notesTable: SyncTable<NotesRow, NotesInsert, NotesUpdate, string> = {
+  name: 'notes',
+  primaryKey: 'id',
+  physicalPrimaryKey: 'id',
+};
+
 export interface NotesInListParams {
   listId: string;
 }

package/template/tauri/README.md

@@ -46,8 +46,8 @@ Prerequisites: [Rust](https://rustup.rs) and the
 
 | File | What it is |
 |---|---|
-| `syncular.json` + `migrations/` | The schema manifest and SQL — typegen's input |
-| `src/syncular.generated.ts` | Generated by `syncular generate` (committed) |
+| `syncular.json` + `migrations/` + `queries/` | Schema and named-query inputs |
+| `src/syncular.generated.ts` + `src/syncular.queries.ts` | Generated descriptors (committed) |
 | `src/server.ts` | Sync server + WebSocket + the web frontend, one Bun process |
 | `src/frontend/engine.ts` | **The seam**: picks worker core vs native core |
 | `src/frontend/main.tsx` | The shared React tree (host-agnostic) |
@@ -63,7 +63,9 @@ dynamic-imports either `createTauriSyncClient` (`@syncular/tauri` — an RPC
 bridge to the native core the plugin hosts) or `createSyncClientHandle`
 (`@syncular/client` — the worker core on OPFS). Both satisfy the one
 structural interface the hooks target, `SyncClientLike`, so a single
-`<SyncProvider>` serves both hosts. The dynamic imports keep each host's
+async client resource and `<SyncProvider>` serve both hosts. Both cores own and
+persist client identity; app code has no localStorage identity mirror. The
+dynamic imports keep each host's
 machinery out of the other's bundle.
 
 On desktop, the plugin owns the database path and the transport — see

package/template/tauri/queries/list-todos.syql

@@ -0,0 +1,6 @@
+query listTodos(listId) {
+  select id, list_id, title, done, position, updated_at_ms
+  from todos
+  where list_id = :listId
+  order by position, id
+}

package/template/tauri/src/frontend/engine.ts

@@ -23,15 +23,9 @@ import { schema } from '../syncular.generated';
 
 /**
  * What the app gets back: the hook surface (`SyncClientLike`) plus the
- * lifecycle both concrete clients share — enough for the boot sequence in
- * `main.tsx`, still fully host-agnostic.
+ * lifecycle both concrete clients share, still fully host-agnostic.
  */
 export interface Engine extends SyncClientLike {
-  subscribe(input: {
-    readonly id: string;
-    readonly table: string;
-    readonly scopes: Record<string, readonly string[]>;
-  }): Promise<unknown>;
   connectRealtime(): Promise<void>;
   close(): Promise<void>;
 }
@@ -39,21 +33,11 @@ export interface Engine extends SyncClientLike {
 /** Tauri v2 injects this into every webview it hosts. */
 const isTauri = () => '__TAURI_INTERNALS__' in window;
 
-/** A stable per-browser client id (the native side persists its own db). */
-function clientId(): string {
-  const KEY = 'syncular-client-id';
-  const existing = localStorage.getItem(KEY);
-  if (existing !== null) return existing;
-  const id = crypto.randomUUID();
-  localStorage.setItem(KEY, id);
-  return id;
-}
-
 export async function createEngine(): Promise<Engine> {
   if (isTauri()) {
     // Desktop: the native Rust core in the Tauri process.
     const { createTauriSyncClient } = await import('@syncular/tauri');
-    return createTauriSyncClient({ clientId: clientId(), schema });
+    return createTauriSyncClient({ schema });
   }
   // Web: the whole core in a worker, persisted on OPFS.
   const { createSyncClientHandle } = await import('@syncular/client');
@@ -61,7 +45,6 @@ export async function createEngine(): Promise<Engine> {
   return createSyncClientHandle({
     worker: () => new Worker('/worker.js', { type: 'module' }),
     schema,
-    clientId: clientId(),
     database: { mode: 'persistent', name: 'app' },
     endpoints: {
       syncUrl: '/sync',

package/template/tauri/src/frontend/main.tsx

@@ -4,21 +4,22 @@
  * the Tauri webview it talks to the native Rust core in the host process.
  * The only host-aware code is `createEngine()` in `./engine.ts`.
  *
- * - `useRawSql` — the live todo list; re-runs exactly when `todos`
- *   invalidates.
- * - `useMutation` — add / toggle / delete; writes go through the outbox.
+ * - generated `useQuery` — exact dependencies, coverage, revision and row key.
+ * - typed `useMutation` — add / toggle / delete through the outbox.
  * - `useSyncStatus` — outbox depth + upgrading / schema-floor badges.
  */
 import {
+  createSyncClientResource,
   SyncProvider,
   useMutation,
-  useRawSql,
+  useQuery,
   useSyncStatus,
 } from '@syncular/react';
-import { StrictMode, useEffect, useState } from 'react';
+import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import { type TodosRow, todoListSubscription } from '../syncular.generated';
-import { createEngine, type Engine } from './engine';
+import { todosTable } from '../syncular.generated';
+import { type ListTodosRow, listTodosQuery } from '../syncular.queries';
+import { createEngine } from './engine';
 
 const LIST_ID = 'welcome';
 
@@ -41,47 +42,33 @@ function StatusLine() {
 }
 
 function TodoApp() {
-  const { mutate, isPending, error } = useMutation();
-
-  // Live local read: re-runs exactly when `todos` invalidates.
-  const { rows, isLoading } = useRawSql<TodosRow>(
-    'SELECT id, list_id AS listId, title, done, position,' +
-      ' updated_at_ms AS updatedAtMs FROM todos WHERE list_id = ?' +
-      ' ORDER BY position, id',
-    [LIST_ID],
-  );
+  const mutation = useMutation(todosTable);
+
+  const todos = useQuery(listTodosQuery, { listId: LIST_ID });
+  const { rows } = todos;
 
   const add = (title: string) => {
     const position =
       rows.reduce((max, row) => Math.max(max, row.position), 0) + 1;
-    void mutate([
-      {
-        table: 'todos',
-        op: 'upsert',
-        values: {
-          id: crypto.randomUUID(),
-          listId: LIST_ID,
-          title,
-          done: false,
-          position,
-          updatedAtMs: Date.now(),
-        },
-      },
-    ]);
+    void mutation.upsert({
+      id: crypto.randomUUID(),
+      listId: LIST_ID,
+      title,
+      done: false,
+      position,
+      updatedAtMs: Date.now(),
+    });
   };
 
-  const toggle = (row: TodosRow) => {
-    void mutate([
-      {
-        table: 'todos',
-        op: 'upsert',
-        values: { ...row, done: !row.done, updatedAtMs: Date.now() },
-      },
-    ]);
+  const toggle = (row: ListTodosRow) => {
+    void mutation.patch(row.id, {
+      done: !row.done,
+      updatedAtMs: Date.now(),
+    });
   };
 
   const remove = (id: string) => {
-    void mutate([{ table: 'todos', op: 'delete', rowId: id }]);
+    void mutation.remove(id);
   };
 
   return (
@@ -105,19 +92,21 @@ function TodoApp() {
         }}
       >
         <input name="title" placeholder="a new todo" autoComplete="off" />
-        <button type="submit" disabled={isPending}>
+        <button type="submit" disabled={mutation.isPending}>
           add
         </button>
       </form>
 
       {/* Always render the write error: a dead worker/bridge RPC otherwise
           fails silently and "add does nothing" is undebuggable. */}
-      {error !== undefined ? (
-        <div className="error">write failed: {String(error)}</div>
+      {mutation.error !== undefined ? (
+        <div className="error">write failed: {mutation.error.message}</div>
       ) : null}
 
-      {isLoading ? (
+      {todos.phase === 'loading' ? (
         <div className="empty">loading…</div>
+      ) : todos.phase === 'error' ? (
+        <div className="empty">query failed: {todos.error?.message}</div>
       ) : rows.length === 0 ? (
         <div className="empty">no todos yet — add one</div>
       ) : (
@@ -152,42 +141,25 @@ function TodoApp() {
   );
 }
 
-function Root() {
-  const [engine, setEngine] = useState<Engine | undefined>(undefined);
-  const [error, setError] = useState<string | undefined>(undefined);
-
-  useEffect(() => {
-    let live: Engine | undefined;
-    void createEngine()
-      .then(async (e) => {
-        live = e;
-        await e.subscribe({
-          id: 'todos',
-          table: 'todos',
-          scopes: todoListSubscription.scopes({ listId: LIST_ID }),
-        });
-        // Ride the socket for realtime; HTTP sync still works without it.
-        try {
-          await e.connectRealtime();
-        } catch {
-          // offline / no socket — the host loop keeps syncing over HTTP
-        }
-        setEngine(e);
-      })
-      .catch((err: unknown) => setError(String(err)));
-    return () => {
-      void live?.close();
-    };
-  }, []);
-
-  if (error !== undefined) {
-    return <div className="empty">failed to start: {error}</div>;
-  }
-  if (engine === undefined) {
-    return <div className="empty">starting client core…</div>;
+const engineResource = createSyncClientResource(async () => {
+  const engine = await createEngine();
+  try {
+    await engine.connectRealtime();
+  } catch {
+    // offline / no socket — the host loop keeps syncing over HTTP
   }
+  return engine;
+});
+
+function Root() {
   return (
-    <SyncProvider client={engine}>
+    <SyncProvider
+      client={engineResource}
+      fallback={<div className="empty">starting client core…</div>}
+      renderError={(error) => (
+        <div className="empty">failed to start: {error.message}</div>
+      )}
+    >
       <TodoApp />
     </SyncProvider>
   );

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

@@ -2,6 +2,20 @@
 // irVersion: 1
 // irHash: sha256:2ffc5b70cb96cd546326de9c06868bd988c9fa3459fb3bac8428a81dcc85fca0
 
+/** Structural descriptor consumed by renderer bindings; phantom type
+ * fields make row/insert/update/id inference available without imports. */
+export interface SyncTable<Row, Insert, Update, Id> {
+  readonly name: string;
+  /** Language-facing key used in generated row and mutation types. */
+  readonly primaryKey: keyof Row & string;
+  /** Physical SQLite/wire primary-key column. */
+  readonly physicalPrimaryKey: string;
+  readonly __row?: Row;
+  readonly __insert?: Insert;
+  readonly __update?: Update;
+  readonly __id?: Id;
+}
+
 /** ServerSchema-compatible schema object (SPEC §2.4, §3.1). */
 export const schema = {
   version: 1,
@@ -54,6 +68,13 @@ export interface TodosUpdate {
   updatedAtMs?: number;
 }
 
+/** Typed mutation/resource descriptor for 'todos'. */
+export const todosTable: SyncTable<TodosRow, TodosInsert, TodosUpdate, string> = {
+  name: 'todos',
+  primaryKey: 'id',
+  physicalPrimaryKey: 'id',
+};
+
 export interface TodoListParams {
   listId: string;
 }

package/template/tauri/src/syncular.queries.ts

@@ -0,0 +1,99 @@
+// Generated by @syncular/typegen — DO NOT EDIT.
+// irVersion: 1
+// irHash: sha256:4c2d58e50c85edd5a15aa6d61f2195b802e90b9056fc3cea17ceddb6ea37d0e7
+
+/** A bindable SQL param/row value (the wrapper's SqlValue subset). */
+export type QueryValue =
+  | string
+  | number
+  | bigint
+  | boolean
+  | Uint8Array
+  | null;
+
+/** Minimal structural client surface — the wrapper's positional
+ *  `query(sql, params?)`. `SyncClient`/`SyncClientHandle`/`SyncClientLike`
+ *  all satisfy it, so this module imports nothing. */
+export interface QueryClient {
+  query(
+    sql: string,
+    params?: readonly QueryValue[],
+  ): unknown[] | Promise<unknown[]>;
+}
+
+/** A named-query descriptor — checked SQL plus revisioned reactive metadata and a
+ *  `bind(params)` → positional args. Consumed by
+ *  `@syncular/react`'s `useQuery`. `Row` is the projection row
+ *  type; `Params` is `undefined` for a param-less query. `sqlFor`
+ *  (present only with an orderBy knob) composes the statement from a
+ *  generate-time-checked column allowlist. */
+export interface NamedQuery<Row, Params = undefined> {
+  readonly id: string;
+  readonly hasParams: boolean;
+  readonly sql: string;
+  readonly tables: readonly string[];
+  readonly bind: (params: Params) => readonly QueryValue[];
+  readonly sqlFor?: (params: Params) => string;
+  readonly dependencies: (params: Params) => readonly QueryDependency[];
+  readonly coverage: (params: Params) => readonly WindowCoverage[];
+  readonly rowKey?: (row: Row) => readonly QueryValue[];
+  /** Phantom — carries the Row type for `useQuery` inference. */
+  readonly __row?: Row;
+}
+
+export interface QueryDependency {
+  readonly table: string;
+  readonly scopeKeys?: readonly string[];
+}
+
+export interface WindowCoverage {
+  readonly base: {
+    readonly table: string;
+    readonly variable: string;
+    readonly fixedScopes?: Readonly<Record<string, readonly string[]>>;
+    readonly params?: string;
+  };
+  readonly units: readonly string[];
+}
+
+/** One row of the 'listTodos' query (its projection). */
+export interface ListTodosRow {
+  id: string;
+  listId: string;
+  title: string;
+  done: boolean;
+  position: number;
+  updatedAtMs: number;
+}
+
+/** Named parameters for 'listTodos'. */
+export interface ListTodosParams {
+  listId: string;
+}
+
+/** Tables 'listTodos' reads (compatibility/export surface). */
+export const listTodosTables = ['todos'] as const;
+
+const listTodosSql = 'select id, list_id AS listId, title, done, position, updated_at_ms AS updatedAtMs from todos where list_id = ? order by position, id';
+
+/** Run the 'listTodos' named query (SELECT-only). */
+export async function listTodos(client: QueryClient, params: ListTodosParams): Promise<ListTodosRow[]> {
+  const rows = await client.query(listTodosSql, [params.listId]);
+  return rows as unknown as ListTodosRow[];
+}
+
+/** Revisioned reactive descriptor for `useQuery(listTodosQuery, params)`. */
+export const listTodosQuery: NamedQuery<ListTodosRow, ListTodosParams> = {
+  id: 'sha256:4c2d58e50c85edd5a15aa6d61f2195b802e90b9056fc3cea17ceddb6ea37d0e7/listTodos',
+  hasParams: true,
+  sql: listTodosSql,
+  tables: listTodosTables,
+  dependencies: (params) => [
+    { table: 'todos', scopeKeys: ['list:' + String(params.listId) + ''] },
+  ],
+  coverage: (params) => [
+    { base: { table: 'todos', variable: 'list_id' }, units: [String(params.listId)] },
+  ],
+  bind: (params: ListTodosParams) => [params.listId],
+  rowKey: (row) => [row.id],
+};

package/template/tauri/src-tauri/Cargo.toml

@@ -21,7 +21,7 @@ tauri = { version = "2", features = [] }
 # The syncular plugin from crates.io. `native-transport` gives the core its
 # real HTTP + WebSocket transport (ureq + tungstenite) inside the host
 # process — the webview never talks to the sync server directly.
-tauri-plugin-syncular = { version = "0.4", features = ["native-transport"] }
+tauri-plugin-syncular = { version = "0.5", features = ["native-transport"] }
 
 [features]
 default = []

package/template/tauri/src-tauri/src/lib.rs

@@ -28,7 +28,6 @@ pub fn run() {
                 base_url: Some("http://localhost:8787".to_owned()),
                 db_path,
                 // Host-loop cadence with a little jitter (§8.4).
-                wake_jitter_ms: 250,
                 auto_sync: true,
                 ..Default::default()
             };

package/template/tauri/syncular.json

@@ -3,7 +3,9 @@
   "migrations": "./migrations",
   "output": {
     "ir": "./syncular.ir.json",
-    "module": "./src/syncular.generated.ts"
+    "module": "./src/syncular.generated.ts",
+    "queryIr": "./syncular.queries.ir.json",
+    "queries": "./src/syncular.queries.ts"
   },
   "schemaVersions": [{ "version": 1, "through": "0001_initial" }],
   "tables": [{ "name": "todos", "scopes": ["list:{list_id}"] }],

package/template/tauri/syncular.queries.ir.json

@@ -0,0 +1,119 @@
+{
+  "queryIrVersion": 2,
+  "queries": [
+    {
+      "name": "listTodos",
+      "file": "list-todos.syql (query listTodos)",
+      "sourceSql": "select id, list_id, title, done, position, updated_at_ms\n  from todos\n  where list_id = :listId\n  order by position, id",
+      "sql": "select id, list_id AS listId, title, done, position, updated_at_ms AS updatedAtMs from todos where list_id = :listId order by position, id",
+      "positionalSql": "select id, list_id AS listId, title, done, position, updated_at_ms AS updatedAtMs from todos where list_id = ? order by position, id",
+      "params": [
+        {
+          "name": "listId",
+          "langName": "listId",
+          "type": "string"
+        }
+      ],
+      "columns": [
+        {
+          "name": "id",
+          "langName": "id",
+          "type": "string",
+          "nullable": false,
+          "fidelity": "exact",
+          "origin": {
+            "table": "todos",
+            "column": "id"
+          }
+        },
+        {
+          "name": "list_id",
+          "langName": "listId",
+          "type": "string",
+          "nullable": false,
+          "fidelity": "exact",
+          "origin": {
+            "table": "todos",
+            "column": "list_id"
+          }
+        },
+        {
+          "name": "title",
+          "langName": "title",
+          "type": "string",
+          "nullable": false,
+          "fidelity": "exact",
+          "origin": {
+            "table": "todos",
+            "column": "title"
+          }
+        },
+        {
+          "name": "done",
+          "langName": "done",
+          "type": "boolean",
+          "nullable": false,
+          "fidelity": "exact",
+          "origin": {
+            "table": "todos",
+            "column": "done"
+          }
+        },
+        {
+          "name": "position",
+          "langName": "position",
+          "type": "integer",
+          "nullable": false,
+          "fidelity": "exact",
+          "origin": {
+            "table": "todos",
+            "column": "position"
+          }
+        },
+        {
+          "name": "updated_at_ms",
+          "langName": "updatedAtMs",
+          "type": "integer",
+          "nullable": false,
+          "fidelity": "exact",
+          "origin": {
+            "table": "todos",
+            "column": "updated_at_ms"
+          }
+        }
+      ],
+      "tables": [
+        "todos"
+      ],
+      "reactive": {
+        "dependencies": [
+          {
+            "table": "todos",
+            "scopes": [
+              {
+                "variable": "list_id",
+                "pattern": "list:{list_id}",
+                "params": [
+                  "listId"
+                ]
+              }
+            ]
+          }
+        ],
+        "coverage": [
+          {
+            "table": "todos",
+            "variable": "list_id",
+            "units": [
+              "listId"
+            ],
+            "fixedScopes": []
+          }
+        ],
+        "rowKey": [
+          "id"
+        ]
+      }
+    }
+  ]
+}

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

@@ -2,6 +2,20 @@
 // irVersion: 1
 // irHash: sha256:2ffc5b70cb96cd546326de9c06868bd988c9fa3459fb3bac8428a81dcc85fca0
 
+/** Structural descriptor consumed by renderer bindings; phantom type
+ * fields make row/insert/update/id inference available without imports. */
+export interface SyncTable<Row, Insert, Update, Id> {
+  readonly name: string;
+  /** Language-facing key used in generated row and mutation types. */
+  readonly primaryKey: keyof Row & string;
+  /** Physical SQLite/wire primary-key column. */
+  readonly physicalPrimaryKey: string;
+  readonly __row?: Row;
+  readonly __insert?: Insert;
+  readonly __update?: Update;
+  readonly __id?: Id;
+}
+
 /** ServerSchema-compatible schema object (SPEC §2.4, §3.1). */
 export const schema = {
   version: 1,
@@ -54,6 +68,13 @@ export interface TodosUpdate {
   updatedAtMs?: number;
 }
 
+/** Typed mutation/resource descriptor for 'todos'. */
+export const todosTable: SyncTable<TodosRow, TodosInsert, TodosUpdate, string> = {
+  name: 'todos',
+  primaryKey: 'id',
+  physicalPrimaryKey: 'id',
+};
+
 export interface TodoListParams {
   listId: string;
 }