@wiscale/velesdb-sdk 1.1.1 → 1.3.0

package/dist/index.mjs

@@ -289,6 +289,60 @@ var WasmBackend = class {
     }
     return Math.abs(hash);
   }
+  // ========================================================================
+  // Index Management (EPIC-009) - Stubs for WASM backend
+  // Note: Full implementation requires velesdb-wasm support
+  // ========================================================================
+  async createIndex(_collection, _options) {
+    this.ensureInitialized();
+    throw new Error(
+      "WasmBackend: createIndex is not yet supported. Index operations require the REST backend with velesdb-server."
+    );
+  }
+  async listIndexes(_collection) {
+    this.ensureInitialized();
+    return [];
+  }
+  async hasIndex(_collection, _label, _property) {
+    this.ensureInitialized();
+    return false;
+  }
+  async dropIndex(_collection, _label, _property) {
+    this.ensureInitialized();
+    return false;
+  }
+  // ========================================================================
+  // Knowledge Graph (EPIC-016 US-041) - Stubs for WASM backend
+  // Note: Graph operations require server-side EdgeStore
+  // ========================================================================
+  async addEdge(_collection, _edge) {
+    this.ensureInitialized();
+    throw new VelesDBError(
+      "Knowledge Graph operations are not supported in WASM backend. Use REST backend for graph features.",
+      "NOT_SUPPORTED"
+    );
+  }
+  async getEdges(_collection, _options) {
+    this.ensureInitialized();
+    throw new VelesDBError(
+      "Knowledge Graph operations are not supported in WASM backend. Use REST backend for graph features.",
+      "NOT_SUPPORTED"
+    );
+  }
+  async traverseGraph(_collection, _request) {
+    this.ensureInitialized();
+    throw new VelesDBError(
+      "Graph traversal is not supported in WASM backend. Use REST backend for graph features.",
+      "NOT_SUPPORTED"
+    );
+  }
+  async getNodeDegree(_collection, _nodeId) {
+    this.ensureInitialized();
+    throw new VelesDBError(
+      "Graph degree query is not supported in WASM backend. Use REST backend for graph features.",
+      "NOT_SUPPORTED"
+    );
+  }
 };
 
 // src/backends/rest.ts
@@ -324,6 +378,38 @@ var RestBackend = class {
       throw new ConnectionError("REST backend not initialized");
     }
   }
