@omendb/omendb 0.0.2-alpha.1 → 0.0.2

package/README.md

@@ -20,12 +20,12 @@ const db = open("./vectors", { dimensions: 384 });
 db.set([
   {
     id: "doc1",
-    embedding: new Float32Array(384).fill(0.1),
+    vector: new Float32Array(384).fill(0.1),
     metadata: { title: "Hello" },
   },
   {
     id: "doc2",
-    embedding: new Float32Array(384).fill(0.2),
+    vector: new Float32Array(384).fill(0.2),
     metadata: { title: "World" },
   },
 ]);

package/index.d.ts

@@ -1,104 +1,130 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
 export declare class VectorDatabase {
-	/**
-	 * Insert or update vectors.
-	 *
-	 * Accepts an array of items with id, embedding, and optional metadata.
-	 */
-	set(items: Array<VectorItem>): Array<number>;
-	/**
-	 * Search for k nearest neighbors.
-	 *
-	 * @param query - Query vector (number[] or Float32Array)
-	 * @param k - Number of results to return
-	 * @param ef - Optional search width override
-	 * @returns Array of {id, distance, metadata}
-	 */
-	search(
-		query: Array<number> | Float32Array,
-		k: number,
-		ef?: number | undefined | null,
-	): Array<SearchResult>;
-	/**
-	 * Batch search with parallel execution (async).
-	 *
-	 * Runs searches in parallel using rayon, returns Promise.
-	 */
-	searchBatch(
-		queries: Array<Array<number> | Float32Array>,
-		k: number,
-		ef?: number | undefined | null,
-	): Promise<Array<Array<SearchResult>>>;
-	/** Get a vector by ID. */
-	get(id: string): GetResult | null;
-	/**
-	 * Delete vectors by ID.
-	 *
-	 * @returns Number of vectors deleted
-	 */
-	delete(ids: Array<string>): number;
-	/** Update a vector's embedding and/or metadata. */
-	update(
-		id: string,
-		embedding: Array<number> | Float32Array,
-		metadata?: Record<string, unknown> | undefined,
-	): void;
-	/** Save database to disk. */
-	save(): void;
-	/** Get number of vectors in database. */
-	get count(): number;
-	/** Get current ef_search value. */
-	get efSearch(): number | null;
-	/** Set ef_search value. */
-	set efSearch(efSearch: number);
-	/** Get or create a named collection. */
-	collection(name: string): VectorDatabase;
-	/** List all collections. */
-	collections(): Array<string>;
-	/** Delete a collection. */
-	deleteCollection(name: string): void;
-	/** Merge another database into this one. */
-	mergeFrom(other: VectorDatabase): number;
+  /**
+   * Insert or update vectors.
+   *
+   * Accepts an array of items with id, vector, and optional metadata.
+   */
+  set(items: Array<VectorItem>): Array<number>
+  /**
+   * Search for k nearest neighbors.
+   *
+   * @param query - Query vector (number[] or Float32Array)
+   * @param k - Number of results to return
+   * @param ef - Optional search width override
+   * @param filter - Optional metadata filter (e.g., {category: "foo"} or {price: {$gt: 10}})
+   * @returns Array of {id, distance, metadata}
+   */
+  search(query: Array<number> | Float32Array, k: number, ef?: number | undefined | null, filter?: Record<string, unknown> | undefined): Array<SearchResult>
+  /**
+   * Batch search with parallel execution (async).
+   *
+   * Runs searches in parallel using rayon, returns Promise.
+   */
+  searchBatch(queries: Array<Array<number> | Float32Array>, k: number, ef?: number | undefined | null): Promise<Array<Array<SearchResult>>>
+  /** Get a vector by ID. */
+  get(id: string): GetResult | null
+  /**
+   * Delete vectors by ID.
+   *
+   * @returns Number of vectors deleted
+   */
+  delete(ids: Array<string>): number
+  /** Update a vector's data and/or metadata. */
+  update(id: string, vector: Array<number> | Float32Array, metadata?: Record<string, unknown> | undefined): void
+  /** Save database to disk. */
+  save(): void
+  /** Get number of vectors in database. */
+  get count(): number
+  /** Get current ef_search value. */
+  get efSearch(): number | null
+  /** Set ef_search value. */
+  set efSearch(efSearch: number)
+  /** Get or create a named collection. */
+  collection(name: string): VectorDatabase
+  /** List all collections. */
+  collections(): Array<string>
+  /** Delete a collection. */
+  deleteCollection(name: string): void
+  /** Merge another database into this one. */
+  mergeFrom(other: VectorDatabase): number
 }
 
 export interface GetResult {
-	id: string;
-	embedding: Array<number>;
-	metadata: Record<string, unknown>;
+  id: string
+  vector: Array<number>
+  metadata: Record<string, unknown>
 }
 
 /**
  * Open or create a vector database.
  *
  * @param path - Database directory path (use ":memory:" for in-memory)
- * @param options - Optional configuration
+ * @param options - Optional configuration (see OpenOptions for defaults)
  * @returns VectorDatabase instance
+ *
+ * @example
+ * ```javascript
+ * // Simple usage with defaults
+ * const db = omendb.open("./mydb");
+ *
+ * // With custom HNSW parameters
+ * const db = omendb.open("./mydb", {
+ *   dimensions: 384,
+ *   m: 32,
+ *   efConstruction: 200,
+ *   efSearch: 150
+ * });
+ *
+ * // With RaBitQ quantization (8x memory reduction)
+ * const db = omendb.open("./mydb", {
+ *   dimensions: 128,
+ *   quantization: 4  // 4-bit quantization
+ * });
+ * ```
  */
