@wiscale/velesdb-sdk 0.5.0

package/README.md

@@ -0,0 +1,160 @@
+# @velesdb/sdk
+
+Official TypeScript SDK for VelesDB - Vector Search in Microseconds.
+
+## Installation
+
+```bash
+npm install @velesdb/sdk
+```
+
+## Quick Start
+
+### WASM Backend (Browser/Node.js)
+
+```typescript
+import { VelesDB } from '@velesdb/sdk';
+
+// Initialize with WASM backend
+const db = new VelesDB({ backend: 'wasm' });
+await db.init();
+
+// Create a collection
+await db.createCollection('documents', {
+  dimension: 768,  // BERT embedding dimension
+  metric: 'cosine'
+});
+
+// Insert vectors
+await db.insert('documents', {
+  id: 'doc-1',
+  vector: new Float32Array(768).fill(0.1),
+  payload: { title: 'Hello World', category: 'greeting' }
+});
+
+// Batch insert
+await db.insertBatch('documents', [
+  { id: 'doc-2', vector: [...], payload: { title: 'Second doc' } },
+  { id: 'doc-3', vector: [...], payload: { title: 'Third doc' } },
+]);
+
+// Search
+const results = await db.search('documents', queryVector, { k: 5 });
+console.log(results);
+// [{ id: 'doc-1', score: 0.95, payload: { title: '...' } }, ...]
+
+// Cleanup
+await db.close();
+```
+
+### REST Backend (Server)
+
+```typescript
+import { VelesDB } from '@velesdb/sdk';
+
+const db = new VelesDB({
+  backend: 'rest',
+  url: 'http://localhost:8080',
+  apiKey: 'your-api-key' // optional
+});
+
+await db.init();
+
+// Same API as WASM backend
+await db.createCollection('products', { dimension: 1536 });
+await db.insert('products', { id: 'p1', vector: [...] });
+const results = await db.search('products', query, { k: 10 });
+```
+
+## API Reference
+
+### `new VelesDB(config)`
+
+Create a new VelesDB client.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `backend` | `'wasm' \| 'rest'` | Yes | Backend type |
+| `url` | `string` | REST only | Server URL |
+| `apiKey` | `string` | No | API key for authentication |
+| `timeout` | `number` | No | Request timeout (ms, default: 30000) |
+
+### `db.init()`
+
+Initialize the client. Must be called before any operations.
+
+### `db.createCollection(name, config)`
+
+Create a new collection.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `dimension` | `number` | Required | Vector dimension |
+| `metric` | `'cosine' \| 'euclidean' \| 'dot'` | `'cosine'` | Distance metric |
+
+### `db.insert(collection, document)`
+
+Insert a single vector.
+
+```typescript
+await db.insert('docs', {
+  id: 'unique-id',
+  vector: [0.1, 0.2, ...],  // or Float32Array
+  payload: { key: 'value' } // optional metadata
+});
+```
+
+### `db.insertBatch(collection, documents)`
+
+Insert multiple vectors efficiently.
+
+### `db.search(collection, query, options)`
+
+Search for similar vectors.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `k` | `number` | `10` | Number of results |
+| `filter` | `object` | - | Filter expression |
+| `includeVectors` | `boolean` | `false` | Include vectors in results |
+
+### `db.delete(collection, id)`
+
+Delete a vector by ID. Returns `true` if deleted.
+
+### `db.get(collection, id)`
+
+Get a vector by ID. Returns `null` if not found.
+
+### `db.close()`
+
+Close the client and release resources.
+
+## Error Handling
+
+```typescript
+import { VelesDBError, ValidationError, ConnectionError, NotFoundError } from '@velesdb/sdk';
+
+try {
+  await db.search('nonexistent', query);
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.log('Collection not found');
+  } else if (error instanceof ValidationError) {
+    console.log('Invalid input:', error.message);
+  } else if (error instanceof ConnectionError) {
+    console.log('Connection failed:', error.message);
+  }
+}
+```
+
+## Performance Tips
+
+1. **Use batch operations** for multiple inserts
+2. **Reuse Float32Array** for queries when possible
+3. **Use WASM backend** for browser apps (no network latency)
+4. **Pre-initialize** the client at app startup
+
+## License
+
+Elastic License 2.0 (ELv2) - See [LICENSE](../../LICENSE) for details.

package/dist/index.d.mts

