@wiscale/velesdb-sdk 0.5.0

package/dist/index.d.ts

@@ -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 };