+  mapStatusToErrorCode(status) {
+    switch (status) {
+      case 400:
+        return "BAD_REQUEST";
+      case 401:
+        return "UNAUTHORIZED";
+      case 403:
+        return "FORBIDDEN";
+      case 404:
+        return "NOT_FOUND";
+      case 409:
+        return "CONFLICT";
+      case 429:
+        return "RATE_LIMITED";
+      case 500:
+        return "INTERNAL_ERROR";
+      case 503:
+        return "SERVICE_UNAVAILABLE";
+      default:
+        return "UNKNOWN_ERROR";
+    }
+  }
+  extractErrorPayload(data) {
+    if (!data || typeof data !== "object") {
+      return {};
+    }
+    const payload = data;
+    const code = typeof payload.code === "string" ? payload.code : void 0;
+    const messageField = payload.message ?? payload.error;
+    const message = typeof messageField === "string" ? messageField : void 0;
+    return { code, message };
+  }
   async request(method, path, body) {
     const url = `${this.baseUrl}${path}`;
     const headers = {
@@ -342,12 +428,13 @@ var RestBackend = class {
         signal: controller.signal
       });
       clearTimeout(timeoutId);
-      const data = await response.json();
+      const data = await response.json().catch(() => ({}));
       if (!response.ok) {
+        const errorPayload = this.extractErrorPayload(data);
         return {
           error: {
-            code: data.code ?? "UNKNOWN_ERROR",
-            message: data.message ?? `HTTP ${response.status}`
+            code: errorPayload.code ?? this.mapStatusToErrorCode(response.status),
+            message: errorPayload.message ?? `HTTP ${response.status}`
           }
         };
       }
@@ -583,8 +670,8 @@ var RestBackend = class {
       {
         vectors: formattedVectors,
         top_k: options?.k ?? 10,
-        fusion: options?.fusion ?? "rrf",
-        fusion_params: options?.fusionParams ?? { k: 60 },
+        strategy: options?.fusion ?? "rrf",
+        rrf_k: options?.fusionParams?.k ?? 60,
         filter: options?.filter
       }
     );
@@ -626,6 +713,158 @@ var RestBackend = class {
   async close() {
     this._initialized = false;
   }
+  // ========================================================================
+  // Index Management (EPIC-009)
+  // ========================================================================
+  async createIndex(collection, options) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "POST",
+      `/collections/${encodeURIComponent(collection)}/indexes`,
+      {
+        label: options.label,
+        property: options.property,
+        index_type: options.indexType ?? "hash"
+      }
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${collection}'`);
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+  }
+  async listIndexes(collection) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "GET",
+      `/collections/${encodeURIComponent(collection)}/indexes`
+    );
+    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?.indexes ?? []).map((idx) => ({
+      label: idx.label,
+      property: idx.property,
+      indexType: idx.index_type,
+      cardinality: idx.cardinality,
+      memoryBytes: idx.memory_bytes
+    }));
+  }
+  async hasIndex(collection, label, property) {
+    const indexes = await this.listIndexes(collection);
+    return indexes.some((idx) => idx.label === label && idx.property === property);
+  }
+  async dropIndex(collection, label, property) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "DELETE",
+      `/collections/${encodeURIComponent(collection)}/indexes/${encodeURIComponent(label)}/${encodeURIComponent(property)}`
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        return false;
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    return response.data?.dropped ?? true;
+  }
+  // ========================================================================
+  // Knowledge Graph (EPIC-016 US-041)
+  // ========================================================================
+  async addEdge(collection, edge) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "POST",
+      `/collections/${encodeURIComponent(collection)}/graph/edges`,
+      {
+        id: edge.id,
+        source: edge.source,
+        target: edge.target,
+        label: edge.label,
+        properties: edge.properties ?? {}
+      }
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${collection}'`);
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+  }
+  async getEdges(collection, options) {
+    this.ensureInitialized();
+    const queryParams = options?.label ? `?label=${encodeURIComponent(options.label)}` : "";
+    const response = await this.request(
+      "GET",
+      `/collections/${encodeURIComponent(collection)}/graph/edges${queryParams}`
+    );
+    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?.edges ?? [];
+  }
+  // ========================================================================
+  // Graph Traversal (EPIC-016 US-050)
+  // ========================================================================
+  async traverseGraph(collection, request) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "POST",
+      `/collections/${encodeURIComponent(collection)}/graph/traverse`,
+      {
+        source: request.source,
+        strategy: request.strategy ?? "bfs",
+        max_depth: request.maxDepth ?? 3,
+        limit: request.limit ?? 100,
+        cursor: request.cursor,
+        rel_types: request.relTypes ?? []
+      }
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${collection}'`);
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    const data = response.data;
+    return {
+      results: data.results.map((r) => ({
+        targetId: r.target_id,
+        depth: r.depth,
+        path: r.path
+      })),
+      nextCursor: data.next_cursor ?? void 0,
+      hasMore: data.has_more,
+      stats: {
+        visited: data.stats.visited,
+        depthReached: data.stats.depth_reached
+      }
+    };
+  }
+  async getNodeDegree(collection, nodeId) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "GET",
+      `/collections/${encodeURIComponent(collection)}/graph/nodes/${nodeId}/degree`
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${collection}'`);
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    return {
+      inDegree: response.data?.in_degree ?? 0,
+      outDegree: response.data?.out_degree ?? 0
+    };
+  }
 };
 
 // src/client.ts
