@wiscale/velesdb-wasm 1.3.0 → 1.4.1

package/README.md

@@ -246,6 +246,82 @@ Ultra-fast serialization thanks to contiguous memory layout:
 - **Electron/Tauri apps** - Desktop AI without a server
 - **PWA applications** - Full offline support with service workers
 
+## ⚠️ Limitations vs REST Backend
+
+The WASM build is optimized for client-side use cases but has some limitations compared to the full REST server.
+
+### Feature Comparison
+
+| Feature | WASM | REST Server |
+|---------|------|-------------|
+| Vector search (NEAR) | ✅ | ✅ |
+| Metadata filtering | ✅ | ✅ |
+| Full VelesQL queries | ❌ | ✅ |
+| Hybrid search (vector + BM25) | ❌ | ✅ |
+| Knowledge Graph operations | ❌ | ✅ |
+| MATCH clause (full-text) | ❌ | ✅ |
+| NEAR_FUSED (multi-query fusion) | ❌ | ✅ |
+| JOIN operations | ❌ | ✅ |
+| Aggregations (GROUP BY) | ❌ | ✅ |
+| Persistence | IndexedDB | Disk (mmap) |
+| Max vectors | ~100K (browser RAM) | Millions |
+
+### Unsupported Operations
+
+When you try to use unsupported features, you'll get clear error messages:
+
+```javascript
+// ❌ VelesQL string queries not supported in WASM
+// Use the native API instead:
+
+// Instead of: store.query("SELECT * FROM docs WHERE vector NEAR $v")
+// Use:
+const results = store.search(queryVector, 10);
+
+// Instead of: store.query("SELECT * FROM docs WHERE category = 'tech'")
+// Use:
+const results = store.search_with_filter(queryVector, 10, {
+  condition: { type: "eq", field: "category", value: "tech" }
+});
+```
+
+### When to Use REST Backend
+
+Consider using the [REST server](https://github.com/cyberlife-coder/VelesDB) if you need:
+
+- **Full VelesQL support** - Complex SQL-like queries
+- **Hybrid search** - Combine semantic + keyword search
+- **Knowledge Graph** - Entity relationships and graph traversal
+- **Large datasets** - More than 100K vectors
+- **Server-side processing** - Centralized vector database
+
+### Migration from WASM to REST
+
+```javascript
+// WASM (client-side)
+import { VectorStore } from '@wiscale/velesdb-wasm';
+const store = new VectorStore(768, 'cosine');
+const results = store.search(query, 10);
+
+// REST (server-side) - using fetch
+const response = await fetch('http://localhost:8080/v1/collections/docs/search', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ vector: query, limit: 10 })
+});
+const results = await response.json();
+
+// REST with VelesQL
+const response = await fetch('http://localhost:8080/v1/query', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    query: "SELECT * FROM docs WHERE vector NEAR $v AND category = 'tech' LIMIT 10",
+    params: { v: query }
+  })
+});
+```
+
 ## Building from Source
 
 ```bash

package/package.json

@@ -5,7 +5,7 @@
     "Julien Lange <contact@wiscale.fr>"
   ],
   "description": "VelesDB for WebAssembly - Vector search in the browser",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "license": "SEE LICENSE IN ../../LICENSE",
   "repository": {
     "type": "git",

package/velesdb_wasm.d.ts

@@ -91,6 +91,43 @@ export class GraphNode {
   readonly label: string;
 }
 
+export class GraphPersistence {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Lists all saved graph names.
+   */
+  list_graphs(): Promise<Array<any>>;
+  /**
+   * Deletes a saved graph by name.
+   *
+   * BUG-7 FIX: Also deletes all nodes and edges with the graph prefix.
+   */
+  delete_graph(graph_name: string): Promise<void>;
+  /**
+   * Gets metadata for a saved graph.
+   */
+  get_metadata(graph_name: string): Promise<any>;
+  /**
+   * Creates a new `GraphPersistence` instance (call `init()` to open database).
+   */
+  constructor();
+  /**
+   * Initializes the database connection. Must be called before save/load.
+   */
+  init(): Promise<void>;
+  /**
+   * Loads a graph from `IndexedDB` by name.
+   *
+   * BUG-6 FIX: Only loads nodes/edges with keys prefixed by `{graph_name}:`
+   */
+  load(graph_name: string): Promise<GraphStore>;
+  /**
+   * Saves a graph to `IndexedDB` with the given name.
+   */
+  save(graph_name: string, store: GraphStore): Promise<void>;
+}
+
 export class GraphStore {
   free(): void;
   [Symbol.dispose](): void;
@@ -230,6 +267,188 @@ export class GraphStore {
   readonly node_count: number;
 }
 
+export class GraphWorkerConfig {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Creates a configuration optimized for large graphs.
+   */
+  static for_large_graphs(): GraphWorkerConfig;
+  /**
+   * Creates a configuration optimized for responsive UI.
+   */
+  static for_responsive_ui(): GraphWorkerConfig;
+  /**
+   * Creates a new configuration with default values.
+   */
+  constructor();
+  /**
+   * Minimum node count to trigger worker offload.
+   */
+  node_threshold: number;
+  /**
+   * Minimum depth to trigger worker offload.
+   */
+  depth_threshold: number;
+  /**
+   * Progress callback interval in milliseconds.
+   */
+  progress_interval_ms: number;
+  /**
+   * Whether to use `SharedArrayBuffer` for result transfer (if available).
+   */
+  use_shared_buffer: boolean;
+}
+
+export class ParsedQuery {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Check if the query uses FUSION (hybrid search).
+   */
+  readonly hasFusion: boolean;
+  /**
+   * Get the number of JOIN clauses.
+   */
+  readonly joinCount: number;
+  /**
+   * Get the table name from the FROM clause.
+   */
+  readonly tableName: string | undefined;
+  /**
+   * Get the LIMIT from the MATCH RETURN clause.
+   */
+  readonly matchLimit: bigint | undefined;
+  /**
+   * Check if DISTINCT modifier is present.
+   */
+  readonly hasDistinct: boolean;
+  /**
+   * Check if the query has a GROUP BY clause.
+   */
+  readonly hasGroupBy: boolean;
+  /**
+   * Check if the query has an ORDER BY clause.
+   */
+  readonly hasOrderBy: boolean;
+  /**
+   * Check if the MATCH clause has a WHERE condition.
+   */
+  readonly matchHasWhere: boolean;
+  /**
+   * Check if the query has a WHERE clause.
+   */
+  readonly hasWhereClause: boolean;
+  /**
+   * Get the number of node patterns in the MATCH clause.
+   */
+  readonly matchNodeCount: number;
+  /**
+   * Check if the query contains vector search (NEAR clause).
+   */
+  readonly hasVectorSearch: boolean;
+  /**
+   * Get node labels from the MATCH clause as JSON array of arrays.
+   * Each inner array contains the labels for one node pattern.
+   */
+  readonly matchNodeLabels: any;
+  /**
+   * Get RETURN items from the MATCH clause as JSON array.
+   */
+  readonly matchReturnItems: any;
+  /**
+   * Get the number of relationship patterns in the MATCH clause.
+   */
+  readonly matchRelationshipCount: number;
+  /**
+   * Get relationship types from the MATCH clause as JSON array of arrays.
+   * Each inner array contains the types for one relationship pattern.
+   */
+  readonly matchRelationshipTypes: any;
+  /**
+   * Get the LIMIT value if present.
+   */
+  readonly limit: bigint | undefined;
+  /**
+   * Get the OFFSET value if present.
+   */
+  readonly offset: bigint | undefined;
+  /**
+   * Get the list of selected columns as JSON array.
+   */
+  readonly columns: any;
+  /**
+   * Get the GROUP BY columns as JSON array.
+   */
+  readonly groupBy: any;
+  /**
+   * Check if this is a MATCH (graph) query.
+   */
+  readonly isMatch: boolean;
+  /**
+   * Check if the query is valid (always true for successfully parsed queries).
+   */
+  readonly isValid: boolean;
+  /**
+   * Get the ORDER BY columns and directions as JSON array.
+   */
+  readonly orderBy: any;
+  /**
+   * Check if the query has JOINs.
+   */
+  readonly hasJoins: boolean;
+  /**
+   * Check if this is a SELECT query.
+   */
+  readonly isSelect: boolean;
+}
+
+export class SemanticMemory {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Returns the number of stored knowledge facts.
+   */
+  len(): number;
+  /**
+   * Creates a new `SemanticMemory` with the given embedding dimension.
+   */
+  constructor(dimension: number);
+  /**
+   * Clears all knowledge facts.
+   */
+  clear(): void;
+  /**
+   * Queries semantic memory by similarity search.
+   *
+   * Returns a JSON array of {id, score, content} objects.
+   */
+  query(embedding: Float32Array, top_k: number): any;
+  /**
+   * Stores a knowledge fact with its embedding vector.
+   *
+   * # Arguments
+   *
+   * * `id` - Unique identifier for this fact
+   * * `content` - Text content of the knowledge
+   * * `embedding` - Vector representation (`Float32Array`)
+   */
+  store(id: bigint, content: string, embedding: Float32Array): void;
+  /**
+   * Removes a knowledge fact by ID.
+   */
+  remove(id: bigint): boolean;
+  /**
+   * Returns true if no knowledge facts are stored.
+   */
+  is_empty(): boolean;
+  /**
+   * Returns the embedding dimension.
+   */
+  dimension(): number;
+}
+
 /**
  * Storage mode for vector quantization.
  */
@@ -248,6 +467,43 @@ export enum StorageMode {
   Binary = 2,
 }
 
+export class TraversalProgress {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Creates a new progress report.
+   */
+  constructor(visited: number, estimated: number, depth: number);
+  /**
+   * Converts to JSON for postMessage.
+   */
+  to_json(): any;
+  /**
+   * Returns the completion percentage (0-100).
+   */
+  readonly percentage: number;
+  /**
+   * Number of nodes visited so far.
+   */
+  visited_count: number;
+  /**
+   * Estimated total nodes to visit (heuristic).
+   */
+  estimated_total: number;
+  /**
+   * Current traversal depth.
+   */
+  current_depth: number;
+  /**
+   * Whether the traversal is complete.
+   */
+  is_complete: boolean;
+  /**
+   * Whether the traversal was cancelled.
+   */
+  is_cancelled: boolean;
+}
+
 export class VectorStore {
   free(): void;
   [Symbol.dispose](): void;
@@ -331,6 +587,20 @@ export class VectorStore {
    * Clears all vectors from the store.
    */
   clear(): void;
+  /**
+   * VelesQL-style query returning multi-model results (EPIC-031 US-009).
+   *
+   * Returns results in `HybridResult` format with `node_id`, `vector_score`,
+   * `graph_score`, `fused_score`, `bindings`, and `column_data`.
+   *
+   * # Arguments
+   * * `query_vector` - Query vector for similarity search
+   * * `k` - Number of results to return
+   *
+   * # Returns
+   * Array of `{nodeId, vectorScore, graphScore, fusedScore, bindings, columnData}`
+   */
+  query(query_vector: Float32Array, k: number): any;
   /**
    * Inserts a vector with the given ID.
    */
@@ -369,14 +639,69 @@ export class VectorStore {
   readonly dimension: number;
 }
 
+export class VelesQL {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Parse a `VelesQL` query string.
+   *
+   * Returns a `ParsedQuery` object with query introspection methods.
+   * Throws an error if the query has syntax errors.
+   */
+  static parse(query: string): ParsedQuery;
+  /**
+   * Validate a `VelesQL` query without full parsing.
+   *
+   * This is faster than `parse()` when you only need to check validity.
+   */
+  static isValid(query: string): boolean;
+}
+
+/**
+ * Estimates the number of nodes that will be visited during traversal.
+ *
+ * Uses a heuristic based on graph density and max depth.
+ */
+export function estimate_traversal_size(node_count: number, edge_count: number, max_depth: number): number;
+
+/**
+ * Determines whether a traversal should be offloaded to a Web Worker.
+ *
+ * # Arguments
+ * * `node_count` - Total nodes in the graph
+ * * `max_depth` - Maximum traversal depth requested
+ * * `config` - Optional configuration (uses defaults if None)
+ *
+ * # Returns
+ * `true` if the operation should use a Web Worker
+ */
+export function should_use_worker(node_count: number, max_depth: number, config?: GraphWorkerConfig | null): boolean;
+
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
   readonly memory: WebAssembly.Memory;
+  readonly __wbg_get_graphworkerconfig_depth_threshold: (a: number) => number;
+  readonly __wbg_get_graphworkerconfig_node_threshold: (a: number) => number;
+  readonly __wbg_get_graphworkerconfig_progress_interval_ms: (a: number) => number;
+  readonly __wbg_get_graphworkerconfig_use_shared_buffer: (a: number) => number;
+  readonly __wbg_get_traversalprogress_is_cancelled: (a: number) => number;
   readonly __wbg_graphedge_free: (a: number, b: number) => void;
   readonly __wbg_graphnode_free: (a: number, b: number) => void;
+  readonly __wbg_graphpersistence_free: (a: number, b: number) => void;
   readonly __wbg_graphstore_free: (a: number, b: number) => void;
+  readonly __wbg_graphworkerconfig_free: (a: number, b: number) => void;
+  readonly __wbg_parsedquery_free: (a: number, b: number) => void;
+  readonly __wbg_semanticmemory_free: (a: number, b: number) => void;
+  readonly __wbg_set_graphworkerconfig_depth_threshold: (a: number, b: number) => void;
+  readonly __wbg_set_graphworkerconfig_node_threshold: (a: number, b: number) => void;
+  readonly __wbg_set_graphworkerconfig_progress_interval_ms: (a: number, b: number) => void;
+  readonly __wbg_set_graphworkerconfig_use_shared_buffer: (a: number, b: number) => void;
+  readonly __wbg_set_traversalprogress_is_cancelled: (a: number, b: number) => void;
   readonly __wbg_vectorstore_free: (a: number, b: number) => void;
+  readonly __wbg_velesql_free: (a: number, b: number) => void;
+  readonly estimate_traversal_size: (a: number, b: number, c: number) => number;
   readonly graphedge_id: (a: number) => bigint;
   readonly graphedge_label: (a: number, b: number) => void;
   readonly graphedge_new: (a: number, b: bigint, c: bigint, d: bigint, e: number, f: number) => void;
@@ -393,6 +718,13 @@ export interface InitOutput {
   readonly graphnode_set_string_property: (a: number, b: number, c: number, d: number, e: number) => void;
   readonly graphnode_set_vector: (a: number, b: number, c: number) => void;
   readonly graphnode_to_json: (a: number, b: number) => void;
+  readonly graphpersistence_delete_graph: (a: number, b: number, c: number) => number;
+  readonly graphpersistence_get_metadata: (a: number, b: number, c: number) => number;
+  readonly graphpersistence_init: (a: number) => number;
+  readonly graphpersistence_list_graphs: (a: number) => number;
+  readonly graphpersistence_load: (a: number, b: number, c: number) => number;
+  readonly graphpersistence_new: () => number;
+  readonly graphpersistence_save: (a: number, b: number, c: number, d: number) => number;
   readonly graphstore_add_edge: (a: number, b: number, c: number) => void;
   readonly graphstore_add_node: (a: number, b: number) => void;
   readonly graphstore_bfs_traverse: (a: number, b: number, c: bigint, d: number, e: number) => void;
@@ -417,6 +749,44 @@ export interface InitOutput {
   readonly graphstore_out_degree: (a: number, b: bigint) => number;
   readonly graphstore_remove_edge: (a: number, b: bigint) => void;
   readonly graphstore_remove_node: (a: number, b: bigint) => void;
+  readonly graphworkerconfig_for_large_graphs: () => number;
+  readonly graphworkerconfig_for_responsive_ui: () => number;
+  readonly graphworkerconfig_new: () => number;
+  readonly parsedquery_columns: (a: number) => number;
+  readonly parsedquery_groupBy: (a: number) => number;
+  readonly parsedquery_hasDistinct: (a: number) => number;
+  readonly parsedquery_hasFusion: (a: number) => number;
+  readonly parsedquery_hasGroupBy: (a: number) => number;
+  readonly parsedquery_hasJoins: (a: number) => number;
+  readonly parsedquery_hasOrderBy: (a: number) => number;
+  readonly parsedquery_hasVectorSearch: (a: number) => number;
+  readonly parsedquery_hasWhereClause: (a: number) => number;
+  readonly parsedquery_isMatch: (a: number) => number;
+  readonly parsedquery_isSelect: (a: number) => number;
+  readonly parsedquery_isValid: (a: number) => number;
+  readonly parsedquery_joinCount: (a: number) => number;
+  readonly parsedquery_limit: (a: number, b: number) => void;
+  readonly parsedquery_matchHasWhere: (a: number) => number;
+  readonly parsedquery_matchLimit: (a: number, b: number) => void;
+  readonly parsedquery_matchNodeCount: (a: number) => number;
+  readonly parsedquery_matchNodeLabels: (a: number) => number;
+  readonly parsedquery_matchRelationshipCount: (a: number) => number;
+  readonly parsedquery_matchRelationshipTypes: (a: number) => number;
+  readonly parsedquery_matchReturnItems: (a: number) => number;
+  readonly parsedquery_offset: (a: number, b: number) => void;
+  readonly parsedquery_orderBy: (a: number) => number;
+  readonly parsedquery_tableName: (a: number, b: number) => void;
+  readonly semanticmemory_clear: (a: number) => void;
+  readonly semanticmemory_dimension: (a: number) => number;
+  readonly semanticmemory_is_empty: (a: number) => number;
+  readonly semanticmemory_new: (a: number, b: number) => void;
+  readonly semanticmemory_query: (a: number, b: number, c: number, d: number, e: number) => void;
+  readonly semanticmemory_remove: (a: number, b: bigint) => number;
+  readonly semanticmemory_store: (a: number, b: number, c: bigint, d: number, e: number, f: number, g: number) => void;
+  readonly should_use_worker: (a: number, b: number, c: number) => number;
+  readonly traversalprogress_new: (a: number, b: number, c: number) => number;
+  readonly traversalprogress_percentage: (a: number) => number;
+  readonly traversalprogress_to_json: (a: number, b: number) => void;
   readonly vectorstore_batch_search: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
   readonly vectorstore_clear: (a: number) => void;
   readonly vectorstore_delete_database: (a: number, b: number) => number;
@@ -437,6 +807,7 @@ export interface InitOutput {
   readonly vectorstore_new: (a: number, b: number, c: number, d: number) => void;
   readonly vectorstore_new_metadata_only: () => number;
   readonly vectorstore_new_with_mode: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+  readonly vectorstore_query: (a: number, b: number, c: number, d: number, e: number) => void;
   readonly vectorstore_remove: (a: number, b: bigint) => number;
   readonly vectorstore_reserve: (a: number, b: number) => void;
   readonly vectorstore_save: (a: number, b: number, c: number) => number;
@@ -446,12 +817,24 @@ export interface InitOutput {
   readonly vectorstore_storage_mode: (a: number, b: number) => void;
   readonly vectorstore_text_search: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
   readonly vectorstore_with_capacity: (a: number, b: number, c: number, d: number, e: number) => void;
+  readonly velesql_isValid: (a: number, b: number) => number;
+  readonly velesql_parse: (a: number, b: number, c: number) => void;
+  readonly __wbg_set_traversalprogress_is_complete: (a: number, b: number) => void;
+  readonly __wbg_set_traversalprogress_current_depth: (a: number, b: number) => void;
+  readonly __wbg_set_traversalprogress_estimated_total: (a: number, b: number) => void;
+  readonly __wbg_set_traversalprogress_visited_count: (a: number, b: number) => void;
+  readonly __wbg_get_traversalprogress_is_complete: (a: number) => number;
+  readonly __wbg_get_traversalprogress_current_depth: (a: number) => number;
+  readonly __wbg_get_traversalprogress_estimated_total: (a: number) => number;
+  readonly __wbg_get_traversalprogress_visited_count: (a: number) => number;
   readonly graphnode_id: (a: number) => bigint;
-  readonly __wasm_bindgen_func_elem_198: (a: number, b: number, c: number) => void;
-  readonly __wasm_bindgen_func_elem_197: (a: number, b: number) => void;
-  readonly __wasm_bindgen_func_elem_640: (a: number, b: number, c: number) => void;
-  readonly __wasm_bindgen_func_elem_639: (a: number, b: number) => void;
-  readonly __wasm_bindgen_func_elem_689: (a: number, b: number, c: number, d: number) => void;
+  readonly semanticmemory_len: (a: number) => number;
+  readonly __wbg_traversalprogress_free: (a: number, b: number) => void;
+  readonly __wasm_bindgen_func_elem_265: (a: number, b: number, c: number) => void;
+  readonly __wasm_bindgen_func_elem_264: (a: number, b: number) => void;
+  readonly __wasm_bindgen_func_elem_1176: (a: number, b: number, c: number) => void;
+  readonly __wasm_bindgen_func_elem_1175: (a: number, b: number) => void;
+  readonly __wasm_bindgen_func_elem_1217: (a: number, b: number, c: number, d: number) => void;
   readonly __wbindgen_export: (a: number, b: number) => number;
   readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
   readonly __wbindgen_export3: (a: number) => void;