@stratadb/core 0.6.0

package/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "stratadb-node"
+version = "0.6.0"
+edition = "2021"
+description = "Node.js bindings for StrataDB"
+license = "MIT"
+repository = "https://github.com/stratadb-labs/strata-node"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+napi = { version = "2", features = ["napi8", "async", "serde-json"] }
+napi-derive = "2"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+
+# Use git dependency during development
+stratadb = { git = "https://github.com/stratadb-labs/strata-core", branch = "main" }
+
+[build-dependencies]
+napi-build = "2"
+
+[profile.release]
+lto = true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Strata
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# strata-node
+
+Node.js SDK for [StrataDB](https://github.com/strata-systems/strata-core) - an embedded database for AI agents.
+
+NAPI-RS bindings embedding the Rust library directly in a native Node.js addon. No network hop, no serialization overhead beyond the Node/Rust boundary.
+
+## Installation
+
+### From npm (coming soon)
+
+```bash
+npm install stratadb
+```
+
+### From Source
+
+Requires Rust toolchain and Node.js:
+
+```bash
+git clone https://github.com/strata-systems/strata-node.git
+cd strata-node
+npm install
+npm run build
+```
+
+## Quick Start
+
+```javascript
+const { Strata } = require('stratadb');
+
+// Open a database (or use Strata.cache() for in-memory)
+const db = Strata.open('/path/to/data');
+
+// Key-value storage
+db.kvPut('user:123', 'Alice');
+console.log(db.kvGet('user:123'));  // "Alice"
+
+// Branch isolation (like git branches)
+db.createBranch('experiment');
+db.setBranch('experiment');
+console.log(db.kvGet('user:123'));  // null - isolated
+
+// Space organization within branches
+db.setSpace('conversations');
+db.kvPut('msg_001', 'hello');
+```
+
+## Features
+
+### Six Data Primitives
+
+| Primitive | Purpose | Key Methods |
+|-----------|---------|-------------|
+| **KV Store** | Working memory, config | `kvPut`, `kvGet`, `kvDelete`, `kvList` |
+| **Event Log** | Immutable audit trail | `eventAppend`, `eventGet`, `eventList` |
+| **State Cell** | CAS-based coordination | `stateSet`, `stateGet`, `stateCas` |
+| **JSON Store** | Structured documents | `jsonSet`, `jsonGet`, `jsonDelete` |
+| **Vector Store** | Embeddings, similarity search | `vectorUpsert`, `vectorSearch` |
+| **Branch** | Data isolation | `createBranch`, `setBranch`, `forkBranch` |
+
+### Vector Operations
+
+```javascript
+// Create a collection
+db.vectorCreateCollection('embeddings', 384, 'cosine');
+
+// Upsert with array
+const embedding = new Array(384).fill(0).map(() => Math.random());
+db.vectorUpsert('embeddings', 'doc-1', embedding, { title: 'Hello' });
+
+// Search returns matches with scores
+const results = db.vectorSearch('embeddings', embedding, 10);
+for (const match of results) {
+  console.log(`${match.key}: ${match.score}`);
+}
+```
+
+### Branch Operations
+
+```javascript
+// Fork current branch (copies all data)
+db.forkBranch('experiment');
+
+// Compare branches
+const diff = db.diffBranches('default', 'experiment');
+console.log(`Added: ${diff.summary.totalAdded}`);
+
+// Merge branches
+const result = db.mergeBranches('experiment', 'last_writer_wins');
+console.log(`Keys applied: ${result.keysApplied}`);
+```
+
+### Event Log
+
+```javascript
+// Append events
+db.eventAppend('tool_call', { tool: 'search', query: 'weather' });
+db.eventAppend('tool_call', { tool: 'calculator', expr: '2+2' });
+
+// Get by sequence number
+const event = db.eventGet(0);
+
+// List by type
+const toolCalls = db.eventList('tool_call');
+```
+
+### Compare-and-Swap (Version-based)
+
+```javascript
+// Initialize if not exists
+db.stateInit('counter', 0);
+
+// CAS is version-based - pass expected version, not expected value
+// Get current value and its version via stateSet (returns version)
+const version = db.stateSet('counter', 1);
+
+// Update only if version matches
+const newVersion = db.stateCas('counter', 2, version);  // (cell, new_value, expected_version)
+if (newVersion === null) {
+  console.log('CAS failed - version mismatch');
+}
+```
+
+## API Reference
+
+### Strata
+
+| Method | Description |
+|--------|-------------|
+| `Strata.open(path)` | Open database at path |
+| `Strata.cache()` | Create in-memory database |
+
+### KV Store
+
+| Method | Description |
+|--------|-------------|
+| `kvPut(key, value)` | Store a value |
+| `kvGet(key)` | Get a value (returns null if missing) |
+| `kvDelete(key)` | Delete a key |
+| `kvList(prefix?)` | List keys |
+| `kvHistory(key)` | Get version history |
+
+### State Cell
+
+| Method | Description |
+|--------|-------------|
+| `stateSet(cell, value)` | Set value |
+| `stateGet(cell)` | Get value |
+| `stateInit(cell, value)` | Initialize if not exists |
+| `stateCas(cell, newValue, expectedVersion?)` | Compare-and-swap (version-based) |
+| `stateHistory(cell)` | Get version history |
+
+### Event Log
+
+| Method | Description |
+|--------|-------------|
+| `eventAppend(type, payload)` | Append event |
+| `eventGet(sequence)` | Get by sequence |
+| `eventList(type)` | List by type |
+| `eventLen()` | Get count |
+
+### JSON Store
+
+| Method | Description |
+|--------|-------------|
+| `jsonSet(key, path, value)` | Set at JSONPath |
+| `jsonGet(key, path)` | Get at JSONPath |
+| `jsonDelete(key, path)` | Delete |
+| `jsonHistory(key)` | Get version history |
+| `jsonList(limit, prefix?, cursor?)` | List keys |
+
+### Vector Store
+
+| Method | Description |
+|--------|-------------|
+| `vectorCreateCollection(name, dim, metric?)` | Create collection |
+| `vectorDeleteCollection(name)` | Delete collection |
+| `vectorListCollections()` | List collections |
+| `vectorUpsert(collection, key, vector, metadata?)` | Insert/update |
+| `vectorGet(collection, key)` | Get vector |
+| `vectorDelete(collection, key)` | Delete vector |
+| `vectorSearch(collection, query, k)` | Search |
+| `vectorCollectionStats(collection)` | Get collection statistics |
+| `vectorBatchUpsert(collection, vectors)` | Batch insert/update vectors |
+
+### Branches
+
+| Method | Description |
+|--------|-------------|
+| `currentBranch()` | Get current branch |
+| `setBranch(name)` | Switch branch |
+| `createBranch(name)` | Create empty branch |
+| `forkBranch(dest)` | Fork with data copy |
+| `listBranches()` | List all branches |
+| `deleteBranch(name)` | Delete branch |
+| `branchExists(name)` | Check if branch exists |
+| `branchGet(name)` | Get branch metadata |
+| `diffBranches(a, b)` | Compare branches |
+| `mergeBranches(source, strategy?)` | Merge into current |
+
+### Spaces
+
+| Method | Description |
+|--------|-------------|
+| `currentSpace()` | Get current space |
+| `setSpace(name)` | Switch space |
+| `listSpaces()` | List spaces |
+| `deleteSpace(name)` | Delete space |
+| `deleteSpaceForce(name)` | Force delete space |
+
+### Database
+
+| Method | Description |
+|--------|-------------|
+| `ping()` | Health check |
+| `info()` | Get database info |
+| `flush()` | Flush to disk |
+| `compact()` | Trigger compaction |
+
+### Bundle Operations
+
+| Method | Description |
+|--------|-------------|
+| `branchExport(branch, path)` | Export branch to bundle file |
+| `branchImport(path)` | Import branch from bundle file |
+| `branchValidateBundle(path)` | Validate bundle file |
+
+## TypeScript
+
+Full TypeScript definitions are included:
+
+```typescript
+import { Strata, JsonValue, SearchMatch } from 'stratadb';
+
+const db = Strata.cache();
+db.kvPut('key', { count: 42 });
+const value: JsonValue = db.kvGet('key');
+```
+
+## Development
+
+```bash
+# Install dev dependencies
+npm install
+
+# Build native module
+npm run build
+
+# Run tests
+npm test
+```
+
+## License
+
+MIT

package/__tests__/strata.test.js

@@ -0,0 +1,217 @@
+/**
+ * Integration tests for the StrataDB Node.js SDK.
+ */
+
+const { Strata } = require('../index');
+
+describe('Strata', () => {
+  let db;
+
+  beforeEach(() => {
+    db = Strata.cache();
+  });
+
+  describe('KV Store', () => {
+    test('put and get', () => {
+      db.kvPut('key1', 'value1');
+      expect(db.kvGet('key1')).toBe('value1');
+    });
+
+    test('put and get object', () => {
+      db.kvPut('config', { theme: 'dark', count: 42 });
+      const result = db.kvGet('config');
+      expect(result.theme).toBe('dark');
+      expect(result.count).toBe(42);
+    });
+
+    test('get missing returns null', () => {
+      expect(db.kvGet('nonexistent')).toBeNull();
+    });
+
+    test('delete', () => {
+      db.kvPut('to_delete', 'value');
+      expect(db.kvDelete('to_delete')).toBe(true);
+      expect(db.kvGet('to_delete')).toBeNull();
+    });
+
+    test('list', () => {
+      db.kvPut('user:1', 'alice');
+      db.kvPut('user:2', 'bob');
+      db.kvPut('item:1', 'book');
+
+      const allKeys = db.kvList();
+      expect(allKeys.length).toBe(3);
+
+      const userKeys = db.kvList('user:');
+      expect(userKeys.length).toBe(2);
+    });
+  });
+
+  describe('State Cell', () => {
+    test('set and get', () => {
+      db.stateSet('counter', 100);
+      expect(db.stateGet('counter')).toBe(100);
+    });
+
+    test('init', () => {
+      db.stateInit('status', 'pending');
+      expect(db.stateGet('status')).toBe('pending');
+    });
+
+    test('cas', () => {
+      // CAS is version-based, not value-based
+      const version = db.stateSet('value', 1);
+      // Try to update with correct version
+      const newVersion = db.stateCas('value', 2, version);
+      expect(newVersion).not.toBeNull();
+      expect(db.stateGet('value')).toBe(2);
+      // Try with wrong version - should fail
+      const result = db.stateCas('value', 3, 999);
+      expect(result).toBeNull(); // CAS failed
+    });
+  });
+
+  describe('Event Log', () => {
+    test('append and get', () => {
+      db.eventAppend('user_action', { action: 'click', target: 'button' });
+      expect(db.eventLen()).toBe(1);
+
+      const event = db.eventGet(0);
+      expect(event).not.toBeNull();
+      expect(event.value.action).toBe('click');
+    });
+
+    test('list by type', () => {
+      db.eventAppend('click', { x: 10 });
+      db.eventAppend('scroll', { y: 100 });
+      db.eventAppend('click', { x: 20 });
+
+      const clicks = db.eventList('click');
+      expect(clicks.length).toBe(2);
+    });
+  });
+
+  describe('JSON Store', () => {
+    test('set and get', () => {
+      db.jsonSet('config', '$', { theme: 'dark', lang: 'en' });
+      const result = db.jsonGet('config', '$');
+      expect(result.theme).toBe('dark');
+    });
+
+    test('get path', () => {
+      db.jsonSet('config', '$', { theme: 'dark', lang: 'en' });
+      const theme = db.jsonGet('config', '$.theme');
+      expect(theme).toBe('dark');
+    });
+
+    test('list', () => {
+      db.jsonSet('doc1', '$', { a: 1 });
+      db.jsonSet('doc2', '$', { b: 2 });
+      const result = db.jsonList(100); // limit is required
+      expect(result.keys.length).toBe(2);
+    });
+  });
+
+  describe('Vector Store', () => {
+    test('create collection', () => {
+      db.vectorCreateCollection('embeddings', 4);
+      const collections = db.vectorListCollections();
+      expect(collections.some((c) => c.name === 'embeddings')).toBe(true);
+    });
+
+    test('upsert and search', () => {
+      db.vectorCreateCollection('embeddings', 4);
+
+      const v1 = [1.0, 0.0, 0.0, 0.0];
+      const v2 = [0.0, 1.0, 0.0, 0.0];
+
+      db.vectorUpsert('embeddings', 'v1', v1);
+      db.vectorUpsert('embeddings', 'v2', v2);
+
+      const results = db.vectorSearch('embeddings', v1, 2);
+      expect(results.length).toBe(2);
+      expect(results[0].key).toBe('v1'); // Most similar
+    });
+
+    test('upsert with metadata', () => {
+      db.vectorCreateCollection('docs', 4);
+      const vec = [1.0, 0.0, 0.0, 0.0];
+      db.vectorUpsert('docs', 'doc1', vec, { title: 'Hello' });
+
+      const result = db.vectorGet('docs', 'doc1');
+      expect(result.metadata.title).toBe('Hello');
+    });
+  });
+
+  describe('Branches', () => {
+    test('create and list', () => {
+      db.createBranch('feature');
+      const branches = db.listBranches();
+      expect(branches).toContain('default');
+      expect(branches).toContain('feature');
+    });
+
+    test('switch', () => {
+      db.kvPut('x', 1);
+      db.createBranch('feature');
+      db.setBranch('feature');
+
+      // Data isolated in new branch
+      expect(db.kvGet('x')).toBeNull();
+
+      db.kvPut('x', 2);
+      db.setBranch('default');
+      expect(db.kvGet('x')).toBe(1);
+    });
+
+    test('fork', () => {
+      db.kvPut('shared', 'original');
+      const result = db.forkBranch('forked');
+      expect(result.keysCopied).toBeGreaterThan(0);
+
+      db.setBranch('forked');
+      expect(db.kvGet('shared')).toBe('original');
+    });
+
+    test('current branch', () => {
+      expect(db.currentBranch()).toBe('default');
+      db.createBranch('test');
+      db.setBranch('test');
+      expect(db.currentBranch()).toBe('test');
+    });
+  });
+
+  describe('Spaces', () => {
+    test('list spaces', () => {
+      const spaces = db.listSpaces();
+      expect(spaces).toContain('default');
+    });
+
+    test('switch space', () => {
+      db.kvPut('key', 'value1');
+      db.setSpace('other');
+      expect(db.kvGet('key')).toBeNull();
+
+      db.kvPut('key', 'value2');
+      db.setSpace('default');
+      expect(db.kvGet('key')).toBe('value1');
+    });
+
+    test('current space', () => {
+      expect(db.currentSpace()).toBe('default');
+    });
+  });
+
+  describe('Database', () => {
+    test('ping', () => {
+      const version = db.ping();
+      expect(version).toBeTruthy();
+    });
+
+    test('info', () => {
+      const info = db.info();
+      expect(info.version).toBeTruthy();
+      expect(info.branchCount).toBeGreaterThanOrEqual(1);
+    });
+  });
+});

package/build.rs

@@ -0,0 +1,5 @@
+extern crate napi_build;
+
+fn main() {
+    napi_build::setup();
+}