@tursodatabase/sync-common 0.2.0-pre.8 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 This package is the Turso Sync common JS library which is shared between final builds for Node and Browser.
 
-Do not use this package directly - instead you must use `@tursodatabase/sync` or `@tursodatabase/sync-browser`.
+Do not use this package directly - instead you must use `@tursodatabase/sync` or `@tursodatabase/sync-wasm`.
 
-> **⚠️ Warning:** This software is ALPHA, only use for development, testing, and experimentation. We are working to make it production ready, but do not use it for critical data right now.
+> **⚠️ Warning:** This software is in BETA. It may still contain bugs and unexpected behavior. Use caution with production data and ensure you have backups.
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { run, memoryIO, SyncEngineGuards } from "./run.js";
-import { SyncOpts, ProtocolIo, RunOpts, DatabaseRowMutation, DatabaseRowStatement, DatabaseRowTransformResult, SyncEngineStats } from "./types.js";
+import { DatabaseOpts, ProtocolIo, RunOpts, DatabaseRowMutation, DatabaseRowStatement, DatabaseRowTransformResult, DatabaseStats, DatabaseChangeType, EncryptionOpts } from "./types.js";
 export { run, memoryIO, SyncEngineGuards };
-export type { SyncOpts, ProtocolIo, RunOpts, DatabaseRowMutation, DatabaseRowStatement, DatabaseRowTransformResult, SyncEngineStats };
+export type { DatabaseStats, DatabaseOpts, DatabaseChangeType, DatabaseRowMutation, DatabaseRowStatement, DatabaseRowTransformResult, EncryptionOpts, ProtocolIo, RunOpts, };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAElJ,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAA;AAC1C,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,eAAe,EAAE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,aAAa,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAExL,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAA;AAC1C,YAAY,EACR,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,0BAA0B,EAC1B,cAAc,EAEd,UAAU,EACV,OAAO,GACV,CAAA"}

package/dist/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../run.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,UAAU,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AA2F3D,wBAAgB,QAAQ,IAAI,UAAU,CAUrC;AAGD,wBAAsB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAwBlG;AAID,qBAAa,gBAAgB;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,SAAS,CAAC;IACpB,cAAc,EAAE,SAAS,CAAC;;IAOpB,IAAI,CAAC,CAAC,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;IAQzC,IAAI,CAAC,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAY3B,KAAK,CAAC,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAc5B,UAAU,CAAC,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;CAc1C"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../run.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,UAAU,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAkG3D,wBAAgB,QAAQ,IAAI,UAAU,CAUrC;AAGD,wBAAsB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAuBlG;AAED,qBAAa,gBAAgB;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,SAAS,CAAC;IACpB,cAAc,EAAE,SAAS,CAAC;;IAOpB,IAAI,CAAC,CAAC,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;IAQzC,IAAI,CAAC,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAY3B,KAAK,CAAC,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAc5B,UAAU,CAAC,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;CAc1C"}

package/dist/run.js

@@ -1,7 +1,5 @@
 "use strict";
 import { AsyncLock } from "@tursodatabase/database-common";