-export declare function open(
-	path: string,
-	options?: OpenOptions | undefined | null,
-): VectorDatabase;
+export declare function open(path: string, options?: OpenOptions | undefined | null): VectorDatabase
 
+/**
+ * Configuration options for opening a vector database.
+ *
+ * All fields are optional with sensible defaults:
+ * - dimensions: 128 (auto-detected on first insert if not specified)
+ * - m: 16 (HNSW neighbors per node, higher = better recall, more memory)
+ * - efConstruction: 100 (build quality, higher = better graph, slower build)
+ * - efSearch: 100 (search quality, higher = better recall, slower search)
+ * - quantization: null (RaBitQ bit width: 2, 4, or 8 for compression)
+ */
 export interface OpenOptions {
-	dimensions?: number;
-	m?: number;
-	efConstruction?: number;
+  /** Vector dimensions (default: 128, auto-detected on first insert) */
+  dimensions?: number
+  /** HNSW M parameter: neighbors per node (default: 16, range: 4-64) */
+  m?: number
+  /** HNSW ef_construction: build quality (default: 100, must be >= m) */
+  efConstruction?: number
+  /** HNSW ef_search: search quality/speed tradeoff (default: 100) */
+  efSearch?: number
+  /**
+   * RaBitQ quantization bits: 2, 4, or 8 (default: null = no quantization)
+   * Enables 4-16x memory compression with ~1-2% recall loss
+   */
+  quantization?: number
 }
 
 export interface SearchResult {
-	id: string;
-	distance: number;
-	/** Metadata as JSON (using serde-json feature) */
-	metadata: Record<string, unknown>;
+  id: string
+  distance: number
+  /** Metadata as JSON (using serde-json feature) */
+  metadata: Record<string, unknown>
 }
 
 export interface VectorItem {
-	id: string;
-	/** Embedding as array of numbers */
-	embedding: Array<number>;
-	/** Optional metadata */
-	metadata?: Record<string, unknown> | undefined;
-	/** Optional document text (stored in metadata.document) */
-	document?: string;
+  id: string
+  /** Vector data as array of numbers */
+  vector: Array<number>
+  /** Optional metadata */
+  metadata?: Record<string, unknown> | undefined
+  /** Optional document text (stored in metadata.document) */
+  document?: string
 }

package/package.json

@@ -1,12 +1,12 @@
 {
 	"name": "@omendb/omendb",
-	"version": "0.0.2-alpha.1",
+	"version": "0.0.2",
 	"description": "Fast embedded vector database with HNSW indexing",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/nijaru/omendb"
+		"url": "https://github.com/omendb/omendb"
 	},
 	"keywords": [
 		"vector",
@@ -26,7 +26,7 @@
 	},
 	"napi": {
 		"binaryName": "omendb",
-		"packageName": "omendb",
+		"packageName": "@omendb/omendb",
 		"targets": [
 			"x86_64-apple-darwin",
 			"aarch64-apple-darwin",
@@ -49,9 +49,9 @@
 		"omendb.node"
 	],
 	"optionalDependencies": {
-		"omendb-darwin-x64": "0.0.2-alpha.1",
-		"omendb-darwin-arm64": "0.0.2-alpha.1",
-		"omendb-linux-x64-gnu": "0.0.2-alpha.1",
-		"omendb-linux-arm64-gnu": "0.0.2-alpha.1"
+		"@omendb/omendb-darwin-x64": "0.0.2",
+		"@omendb/omendb-darwin-arm64": "0.0.2",
+		"@omendb/omendb-linux-x64-gnu": "0.0.2",
+		"@omendb/omendb-linux-arm64-gnu": "0.0.2"
 	}
 }