diff --git a/bindings/javascript/README.md b/bindings/javascript/README.md index 2f73bb627..294b0a806 100644 --- a/bindings/javascript/README.md +++ b/bindings/javascript/README.md @@ -1,16 +1,29 @@ -# @tursodatabase/database +

+

Turso Database for JavaScript

+

-The next evolution of SQLite: A high-performance, SQLite-compatible database library for Node.js +

+ npm + +

+

+ Chat with other users of Turso on Discord +

+ +--- + +## About + +This package is the Turso in-memory database library for JavaScript. + +> **⚠️ 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**: Drop-in replacement for better-sqlite3 with familiar API -- **High Performance**: Built with Rust for maximum speed and efficiency -- **In-Process**: No network overhead, runs directly in your Node.js process -- **TypeScript Support**: Full TypeScript definitions included -- **Cross-Platform**: Supports Linux, macOS, Windows and browsers (through WebAssembly) -- **Transaction Support**: Full ACID transactions with rollback support -- **Prepared Statements**: Optimized query execution with parameter binding +- **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, macOS, Windows and browsers (through WebAssembly) ## Installation @@ -18,15 +31,15 @@ The next evolution of SQLite: A high-performance, SQLite-compatible database lib npm install @tursodatabase/database ``` -## Quick Start +## Getting Started ### In-Memory Database ```javascript -import Database from '@tursodatabase/database'; +import { connect } from '@tursodatabase/database'; // Create an in-memory database -const db = new Database(':memory:'); +const db = await connect(':memory:'); // Create a table db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)'); @@ -48,10 +61,10 @@ console.log(users); ### File-Based Database ```javascript -import Database from '@tursodatabase/database'; +import { connect } from '@tursodatabase/database'; // Create or open a database file -const db = new Database('my-database.db'); +const db = await connect('my-database.db'); // Create a table db.exec(` @@ -70,13 +83,47 @@ const result = 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((users) => { + const insert = db.prepare('INSERT INTO users (name, email) VALUES (?, ?)'); + for (const user of users) { + insert.run(user.name, user.email); + } +}); + +// Execute transaction +transaction([ + { name: 'Alice', email: 'alice@example.com' }, + { name: 'Bob', email: 'bob@example.com' } +]); +``` + +### WebAssembly Support + +Turso Database can run in browsers using WebAssembly. Check the `browser.js` and WASM artifacts for browser usage. + ## API Reference + +For complete API documentation, see [JavaScript API Reference](../../docs/javascript-api-reference.md). + +## Related Packages + +* 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 -MIT +This project is licensed under the [MIT license](../../LICENSE.md). ## Support - [GitHub Issues](https://github.com/tursodatabase/turso/issues) - [Documentation](https://docs.turso.tech) -- [Discord Community](https://discord.gg/turso) +- [Discord Community](https://tur.so/discord) \ No newline at end of file diff --git a/packages/turso-serverless/README.md b/packages/turso-serverless/README.md index 79c407319..0b3e119a4 100644 --- a/packages/turso-serverless/README.md +++ b/packages/turso-serverless/README.md @@ -1,9 +1,22 @@ -# Turso serverless JavaScript driver +

+

Turso Serverless Driver for JavaScript

+

+ +

+ npm + +

+

+ Chat with other users of Turso on Discord +

+ +--- + +## About A serverless database driver for Turso Cloud, using only `fetch()`. Connect to your database from serverless and edge functions, such as Cloudflare Workers and Vercel. -> [!NOTE] -> This driver is experimental and, therefore, subject to change at any time. +> **📝 Note:** This driver is experimental and, therefore, subject to change at any time. ## Installation @@ -11,7 +24,9 @@ A serverless database driver for Turso Cloud, using only `fetch()`. Connect to y npm install @tursodatabase/serverless ``` -## Usage +## Getting Started + +### Basic Usage ```javascript import { connect } from "@tursodatabase/serverless"; @@ -36,7 +51,11 @@ console.log(rows); for await (const row of stmt.iterate([123])) { console.log(row); } +``` +### Batch Operations + +```javascript // Execute multiple statements in a batch await conn.batch([ "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, email TEXT)", @@ -45,9 +64,9 @@ await conn.batch([ ]); ``` -### Compatibility layer for libSQL API +### libSQL Compatibility Layer -This driver supports the libSQL API as a compatibility layer. +For existing libSQL applications, use the compatibility layer: ```javascript import { createClient } from "@tursodatabase/serverless/compat"; @@ -73,6 +92,21 @@ await client.batch([ Check out the `examples/` directory for complete usage examples. +## 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/sync](https://www.npmjs.com/package/@tursodatabase/sync) package provides bidirectional sync between a local Turso database and Turso Cloud. + ## License -MIT +This project is licensed under the [MIT license](../../LICENSE.md). + +## Support + +- [GitHub Issues](https://github.com/tursodatabase/turso/issues) +- [Documentation](https://docs.turso.tech) +- [Discord Community](https://tur.so/discord) \ No newline at end of file diff --git a/packages/turso-sync-js/README.md b/packages/turso-sync-js/README.md index 6ab633b74..88bb0c4a0 100644 --- a/packages/turso-sync-js/README.md +++ b/packages/turso-sync-js/README.md @@ -1,20 +1,32 @@ -# turso-sync-js package +

+

Turso Sync for JavaScript

+

-> [!WARNING] -> **`@tursodatabase/sync`** is in a **very experimental** stage. -> It may cause **data corruption** in **both local and remote databases**. -> -> We are actively working to make it a **production-grade** package, but **it is not safe for critical data yet**. +

+ npm + +

+

+ Chat with other users of Turso on Discord +

-## Usage +--- -[![npm version](https://img.shields.io/npm/v/@tursodatabase/sync)](https://www.npmjs.com/package/@tursodatabase/sync) +## About -``` -npm i @tursodatabase/sync +This package is for syncing local Turso databases to the Turso Cloud and back. + +> **⚠️ 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. + +## Installation + +```bash +npm install @tursodatabase/sync ``` -Example usage with remote DB hosting at [Turso Cloud](https://turso.tech) +## Getting Started + +To sync a database hosted at [Turso Cloud](https://turso.tech): ```js import { connect } from '@tursodatabase/sync'; @@ -31,3 +43,18 @@ await db.pull(); // pull changes from the remote await db.push(); // push changes to the remote await db.sync(); // pull & push changes ``` + +## 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. + +## License + +This project is licensed under the [MIT license](../../LICENSE.md). + +## Support + +- [GitHub Issues](https://github.com/tursodatabase/turso/issues) +- [Documentation](https://docs.turso.tech) +- [Discord Community](https://tur.so/discord) \ No newline at end of file