-const GENERATOR_RESUME_IO = 0;
-const GENERATOR_RESUME_DONE = 1;
 function trackPromise(p) {
     let status = { promise: null, finished: false };
     status.promise = p.finally(() => status.finished = true);
@@ -14,15 +12,26 @@ async function process(opts, io, request) {
     const requestType = request.request();
     const completion = request.completion();
     if (requestType.type == 'Http') {
+        let url = null;
+        if (typeof opts.url == "function") {
+            url = opts.url();
+        }
+        else {
+            url = opts.url;
+        }
+        if (url == null) {
+            completion.poison(`url is empty - sync is paused`);
+            return;
+        }
         try {
-            let headers = opts.headers;
+            let headers = typeof opts.headers === "function" ? await opts.headers() : opts.headers;
             if (requestType.headers != null && requestType.headers.length > 0) {
-                headers = { ...opts.headers };
+                headers = { ...headers };
                 for (let header of requestType.headers) {
                     headers[header[0]] = header[1];
                 }
             }
-            const response = await fetch(`${opts.url}${requestType.path}`, {
+            const response = await fetch(`${url}${requestType.path}`, {
                 method: requestType.method,
                 headers: headers,
                 body: requestType.body != null ? new Uint8Array(requestType.body) : null,
@@ -122,7 +131,6 @@ export async function run(opts, io, engine, generator) {
         await Promise.all([engine.ioLoopAsync(), tasksRace]);
         tasks = tasks.filter(t => !t.finished);
     }
-    return generator.take();
 }
 export class SyncEngineGuards {
     waitLock;

package/dist/types.d.ts

@@ -1,66 +1,158 @@
 export declare const enum DatabaseChangeType {
-    Insert = 0,
-    Update = 1,
-    Delete = 2
+    Insert = "insert",
+    Update = "update",
+    Delete = "delete"
 }
+export interface DatabaseRowStatement {
+    /**
+     * SQL statements with positional placeholders (?)
+     */
+    sql: string;
+    /**
+     * values to substitute placeholders
+     */
+    values: Array<any>;
+}
+/**
+ * transformation result:
+ * - skip: ignore the mutation completely and do not apply it
+ * - rewrite: replace mutation with the provided statement
+ * - null: do not change mutation and keep it as is
+ */
+export type DatabaseRowTransformResult = {
+    operation: 'skip';
+} | {
+    operation: 'rewrite';
+    stmt: DatabaseRowStatement;
+} | null;
 export interface DatabaseRowMutation {
+    /**
+     * unix seconds timestamp of the change
+     */
     changeTime: number;
+    /**
+     * table name of the change
+     */
     tableName: string;
+    /**
+     * rowid of the change
+     */
     id: number;
+    /**
+     * type of the change (insert/delete/update)
+     */
     changeType: DatabaseChangeType;
+    /**
+     * columns of the row before the change
+     */
     before?: Record<string, any>;
+    /**
+     * columns of the row after the change
+     */
     after?: Record<string, any>;
+    /**
+     * only updated columns of the row after the change
+     */
     updates?: Record<string, any>;
 }
-export type DatabaseRowTransformResult = {
-    operation: 'skip';
-} | {
-    operation: 'rewrite';
-    stmt: DatabaseRowStatement;
-} | null;
 export type Transform = (arg: DatabaseRowMutation) => DatabaseRowTransformResult;
-export interface RunOpts {
-    preemptionMs: number;
-    url: string;
-    headers: {
-        [K: string]: string;
-    };
-    transform?: Transform;
-}
-export interface ProtocolIo {
-    read(path: string): Promise<Buffer | Uint8Array | null>;
-    write(path: string, content: Buffer | Uint8Array): Promise<void>;
+export interface EncryptionOpts {
+    key: string;
+    cipher: 'aes256gcm' | 'aes128gcm' | 'chacha20poly1305' | 'aegis256';
 }
-export interface SyncOpts {
+export interface DatabaseOpts {
+    /**
+     * local path where to store all synced database files (e.g. local.db)
+     * note, that synced database will write several files with that prefix
+     * (e.g. local.db-info, local.db-wal, etc)
+     * */
     path: string;
+    /**
+     * optional url of the remote database (e.g. libsql://db-org.turso.io)
+     * (if omitted - local-only database will be created)
+     *
+     * you can also promide function which will return URL or null
+     * in this case local database will be created and sync will be "switched-on" whenever the url will return non-empty value
+     * note, that all other parameters (like encryption) must be set in advance in order for the "deferred" sync to work properly
+     */
+    url?: string | (() => string | null);
+    /**
+     * auth token for the remote database
+     * (can be either static string or function which will provide short-lived credentials for every new request)
+     */
+    authToken?: string | (() => Promise<string>);
+    /**
+     * arbitrary client name which can be used to distinguish clients internally
+     * the library will gurantee uniquiness of the clientId by appending unique suffix to the clientName
+     */
     clientName?: string;
-    url: string;
-    authToken?: string;
-    encryptionKey?: string;
-    tablesIgnore?: string[];
+    /**
+     * optional remote encryption parameters if cloud database were encrypted by default
+     */
+    remoteEncryption?: EncryptionOpts;
+    /**
+     * optional callback which will be called for every mutation before sending it to the remote
+     * this callback can transform the update in order to support complex conflict resolution strategy
+     */
     transform?: Transform;
+    /**
+     * optional long-polling timeout for pull operation
+     * if not set - no timeout is applied
+     */
     longPollTimeoutMs?: number;
-    tracing?: string;
+    /**
+     * optional parameter to enable internal logging for the database
+     */
+    tracing?: 'error' | 'warn' | 'info' | 'debug' | 'trace';
 }
-export interface DatabaseRowStatement {
-    sql: string;
-    values: Array<any>;
-}
-export interface SyncEngineStats {
+export interface DatabaseStats {
+    /**
+     * amount of local changes not sent to the remote
+     */
     operations: number;
+    /**
+     * size of the main WAL file in bytes
+     */
     mainWal: number;
+    /**
+     * size of the revert WAL file in bytes
+     */
     revertWal: number;
+    /**
+     * unix timestamp of last successful pull time
+     */
     lastPullUnixTime: number;
+    /**
+     * unix timestamp of last successful push time
+     */
     lastPushUnixTime: number | null;
+    /**
+     * opaque revision of the changes pulled locally from remote
+     * (can be used as e-tag, but string must not be interpreted in any way and must be used as opaque value)
+     */
     revision: string | null;
 }
+export interface RunOpts {
+    preemptionMs: number;
+    url: string | (() => string | null);
+    headers: {
+        [K: string]: string;
+    } | (() => Promise<{
+        [K: string]: string;
+    }>);
+    transform?: Transform;
+}
+export interface ProtocolIo {
+    read(path: string): Promise<Buffer | Uint8Array | null>;
+    write(path: string, content: Buffer | Uint8Array): Promise<void>;
+}
 export type GeneratorResponse = {
     type: 'IO';
 } | {
     type: 'Done';
 } | ({
     type: 'SyncEngineStats';
-} & SyncEngineStats) | {
+} & DatabaseStats) | {
     type: 'SyncEngineChanges';
     changes: any;
 };

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,CAAC,KAAK,MAAM,kBAAkB;IACxC,MAAM,IAAI;IACV,MAAM,IAAI;IACV,MAAM,IAAI;CACb;AAED,MAAM,WAAW,mBAAmB;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,kBAAkB,CAAA;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAChC;AAED,MAAM,MAAM,0BAA0B,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,oBAAoB,CAAA;CAAE,GAAG,IAAI,CAAC;AAC7H,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,mBAAmB,KAAK,0BAA0B,CAAC;AACjF,MAAM,WAAW,OAAO;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;IAChC,SAAS,CAAC,EAAE,SAAS,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACvB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC,CAAC;IACxD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,QAAQ;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;CACrB;AAED,MAAM,WAAW,eAAe;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,MAAM,iBAAiB,GAAG;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,CAAC;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAAG,eAAe,CAAC,GAAG;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,OAAO,EAAE,GAAG,CAAA;CAAE,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tursodatabase/sync-common",
-  "version": "0.2.0-pre.8",
+  "version": "0.2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/tursodatabase/turso"
@@ -23,6 +23,6 @@
     "test": "echo 'no tests'"
   },
   "dependencies": {
-    "@tursodatabase/database-common": "^0.2.0-pre.8"
+    "@tursodatabase/database-common": "^0.2.0"
   }
 }