@tursodatabase/sync 0.1.5 → 0.2.0-pre.10

package/README.md

@@ -1,9 +1,9 @@
 <p align="center">
-  <h1 align="center">Turso Sync for JavaScript</h1>
+  <h1 align="center">Turso Database for JavaScript in Node</h1>
 </p>
 
 <p align="center">
-  <a title="JavaScript" target="_blank" href="https://www.npmjs.com/package/@tursodatabase/sync"><img alt="npm" src="https://img.shields.io/npm/v/@tursodatabase/sync"></a>
+  <a title="JavaScript" target="_blank" href="https://www.npmjs.com/package/@tursodatabase/database"><img alt="npm" src="https://img.shields.io/npm/v/@tursodatabase/database"></a>
   <a title="MIT" target="_blank" href="https://github.com/tursodatabase/turso/blob/main/LICENSE.md"><img src="http://img.shields.io/badge/license-MIT-orange.svg?style=flat-square"></a>
 </p>
 <p align="center">
@@ -14,40 +14,105 @@
 
 ## About
 
-This package is for syncing local Turso databases to the Turso Cloud and back.
+This package is the Turso embedded database library for JavaScript in Node.
 
 > **⚠️ 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.
 
+## Features
+
+- **SQLite compatible:** SQLite query language and file format support ([status](https://github.com/tursodatabase/turso/blob/main/COMPAT.md)).
+- **In-process**: No network overhead, runs directly in your Node.js process
+- **TypeScript support**: Full TypeScript definitions included
+- **Cross-platform**: Supports Linux (x86 and arm64), macOS, Windows (browser is supported in the separate package `@tursodatabase/database-browser` package)
+
 ## Installation
 
 ```bash
-npm install @tursodatabase/sync
+npm install @tursodatabase/database
 ```
 
 ## Getting Started
 
-To sync a database hosted at [Turso Cloud](https://turso.tech):
+### In-Memory Database
+
+```javascript
+import { connect } from '@tursodatabase/database';
+
+// Create an in-memory database
+const db = await connect(':memory:');
+
+// Create a table
+await db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)');
+
+// Insert data
+const insert = db.prepare('INSERT INTO users (name, email) VALUES (?, ?)');
+await insert.run('Alice', 'alice@example.com');
+await insert.run('Bob', 'bob@example.com');
+
+// Query data
+const users = await db.prepare('SELECT * FROM users').all();
+console.log(users);
+// Output: [
+//   { id: 1, name: 'Alice', email: 'alice@example.com' },
+//   { id: 2, name: 'Bob', email: 'bob@example.com' }
+// ]
+```
+
+### File-Based Database
+
+```javascript
+import { connect } from '@tursodatabase/database';
 
-```js
-import { connect } from '@tursodatabase/sync';
+// Create or open a database file
+const db = await connect('my-database.db');
 
-const db = await connect({
-    path: 'local.db',                // path used as a prefix for local files created by sync-engine
-    url: 'https://<db>.turso.io',    // URL of the remote database: turso db show <db>
-    authToken: '...',                // auth token issued from the Turso Cloud: turso db tokens create <db>
-    clientName: 'turso-sync-example' // arbitrary client name
+// Create a table
+await db.exec(`
+  CREATE TABLE IF NOT EXISTS posts (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    title TEXT NOT NULL,
+    content TEXT,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+  )
+`);
+
+// Insert a post
+const insertPost = db.prepare('INSERT INTO posts (title, content) VALUES (?, ?)');
+const result = await insertPost.run('Hello World', 'This is my first blog post!');
+
+console.log(`Inserted post with ID: ${result.lastInsertRowid}`);
+```
+
+### Transactions
+
+```javascript
+import { connect } from '@tursodatabase/database';
+
+const db = await connect('transactions.db');
+
+// Using transactions for atomic operations
+const transaction = db.transaction(async (users) => {
+  const insert = db.prepare('INSERT INTO users (name, email) VALUES (?, ?)');
+  for (const user of users) {
+    await insert.run(user.name, user.email);
+  }
 });
 
-// db has same functions as Database class from @tursodatabase/database package but adds few more methods for sync:
-await db.pull(); // pull changes from the remote
-await db.push(); // push changes to the remote
-await db.sync(); // pull & push changes
+// Execute transaction
+await transaction([
+  { name: 'Alice', email: 'alice@example.com' },
+  { name: 'Bob', email: 'bob@example.com' }
+]);
 ```
 
+## API Reference
+
+For complete API documentation, see [JavaScript API Reference](../../../../docs/javascript-api-reference.md).
+
 ## Related Packages
 
-* The [@tursodatabase/database](https://www.npmjs.com/package/@tursodatabase/database) package provides the Turso in-memory database, compatible with SQLite.
 * The [@tursodatabase/serverless](https://www.npmjs.com/package/@tursodatabase/serverless) package provides a serverless driver with the same API.
+* The [@tursodatabase/sync](https://www.npmjs.com/package/@tursodatabase/sync) package provides bidirectional sync between a local Turso database and Turso Cloud. 
 
 ## License
 
@@ -57,4 +122,4 @@ This project is licensed under the [MIT license](../../LICENSE.md).
 
 - [GitHub Issues](https://github.com/tursodatabase/turso/issues)
 - [Documentation](https://docs.turso.tech)
-- [Discord Community](https://tur.so/discord)
+- [Discord Community](https://tur.so/discord)

package/dist/promise.d.ts

@@ -0,0 +1,43 @@
+import { DatabasePromise } from "@tursodatabase/database-common";
+import { DatabaseOpts, EncryptionOpts, DatabaseRowMutation, DatabaseRowStatement, DatabaseRowTransformResult, DatabaseStats } from "@tursodatabase/sync-common";
+declare class Database extends DatabasePromise {
+    #private;
+    constructor(opts: DatabaseOpts);
+    /**
+     * connect database and initialize it in case of clean start
+     */
+    connect(): Promise<void>;
+    /**
+     * pull new changes from the remote database
+     * if {@link DatabaseOpts.longPollTimeoutMs} is set - then server will hold the connection open until either new changes will appear in the database or timeout occurs.
+     * @returns true if new changes were pulled from the remote
+     */
+    pull(): Promise<boolean>;
+    /**
+     * push new local changes to the remote database
+     * if {@link DatabaseOpts.transform} is set - then provided callback will be called for every mutation before sending it to the remote
+     */
+    push(): Promise<void>;
+    /**
+     * checkpoint WAL for local database
+     */
+    checkpoint(): Promise<void>;
+    /**
+     * @returns statistic of current local database
+     */
+    stats(): Promise<DatabaseStats>;
+    /**
+     * close the database
+     */
+    close(): Promise<void>;
+}
+/**
+ * Creates a new database connection asynchronously.
+ *
+ * @param {Object} opts - Options for database behavior.
+ * @returns {Promise<Database>} - A promise that resolves to a Database instance.
+ */
+declare function connect(opts: DatabaseOpts): Promise<Database>;
+export { connect, Database };
+export type { DatabaseOpts, EncryptionOpts, DatabaseRowMutation, DatabaseRowStatement, DatabaseRowTransformResult };
+//# sourceMappingURL=promise.d.ts.map

package/dist/promise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promise.d.ts","sourceRoot":"","sources":["../promise.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAA;AAChE,OAAO,EAAmB,YAAY,EAAE,cAAc,EAAW,mBAAmB,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,aAAa,EAAoB,MAAM,4BAA4B,CAAC;AAwC5M,cAAM,QAAS,SAAQ,eAAe;;gBAKtB,IAAI,EAAE,YAAY;IAmC9B;;OAEG;IACY,OAAO;IAGtB;;;;OAIG;IACG,IAAI;IAQV;;;OAGG;IACG,IAAI;IAGV;;OAEG;IACG,UAAU;IAGhB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC;IAGrC;;OAEG;IACY,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGxC;AAED;;;;;GAKG;AACH,iBAAe,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAI5D;AAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAA;AAC5B,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,CAAA"}

package/dist/promise.js

@@ -0,0 +1,137 @@
+import { DatabasePromise } from "@tursodatabase/database-common";
+import { run, SyncEngineGuards } from "@tursodatabase/sync-common";
+import { SyncEngine } from "#index";
+import { promises } from "node:fs";
+let NodeIO = {
+    async read(path) {
+        try {
+            return await promises.readFile(path);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            throw error;
+        }
+    },
+    async write(path, data) {
+        const unix = Math.floor(Date.now() / 1000);
+        const nonce = Math.floor(Math.random() * 1000000000);
+        const tmp = `${path}.tmp.${unix}.${nonce}`;
+        await promises.writeFile(tmp, new Uint8Array(data));
+        try {
+            await promises.rename(tmp, path);
+        }
+        catch (err) {
+            await promises.unlink(tmp);
+            throw err;
+        }
+    }
+};
+function memoryIO() {
+    let values = new Map();
+    return {
+        async read(path) {
+            return values.get(path);
+        },
+        async write(path, data) {
+            values.set(path, data);
+        }
+    };
+}
+;
+class Database extends DatabasePromise {
+    #runOpts;
+    #engine;
+    #io;
+    #guards;
+    constructor(opts) {
+        const engine = new SyncEngine({
+            path: opts.path,
+            clientName: opts.clientName,
+            useTransform: opts.transform != null,
+            protocolVersion: "v1" /* SyncEngineProtocolVersion.V1 */,
+            longPollTimeoutMs: opts.longPollTimeoutMs,
+            tracing: opts.tracing,
+        });
+        super(engine.db());
+        let headers = typeof opts.authToken === "function" ? () => ({
+            ...(opts.authToken != null && { "Authorization": `Bearer ${opts.authToken()}` }),
+            ...(opts.encryption != null && {
+                "x-turso-encryption-key": opts.encryption.key,
+                "x-turso-encryption-cipher": opts.encryption.cipher,
+            })
+        }) : {
+            ...(opts.authToken != null && { "Authorization": `Bearer ${opts.authToken}` }),
+            ...(opts.encryption != null && {
+                "x-turso-encryption-key": opts.encryption.key,
+                "x-turso-encryption-cipher": opts.encryption.cipher,
+            })
+        };
+        this.#runOpts = {
+            url: opts.url,
+            headers: headers,
+            preemptionMs: 1,
+            transform: opts.transform,
+        };
+        this.#engine = engine;
+        this.#io = this.memory ? memoryIO() : NodeIO;
+        this.#guards = new SyncEngineGuards();
+    }
+    /**
+     * connect database and initialize it in case of clean start
+     */
+    async connect() {
+        await run(this.#runOpts, this.#io, this.#engine, this.#engine.connect());
+    }
+    /**
+     * pull new changes from the remote database
+     * if {@link DatabaseOpts.longPollTimeoutMs} is set - then server will hold the connection open until either new changes will appear in the database or timeout occurs.
+     * @returns true if new changes were pulled from the remote
+     */
+    async pull() {
+        const changes = await this.#guards.wait(async () => await run(this.#runOpts, this.#io, this.#engine, this.#engine.wait()));
+        if (changes.empty()) {
+            return false;
+        }
+        await this.#guards.apply(async () => await run(this.#runOpts, this.#io, this.#engine, this.#engine.apply(changes)));
+        return true;
+    }
+    /**
+     * push new local changes to the remote database
+     * if {@link DatabaseOpts.transform} is set - then provided callback will be called for every mutation before sending it to the remote
+     */
+    async push() {
+        await this.#guards.push(async () => await run(this.#runOpts, this.#io, this.#engine, this.#engine.push()));
+    }
+    /**
+     * checkpoint WAL for local database
+     */
+    async checkpoint() {
+        await this.#guards.checkpoint(async () => await run(this.#runOpts, this.#io, this.#engine, this.#engine.checkpoint()));
+    }
+    /**
+     * @returns statistic of current local database
+     */
+    async stats() {
+        return (await run(this.#runOpts, this.#io, this.#engine, this.#engine.stats()));
+    }
+    /**
+     * close the database
+     */
+    async close() {
+        this.#engine.close();
+    }
+}
+/**
+ * Creates a new database connection asynchronously.
+ *
+ * @param {Object} opts - Options for database behavior.
+ * @returns {Promise<Database>} - A promise that resolves to a Database instance.
+ */
+async function connect(opts) {
+    const db = new Database(opts);
+    await db.connect();
+    return db;
+}
+export { connect, Database };

package/dist/promise.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=promise.test.d.ts.map

package/dist/promise.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promise.test.d.ts","sourceRoot":"","sources":["../promise.test.ts"],"names":[],"mappings":""}