@wiscale/velesdb-sdk 0.5.0

package/dist/index.mjs

@@ -0,0 +1,647 @@
+// src/types.ts
+var VelesDBError = class extends Error {
+  constructor(message, code, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+    this.name = "VelesDBError";
+  }
+};
+var ConnectionError = class extends VelesDBError {
+  constructor(message, cause) {
+    super(message, "CONNECTION_ERROR", cause);
+    this.name = "ConnectionError";
+  }
+};
+var ValidationError = class extends VelesDBError {
+  constructor(message) {
+    super(message, "VALIDATION_ERROR");
+    this.name = "ValidationError";
+  }
+};
+var NotFoundError = class extends VelesDBError {
+  constructor(resource) {
+    super(`${resource} not found`, "NOT_FOUND");
+    this.name = "NotFoundError";
+  }
+};
+
+// src/backends/wasm.ts
+var WasmBackend = class {
+  constructor() {
+    this.wasmModule = null;
+    this.collections = /* @__PURE__ */ new Map();
+    this._initialized = false;
+  }
+  async init() {
+    if (this._initialized) {
+      return;
+    }
+    try {
+      this.wasmModule = await import("velesdb-wasm");
+      await this.wasmModule.default();
+      this._initialized = true;
+    } catch (error) {
+      throw new ConnectionError(
+        "Failed to initialize WASM module",
+        error instanceof Error ? error : void 0
+      );
+    }
+  }
+  isInitialized() {
+    return this._initialized;
+  }
+  ensureInitialized() {
+    if (!this._initialized || !this.wasmModule) {
+      throw new ConnectionError("WASM backend not initialized");
+    }
+  }
+  async createCollection(name, config) {
+    this.ensureInitialized();
+    if (this.collections.has(name)) {
+      throw new VelesDBError(`Collection '${name}' already exists`, "COLLECTION_EXISTS");
+    }
+    const metric = config.metric ?? "cosine";
+    const store = new this.wasmModule.VectorStore(config.dimension, metric);
+    this.collections.set(name, {
+      config: { ...config, metric },
+      store,
+      payloads: /* @__PURE__ */ new Map(),
+      createdAt: /* @__PURE__ */ new Date()
+    });
+  }
+  async deleteCollection(name) {
+    this.ensureInitialized();
+    const collection = this.collections.get(name);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${name}'`);
+    }
+    collection.store.free();
+    this.collections.delete(name);
+  }
+  async getCollection(name) {
+    this.ensureInitialized();
+    const collection = this.collections.get(name);
+    if (!collection) {
+      return null;
+    }
+    return {
+      name,
+      dimension: collection.config.dimension,
+      metric: collection.config.metric ?? "cosine",
+      count: collection.store.len,
+      createdAt: collection.createdAt
+    };
+  }
+  async listCollections() {
+    this.ensureInitialized();
+    const result = [];
+    for (const [name, data] of this.collections) {
+      result.push({
+        name,
+        dimension: data.config.dimension,
+        metric: data.config.metric ?? "cosine",
+        count: data.store.len,
+        createdAt: data.createdAt
+      });
+    }
+    return result;
+  }
+  async insert(collectionName, doc) {
+    this.ensureInitialized();
+    const collection = this.collections.get(collectionName);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${collectionName}'`);
+    }
+    const id = this.toNumericId(doc.id);
+    const vector = doc.vector instanceof Float32Array ? doc.vector : new Float32Array(doc.vector);
+    if (vector.length !== collection.config.dimension) {
+      throw new VelesDBError(
+        `Vector dimension mismatch: expected ${collection.config.dimension}, got ${vector.length}`,
+        "DIMENSION_MISMATCH"
+      );
+    }
+    collection.store.insert(BigInt(id), vector);
+    if (doc.payload) {
+      collection.payloads.set(String(doc.id), doc.payload);
+    }
+  }
+  async insertBatch(collectionName, docs) {
+    this.ensureInitialized();
+    const collection = this.collections.get(collectionName);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${collectionName}'`);
+    }
+    for (const doc of docs) {
+      const vectorLen = Array.isArray(doc.vector) ? doc.vector.length : doc.vector.length;
+      if (vectorLen !== collection.config.dimension) {
+        throw new VelesDBError(
+          `Vector dimension mismatch for doc ${doc.id}: expected ${collection.config.dimension}, got ${vectorLen}`,
+          "DIMENSION_MISMATCH"
+        );
+      }
+    }
+    collection.store.reserve(docs.length);
+    const batch = docs.map((doc) => [
+      BigInt(this.toNumericId(doc.id)),
+      Array.isArray(doc.vector) ? doc.vector : Array.from(doc.vector)
+    ]);
+    collection.store.insert_batch(batch);
+    for (const doc of docs) {
+      if (doc.payload) {
+        collection.payloads.set(String(doc.id), doc.payload);
+      }
+    }
+  }
+  async search(collectionName, query, options) {
+    this.ensureInitialized();
+    const collection = this.collections.get(collectionName);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${collectionName}'`);
+    }
+    const queryVector = query instanceof Float32Array ? query : new Float32Array(query);
+    if (queryVector.length !== collection.config.dimension) {
+      throw new VelesDBError(
+        `Query dimension mismatch: expected ${collection.config.dimension}, got ${queryVector.length}`,
+        "DIMENSION_MISMATCH"
+      );
+    }
+    const k = options?.k ?? 10;
+    const rawResults = collection.store.search(queryVector, k);
+    return rawResults.map(([id, score]) => {
+      const stringId = String(id);
+      const result = {
+        id: stringId,
+        score
+      };
+      const payload = collection.payloads.get(stringId);
+      if (payload) {
+        result.payload = payload;
+      }
+      return result;
+    });
+  }
+  async delete(collectionName, id) {
+    this.ensureInitialized();
+    const collection = this.collections.get(collectionName);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${collectionName}'`);
+    }
+    const numericId = this.toNumericId(id);
+    const removed = collection.store.remove(BigInt(numericId));
+    if (removed) {
+      collection.payloads.delete(String(id));
+    }
+    return removed;
+  }
+  async get(collectionName, id) {
+    this.ensureInitialized();
+    const collection = this.collections.get(collectionName);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${collectionName}'`);
+    }
+    const payload = collection.payloads.get(String(id));
+    if (!payload) {
+      return null;
+    }
+    return {
+      id,
+      vector: [],
+      // Not available in current WASM impl
+      payload
+    };
+  }
+  async close() {
+    for (const [, data] of this.collections) {
+      data.store.free();
+    }
+    this.collections.clear();
+    this._initialized = false;
+  }
+  toNumericId(id) {
+    if (typeof id === "number") {
+      return id;
+    }
+    const parsed = parseInt(id, 10);
+    if (!isNaN(parsed)) {
+      return parsed;
+    }
+    let hash = 0;
+    for (let i = 0; i < id.length; i++) {
+      const char = id.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash;
+    }
+    return Math.abs(hash);
+  }
+};
+
+// src/backends/rest.ts
+var RestBackend = class {
+  constructor(url, apiKey, timeout = 3e4) {
+    this._initialized = false;
+    this.baseUrl = url.replace(/\/$/, "");
+    this.apiKey = apiKey;
+    this.timeout = timeout;
+  }
+  async init() {
+    if (this._initialized) {
+      return;
+    }
+    try {
+      const response = await this.request("GET", "/health");
+      if (response.error) {
+        throw new Error(response.error.message);
+      }
+      this._initialized = true;
+    } catch (error) {
+      throw new ConnectionError(
+        `Failed to connect to VelesDB server at ${this.baseUrl}`,
+        error instanceof Error ? error : void 0
+      );
+    }
+  }
+  isInitialized() {
+    return this._initialized;
+  }
+  ensureInitialized() {
+    if (!this._initialized) {
+      throw new ConnectionError("REST backend not initialized");
+    }
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      const data = await response.json();
+      if (!response.ok) {
+        return {
+          error: {
+            code: data.code ?? "UNKNOWN_ERROR",
+            message: data.message ?? `HTTP ${response.status}`
+          }
+        };
+      }
+      return { data };
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new ConnectionError("Request timeout");
+      }
+      throw new ConnectionError(
+        `Request failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error instanceof Error ? error : void 0
+      );
+    }
+  }
+  async createCollection(name, config) {
+    this.ensureInitialized();
+    const response = await this.request("POST", "/collections", {
+      name,
+      dimension: config.dimension,
+      metric: config.metric ?? "cosine",
+      description: config.description
+    });
+    if (response.error) {
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+  }
+  async deleteCollection(name) {
+    this.ensureInitialized();
+    const response = await this.request("DELETE", `/collections/${encodeURIComponent(name)}`);
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${name}'`);
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+  }
+  async getCollection(name) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "GET",
+      `/collections/${encodeURIComponent(name)}`
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        return null;
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    return response.data ?? null;
+  }
+  async listCollections() {
+    this.ensureInitialized();
+    const response = await this.request("GET", "/collections");
+    if (response.error) {
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    return response.data ?? [];
+  }
+  async insert(collection, doc) {
+    this.ensureInitialized();
+    const vector = doc.vector instanceof Float32Array ? Array.from(doc.vector) : doc.vector;
+    const response = await this.request(
+      "POST",
+      `/collections/${encodeURIComponent(collection)}/vectors`,
+      {
+        id: doc.id,
+        vector,
+        payload: doc.payload
+      }
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${collection}'`);
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+  }
+  async insertBatch(collection, docs) {
+    this.ensureInitialized();
+    const vectors = docs.map((doc) => ({
+      id: doc.id,
+      vector: doc.vector instanceof Float32Array ? Array.from(doc.vector) : doc.vector,
+      payload: doc.payload
+    }));
+    const response = await this.request(
+      "POST",
+      `/collections/${encodeURIComponent(collection)}/vectors/batch`,
+      { vectors }
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${collection}'`);
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+  }
+  async search(collection, query, options) {
+    this.ensureInitialized();
+    const queryVector = query instanceof Float32Array ? Array.from(query) : query;
+    const response = await this.request(
+      "POST",
+      `/collections/${encodeURIComponent(collection)}/search`,
+      {
+        vector: queryVector,
+        k: options?.k ?? 10,
+        filter: options?.filter,
+        include_vectors: options?.includeVectors ?? false
+      }
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${collection}'`);
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    return response.data ?? [];
+  }
+  async delete(collection, id) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "DELETE",
+      `/collections/${encodeURIComponent(collection)}/vectors/${encodeURIComponent(String(id))}`
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        return false;
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    return response.data?.deleted ?? false;
+  }
+  async get(collection, id) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "GET",
+      `/collections/${encodeURIComponent(collection)}/vectors/${encodeURIComponent(String(id))}`
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        return null;
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    return response.data ?? null;
+  }
+  async close() {
+    this._initialized = false;
+  }
+};
+
+// src/client.ts
+var VelesDB = class {
+  /**
+   * Create a new VelesDB client
+   * 
+   * @param config - Client configuration
+   * @throws {ValidationError} If configuration is invalid
+   */
+  constructor(config) {
+    this.initialized = false;
+    this.validateConfig(config);
+    this.config = config;
+    this.backend = this.createBackend(config);
+  }
+  validateConfig(config) {
+    if (!config.backend) {
+      throw new ValidationError("Backend type is required");
+    }
+    if (config.backend !== "wasm" && config.backend !== "rest") {
+      throw new ValidationError(`Invalid backend type: ${config.backend}. Use 'wasm' or 'rest'`);
+    }
+    if (config.backend === "rest" && !config.url) {
+      throw new ValidationError("URL is required for REST backend");
+    }
+  }
+  createBackend(config) {
+    switch (config.backend) {
+      case "wasm":
+        return new WasmBackend();
+      case "rest":
+        return new RestBackend(config.url, config.apiKey, config.timeout);
+      default:
+        throw new ValidationError(`Unknown backend: ${config.backend}`);
+    }
+  }
+  /**
+   * Initialize the client
+   * Must be called before any other operations
+   */
+  async init() {
+    if (this.initialized) {
+      return;
+    }
+    await this.backend.init();
+    this.initialized = true;
+  }
+  /**
+   * Check if client is initialized
+   */
+  isInitialized() {
+    return this.initialized;
+  }
+  ensureInitialized() {
+    if (!this.initialized) {
+      throw new ValidationError("Client not initialized. Call init() first.");
+    }
+  }
+  /**
+   * Create a new collection
+   * 
+   * @param name - Collection name
+   * @param config - Collection configuration
+   */
+  async createCollection(name, config) {
+    this.ensureInitialized();
+    if (!name || typeof name !== "string") {
+      throw new ValidationError("Collection name must be a non-empty string");
+    }
+    if (!config.dimension || config.dimension <= 0) {
+      throw new ValidationError("Dimension must be a positive integer");
+    }
+    await this.backend.createCollection(name, config);
+  }
+  /**
+   * Delete a collection
+   * 
+   * @param name - Collection name
+   */
+  async deleteCollection(name) {
+    this.ensureInitialized();
+    await this.backend.deleteCollection(name);
+  }
+  /**
+   * Get collection information
+   * 
+   * @param name - Collection name
+   * @returns Collection info or null if not found
+   */
+  async getCollection(name) {
+    this.ensureInitialized();
+    return this.backend.getCollection(name);
+  }
+  /**
+   * List all collections
+   * 
+   * @returns Array of collections
+   */
+  async listCollections() {
+    this.ensureInitialized();
+    return this.backend.listCollections();
+  }
+  /**
+   * Insert a vector document
+   * 
+   * @param collection - Collection name
+   * @param doc - Document to insert
+   */
+  async insert(collection, doc) {
+    this.ensureInitialized();
+    this.validateDocument(doc);
+    await this.backend.insert(collection, doc);
+  }
+  /**
+   * Insert multiple vector documents
+   * 
+   * @param collection - Collection name
+   * @param docs - Documents to insert
+   */
+  async insertBatch(collection, docs) {
+    this.ensureInitialized();
+    if (!Array.isArray(docs)) {
+      throw new ValidationError("Documents must be an array");
+    }
+    for (const doc of docs) {
+      this.validateDocument(doc);
+    }
+    await this.backend.insertBatch(collection, docs);
+  }
+  validateDocument(doc) {
+    if (doc.id === void 0 || doc.id === null) {
+      throw new ValidationError("Document ID is required");
+    }
+    if (!doc.vector) {
+      throw new ValidationError("Document vector is required");
+    }
+    if (!Array.isArray(doc.vector) && !(doc.vector instanceof Float32Array)) {
+      throw new ValidationError("Vector must be an array or Float32Array");
+    }
+  }
+  /**
+   * Search for similar vectors
+   * 
+   * @param collection - Collection name
+   * @param query - Query vector
+   * @param options - Search options
+   * @returns Search results sorted by relevance
+   */
+  async search(collection, query, options) {
+    this.ensureInitialized();
+    if (!query || !Array.isArray(query) && !(query instanceof Float32Array)) {
+      throw new ValidationError("Query must be an array or Float32Array");
+    }
+    return this.backend.search(collection, query, options);
+  }
+  /**
+   * Delete a vector by ID
+   * 
+   * @param collection - Collection name
+   * @param id - Document ID
+   * @returns true if deleted, false if not found
+   */
+  async delete(collection, id) {
+    this.ensureInitialized();
+    return this.backend.delete(collection, id);
+  }
+  /**
+   * Get a vector by ID
+   * 
+   * @param collection - Collection name
+   * @param id - Document ID
+   * @returns Document or null if not found
+   */
+  async get(collection, id) {
+    this.ensureInitialized();
+    return this.backend.get(collection, id);
+  }
+  /**
+   * Close the client and release resources
+   */
+  async close() {
+    if (this.initialized) {
+      await this.backend.close();
+      this.initialized = false;
+    }
+  }
+  /**
+   * Get the current backend type
+   */
+  get backendType() {
+    return this.config.backend;
+  }
+};
+export {
+  ConnectionError,
+  NotFoundError,
+  RestBackend,
+  ValidationError,
+  VelesDB,
+  VelesDBError,
+  WasmBackend
+};

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@wiscale/velesdb-sdk",
+  "version": "0.5.0",
+  "description": "Official TypeScript SDK for VelesDB - Vector Search in Microseconds",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write src",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "velesdb",
+    "vector",
+    "database",
+    "similarity-search",
+    "embeddings",
+    "ai",
+    "machine-learning",
+    "wasm",
+    "typescript"
+  ],
+  "author": "Wiscale France",
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cyberlife-coder/VelesDB.git",
+    "directory": "sdks/typescript"
+  },
+  "homepage": "https://github.com/cyberlife-coder/VelesDB#readme",
+  "bugs": {
+    "url": "https://github.com/cyberlife-coder/VelesDB/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "@vitest/coverage-v8": "^4.0.16",
+    "eslint": "^8.0.0",
+    "eslint-config-prettier": "^9.0.0",
+    "prettier": "^3.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "velesdb-wasm": "^0.5.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}