@sqlite-sync/core 0.3.0 → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sqlite-sync contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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/{chunk-RKBTBPNC.js → chunk-DYAQIVJO.js}

@@ -1392,8 +1392,67 @@ var createCrdtSyncProducer = ({ storage, broadcastEvents }) => {
   });
 };
 
+// src/sqlite-crdt/retry-remote-operation.ts
+var REMOTE_RETRY_OPTIONS = {
+  maxAttempts: 3,
+  backoffBaseMs: 100,
+  backoffExponent: 1.5,
+  backoffJitterMs: 150,
+  timeoutMs: 1e4
+};
+var RetryTimeoutError = class extends Error {
+  constructor(message, previous) {
+    super(message);
+    this.previous = previous;
+    this.name = "TimeoutError";
+  }
+};
+var applyJitter = (delayMs, maxJitterMs) => {
+  const jitter = Math.random() * maxJitterMs * (Math.random() > 0.5 ? 1 : -1);
+  return Math.max(0, delayMs + jitter);
+};
+var delay = (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs));
+var withTimeout = async (operation, timeoutMs, previousError) => {
+  let timeoutId;
+  try {
+    return await Promise.race([
+      operation(),
+      new Promise((_, reject) => {
+        timeoutId = setTimeout(
+          () => reject(new RetryTimeoutError("Remote operation timed out", previousError)),
+          timeoutMs
+        );
+      })
+    ]);
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+  }
+};
+var retryRemoteOperation = async (operation, options) => {
+  let lastError;
+  for (let attempt = 1; attempt <= options.maxAttempts; attempt++) {
+    try {
+      return await withTimeout(operation, options.timeoutMs, lastError);
+    } catch (error) {
+      lastError = error;
+      if (attempt >= options.maxAttempts) {
+        throw error;
+      }
+      const backoffDelay = applyJitter(
+        options.backoffBaseMs * options.backoffExponent ** (attempt - 1),
+        options.backoffJitterMs
+      );
+      if (backoffDelay > 0) {
+        await delay(backoffDelay);
+      }
+    }
+  }
+  throw lastError;
+};
+
 // src/sqlite-crdt/crdt-sync-remote-source.ts
