@sqlite-sync/core 0.4.0 → 0.4.2

package/README.md

@@ -0,0 +1,81 @@
+# @sqlite-sync/core
+
+Core sync engine for [sqlite-sync](https://github.com/krolebord-dev/sqlite-sync) — a local-first SQLite sync engine for web apps, with reactive queries, offline persistence, and CRDT-based replication.
+
+This package provides:
+
+- `createSyncedDb()` for client orchestration (worker attach, snapshot hydration, sync state).
+- The schema builder (`createSyncDbSchema`) and migrations (`createMigrations`).
+- Live query primitives (`db.createLiveQuery(...)`), typed through [Kysely](https://kysely.dev/).
+- CRDT primitives with Last-Write-Wins per-field replication and HLC timestamps.
+- The worker runtime (`@sqlite-sync/core/worker`) and server protocol types (`@sqlite-sync/core/server`).
+
+## Install
+
+```bash
+pnpm add @sqlite-sync/core kysely
+```
+
+For React bindings, add [`@sqlite-sync/react`](https://www.npmjs.com/package/@sqlite-sync/react).
+
+## Quick start
+
+```ts
+import { createMigrations, createSyncDbSchema, createSyncedDb } from "@sqlite-sync/core";
+
+type Todo = {
+  id: string;
+  title: string;
+  completed: boolean;
+  tombstone?: boolean;
+};
+
+const migrations = createMigrations((b) => ({
+  0: [
+    b.createTable("_todo", (t) =>
+      t
+        .addColumn("id", "text", (col) => col.primaryKey().notNull())
+        .addColumn("title", "text", (col) => col.notNull())
+        .addColumn("completed", "boolean", (col) => col.notNull().defaultTo(false))
+        .addColumn("tombstone", "boolean", (col) => col.notNull().defaultTo(false)),
+    ),
+  ],
+}));
+
+export const syncDbSchema = createSyncDbSchema({ migrations })
+  .addTable<Todo>()
+  .withConfig({ baseTableName: "_todo", crdtTableName: "todo" })
+  .build();
+
+const worker = new Worker(new URL("./db-worker.ts", import.meta.url), { type: "module" });
+
+export const db = await createSyncedDb({
+  dbId: "app-db",
+  worker,
+  workerProps: undefined,
+  syncDbSchema,
+});
+```
+
+Start the worker (remote sync optional):
+
+```ts
+// db-worker.ts
+import { startDbWorker } from "@sqlite-sync/core/worker";
+import { syncDbSchema } from "./db-schema";
+
+await startDbWorker({ syncDbSchema });
+```
+
+## Requirements
+
+- Browser: Web Workers + Web Locks + an OPFS-capable SQLite WASM environment.
+- Peer dependency: `kysely` (`^0.28.0 || ^0.29.0`).
+
+## Documentation
+
+See the [full documentation](https://github.com/krolebord-dev/sqlite-sync/blob/main/docs.md) and the [project README](https://github.com/krolebord-dev/sqlite-sync) for guides, recovery/storage versioning, and the Cloudflare sync backend.
+
+## License
+
+MIT

package/dist/{crdt-sync-remote-source-DyEELVsx.d.ts → crdt-sync-remote-source-Bv39_fZl.d.ts}

@@ -452,6 +452,26 @@ declare function createCrdtStorage(storage: DbSyncerStorage): {
     }[K]>) => void) => void;
 };
 
+type WorkerNotificationMessage = {
+    notificationType: "new-event-chunk-applied";
+    newSyncId: number;
+    /** Worker's HLC checksum after applying up to `newSyncId`. */
+    eventHlcSum: string | null;
+} | {
+    notificationType: "state-changed";
+    state: WorkerState;
+} | {
+    notificationType: "reload-requested";
+    reloadEpoch: string;
+    clean: boolean;
+} | {
+    notificationType: "de-sync-detected";
+    reason: DeSyncDetectedReason;
+} | {
+    notificationType: "remote-schema-version-mismatch";
+    remoteSchemaVersion: number;
+    localSchemaVersion: number;
+};
 type WorkerState = {
     remoteState: "online" | "offline" | "pending";
     deSynced: boolean;
@@ -569,4 +589,4 @@ declare const createCrdtSyncRemoteSource: ({ bufferSize, storage, migrator, pull
     }[K]>) => void) => void;
 };
 
