Browser / WebSocket SDK

The @particledb/web package is a browser-compatible TypeScript SDK that connects to ParticleDB via a WebSocket proxy. It provides SQL queries, vector search, KV operations, RAG, AI functions, and real-time pub/sub — all from the browser.

Installation

npm install @particledb/web

Quick Start

import { ParticleDBWeb } from '@particledb/web';

const db = new ParticleDBWeb({ wsUrl: 'ws://localhost:8080' });
await db.connect();

// SQL queries
const result = await db.query('SELECT * FROM users WHERE id = 1');
console.log(result.rows);

// Vector search
const results = await db.vector.search('docs', 'embedding', [0.1, 0.2, 0.3], 5);

// Key-value
await db.kv.set('key', 'value');
const val = await db.kv.get('key');

// RAG
const answer = await db.rag.query('What is ParticleDB?',
  'documents', 'embedding', 'content');

// AI
const embedding = await db.ai.embed('Hello world');

// Pub/sub
db.subscribe('events', (payload) => console.log('Event:', payload));

db.disconnect();

Configuration

const db = new ParticleDBWeb({
  wsUrl: 'ws://localhost:8080',     // WebSocket URL
  httpUrl: 'http://localhost:8080', // HTTP API URL (future use)
  apiKey: 'your-api-key',          // Authentication token
  reconnect: true,                  // Auto-reconnect (default: true)
  maxRetries: 5,                    // Max reconnect attempts (default: 5)
});

SQL Queries

// Query with results
const result = await db.query('SELECT * FROM users');
console.log(result.rows);

// Execute DML
const affected = await db.execute('INSERT INTO users (id, name) VALUES (1, "alice")');

Vector Search

const results = await db.vector.search('documents', 'embedding', [0.1, 0.2, 0.3], 5);
for (const { row, distance } of results) {
  console.log(`${row.title}: ${distance}`);
}

Key-Value Operations

await db.kv.set('session:123', '{"user":"alice"}');
const val = await db.kv.get('session:123');
await db.kv.delete('session:123');

RAG (Retrieval-Augmented Generation)

const answer = await db.rag.query(
  'What is ParticleDB?',
  'documents', 'embedding', 'content'
);
console.log(answer);

AI Functions

const embedding = await db.ai.embed('Hello world');
const text = await db.ai.generate('Explain vector databases');
const label = await db.ai.classify('Great!', ['positive', 'negative']);

Real-Time Pub/Sub

Subscribe to server-side events in real time:

// Subscribe to a channel
db.subscribe('events', (payload) => {
  console.log('Received event:', payload);
});

// Multiple subscriptions
db.subscribe('cdc_users', (event) => {
  console.log(`User ${event.event}: ${event.payload}`);
});

Architecture

The SDK uses a layered architecture:

• WebSocketTransport — Manages WebSocket connection lifecycle, message correlation, reconnection, and pub/sub routing
• ParticleDBWeb — Main client providing query(), execute(), subscribe(), and lazy-initialized operation modules
• SqlBuilder — Pure-function SQL generation (no dependencies, independently testable)
• VectorOps / KVOps / RAGOps / AIOps — Typed operation wrappers composing SqlBuilder + client query functions

Next Steps

• TypeScript SDK — Full Node.js SDK with PG wire, gRPC, and streaming
• SQL Reference — Full SQL syntax
• HTTP API — REST API reference