sqlite-actor 0.1.0 → 0.1.2

package/README.md

@@ -1,37 +1,27 @@
-# Actordb 🎭
+# sqlite-actor 🎭
 
-A high-performance SQLite + `sqlite-vec` vector database designed for Actor platforms (like Cloudflare Durable Objects) that support durable key-value storage.
+> [!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
-- **Vector Search in Actors**: Enable RAG and semantic search directly within your Durable Objects.
-- **Zero-Config**: WASM is inlined. Just `import { SqliteActor }` and you're ready to go.
-- **Performance**: Optimized with SIMD and a slim C VFS bridge.
-- **Reliable**: Professional VFS implementation with multi-page support, VACUUM, and ACID compliance (through underlying KV).
-
-## Architecture
-
-Actordb bridges the gap between the SQLite engine and the Actor's KV storage using a custom VFS (Virtual File System) implementation.
-
-```mermaid
-graph TD
-    subgraph "Application"
-        App[Your Code] --> SDK[SqliteActor SDK]
-    end
-
-    subgraph "Actordb Core (WASM)"
-        SDK --> WASM[WASM DB]
-        WASM --> VFS[C VFS Bridge]
-        VFS --> KV[JS KV Interface]
-    end
-
-    subgraph "Actor Platform (e.g. Cloudflare)"
-        KV --> Storage[Durable Storage]
-        Storage --> Replication[Global Replication]
-    end
-
-    style KV fill:#f96,stroke:#333,stroke-width:2px
-    note[Actor platform provides the KV Interface]
-```
+- **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
 
@@ -49,13 +39,13 @@ export class MyVectorActor {
     // Initialize DB with the Durable Object storage (kv)
     const db = await SqliteActor.create(this.state.storage);
 
-    // Create a vector table
+    // Create a vector table powered by sqlite-vec
     db.execute("CREATE VIRTUAL TABLE vec_items USING vec0(embedding float[3]);");
 
-    // Insert a vector
+    // Insert a vector embedding
     db.execute("INSERT INTO vec_items(rowid, embedding) VALUES (1, '[1.1, 2.2, 3.3]');");
 
-    // Perform vector search
+    // 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));
@@ -63,22 +53,18 @@ export class MyVectorActor {
 }
 ```
 
-## Development
+## Development setup (Building from Source)
 
-### Setup
-Ensure you have [Emscripten](https://emscripten.org/docs/getting_started/downloads.html) installed and in your path. Then, download the SQLite and `sqlite-vec` sources:
+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
-```
 
-### Build (WASM + TypeScript)
-```bash
+# Compile the WASM and build the TypeScript SDK
 npm run build
-```
 
-### Test
-```bash
+# Run the test suite
 npm test
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlite-actor",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "SQLite + sqlite-vec vector database for actor platforms",
   "main": "dist/index.js",