-export { type PersistedCrdtEvent as $, createSQLiteCrdtApplyFunction as A, createCrdtStorage as B, type CrdtStorage as C, type DeSyncDetectedReason as D, type ExecuteParams as E, type CrdtSyncRemoteSource as F, createCrdtSyncRemoteSource as G, type HLC as H, type InternalSQLiteWrapper as I, type EventsPullRequest as J, type KyselyQueryFactory as K, type Logger as L, type MigratableEvent as M, type EventsPushRequest as N, type EventsPushResponse as O, type PendingCrdtEvent as P, type QueryBuilderOutput as Q, CRDT_EVENT_NO_OP_PAYLOAD as R, SQLiteDbWrapper as S, TypedEvent as T, type CrdtEventOrigin as U, type CrdtEventStatus as V, type WorkerState as W, type CrdtEventType as X, type CrdtUpdateLogItem as Y, type CrdtUpdateLogPayload as Z, isNoOpCrdtEventPayload as _, type StoredValue as a, createStoredValue as a0, type KyselyStatementFactory as a1, type PreparedStatement as a2, createDeferredPromise as a3, createTypedEventTarget as a4, type DeferredPromise as a5, type DistributiveOmit as a6, generateId as a7, jsonSafeParse as a8, quoteId as a9, TypedBroadcastChannel as aa, type TypedEventTarget as ab, tryCatch as ac, tryCatchAsync as ad, type WorkerConfig as ae, type CreateRemoteSourceFactory as af, type GetEventsBatch as ag, type EventsPullResponse as ah, type ExecuteResult as b, type SQLiteTransactionWrapper as c, compareHLC as d, deserializeHLC as e, HLCCounter as f, type DatabaseIntrospection as g, type TableMetadata as h, introspectDb as i, type LogLevel as j, startPerformanceLogger as k, createMigrations as l, createMigrator as m, type Migrations as n, type MigrationsDb as o, type SyncDbMigrator as p, applyMemoryDbSchema as q, applyWorkerDbSchema as r, serializeHLC as s, baseSystemMigrations as t, createSystemDbConfig as u, runSystemMigrations as v, type SystemDbConfig as w, type SystemMigration as x, type SystemMigrationContext as y, createCrdtApplyFunction as z };
+export { type PersistedCrdtEvent as $, createSQLiteCrdtApplyFunction as A, createCrdtStorage as B, type CrdtStorage as C, type DeSyncDetectedReason as D, type ExecuteParams as E, type CrdtSyncRemoteSource as F, createCrdtSyncRemoteSource as G, type HLC as H, type InternalSQLiteWrapper as I, type EventsPullRequest as J, type KyselyQueryFactory as K, type Logger as L, type MigratableEvent as M, type EventsPushRequest as N, type EventsPushResponse as O, type PendingCrdtEvent as P, type QueryBuilderOutput as Q, CRDT_EVENT_NO_OP_PAYLOAD as R, SQLiteDbWrapper as S, TypedEvent as T, type CrdtEventOrigin as U, type CrdtEventStatus as V, type WorkerState as W, type CrdtEventType as X, type CrdtUpdateLogItem as Y, type CrdtUpdateLogPayload as Z, isNoOpCrdtEventPayload as _, type StoredValue as a, createStoredValue as a0, type KyselyStatementFactory as a1, type PreparedStatement as a2, createDeferredPromise as a3, createTypedEventTarget as a4, type DeferredPromise as a5, type DistributiveOmit as a6, generateId as a7, jsonSafeParse as a8, quoteId as a9, TypedBroadcastChannel as aa, type TypedEventTarget as ab, tryCatch as ac, tryCatchAsync as ad, type WorkerConfig as ae, type WorkerNotificationMessage as af, type CreateRemoteSourceFactory as ag, type GetEventsBatch as ah, type EventsPullResponse as ai, type ExecuteResult as b, type SQLiteTransactionWrapper as c, compareHLC as d, deserializeHLC as e, HLCCounter as f, type DatabaseIntrospection as g, type TableMetadata as h, introspectDb as i, type LogLevel as j, startPerformanceLogger as k, createMigrations as l, createMigrator as m, type Migrations as n, type MigrationsDb as o, type SyncDbMigrator as p, applyMemoryDbSchema as q, applyWorkerDbSchema as r, serializeHLC as s, baseSystemMigrations as t, createSystemDbConfig as u, runSystemMigrations as v, type SystemDbConfig as w, type SystemMigration as x, type SystemMigrationContext as y, createCrdtApplyFunction as z };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import * as kysely from 'kysely';
 import { Kysely, SchemaModule } from 'kysely';