-import retryAsPromised from "retry-as-promised";
 var SchemaVersionMismatchError = class extends Error {
   constructor(remoteSchemaVersion, localSchemaVersion) {
     super(`Schema version mismatch: remote ${remoteSchemaVersion} != local ${localSchemaVersion}`);
@@ -1412,10 +1471,15 @@ var createCrdtSyncRemoteSource = ({
   remoteFactory
 }) => {
   const eventTarget = createTypedEventTarget();
-  let remoteState = { type: "offline", reason: "NOT_INITIALIZED" };
-  const setRemoteState = (state) => {
-    remoteState = state;
-    eventTarget.dispatchEvent("state-changed", state.type);
+  let remoteState = {
+    type: "offline",
+    reason: "NOT_INITIALIZED",
+    deSynced: false,
+    schemaVersionMismatched: false
+  };
+  const patchRemoteState = (state) => {
+    remoteState = { ...remoteState, ...state };
+    eventTarget.dispatchEvent("state-changed", remoteState.type);
   };
   const initRemote = ensureSingletonExecution(
     async () => {
@@ -1424,10 +1488,10 @@ var createCrdtSyncRemoteSource = ({
       }
       if (!remoteFactory) {
         console.warn("Remote source factory not provided. Going offline.");
-        setRemoteState({ type: "offline", reason: "NOT_INITIALIZED" });
+        patchRemoteState({ type: "offline", reason: "NOT_INITIALIZED" });
         return;
       }
-      setRemoteState({ type: "pending" });
+      patchRemoteState({ type: "pending" });
       const factoryResult = await tryCatchAsync(async () => {
         return await remoteFactory?.({
           onEventsAvailable: ({ newSyncId, remoteEventHlcSum }) => {
@@ -1436,13 +1500,15 @@ var createCrdtSyncRemoteSource = ({
         });
       });
       if (!factoryResult.success) {
-        setRemoteState({ type: "offline", reason: "INITIALIZATION_FAILED" });
+        patchRemoteState({ type: "offline", reason: "INITIALIZATION_FAILED" });
         console.warn("Failed to create remote source", factoryResult.error);
         return;
       }
-      setRemoteState({
+      patchRemoteState({
         type: "online",
-        source: factoryResult.data
+        source: factoryResult.data,
+        deSynced: false,
+        schemaVersionMismatched: false
       });
     },
     { queueReExecution: false }
@@ -1463,14 +1529,14 @@ var createCrdtSyncRemoteSource = ({
         return;
       }
       const source = remoteState.source;
-      setRemoteState({ type: "pending" });
+      patchRemoteState({ type: "pending" });
       const disconnectResult = await tryCatchAsync(async () => {
         return await source.disconnect?.();
       });
       if (!disconnectResult.success) {
         console.warn("Error while disconnecting from remote source", disconnectResult.error);
       }
-      setRemoteState({ type: "offline", reason });
+      patchRemoteState({ type: "offline", reason });
     },
     { queueReExecution: false }
   );
@@ -1523,18 +1589,12 @@ var createCrdtSyncRemoteSource = ({
         return;
       }
       const source = remoteState.source;
-      const response = await retryAsPromised(
+      const response = await retryRemoteOperation(
         () => source.pullEvents({
           ...opts,
           afterSyncId
         }),
-        {
-          max: 3,
-          backoffBase: 100,
-          backoffExponent: 1.5,
-          backoffJitter: 150,
-          timeout: 1e4
-        }
+        REMOTE_RETRY_OPTIONS
       );
       hasMore = response.hasMore;
       afterSyncId = response.nextSyncId;
@@ -1546,6 +1606,9 @@ var createCrdtSyncRemoteSource = ({
                 remoteSchemaVersion: x.schema_version,
                 localSchemaVersion: migrator.currentSchemaVersion
               });
+              if (remoteState.type === "online" && !remoteState.schemaVersionMismatched) {
+                patchRemoteState({ schemaVersionMismatched: true });
+              }
               throw new SchemaVersionMismatchError(x.schema_version, migrator.currentSchemaVersion);
             }
             return x;
@@ -1574,11 +1637,15 @@ var createCrdtSyncRemoteSource = ({
     if (localEventHlcSum === null) {
       return;
     }
-    if (localEventHlcSum !== remoteEventHlcSum) {
-      eventTarget.dispatchEvent("de-sync-detected", { reason: "CHECKSUM_MISMATCH" });
-      console.warn(
-        `[sqlite-sync] De-sync detected at syncId ${remoteSyncId}: local HLC checksum ${localEventHlcSum} != remote ${remoteEventHlcSum}. Local and remote have diverged despite being caught up.`
-      );
+    if (localEventHlcSum === remoteEventHlcSum) {
+      return;
+    }
+    eventTarget.dispatchEvent("de-sync-detected", { reason: "CHECKSUM_MISMATCH" });
+    console.warn(
+      `[sqlite-sync] De-sync detected at syncId ${remoteSyncId}: local HLC checksum ${localEventHlcSum} != remote ${remoteEventHlcSum}. Local and remote have diverged despite being caught up.`
+    );
+    if (remoteState.type === "online" && !remoteState.deSynced) {
+      patchRemoteState({ deSynced: true });
     }
   };
   const startPushingEvents = ensureSingletonExecution(async () => {
@@ -1598,7 +1665,7 @@ var createCrdtSyncRemoteSource = ({
       const source = remoteState.source;
       let response;
       try {
-        response = await retryAsPromised(
+        response = await retryRemoteOperation(
           () => source.pushEvents({
             nodeId,
             events: eventsBatch.events.map((event) => ({
@@ -1610,13 +1677,7 @@ var createCrdtSyncRemoteSource = ({
               payload: event.payload
             }))
           }),
-          {
-            max: 3,
-            backoffBase: 100,
-            backoffExponent: 1.5,
-            backoffJitter: 150,
-            timeout: 1e4
-          }
+          REMOTE_RETRY_OPTIONS
         );
       } catch (error) {
         console.error("Error pushing events. Going offline.", error);
@@ -1637,8 +1698,15 @@ var createCrdtSyncRemoteSource = ({
   });
   const remoteEventApplyFailedSubscription = storage.addEventListener("remote-event-apply-failed", () => {
     eventTarget.dispatchEvent("de-sync-detected", { reason: "ERROR_APPLYING_REMOTE_EVENT" });
+    if (remoteState.type === "online" && !remoteState.deSynced) {
+      patchRemoteState({ deSynced: true });
+    }
+  });
+  const getState = () => ({
+    remoteState: remoteState.type,
+    deSynced: remoteState.deSynced,
+    schemaVersionMismatched: remoteState.schemaVersionMismatched
   });
-  const getState = () => remoteState.type;
   const dispose = async () => {
     await goOffline("DISCONNECTED");
     eventsAppliedSubscription.unsubscribe();
@@ -1796,4 +1864,4 @@ export {
   createResetStateStore,
   createReloadRequestHandler
 };
-//# sourceMappingURL=chunk-RKBTBPNC.js.map
+//# sourceMappingURL=chunk-DYAQIVJO.js.map