About

This package is the Turso embedded database library for JavaScript in Browser, forked to enable mutable FTS indexing in the wasm browser build.

It is intended for browser apps that run Turso from a single Web Worker with OPFS persistence. The FTS path supports creating FTS indexes, querying, inserts, updates, deletes, INSERT OR REPLACE, rollbacks, statement aborts, close/reopen persistence, and large text documents tested around 30k characters.

⚠️ Warning: This software is in BETA. It may still contain bugs and unexpected behavior. Use caution with production data and ensure you have backups.

Features

• SQLite compatible: SQLite query language and file format support (status).
• Browser FTS: FTS indexes are enabled in the wasm browser build.
• Persistent browser storage: Designed for OPFS-backed databases in a Web Worker.
• TypeScript support: Full TypeScript definitions included.

Browser FTS Compared With Native Turso

The browser FTS cache is enabled and is invalidated on writes, statement aborts, full rollbacks, and savepoint rollbacks. The main tradeoff compared with native Turso FTS is the writer implementation:

• Native Turso uses Tantivy's native IndexWriter path, including native filesystem and threading assumptions.
• This browser build uses a wasm-compatible single-segment writer path and maintains delete bitsets explicitly.
• The browser path prioritizes correctness for single-Worker OPFS usage over native indexing throughput.

Use native Turso for server-side workloads, concurrent writers, multi-process access, or maximum FTS indexing performance. Use this package when you need FTS inside a browser Worker with persistent OPFS storage.

Validation

Browser FTS is covered by a Worker/OPFS smoke test:

npm run build --workspace=packages/wasm
npm run test:fts-smoke --workspace=packages/wasm

The smoke test creates an OPFS-backed database in a Web Worker, creates an FTS index, verifies statement abort rollback, full rollback cache invalidation, inserts, updates, deletes, INSERT OR REPLACE, close/reopen persistence, bulk indexing, and a 30k+ character Wikipedia document insert/update/delete cycle.

Native FTS transaction regressions live in tests/integration/index_method/mod.rs and cover statement abort, full rollback, and savepoint rollback cache invalidation:

cargo test -p turso_tests --features fts test_fts_ --test integration

Installation

npm install @unni-craftsman/turso-fts

Getting Started

Persistent Browser Database

import { connect } from '@unni-craftsman/turso-fts';

// Create or open an OPFS-backed database from a Web Worker.
const db = await connect('my-database.db');

await db.exec('CREATE TABLE documents (id INTEGER PRIMARY KEY, content TEXT)');
await db.exec('CREATE INDEX documents_fts ON documents USING fts (content)');

await db.prepare('INSERT INTO documents VALUES (?, ?)').run(
  1,
  'the quick brown fox'
);

const rows = await db
  .prepare('SELECT id, content FROM documents WHERE fts_match(content, ?)')
  .all('fox');

console.log(rows);
// [{ id: 1, content: 'the quick brown fox' }]

Transactions

import { connect } from '@unni-craftsman/turso-fts';

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);
  }
});

// Execute transaction
await transaction([
  { name: 'Alice', email: '[email protected]' },
  { name: 'Bob', email: '[email protected]' }
]);

API Reference

For complete API documentation, see JavaScript API Reference.

Related Packages

• The @tursodatabase/serverless package provides a serverless driver with the same API.
• The @tursodatabase/sync package provides bidirectional sync between a local Turso database and Turso Cloud.

License

This project is licensed under the MIT license.

Support

• GitHub Issues
• Documentation
• Discord Community