-import { S as SQLiteDbWrapper, L as Logger, T as TypedEvent, I as InternalSQLiteWrapper, a as StoredValue, C as CrdtStorage, E as ExecuteParams, b as ExecuteResult, Q as QueryBuilderOutput, K as KyselyQueryFactory, c as SQLiteTransactionWrapper, W as WorkerState, D as DeSyncDetectedReason } from './crdt-sync-remote-source-DyEELVsx.js';
-export { R as CRDT_EVENT_NO_OP_PAYLOAD, U as CrdtEventOrigin, V as CrdtEventStatus, X as CrdtEventType, F as CrdtSyncRemoteSource, Y as CrdtUpdateLogItem, Z as CrdtUpdateLogPayload, g as DatabaseIntrospection, a5 as DeferredPromise, a6 as DistributiveOmit, J as EventsPullRequest, N as EventsPushRequest, O as EventsPushResponse, H as HLC, f as HLCCounter, a1 as KyselyStatementFactory, j as LogLevel, M as MigratableEvent, n as Migrations, o as MigrationsDb, P as PendingCrdtEvent, $ as PersistedCrdtEvent, a2 as PreparedStatement, p as SyncDbMigrator, w as SystemDbConfig, x as SystemMigration, y as SystemMigrationContext, h as TableMetadata, aa as TypedBroadcastChannel, ab as TypedEventTarget, ae as WorkerConfig, q as applyMemoryDbSchema, r as applyWorkerDbSchema, t as baseSystemMigrations, d as compareHLC, z as createCrdtApplyFunction, B as createCrdtStorage, G as createCrdtSyncRemoteSource, a3 as createDeferredPromise, l as createMigrations, m as createMigrator, A as createSQLiteCrdtApplyFunction, a0 as createStoredValue, u as createSystemDbConfig, a4 as createTypedEventTarget, e as deserializeHLC, a7 as generateId, i as introspectDb, _ as isNoOpCrdtEventPayload, a8 as jsonSafeParse, a9 as quoteId, v as runSystemMigrations, s as serializeHLC, k as startPerformanceLogger, ac as tryCatch, ad as tryCatchAsync } from './crdt-sync-remote-source-DyEELVsx.js';
-import { S as SyncDbSchema, C as CrdtTableConfig } from './reset-state-BeduI9vB.js';
-export { a as CreateCrdtSchemaOptions, R as RESET_REQUEST_TTL_MS, b as ResetRequest, d as ResetStore, c as createSyncDbSchema } from './reset-state-BeduI9vB.js';
+import { S as SQLiteDbWrapper, L as Logger, T as TypedEvent, I as InternalSQLiteWrapper, a as StoredValue, C as CrdtStorage, E as ExecuteParams, b as ExecuteResult, Q as QueryBuilderOutput, K as KyselyQueryFactory, c as SQLiteTransactionWrapper, W as WorkerState, D as DeSyncDetectedReason } from './crdt-sync-remote-source-Bv39_fZl.js';
+export { R as CRDT_EVENT_NO_OP_PAYLOAD, U as CrdtEventOrigin, V as CrdtEventStatus, X as CrdtEventType, F as CrdtSyncRemoteSource, Y as CrdtUpdateLogItem, Z as CrdtUpdateLogPayload, g as DatabaseIntrospection, a5 as DeferredPromise, a6 as DistributiveOmit, J as EventsPullRequest, N as EventsPushRequest, O as EventsPushResponse, H as HLC, f as HLCCounter, a1 as KyselyStatementFactory, j as LogLevel, M as MigratableEvent, n as Migrations, o as MigrationsDb, P as PendingCrdtEvent, $ as PersistedCrdtEvent, a2 as PreparedStatement, p as SyncDbMigrator, w as SystemDbConfig, x as SystemMigration, y as SystemMigrationContext, h as TableMetadata, aa as TypedBroadcastChannel, ab as TypedEventTarget, ae as WorkerConfig, af as WorkerNotificationMessage, q as applyMemoryDbSchema, r as applyWorkerDbSchema, t as baseSystemMigrations, d as compareHLC, z as createCrdtApplyFunction, B as createCrdtStorage, G as createCrdtSyncRemoteSource, a3 as createDeferredPromise, l as createMigrations, m as createMigrator, A as createSQLiteCrdtApplyFunction, a0 as createStoredValue, u as createSystemDbConfig, a4 as createTypedEventTarget, e as deserializeHLC, a7 as generateId, i as introspectDb, _ as isNoOpCrdtEventPayload, a8 as jsonSafeParse, a9 as quoteId, v as runSystemMigrations, s as serializeHLC, k as startPerformanceLogger, ac as tryCatch, ad as tryCatchAsync } from './crdt-sync-remote-source-Bv39_fZl.js';
+import { S as SyncDbSchema, C as CrdtTableConfig } from './reset-state-BR4Zs-Jy.js';
+export { a as CreateCrdtSchemaOptions, R as RESET_REQUEST_TTL_MS, b as ResetRequest, d as ResetStore, c as createSyncDbSchema } from './reset-state-BR4Zs-Jy.js';
 import '@sqlite.org/sqlite-wasm';
 
 declare const dummyKysely: Kysely<any>;