@@ -965,6 +1204,168 @@ var VelesDB = class {
   get backendType() {
     return this.config.backend;
   }
+  // ========================================================================
+  // Index Management (EPIC-009)
+  // ========================================================================
+  /**
+   * Create a property index for O(1) equality lookups or O(log n) range queries
+   * 
+   * @param collection - Collection name
+   * @param options - Index configuration (label, property, indexType)
+   * 
+   * @example
+   * ```typescript
+   * // Create hash index for fast email lookups
+   * await db.createIndex('users', { label: 'Person', property: 'email' });
+   * 
+   * // Create range index for timestamp queries
+   * await db.createIndex('events', { label: 'Event', property: 'timestamp', indexType: 'range' });
+   * ```
+   */
+  async createIndex(collection, options) {
+    this.ensureInitialized();
+    if (!options.label || !options.property) {
+      throw new ValidationError("Index requires label and property");
+    }
+    await this.backend.createIndex(collection, options);
+  }
+  /**
+   * List all indexes on a collection
+   * 
+   * @param collection - Collection name
+   * @returns Array of index information
+   */
+  async listIndexes(collection) {
+    this.ensureInitialized();
+    return this.backend.listIndexes(collection);
+  }
+  /**
+   * Check if an index exists
+   * 
+   * @param collection - Collection name
+   * @param label - Node label
+   * @param property - Property name
+   * @returns true if index exists
+   */
+  async hasIndex(collection, label, property) {
+    this.ensureInitialized();
+    return this.backend.hasIndex(collection, label, property);
+  }
+  /**
+   * Drop an index
+   * 
+   * @param collection - Collection name
+   * @param label - Node label
+   * @param property - Property name
+   * @returns true if index was dropped, false if it didn't exist
+   */
+  async dropIndex(collection, label, property) {
+    this.ensureInitialized();
+    return this.backend.dropIndex(collection, label, property);
+  }
+  // ========================================================================
+  // Knowledge Graph (EPIC-016 US-041)
+  // ========================================================================
+  /**
+   * Add an edge to the collection's knowledge graph
+   * 
+   * @param collection - Collection name
+   * @param edge - Edge to add (id, source, target, label, properties)
+   * 
+   * @example
+   * ```typescript
+   * await db.addEdge('social', {
+   *   id: 1,
+   *   source: 100,
+   *   target: 200,
+   *   label: 'FOLLOWS',
+   *   properties: { since: '2024-01-01' }
+   * });
+   * ```
+   */
+  async addEdge(collection, edge) {
+    this.ensureInitialized();
+    if (!edge.label || typeof edge.label !== "string") {
+      throw new ValidationError("Edge label is required and must be a string");
+    }
+    if (typeof edge.source !== "number" || typeof edge.target !== "number") {
+      throw new ValidationError("Edge source and target must be numbers");
+    }
+    await this.backend.addEdge(collection, edge);
+  }
+  /**
+   * Get edges from the collection's knowledge graph
+   * 
+   * @param collection - Collection name
+   * @param options - Query options (filter by label)
+   * @returns Array of edges
+   * 
+   * @example
+   * ```typescript
+   * // Get all edges with label "FOLLOWS"
+   * const edges = await db.getEdges('social', { label: 'FOLLOWS' });
+   * ```
+   */
+  async getEdges(collection, options) {
+    this.ensureInitialized();
+    return this.backend.getEdges(collection, options);
+  }
+  // ========================================================================
+  // Graph Traversal (EPIC-016 US-050)
+  // ========================================================================
+  /**
+   * Traverse the graph using BFS or DFS from a source node
+   * 
+   * @param collection - Collection name
+   * @param request - Traversal request options
+   * @returns Traversal response with results and stats
+   * 
+   * @example
+   * ```typescript
+   * // BFS traversal from node 100
+   * const result = await db.traverseGraph('social', {
+   *   source: 100,
+   *   strategy: 'bfs',
+   *   maxDepth: 3,
+   *   limit: 100,
+   *   relTypes: ['FOLLOWS', 'KNOWS']
+   * });
+   * 
+   * for (const node of result.results) {
+   *   console.log(`Reached node ${node.targetId} at depth ${node.depth}`);
+   * }
+   * ```
+   */
+  async traverseGraph(collection, request) {
+    this.ensureInitialized();
+    if (typeof request.source !== "number") {
+      throw new ValidationError("Source node ID must be a number");
+    }
+    if (request.strategy && !["bfs", "dfs"].includes(request.strategy)) {
+      throw new ValidationError("Strategy must be 'bfs' or 'dfs'");
+    }
+    return this.backend.traverseGraph(collection, request);
+  }
+  /**
+   * Get the in-degree and out-degree of a node
+   * 
+   * @param collection - Collection name
+   * @param nodeId - Node ID
+   * @returns Degree response with inDegree and outDegree
+   * 
+   * @example
+   * ```typescript
+   * const degree = await db.getNodeDegree('social', 100);
+   * console.log(`In: ${degree.inDegree}, Out: ${degree.outDegree}`);
+   * ```
+   */
+  async getNodeDegree(collection, nodeId) {
+    this.ensureInitialized();
+    if (typeof nodeId !== "number") {
+      throw new ValidationError("Node ID must be a number");
+    }
+    return this.backend.getNodeDegree(collection, nodeId);
+  }
 };
 export {
   ConnectionError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wiscale/velesdb-sdk",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "VelesDB TypeScript SDK: The Local Vector Database for AI & RAG. Microsecond semantic search in Browser & Node.js.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",