@@ -0,0 +1,299 @@
+/**
+ * VelesDB TypeScript SDK - Type Definitions
+ * @packageDocumentation
+ */
+/** Supported distance metrics for vector similarity */
+type DistanceMetric = 'cosine' | 'euclidean' | 'dot';
+/** Backend type for VelesDB connection */
+type BackendType = 'wasm' | 'rest';
+/** Configuration options for VelesDB client */
+interface VelesDBConfig {
+    /** Backend type: 'wasm' for browser/Node.js, 'rest' for server */
+    backend: BackendType;
+    /** REST API URL (required for 'rest' backend) */
+    url?: string;
+    /** API key for authentication (optional) */
+    apiKey?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/** Collection configuration */
+interface CollectionConfig {
+    /** Vector dimension (e.g., 768 for BERT, 1536 for GPT) */
+    dimension: number;
+    /** Distance metric (default: 'cosine') */
+    metric?: DistanceMetric;
+    /** Optional collection description */
+    description?: string;
+}
+/** Collection metadata */
+interface Collection {
+    /** Collection name */
+    name: string;
+    /** Vector dimension */
+    dimension: number;
+    /** Distance metric */
+    metric: DistanceMetric;
+    /** Number of vectors */
+    count: number;
+    /** Creation timestamp */
+    createdAt?: Date;
+}
+/** Vector document to insert */
+interface VectorDocument {
+    /** Unique identifier */
+    id: string | number;
+    /** Vector data */
+    vector: number[] | Float32Array;
+    /** Optional payload/metadata */
+    payload?: Record<string, unknown>;
+}
+/** Search options */
+interface SearchOptions {
+    /** Number of results to return (default: 10) */
+    k?: number;
+    /** Filter expression (optional) */
+    filter?: Record<string, unknown>;
+    /** Include vectors in results (default: false) */
+    includeVectors?: boolean;
+}
+/** Search result */
+interface SearchResult {
+    /** Document ID */
+    id: string | number;
+    /** Similarity score */
+    score: number;
+    /** Document payload (if requested) */
+    payload?: Record<string, unknown>;
+    /** Vector data (if includeVectors is true) */
+    vector?: number[];
+}
+/** Backend interface that all backends must implement */
+interface IVelesDBBackend {
+    /** Initialize the backend */
+    init(): Promise<void>;
+    /** Check if backend is initialized */
+    isInitialized(): boolean;
+    /** Create a new collection */
+    createCollection(name: string, config: CollectionConfig): Promise<void>;
+    /** Delete a collection */
+    deleteCollection(name: string): Promise<void>;
+    /** Get collection info */
+    getCollection(name: string): Promise<Collection | null>;
+    /** List all collections */
+    listCollections(): Promise<Collection[]>;
+    /** Insert a single vector */
+    insert(collection: string, doc: VectorDocument): Promise<void>;
+    /** Insert multiple vectors */
+    insertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
+    /** Search for similar vectors */
+    search(collection: string, query: number[] | Float32Array, options?: SearchOptions): Promise<SearchResult[]>;
+    /** Delete a vector by ID */
+    delete(collection: string, id: string | number): Promise<boolean>;
+    /** Get a vector by ID */
+    get(collection: string, id: string | number): Promise<VectorDocument | null>;
+    /** Close/cleanup the backend */
+    close(): Promise<void>;
+}
+/** Error types */
+declare class VelesDBError extends Error {
+    readonly code: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, code: string, cause?: Error | undefined);
+}
+declare class ConnectionError extends VelesDBError {
+    constructor(message: string, cause?: Error);
+}
+declare class ValidationError extends VelesDBError {
+    constructor(message: string);
+}
+declare class NotFoundError extends VelesDBError {
+    constructor(resource: string);
+}
+
+/**
+ * VelesDB Client - Unified interface for all backends
+ */
+
+/**
+ * VelesDB Client
+ *
+ * Provides a unified interface for interacting with VelesDB
+ * using either WASM (browser/Node.js) or REST API backends.
+ *
+ * @example
+ * ```typescript
+ * const db = new VelesDB({ backend: 'wasm' });
+ * await db.init();
+ *
+ * await db.createCollection('embeddings', { dimension: 768, metric: 'cosine' });
+ * await db.insert('embeddings', { id: 'doc1', vector: [...], payload: { title: 'Hello' } });
+ *
+ * const results = await db.search('embeddings', queryVector, { k: 5 });
+ * ```
+ */
+declare class VelesDB {
+    private readonly config;
+    private backend;
+    private initialized;
+    /**
+     * Create a new VelesDB client
+     *
+     * @param config - Client configuration
+     * @throws {ValidationError} If configuration is invalid
+     */
+    constructor(config: VelesDBConfig);
+    private validateConfig;
+    private createBackend;
+    /**
+     * Initialize the client
+     * Must be called before any other operations
+     */
+    init(): Promise<void>;
+    /**
+     * Check if client is initialized
+     */
+    isInitialized(): boolean;
+    private ensureInitialized;
+    /**
+     * Create a new collection
+     *
+     * @param name - Collection name
+     * @param config - Collection configuration
+     */
+    createCollection(name: string, config: CollectionConfig): Promise<void>;
+    /**
+     * Delete a collection
+     *
+     * @param name - Collection name
+     */
+    deleteCollection(name: string): Promise<void>;
+    /**
+     * Get collection information
+     *
+     * @param name - Collection name
+     * @returns Collection info or null if not found
+     */
+    getCollection(name: string): Promise<Collection | null>;
+    /**
+     * List all collections
+     *
+     * @returns Array of collections
+     */
+    listCollections(): Promise<Collection[]>;
+    /**
+     * Insert a vector document
+     *
+     * @param collection - Collection name
+     * @param doc - Document to insert
+     */
+    insert(collection: string, doc: VectorDocument): Promise<void>;
+    /**
+     * Insert multiple vector documents
+     *
+     * @param collection - Collection name
+     * @param docs - Documents to insert
+     */
+    insertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
+    private validateDocument;
+    /**
+     * Search for similar vectors
+     *
+     * @param collection - Collection name
+     * @param query - Query vector
+     * @param options - Search options
+     * @returns Search results sorted by relevance
+     */
+    search(collection: string, query: number[] | Float32Array, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Delete a vector by ID
+     *
+     * @param collection - Collection name
+     * @param id - Document ID
+     * @returns true if deleted, false if not found
+     */
+    delete(collection: string, id: string | number): Promise<boolean>;
+    /**
+     * Get a vector by ID
+     *
+     * @param collection - Collection name
+     * @param id - Document ID
+     * @returns Document or null if not found
+     */
+    get(collection: string, id: string | number): Promise<VectorDocument | null>;
+    /**
+     * Close the client and release resources
+     */
+    close(): Promise<void>;
+    /**
+     * Get the current backend type
+     */
+    get backendType(): string;
+}
+
+/**
+ * WASM Backend for VelesDB
+ *
+ * Uses velesdb-wasm for in-browser/Node.js vector operations
+ */
+
+/**
+ * WASM Backend
+ *
+ * Provides vector storage using WebAssembly for optimal performance
+ * in browser and Node.js environments.
+ */
+declare class WasmBackend implements IVelesDBBackend {
+    private wasmModule;
+    private collections;
+    private _initialized;
+    init(): Promise<void>;
+    isInitialized(): boolean;
+    private ensureInitialized;
+    createCollection(name: string, config: CollectionConfig): Promise<void>;
+    deleteCollection(name: string): Promise<void>;
+    getCollection(name: string): Promise<Collection | null>;
+    listCollections(): Promise<Collection[]>;
+    insert(collectionName: string, doc: VectorDocument): Promise<void>;
+    insertBatch(collectionName: string, docs: VectorDocument[]): Promise<void>;
+    search(collectionName: string, query: number[] | Float32Array, options?: SearchOptions): Promise<SearchResult[]>;
+    delete(collectionName: string, id: string | number): Promise<boolean>;
+    get(collectionName: string, id: string | number): Promise<VectorDocument | null>;
+    close(): Promise<void>;
+    private toNumericId;
+}
+
+/**
+ * REST Backend for VelesDB
+ *
+ * Connects to VelesDB server via REST API
+ */
+
+/**
+ * REST Backend
+ *
+ * Provides vector storage via VelesDB REST API server.
+ */
+declare class RestBackend implements IVelesDBBackend {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly timeout;
+    private _initialized;
+    constructor(url: string, apiKey?: string, timeout?: number);
+    init(): Promise<void>;
+    isInitialized(): boolean;
+    private ensureInitialized;
+    private request;
+    createCollection(name: string, config: CollectionConfig): Promise<void>;
+    deleteCollection(name: string): Promise<void>;
+    getCollection(name: string): Promise<Collection | null>;
+    listCollections(): Promise<Collection[]>;
+    insert(collection: string, doc: VectorDocument): Promise<void>;
+    insertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
+    search(collection: string, query: number[] | Float32Array, options?: SearchOptions): Promise<SearchResult[]>;
+    delete(collection: string, id: string | number): Promise<boolean>;
+    get(collection: string, id: string | number): Promise<VectorDocument | null>;
+    close(): Promise<void>;
+}
+
+export { type BackendType, type Collection, type CollectionConfig, ConnectionError, type DistanceMetric, type IVelesDBBackend, NotFoundError, RestBackend, type SearchOptions, type SearchResult, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, WasmBackend };