eigen-db 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# v4.4.0
+
+Added: `entries()`, `keys()`, `values()`, `delete()`, `has()` methods, and `dimensions` property
+
+# v4.3.0
+
+Added: option to choose between in memory or OPFS storage backends
+
 # v4.2.0
 
 Added: import/export in binary format

package/README.md

@@ -4,7 +4,7 @@ High-performance vector database for the web.
 
 `eigen-db` stores and queries embedding vectors in-browser, using:
 
-- OPFS (Origin Private File System) for persistence
+- Pluggable storage backends (in-memory by default, OPFS for browser persistence)
 - WASM SIMD for fast compute when available
 - JavaScript fallback when WASM SIMD is unavailable
 
@@ -21,13 +21,24 @@ npm install eigen-db
 ```ts
 import { DB } from "eigen-db";
 
+// In-memory (default) — no persistence, great for ephemeral sessions
 const db = await DB.open({
-  name: "my-index", // optional, defaults to "default"
   dimensions: 1536, // required
   normalize: true, // optional, defaults to true
 });
 ```
 
+For browser persistence, mount an OPFS storage backend:
+
+```ts
+import { DB, OPFSStorageProvider } from "eigen-db";
+
+const db = await DB.open({
+  dimensions: 1536,
+  storage: new OPFSStorageProvider("my-index"), // persistent OPFS directory
+});
+```
+
 ### 2) Insert vectors
 
 ```ts
@@ -45,7 +56,34 @@ Notes:
 - Each vector must be a `number[]` (or `Float32Array`) with exactly `dimensions` elements.
 - Duplicate keys use last-write-wins semantics.
 
-### 3) Query nearest vectors
+### 3) Look up, check, and remove vectors
+
+```ts
+db.get("doc:1"); // number[] | undefined
+db.has("doc:1"); // true
+db.delete("doc:1"); // true (removed), false (not found)
+db.dimensions; // configured vector dimensions
+db.size; // number of entries
+```
+
+### 4) Iterate over the database
+
+```ts
+// Iterate over all keys
+for (const key of db.keys()) {
+  console.log(key);
+}
+
+// Iterate over all [key, value] pairs
+for (const [key, vector] of db.entries()) {
+  console.log(key, vector);
+}
+
+// Spread into an array (uses Symbol.iterator, same as entries())
+const all = [...db];
+```
+
+### 5) Query nearest vectors
 
 ```ts
 const queryVector = embeddingQuery;
@@ -83,7 +121,7 @@ const results = db.query(queryVector, { minSimilarity: 0.7 });
 const results = db.query(queryVector, { minSimilarity: 0.7, iterable: true });
 ```
 
-### 4) Persist and lifecycle
+### 6) Persist and lifecycle
 
 ```ts
 await db.flush(); // persist current state
@@ -96,7 +134,7 @@ To delete all vectors and storage:
 await db.clear();
 ```
 
-### 5) Export and import
+### 7) Export and import
 
 Export the entire database as a streaming binary file:
 
@@ -172,6 +210,7 @@ Opens (or creates) a database instance and loads persisted data.
 #### Properties
 
 - `size: number` — current number of key-vector pairs
+- `dimensions: number` — number of dimensions per vector
 
 #### Methods
 
@@ -180,10 +219,20 @@ Opens (or creates) a database instance and loads persisted data.
   - Throws on dimension mismatch.
 - `get(key: string): number[] | undefined`
   - Returns a copy of the stored vector.
+- `has(key: string): boolean`
+  - Returns `true` if the key exists, `false` otherwise. O(1) lookup.
+- `delete(key: string): boolean`
+  - Removes the entry for the given key. Returns `true` if the key existed, `false` otherwise.
 - `setMany(entries: [string, VectorInput][]): void`
   - Batch insert/update.
 - `getMany(keys: string[]): (number[] | undefined)[]`
   - Batch lookup.
+- `keys(): IterableIterator<string>`
+  - Returns an iterable of all keys.
+- `entries(): IterableIterator<[string, number[]]>`
+  - Returns an iterable of `[key, value]` pairs. Values are plain number array copies.
+- `[Symbol.iterator](): IterableIterator<[string, number[]]>`
+  - Same as `entries()`. Enables `[...db]` and `for...of` iteration.
 - `query(value: VectorInput, options?: QueryOptions): ResultItem[]`
   - Returns results sorted by descending similarity as a plain array.
   - Throws on dimension mismatch.
@@ -221,9 +270,9 @@ interface ResultItem {
 
 ```ts
 interface OpenOptions {
-  name?: string; // OPFS directory name, default: "default"
   dimensions: number; // vector size
   normalize?: boolean; // default: true
+  storage?: StorageProvider; // default: InMemoryStorageProvider
 }
 ```
 
@@ -233,12 +282,10 @@ Advanced/testing override options.
 
 ```ts
 interface OpenOptionsInternal extends OpenOptions {
-  storage?: StorageProvider;
   wasmBinary?: Uint8Array | null;
 }
 ```
 
-- `storage`: provide custom storage implementation (for example, tests)
 - `wasmBinary`:
   - `Uint8Array`: use provided precompiled WASM
   - `null`: force JavaScript-only compute

package/dist/compute.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure JavaScript compute functions for vector operations.
+ * These serve as the reference implementation and fallback when WASM SIMD is unavailable.
+ */
+/**
+ * Normalizes a vector in-place to unit length.
+ * After normalization, cosine similarity reduces to a simple dot product.
+ */
+export declare function normalize(vec: Float32Array): void;
+/**
+ * Computes dot products of query against all vectors in the database.
+ * Writes scores to the output array.
+ *
+ * @param query - Normalized query vector (length = dimensions)
+ * @param db - Contiguous flat array of normalized vectors (length = dbSize * dimensions)
+ * @param scores - Output array for dot product scores (length = dbSize)
+ * @param dbSize - Number of vectors in the database
+ * @param dimensions - Dimensionality of each vector
+ */
+export declare function searchAll(query: Float32Array, db: Float32Array, scores: Float32Array, dbSize: number, dimensions: number): void;