package/dist/{reset-state-BeduI9vB.d.ts → reset-state-BR4Zs-Jy.d.ts}

@@ -1,4 +1,4 @@
-import { n as Migrations, X as CrdtEventType } from './crdt-sync-remote-source-DyEELVsx.js';
+import { n as Migrations, X as CrdtEventType } from './crdt-sync-remote-source-Bv39_fZl.js';
 import { ColumnType } from 'kysely';
 
 type CrdtTableConfig = {

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { ah as EventsPullResponse, O as EventsPushResponse } from './crdt-sync-remote-source-DyEELVsx.js';
-export { a8 as jsonSafeParse } from './crdt-sync-remote-source-DyEELVsx.js';
+import { ai as EventsPullResponse, O as EventsPushResponse } from './crdt-sync-remote-source-Bv39_fZl.js';
+export { a8 as jsonSafeParse } from './crdt-sync-remote-source-Bv39_fZl.js';
 import { z } from 'zod';
 import 'kysely';
 import '@sqlite.org/sqlite-wasm';

package/dist/worker.d.ts

@@ -1,6 +1,6 @@
-import { af as CreateRemoteSourceFactory, ae as WorkerConfig, L as Logger } from './crdt-sync-remote-source-DyEELVsx.js';
-export { J as EventsPullRequest, N as EventsPushRequest, O as EventsPushResponse, ag as GetEventsBatch } from './crdt-sync-remote-source-DyEELVsx.js';
-import { S as SyncDbSchema, d as ResetStore } from './reset-state-BeduI9vB.js';
+import { ag as CreateRemoteSourceFactory, ae as WorkerConfig, L as Logger } from './crdt-sync-remote-source-Bv39_fZl.js';
+export { J as EventsPullRequest, N as EventsPushRequest, O as EventsPushResponse, ah as GetEventsBatch } from './crdt-sync-remote-source-Bv39_fZl.js';
+import { S as SyncDbSchema, d as ResetStore } from './reset-state-BR4Zs-Jy.js';
 import 'kysely';
 import '@sqlite.org/sqlite-wasm';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqlite-sync/core",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "SQLite synchronization library with CRDT support",
   "type": "module",
   "license": "MIT",