@wiscale/velesdb-wasm 1.1.2 → 1.3.0

package/package.json

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

package/velesdb_wasm.d.ts

@@ -1,299 +1,330 @@
 /* tslint:disable */
 /* eslint-disable */
 
-/**
- * Storage mode for vector quantization.
- */
-export enum StorageMode {
+export class GraphEdge {
+  free(): void;
+  [Symbol.dispose](): void;
   /**
-   * Full f32 precision (4 bytes per dimension)
+   * Sets a numeric property on the edge.
    */
-  Full = 0,
+  set_number_property(key: string, value: number): void;
   /**
-   * SQ8: 8-bit scalar quantization (1 byte per dimension, 4x compression)
+   * Sets a string property on the edge.
    */
-  SQ8 = 1,
+  set_string_property(key: string, value: string): void;
   /**
-   * Binary: 1-bit quantization (1 bit per dimension, 32x compression)
+   * Creates a new graph edge.
+   *
+   * # Arguments
+   *
+   * * `id` - Unique identifier for the edge
+   * * `source` - Source node ID
+   * * `target` - Target node ID
+   * * `label` - Relationship type (e.g., "KNOWS", "WROTE")
    */
-  Binary = 2,
+  constructor(id: bigint, source: bigint, target: bigint, label: string);
+  /**
+   * Converts to JSON for JavaScript interop.
+   */
+  to_json(): any;
+  /**
+   * Returns the edge ID.
+   */
+  readonly id: bigint;
+  /**
+   * Returns the edge label (relationship type).
+   */
+  readonly label: string;
+  /**
+   * Returns the source node ID.
+   */
+  readonly source: bigint;
+  /**
+   * Returns the target node ID.
+   */
+  readonly target: bigint;
 }
 
-export class VectorStore {
+export class GraphNode {
   free(): void;
   [Symbol.dispose](): void;
   /**
-   * Performs text search on payload fields.
-   *
-   * This is a simple substring-based search on payload text fields.
-   * For full BM25 text search, use the REST API backend.
+   * Returns true if this node has a vector embedding.
+   */
+  has_vector(): boolean;
+  /**
+   * Sets a vector embedding on the node.
+   */
+  set_vector(vector: Float32Array): void;
+  /**
+   * Sets a boolean property on the node.
+   */
+  set_bool_property(key: string, value: boolean): void;
+  /**
+   * Sets a numeric property on the node.
+   */
+  set_number_property(key: string, value: number): void;
+  /**
+   * Sets a string property on the node.
+   */
+  set_string_property(key: string, value: string): void;
+  /**
+   * Creates a new graph node.
    *
    * # Arguments
    *
-   * * `query` - Text query to search for
-   * * `k` - Number of results
-   * * `field` - Optional field name to search in (default: searches all string fields)
-   *
-   * # Returns
-   *
-   * Array of results with matching payloads.
+   * * `id` - Unique identifier for the node
+   * * `label` - Node type/label (e.g., "Person", "Document")
    */
-  text_search(query: string, k: number, field?: string | null): any;
+  constructor(id: bigint, label: string);
+  /**
+   * Converts to JSON for JavaScript interop.
+   */
+  to_json(): any;
+  /**
+   * Returns the node ID.
+   */
+  readonly id: bigint;
+  /**
+   * Returns the node label.
+   */
+  readonly label: string;
+}
+
+export class GraphStore {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Gets the degree (number of outgoing edges) of a node.
+   */
+  out_degree(node_id: bigint): number;
+  /**
+   * Removes an edge by ID.
+   */
+  remove_edge(edge_id: bigint): void;
+  /**
+   * Removes a node and all connected edges.
+   */
+  remove_node(node_id: bigint): void;
   /**
-   * Batch search for multiple vectors in parallel.
+   * Performs BFS traversal from a source node.
    *
    * # Arguments
    *
-   * * `vectors` - Flat array of query vectors (concatenated)
-   * * `num_vectors` - Number of vectors
-   * * `k` - Results per query
+   * * `source_id` - Starting node ID
+   * * `max_depth` - Maximum traversal depth
+   * * `limit` - Maximum number of results
    *
    * # Returns
    *
-   * Array of arrays of (id, score) tuples.
+   * Array of reachable node IDs with their depths.
    */
-  batch_search(vectors: Float32Array, num_vectors: number, k: number): any;
+  bfs_traverse(source_id: bigint, max_depth: number, limit: number): any;
   /**
-   * Inserts multiple vectors in a single batch operation.
-   *
-   * This is significantly faster than calling `insert()` multiple times
-   * because it pre-allocates memory and reduces per-call overhead.
+   * Performs DFS traversal from a source node.
    *
    * # Arguments
    *
-   * * `batch` - JavaScript array of `[id, Float32Array]` pairs
+   * * `source_id` - Starting node ID
+   * * `max_depth` - Maximum traversal depth
+   * * `limit` - Maximum number of results
    *
-   * # Errors
+   * # Returns
    *
-   * Returns an error if any vector dimension doesn't match store dimension.
+   * Array of reachable node IDs with their depths (depth-first order).
    */
-  insert_batch(batch: any): void;
+  dfs_traverse(source_id: bigint, max_depth: number, limit: number): any;
   /**
-   * Returns memory usage estimate in bytes.
+   * Gets incoming edges to a node.
    */
-  memory_usage(): number;
+  get_incoming(node_id: bigint): GraphEdge[];
   /**
-   * Performs hybrid search combining vector similarity and text search.
-   *
-   * Uses a simple weighted fusion of vector search and text search results.
+   * Gets outgoing edges from a node.
+   */
+  get_outgoing(node_id: bigint): GraphEdge[];
+  /**
+   * Gets neighbors reachable from a node (1-hop).
+   */
+  get_neighbors(node_id: bigint): BigUint64Array;
+  /**
+   * Gets all edge IDs in the graph.
+   */
+  get_all_edge_ids(): BigUint64Array;
+  /**
+   * Gets all node IDs in the graph.
+   */
+  get_all_node_ids(): BigUint64Array;
+  /**
+   * Gets all edges with a specific label.
    *
    * # Arguments
    *
-   * * `query_vector` - Query vector for similarity search
-   * * `text_query` - Text query for payload search
-   * * `k` - Number of results to return
-   * * `vector_weight` - Weight for vector results (0.0-1.0, default 0.5)
+   * * `label` - The relationship type to filter by
    *
    * # Returns
    *
-   * Array of fused results with id, score, and payload.
+   * Array of edges matching the label.
    */
-  hybrid_search(query_vector: Float32Array, text_query: string, k: number, vector_weight?: number | null): any;
+  get_edges_by_label(label: string): GraphEdge[];
   /**
-   * Creates a new vector store with specified storage mode for memory optimization.
+   * Gets all nodes with a specific label.
    *
    * # Arguments
    *
-   * * `dimension` - Vector dimension
-   * * `metric` - Distance metric
-   * * `mode` - Storage mode: "full", "sq8", or "binary"
-   *
-   * # Storage Modes
+   * * `label` - The label to filter by
    *
-   * - `full`: Best recall, 4 bytes/dimension
-   * - `sq8`: 4x compression, ~1% recall loss
-   * - `binary`: 32x compression, ~5-10% recall loss
+   * # Returns
    *
-   * # Errors
+   * Array of nodes matching the label.
+   */
+  get_nodes_by_label(label: string): GraphNode[];
+  /**
+   * Gets outgoing edges filtered by label.
+   */
+  get_outgoing_by_label(node_id: bigint, label: string): GraphEdge[];
+  /**
+   * Creates a new empty graph store.
+   */
+  constructor();
+  /**
+   * Clears all nodes and edges.
+   */
+  clear(): void;
+  /**
+   * Adds an edge to the graph.
    *
-   * Returns an error if the metric or storage mode is unknown.
+   * Returns an error if an edge with the same ID already exists.
+   */
+  add_edge(edge: GraphEdge): void;
+  /**
+   * Adds a node to the graph.
+   */
+  add_node(node: GraphNode): void;
+  /**
+   * Gets an edge by ID.
+   */
+  get_edge(id: bigint): GraphEdge | undefined;
+  /**
+   * Gets a node by ID.
+   */
+  get_node(id: bigint): GraphNode | undefined;
+  /**
+   * Checks if an edge exists.
+   */
+  has_edge(id: bigint): boolean;
+  /**
+   * Checks if a node exists.
+   */
+  has_node(id: bigint): boolean;
+  /**
+   * Gets the in-degree (number of incoming edges) of a node.
+   */
+  in_degree(node_id: bigint): number;
+  /**
+   * Returns the number of edges.
+   */
+  readonly edge_count: number;
+  /**
+   * Returns the number of nodes.
+   */
+  readonly node_count: number;
+}
+
+/**
+ * Storage mode for vector quantization.
+ */
+export enum StorageMode {
+  /**
+   * Full f32 precision (4 bytes per dimension)
+   */
+  Full = 0,
+  /**
+   * SQ8: 8-bit scalar quantization (1 byte per dimension, 4x compression)
+   */
+  SQ8 = 1,
+  /**
+   * Binary: 1-bit quantization (1 bit per dimension, 32x compression)
+   */
+  Binary = 2,
+}
+
+export class VectorStore {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Text search on payload fields (substring matching).
+   */
+  text_search(query: string, k: number, field?: string | null): any;
+  /**
+   * Batch search for multiple vectors. Returns [[[id, score], ...], ...].
+   */
+  batch_search(vectors: Float32Array, num_vectors: number, k: number): any;
+  /**
+   * Batch insert. Input: `[[id, Float32Array], ...]`.
+   */
+  insert_batch(batch: any): void;
+  /**
+   * Returns memory usage estimate in bytes.
+   */
+  memory_usage(): number;
+  /**
+   * Hybrid search (vector + text). `vector_weight` 0-1 (default 0.5).
+   */
+  hybrid_search(query_vector: Float32Array, text_query: string, k: number, vector_weight?: number | null): any;
+  /**
+   * Creates store with mode: full (4B/dim), sq8 (4x compression), binary (32x).
    */
   static new_with_mode(dimension: number, metric: string, mode: string): VectorStore;
   /**
-   * Creates a new vector store with pre-allocated capacity.
-   *
-   * This is more efficient when you know the approximate number of vectors
-   * you'll be inserting, as it avoids repeated memory allocations.
-   *
-   * # Arguments
-   *
-   * * `dimension` - Vector dimension
-   * * `metric` - Distance metric: "cosine", "euclidean", or "dot"
-   * * `capacity` - Number of vectors to pre-allocate space for
-   *
-   * # Errors
-   *
-   * Returns an error if the metric is not recognized.
+   * Creates store with pre-allocated capacity.
    */
   static with_capacity(dimension: number, metric: string, capacity: number): VectorStore;
   /**
-   * Deletes the `IndexedDB` database.
-   *
-   * Use this to clear all persisted data.
-   *
-   * # Arguments
-   *
-   * * `db_name` - Name of the `IndexedDB` database to delete
-   *
-   * # Errors
-   *
-   * Returns an error if the deletion fails.
+   * Deletes `IndexedDB` database.
    */
   static delete_database(db_name: string): Promise<void>;
   /**
-   * Exports the vector store to a binary format.
-   *
-   * The binary format contains:
-   * - Header: dimension (u32), metric (u8), count (u64)
-   * - For each vector: id (u64), data (f32 array)
-   *
-   * Use this to persist data to `IndexedDB` or `localStorage`.
-   *
-   * # Errors
-   *
-   * This function currently does not return errors but uses `Result`
-   * for future extensibility.
-   *
-   * # Performance
-   *
-   * Perf: Pre-allocates exact buffer size to avoid reallocations.
-   * Throughput: ~1600 MB/s on 10k vectors (768D)
+   * Exports to binary format for IndexedDB/localStorage.
    */
   export_to_bytes(): Uint8Array;
   /**
-   * Imports a vector store from binary format.
-   *
-   * Use this to restore data from `IndexedDB` or `localStorage`.
-   *
-   * # Errors
-   *
-   * Returns an error if:
-   * - The data is too short or corrupted
-   * - The magic number is invalid
-   * - The version is unsupported
-   * - The metric byte is invalid
+   * Imports from binary format.
    */
   static import_from_bytes(bytes: Uint8Array): VectorStore;
   /**
    * Creates a metadata-only store (no vectors, only payloads).
-   *
-   * Useful for storing auxiliary data without vector embeddings.
    */
   static new_metadata_only(): VectorStore;
   /**
-   * Performs multi-query search with result fusion.
-   *
-   * Executes searches for multiple query vectors and fuses results
-   * using the specified strategy.
-   *
-   * # Arguments
-   *
-   * * `vectors` - Array of query vectors (as flat array with dimension stride)
-   * * `num_vectors` - Number of vectors in the array
-   * * `k` - Number of results to return
-   * * `strategy` - Fusion strategy: "average", "maximum", "rrf"
-   * * `rrf_k` - RRF k parameter (only used when strategy = "rrf", default 60)
-   *
-   * # Returns
-   *
-   * Array of fused results with id and score.
+   * Similarity search with threshold. Operators: >, >=, <, <=, =, !=.
+   */
+  similarity_search(query: Float32Array, threshold: number, operator: string, k: number): any;
+  /**
+   * Multi-query search with fusion. Strategies: average, maximum, rrf.
    */
   multi_query_search(vectors: Float32Array, num_vectors: number, k: number, strategy: string, rrf_k?: number | null): any;
   /**
-   * Searches with metadata filtering.
-   *
-   * # Arguments
-   *
-   * * `query` - Query vector
-   * * `k` - Number of results
-   * * `filter` - JSON filter object (e.g., `{"condition": {"type": "eq", "field": "category", "value": "tech"}}`)
-   *
-   * # Returns
-   *
-   * Array of `[id, score, payload]` tuples sorted by relevance.
+   * Searches with metadata filtering. Returns [{id, score, payload}].
    */
   search_with_filter(query: Float32Array, k: number, filter: any): any;
   /**
-   * Inserts a vector with the given ID and optional JSON payload.
-   *
-   * # Arguments
-   *
-   * * `id` - Unique identifier for the vector
-   * * `vector` - `Float32Array` of the vector data
-   * * `payload` - Optional JSON payload (metadata)
-   *
-   * # Errors
-   *
-   * Returns an error if vector dimension doesn't match store dimension.
+   * Inserts a vector with ID and optional JSON payload.
    */
   insert_with_payload(id: bigint, vector: Float32Array, payload: any): void;
   /**
-   * Gets a vector by ID.
-   *
-   * # Arguments
-   *
-   * * `id` - The vector ID to retrieve
-   *
-   * # Returns
-   *
-   * An object with `id`, `vector`, and `payload` fields, or null if not found.
+   * Gets a vector by ID. Returns {id, vector, payload} or null.
    */
   get(id: bigint): any;
   /**
-   * Creates a new vector store with the specified dimension and distance metric.
-   *
-   * # Arguments
-   *
-   * * `dimension` - Vector dimension (e.g., 768 for BERT, 1536 for GPT)
-   * * `metric` - Distance metric: "cosine", "euclidean", or "dot"
-   *
-   * # Errors
-   *
-   * Returns an error if the metric is not recognized.
+   * Creates a new vector store. Metrics: cosine, euclidean, dot, hamming, jaccard.
    */
   constructor(dimension: number, metric: string);
   /**
-   * Loads a vector store from `IndexedDB`.
-   *
-   * This method restores all vectors from the browser's `IndexedDB`.
-   *
-   * # Arguments
-   *
-   * * `db_name` - Name of the `IndexedDB` database
-   *
-   * # Errors
-   *
-   * Returns an error if the database doesn't exist or is corrupted.
-   *
-   * # Example
-   *
-   * ```javascript
-   * const store = await VectorStore.load("my-vectors");
-   * console.log(store.len); // Number of restored vectors
-   * ```
+   * Loads from `IndexedDB`.
    */
   static load(db_name: string): Promise<VectorStore>;
   /**
-   * Saves the vector store to `IndexedDB`.
-   *
-   * This method persists all vectors to the browser's `IndexedDB`,
-   * enabling offline-first applications.
-   *
-   * # Arguments
-   *
-   * * `db_name` - Name of the `IndexedDB` database
-   *
-   * # Errors
-   *
-   * Returns an error if `IndexedDB` is not available or the save fails.
-   *
-   * # Example
-   *
-   * ```javascript
-   * const store = new VectorStore(768, "cosine");
-   * store.insert(1n, vector1);
-   * await store.save("my-vectors");
-   * ```
+   * Saves to `IndexedDB`.
    */
   save(db_name: string): Promise<void>;
   /**
@@ -302,15 +333,6 @@ export class VectorStore {
   clear(): void;
   /**
    * Inserts a vector with the given ID.
-   *
-   * # Arguments
-   *
-   * * `id` - Unique identifier for the vector
-   * * `vector` - `Float32Array` of the vector data
-   *
-   * # Errors
-   *
-   * Returns an error if vector dimension doesn't match store dimension.
    */
   insert(id: bigint, vector: Float32Array): void;
   /**
@@ -318,30 +340,11 @@ export class VectorStore {
    */
   remove(id: bigint): boolean;
   /**
-   * Searches for the k nearest neighbors to the query vector.
-   *
-   * # Arguments
-   *
-   * * `query` - Query vector as `Float32Array`
-   * * `k` - Number of results to return
-   *
-   * # Returns
-   *
-   * Array of [id, score] pairs sorted by relevance.
-   *
-   * # Errors
-   *
-   * Returns an error if query dimension doesn't match store dimension.
+   * k-NN search. Returns [[id, score], ...].
    */
   search(query: Float32Array, k: number): any;
   /**
-   * Pre-allocates memory for the specified number of additional vectors.
-   *
-   * Call this before bulk insertions to avoid repeated allocations.
-   *
-   * # Arguments
-   *
-   * * `additional` - Number of additional vectors to reserve space for
+   * Pre-allocates memory for additional vectors.
    */
   reserve(additional: number): void;
   /**
@@ -370,7 +373,50 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
   readonly memory: WebAssembly.Memory;
+  readonly __wbg_graphedge_free: (a: number, b: number) => void;
+  readonly __wbg_graphnode_free: (a: number, b: number) => void;
+  readonly __wbg_graphstore_free: (a: number, b: number) => void;
   readonly __wbg_vectorstore_free: (a: number, b: number) => void;
+  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;
+  readonly graphedge_set_number_property: (a: number, b: number, c: number, d: number) => void;
+  readonly graphedge_set_string_property: (a: number, b: number, c: number, d: number, e: number) => void;
+  readonly graphedge_source: (a: number) => bigint;
+  readonly graphedge_target: (a: number) => bigint;
+  readonly graphedge_to_json: (a: number, b: number) => void;
+  readonly graphnode_has_vector: (a: number) => number;
+  readonly graphnode_label: (a: number, b: number) => void;
+  readonly graphnode_new: (a: bigint, b: number, c: number) => number;
+  readonly graphnode_set_bool_property: (a: number, b: number, c: number, d: number) => void;
+  readonly graphnode_set_number_property: (a: number, b: number, c: number, d: number) => void;
+  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 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;
+  readonly graphstore_clear: (a: number) => void;
+  readonly graphstore_dfs_traverse: (a: number, b: number, c: bigint, d: number, e: number) => void;
+  readonly graphstore_edge_count: (a: number) => number;
+  readonly graphstore_get_all_edge_ids: (a: number, b: number) => void;
+  readonly graphstore_get_all_node_ids: (a: number, b: number) => void;
+  readonly graphstore_get_edge: (a: number, b: bigint) => number;
+  readonly graphstore_get_edges_by_label: (a: number, b: number, c: number, d: number) => void;
+  readonly graphstore_get_incoming: (a: number, b: number, c: bigint) => void;
+  readonly graphstore_get_neighbors: (a: number, b: number, c: bigint) => void;
+  readonly graphstore_get_node: (a: number, b: bigint) => number;
+  readonly graphstore_get_nodes_by_label: (a: number, b: number, c: number, d: number) => void;
+  readonly graphstore_get_outgoing: (a: number, b: number, c: bigint) => void;
+  readonly graphstore_get_outgoing_by_label: (a: number, b: number, c: bigint, d: number, e: number) => void;
+  readonly graphstore_has_edge: (a: number, b: bigint) => number;
+  readonly graphstore_has_node: (a: number, b: bigint) => number;
+  readonly graphstore_in_degree: (a: number, b: bigint) => number;
+  readonly graphstore_new: () => number;
+  readonly graphstore_node_count: (a: number) => number;
+  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 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;
@@ -396,14 +442,16 @@ export interface InitOutput {
   readonly vectorstore_save: (a: number, b: number, c: number) => number;
   readonly vectorstore_search: (a: number, b: number, c: number, d: number, e: number) => void;
   readonly vectorstore_search_with_filter: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+  readonly vectorstore_similarity_search: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
   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 __wasm_bindgen_func_elem_148: (a: number, b: number, c: number) => void;
-  readonly __wasm_bindgen_func_elem_147: (a: number, b: number) => void;
-  readonly __wasm_bindgen_func_elem_528: (a: number, b: number, c: number) => void;
-  readonly __wasm_bindgen_func_elem_527: (a: number, b: number) => void;
-  readonly __wasm_bindgen_func_elem_577: (a: number, b: number, c: number, d: number) => void;
+  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 __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;