tinysynq-tauri

TinySynq bindings for Tauri desktop apps.
This package adapts @bspeckco/tinysynq-lib to the @tauri-apps/plugin-sql driver and ships a WebSocket client you can embed in your frontend to pull/push changes from a TinySynq hub.

What’s inside

• initTinySynq – bootstraps a TinySynq instance backed by the Tauri SQL plugin.
• TinySynqClient – browser/WebView-side helper for WebSocket sync.
• Re-exports of the core TinySynq types plus TinySynqClientConfig.

Prerequisites

• Node.js ≥ 18.18.2
• Tauri v2 project configured with:
  • Rust crate tauri-plugin-sql with the sqlite feature
  • Frontend package @tauri-apps/plugin-sql
• A TinySynq hub (e.g. @bspeckco/tinysynq-node) reachable over WebSockets.

Installation

pnpm add @bspeckco/tinysynq-tauri
# core dependencies (if not already present)
pnpm add @bspeckco/tinysynq-lib nanoid tslog

Quick start

// src/lib/sync.ts
import Database from '@tauri-apps/plugin-sql';
import { initTinySynq, TinySynqClient } from '@bspeckco/tinysynq-tauri';

export async function bootstrapSync() {
  const sqlite = await Database.load('sqlite:app.db');

  const ts = await initTinySynq({
    sqlite3: sqlite,
    prefix: 'app',
    tables: [
      {
        name: 'todos',
        id: 'todo_id',
        editable: ['title', 'completed'],
      },
    ],
    preInit: [
      `CREATE TABLE IF NOT EXISTS todos (
         todo_id TEXT PRIMARY KEY,
         title TEXT NOT NULL,
         completed INTEGER DEFAULT 0,
         updated_at TEXT DEFAULT (STRFTIME('%Y-%m-%dT%H:%M:%f','now'))
       );`,
    ],
    logOptions: { type: 'pretty', minLevel: 3 },
  });

  const client = new TinySynqClient({
    ts,
    hostname: 'localhost',
    port: 7174,
    secure: false,
  });

  await client.connect();
  await client.pull(); // initial sync

  client.addEventListener('changes', (event) => {
    console.log('Applied remote changes', event.detail);
  });

  return { ts, client };
}

From your Svelte/React component:

import { onMount } from 'svelte';
import { bootstrapSync } from '$lib/sync';

onMount(async () => {
  const { client } = await bootstrapSync();
  await client.push(); // optional: upload local changes

  return () => client.ws?.close();
});

API reference

initTinySynq(options: TinySynqOptions)

Creates and bootstraps a TinySynq instance using the supplied Tauri SQL connection.

Required:

• prefix – namespace for TinySynq system tables.
• tables – array of { name, id, editable }.
• One of sqlite3, filePath, or adapter. In Tauri you typically pass sqlite3.

Optional highlights:

• preInit / postInit SQL arrays.
• logOptions, debug, wal, batchSize.
• telemetry emitter for lab tooling.

Returns a fully initialised TinySynq.

TinySynq

Extends TinySynqAsync. You usually interact with the instance returned from initTinySynq to query change state (getFilteredChanges, applyChangesToLocalDB, etc.).

TinySynqClient

new TinySynqClient(config: TinySynqClientConfig)

Key config fields:

| Field | Type | Default | Description | | ------------ | ------------------- | ------------ | ------------------------------------------------ | | ts | TinySynq (required)| — | The TinySynq instance returned by initTinySynq.| | hostname | string | localhost | Hostname/IP of the sync hub. | | port | number | 7174 | Hub port. | | secure | boolean | false | Use wss:// when true. | | wsToken | string | — | Optional token appended as ?token=. | | logOptions | Logger settings | { name: 'tinysynq-client', minLevel: 3, type: 'json' } | Forwarded to tslog. | | telemetry | TinySynqTelemetryEmitter | — | Receives structured lifecycle events. |

Methods:

• connect() → Promise<WebSocket> – opens the socket.
• push(since?) – sends pending local changes.
• pull(since?) – requests remote changes.
• isOpenOrConnecting() – connection state helper.

Events (inherited from EventTarget):

• changes – fired with event.detail = Change[] after applying remote mutations.
• error – fired when the hub responds with a NACK or connection error.

Type exports

The package re-exports:

• Core TinySynq types: TinySynqOptions, SyncableTable, Change, QueryParams, LogLevel.
• Local types: TinySynq, TinySynqClient, TinySynqClientConfig.

Notes

• The default export (import initTinySynq from '@bspeckco/tinysynq-tauri') is deprecated; use named imports instead.
• WAL mode is enabled by default. Disable it by passing wal: false if your environment cannot support WAL.
• When using telemetry, the provided emitter also drives TinySynq server-side instrumentation, enabling consistent lab tooling across platforms.

Development scripts

pnpm i
pnpm test
pnpm build
pnpm watch

License

MIT