TypeScript/JavaScript SDK
Relevant source files
The following files were used as context for generating this wiki page:
The EdgeVec TypeScript/JavaScript SDK is a high-level wrapper designed to interface with the core Rust-based vector engine via WebAssembly (WASM). It provides an ergonomic, Promise-based API for browser and Node.js environments, enabling developers to perform high-performance vector similarity searches, metadata filtering, and persistent storage using IndexedDB.
Sources: wasm/README.md:1-5, README.md:5-9
The SDK abstracts the complexities of WASM memory management and initialization, offering typed structures for configuration and search results. It is specifically optimized for client-side operations, allowing for "server-grade" features like binary quantization and SQL-like metadata queries directly in the user's browser.
Sources: README.md:12-16, wasm/README.md:8-12
Core Architecture and Initialization
The SDK operates as a bridge between the JavaScript environment and the WASM memory space. Initialization is a mandatory first step, typically handled via a default export function that loads the .wasm binary.
Initialization Flow
The following diagram illustrates the standard initialization and setup process for the SDK:
An explicit call to init() is required before any class instantiation. The SDK then provides the EdgeVec and EdgeVecConfig classes for database operations.
Sources: README.md:51-55, wasm/examples/filter-playground.html:565-595, wasm/examples/batch_insert.js:510-530
Configuration and Indexing
Database behavior is governed by EdgeVecConfig. This object defines the dimensionality of the vectors and the performance parameters for the Hierarchical Navigable Small World (HNSW) index.
Configuration Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dimensions | number | Required | The fixed size of vector embeddings (e.g., 768). |
metric | string | 'l2' | Distance metric: 'l2', 'cosine', or 'dot'. |
quantization | string | 'none' | Compression mode: 'none', 'sq8', or 'bq'. |
m | number | 16 | HNSW parameter: number of bi-directional links per node. |
ef_construction | number | 200 | Size of dynamic candidate list during construction. |
Sources: wasm/README.md:55-65, README.md:213-220, wasm/examples/stress-test.html:610-615
Vector Insertion Methods
The SDK provides both synchronous single-point insertion and optimized batch insertion to minimize JS-WASM bridge overhead.
insert(vector: Float32Array): Inserts a single vector and returns a unique integer ID.insertWithMetadata(vector, metadata): Associates a JSON-serializable object with the vector for filtered searching.insertBatch(vectors: Float32Array[]): Processes multiple vectors in a single call, significantly increasing throughput.
Sources: wasm/README.md:71-77, README.md:58-65, wasm/examples/batch_insert.js:415-430
Metadata Filtering and Search
One of the SDK's primary features is the ability to execute SQL-like queries against vector metadata. This allows users to narrow down similarity results based on attributes like price, category, or status.
Filter Syntax
The SDK supports a variety of operators for metadata queries:
- Comparison:
=,!=,>,<,>=,<= - Logical:
AND,OR,NOT - Array/Membership:
IN,ANY,CONTAINS,STARTS_WITH,ENDS_WITH - Null Checks:
IS NULL,IS NOT NULL
Sources: wasm/examples/filter-playground.html:485-535, README.md:144-155
Search Execution Flow
The following diagram shows how a filtered search is processed:
The SDK exposes searchWithFilter(query, filter, k) for these operations. Results are returned as an array of SearchResult objects containing the vector id and its calculated distance.
Sources: wasm/examples/filter-playground.html:910-930, wasm/README.md:112-118, README.md:68-75
Memory Management and Persistence
Since the SDK runs in the browser's restricted environment, it provides specialized APIs for memory pressure monitoring and disk persistence.
Persistence API
Data can be persisted to IndexedDB using the save(name) and load(name) methods. These operations are asynchronous.
save(name: string): Serializes the current index state and writes it to IndexedDB.load(name: string, config): Reconstructs an index from stored data.
Sources: wasm/README.md:81-89, wasm/examples/stress-test.html:665-685
Memory and Maintenance
The SDK uses a "soft delete" strategy where vectors are marked with tombstones rather than immediate removal to maintain HNSW graph integrity.
| Function | Purpose |
|---|---|
softDelete(id) | Marks a vector as deleted in O(1) time. |
getMemoryPressure() | Returns heap usage stats (used, total, percentage). |
needsCompaction() | Boolean check if tombstones exceed efficiency thresholds. |
compact() | Removes tombstones and rebuilds the index to reclaim memory. |
Sources: README.md:158-175, wasm/examples/soft_delete.html:840-870, GATE_1_COMPLETE.md:200-215
Conclusion
The TypeScript/JavaScript SDK acts as the primary interface for the EdgeVec engine, providing a robust set of tools for vector operations in the browser. By combining high-performance WASM execution with convenient JavaScript abstractions for filtering, batching, and persistence, it enables sophisticated AI-driven search capabilities without requiring server-side infrastructure.
Sources: wasm/README.md:1-12, README.md:5-20