# sqlite-actor 🎭

> [!IMPORTANT]
> `sqlite-actor` is pre-v1, so expect breaking changes!

A WebAssembly (WASM) build of SQLite designed specifically to run in single-threaded Actor environments (such as Cloudflare Durable Objects). 

Since modern Actor platforms increasingly provide robust native SQLite storage (instead of purely key-value), `sqlite-actor` gives you access to a custom WASM SQLite build that you can run *on top of* your actor's standard storage.

**Why use this instead of the platform's native SQLite?**
To get access to SQLite extensions that aren't natively supported by your platform!

## Supported Extensions

Currently, `sqlite-actor` bundles the following extensions directly into its WASM build:

- **[sqlite-vec](https://github.com/asg017/sqlite-vec)**: A vector search extension that enables RAG and semantic search directly isolated inside your Actors.

*(Note: We plan to support more extensions in the future based on user requests. Please open a GitHub issue if you need another extension.)*

## Features
- **Zero-Config**: The WASM binary is heavily optimized and compiled directly into the JavaScript bundle. No `.wasm` file fetching is required—just `import` and run.
- **Synchronous API**: Designed for the single-threaded nature of Actors, the SDK is completely synchronous after the initial load.
- **VFS Bridge**: It uses a memory-first Virtual File System (VFS) to back the database to the actor's provided key-value storage.

## Getting Started

### Installation
```bash
npm install sqlite-actor
```

### Basic Usage (Cloudflare Durable Objects)
```javascript
import { SqliteActor } from "sqlite-actor";

export class MyVectorActor {
  async fetch(request) {
    // Initialize DB with the Durable Object storage (kv)
    const db = await SqliteActor.create(this.state.storage);

    // Create a vector table powered by sqlite-vec
    db.execute("CREATE VIRTUAL TABLE vec_items USING vec0(embedding float[3]);");

    // Insert a vector embedding
    db.execute("INSERT INTO vec_items(rowid, embedding) VALUES (1, '[1.1, 2.2, 3.3]');");

    // Perform a vector search
    const results = db.query("SELECT rowid, distance FROM vec_items WHERE embedding MATCH '[1.0, 2.0, 3.0]' AND k = 1;");
    
    return new Response(JSON.stringify(results));
  }
}
```

## Development setup (Building from Source)

Ensure you have [Emscripten](https://emscripten.org/docs/getting_started/downloads.html) installed locally.

```bash
# Fetch upstream SQLite and sqlite-vec C sources
npm run setup

# Compile the WASM and build the TypeScript SDK
npm run build

# Run the test suite
npm test
```

## License
MIT
