@omendb/omendb 0.0.19 → 0.0.20

package/index.d.ts

@@ -1,207 +1,229 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
 export declare class VectorDatabase {
-  /**
-   * 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}})
-   * @param maxDistance - Optional max distance threshold (filter out distant results)
-   * @returns Array of {id, distance, metadata}
-   */
-  search(query: Array<number> | Float32Array, k: number, ef?: number | undefined | null, filter?: Record<string, unknown> | undefined, maxDistance?: 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
-  /**
-   * Delete vectors matching a metadata filter.
-   *
-   * Evaluates the filter against all vectors and deletes those that match.
-   * Uses the same MongoDB-style filter syntax as search().
-   *
-   * @param filter - MongoDB-style metadata filter
-   * @returns Number of vectors deleted
-   *
-   * @example
-   * ```javascript
-   * // Delete by equality
-   * db.deleteWhere({ status: "archived" });
-   *
-   * // Delete with comparison
-   * db.deleteWhere({ score: { $lt: 0.5 } });
-   *
-   * // Complex filter
-   * db.deleteWhere({ $and: [{ type: "draft" }, { age: { $gt: 30 } }] });
-   * ```
-   */
-  deleteWhere(filter: Record<string, unknown>): number
-  /**
-   * Count vectors, optionally filtered by metadata.
-   *
-   * Without a filter, returns total count (same as db.length).
-   * With a filter, returns count of vectors matching the filter.
-   *
-   * @param filter - Optional MongoDB-style metadata filter
-   * @returns Number of vectors (matching filter if provided)
-   *
-   * @example
-   * ```javascript
-   * // Total count
-   * const total = db.count();
-   *
-   * // Filtered count
-   * const active = db.count({ status: "active" });
-   *
-   * // With comparison operators
-   * const highScore = db.count({ score: { $gte: 0.8 } });
-   * ```
-   */
-  count(filter?: Record<string, unknown> | undefined): number
-  /** Update a vector's data and/or metadata. */
-  update(id: string, vector: Array<number> | Float32Array, metadata?: Record<string, unknown> | undefined): void
-  /** Get number of vectors in database. */
-  get length(): number
-  /** Get vector dimensions of this database. */
-  get dimensions(): number
-  /** Check if database is empty. */
-  isEmpty(): boolean
-  /** Get database statistics. */
-  stats(): StatsResult
-  /** Get current ef_search value. */
-  get efSearch(): number
-  /** Set ef_search value. */
-  set efSearch(efSearch: number)
-  /**
-   * Get or create a named collection.
-   *
-   * Collection handles share state - changes made through one handle
-   * are immediately visible through another (no flush required).
-   */
-  collection(name: string): VectorDatabase
-  /** List all collections. */
-  collections(): Array<string>
-  /** Delete a collection. */
-  deleteCollection(name: string): void
-  /**
-   * Enable text search for hybrid (vector + text) search.
-   *
-   * Must be called before using setWithText() or hybridSearch().
-   */
-  enableTextSearch(): void
-  /** Check if text search is enabled. */
-  get hasTextSearch(): boolean
-  /**
-   * Set vectors with associated text for hybrid search.
-   *
-   * @param items - Array of {id, vector, text, metadata?}
-   * @returns Array of internal indices
-   */
-  setWithText(items: Array<VectorItemWithText>): Array<number>
-  /**
-   * Search using text only (BM25 scoring).
-   *
-   * @param query - Text query
-   * @param k - Number of results
-   * @returns Array of {id, score, metadata}
-   */
-  textSearch(query: string, k: number): Array<TextSearchResult>
-  /**
-   * Hybrid search combining vector similarity and text relevance.
-   *
-   * Uses Reciprocal Rank Fusion (RRF) to combine HNSW and BM25 results.
-   *
-   * @param queryVector - Query embedding
-   * @param queryText - Text query for BM25
-   * @param k - Number of results
-   * @param filter - Optional metadata filter
-   * @param alpha - Weight for vector vs text (0.0=text only, 1.0=vector only, default=0.5)
-   * @param rrfK - RRF constant (default=60, higher reduces rank influence)
-   * @param subscores - Return separate keyword_score and semantic_score (default: false)
-   * @returns Array of {id, score, metadata, keyword_score?, semantic_score?}
-   */
-  hybridSearch(queryVector: Array<number> | Float32Array, queryText: string, k: number, filter?: Record<string, unknown> | undefined, alpha?: number | undefined | null, rrfK?: number | undefined | null, subscores?: boolean | undefined | null): Array<HybridSearchResult>
-  /**
-   * Flush pending changes to disk.
-   *
-   * For hybrid search, this commits text index changes.
-   */
-  flush(): void
-  /**
-   * Optimize index for cache-efficient search.
-   *
-   * Reorders nodes for better memory locality, improving search performance by 6-40%.
-   * Call after inserting a large batch of vectors.
-   *
-   * @returns Number of nodes reordered
-   */
-  optimize(): number
-  /** Merge another database into this one. */
-  mergeFrom(other: VectorDatabase): number
-  /**
-   * List all vector IDs (without loading vector data).
-   *
-   * Efficient way to get all IDs for iteration, export, or debugging.
-   * @returns Array of all vector IDs in the database
-   */
-  ids(): Array<string>
-  /**
-   * Get all items as array of {id, vector, metadata}.
-   *
-   * Returns all vectors with their IDs and metadata.
-   * For large datasets, consider using ids() and get() in batches.
-   */
-  items(): Array<GetResult>
-  /**
-   * Check if an ID exists in the database.
-   *
-   * @param id - Vector ID to check
-   * @returns true if ID exists and is not deleted
-   */
-  exists(id: string): boolean
-  /**
-   * Get multiple vectors by ID.
-   *
-   * Batch version of get(). More efficient than calling get() in a loop.
-   *
-   * @param ids - Array of vector IDs to retrieve
-   * @returns Array of results in same order as input, null for missing IDs
-   */
-  getMany(ids: Array<string>): Array<GetResult | undefined | null>
+	/**
+	 * 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}})
+	 * @param maxDistance - Optional max distance threshold (filter out distant results)
+	 * @returns Array of {id, distance, metadata}
+	 */
+	search(
+		query: Array<number> | Float32Array,
+		k: number,
+		ef?: number | undefined | null,
+		filter?: Record<string, unknown> | undefined,
+		maxDistance?: 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;
+	/**
+	 * Delete vectors matching a metadata filter.
+	 *
+	 * Evaluates the filter against all vectors and deletes those that match.
+	 * Uses the same MongoDB-style filter syntax as search().
+	 *
+	 * @param filter - MongoDB-style metadata filter
+	 * @returns Number of vectors deleted
+	 *
+	 * @example
+	 * ```javascript
+	 * // Delete by equality
+	 * db.deleteWhere({ status: "archived" });
+	 *
+	 * // Delete with comparison
+	 * db.deleteWhere({ score: { $lt: 0.5 } });
+	 *
+	 * // Complex filter
+	 * db.deleteWhere({ $and: [{ type: "draft" }, { age: { $gt: 30 } }] });
+	 * ```
+	 */
+	deleteWhere(filter: Record<string, unknown>): number;
+	/**
+	 * Count vectors, optionally filtered by metadata.
+	 *
+	 * Without a filter, returns total count (same as db.length).
+	 * With a filter, returns count of vectors matching the filter.
+	 *
+	 * @param filter - Optional MongoDB-style metadata filter
+	 * @returns Number of vectors (matching filter if provided)
+	 *
+	 * @example
+	 * ```javascript
+	 * // Total count
+	 * const total = db.count();
+	 *
+	 * // Filtered count
+	 * const active = db.count({ status: "active" });
+	 *
+	 * // With comparison operators
+	 * const highScore = db.count({ score: { $gte: 0.8 } });
+	 * ```
+	 */
+	count(filter?: Record<string, unknown> | undefined): number;
+	/** Update a vector's data and/or metadata. */
+	update(
+		id: string,
+		vector: Array<number> | Float32Array,
+		metadata?: Record<string, unknown> | undefined,
+	): void;
+	/** Get number of vectors in database. */
+	get length(): number;
+	/** Get vector dimensions of this database. */
+	get dimensions(): number;
+	/** Check if database is empty. */
+	isEmpty(): boolean;
+	/** Get database statistics. */
+	stats(): StatsResult;
+	/** Get current ef_search value. */
+	get efSearch(): number;
+	/** Set ef_search value. */
+	set efSearch(efSearch: number);
+	/**
+	 * Get or create a named collection.
+	 *
+	 * Collection handles share state - changes made through one handle
+	 * are immediately visible through another (no flush required).
+	 */
+	collection(name: string): VectorDatabase;
+	/** List all collections. */
+	collections(): Array<string>;
+	/** Delete a collection. */
+	deleteCollection(name: string): void;
+	/**
+	 * Enable text search for hybrid (vector + text) search.
+	 *
+	 * Must be called before using setWithText() or hybridSearch().
+	 */
+	enableTextSearch(): void;
+	/** Check if text search is enabled. */
+	get hasTextSearch(): boolean;
+	/**
+	 * Set vectors with associated text for hybrid search.
+	 *
+	 * @param items - Array of {id, vector, text, metadata?}
+	 * @returns Array of internal indices
+	 */
+	setWithText(items: Array<VectorItemWithText>): Array<number>;
+	/**
+	 * Search using text only (BM25 scoring).
+	 *
+	 * @param query - Text query
+	 * @param k - Number of results
+	 * @returns Array of {id, score, metadata}
+	 */
+	textSearch(query: string, k: number): Array<TextSearchResult>;
+	/**
+	 * Hybrid search combining vector similarity and text relevance.
+	 *
+	 * Uses Reciprocal Rank Fusion (RRF) to combine HNSW and BM25 results.
+	 *
+	 * @param queryVector - Query embedding
+	 * @param queryText - Text query for BM25
+	 * @param k - Number of results
+	 * @param filter - Optional metadata filter
+	 * @param alpha - Weight for vector vs text (0.0=text only, 1.0=vector only, default=0.5)
+	 * @param rrfK - RRF constant (default=60, higher reduces rank influence)
+	 * @param subscores - Return separate keyword_score and semantic_score (default: false)
+	 * @returns Array of {id, score, metadata, keyword_score?, semantic_score?}
+	 */
+	hybridSearch(
+		queryVector: Array<number> | Float32Array,
+		queryText: string,
+		k: number,
+		filter?: Record<string, unknown> | undefined,
+		alpha?: number | undefined | null,
+		rrfK?: number | undefined | null,
+		subscores?: boolean | undefined | null,
+	): Array<HybridSearchResult>;
+	/**
+	 * Flush pending changes to disk.
+	 *
+	 * For hybrid search, this commits text index changes.
+	 */
+	flush(): void;
+	/**
+	 * Optimize index for cache-efficient search.
+	 *
+	 * Reorders nodes for better memory locality, improving search performance by 6-40%.
+	 * Call after inserting a large batch of vectors.
+	 *
+	 * @returns Number of nodes reordered
+	 */
+	optimize(): number;
+	/** Merge another database into this one. */
+	mergeFrom(other: VectorDatabase): number;
+	/**
+	 * List all vector IDs (without loading vector data).
+	 *
+	 * Efficient way to get all IDs for iteration, export, or debugging.
+	 * @returns Array of all vector IDs in the database
+	 */
+	ids(): Array<string>;
+	/**
+	 * Get all items as array of {id, vector, metadata}.
+	 *
+	 * Returns all vectors with their IDs and metadata.
+	 * For large datasets, consider using ids() and get() in batches.
+	 */
+	items(): Array<GetResult>;
+	/**
+	 * Check if an ID exists in the database.
+	 *
+	 * @param id - Vector ID to check
+	 * @returns true if ID exists and is not deleted
+	 */
+	exists(id: string): boolean;
+	/**
+	 * Get multiple vectors by ID.
+	 *
+	 * Batch version of get(). More efficient than calling get() in a loop.
+	 *
+	 * @param ids - Array of vector IDs to retrieve
+	 * @returns Array of results in same order as input, null for missing IDs
+	 */
+	getMany(ids: Array<string>): Array<GetResult | undefined | null>;
 }
 
 export interface GetResult {
-  id: string
-  vector: Array<number>
-  metadata: Record<string, unknown>
+	id: string;
+	vector: Float32Array;
+	metadata: Record<string, unknown>;
 }
 
 export interface HybridSearchResult {
-  id: string
-  score: number
-  metadata: Record<string, unknown>
-  /** BM25 keyword matching score (null if document only matched vector search) */
-  keywordScore?: number
-  /** Vector similarity score (null if document only matched text search) */
-  semanticScore?: number
+	id: string;
+	score: number;
+	metadata: Record<string, unknown>;
+	/** BM25 keyword matching score (null if document only matched vector search) */
+	keywordScore?: number;
+	/** Vector similarity score (null if document only matched text search) */
+	semanticScore?: number;
 }
 
 /**
@@ -239,7 +261,10 @@ export interface HybridSearchResult {
  * });
  * ```
  */
-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.
@@ -255,68 +280,69 @@ export declare function open(path: string, options?: OpenOptions | undefined | n
  * - metric: "l2" (distance metric: "l2", "euclidean", "cosine", "dot", "ip")
  */
 export interface OpenOptions {
-  /** 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
-  /**
-   * Quantization mode (default: null = no quantization)
-   * - true or "sq8": SQ8 4x compression, ~99% recall (RECOMMENDED)
-   * - "rabitq": RaBitQ 8x compression, ~98% recall
-   * - "binary": Binary 32x compression, ~95% recall
-   * - 2, 4, 8: RaBitQ with specific bits (legacy)
-   */
-  quantization?: boolean | string | number | null | undefined
-  /**
-   * Rescore candidates with exact distance (default: true when quantization enabled)
-   * Set to false for maximum speed at the cost of ~20% recall
-   */
-  rescore?: boolean
-  /**
-   * Oversampling factor for rescoring (default: 3.0)
-   * Fetches k*oversample candidates then reranks to return top k
-   */
-  oversample?: number
-  /** Distance metric: "l2"/"euclidean" (default), "cosine", "dot"/"ip" */
-  metric?: string
+	/** 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;
+	/**
+	 * Quantization mode (default: null = no quantization)
+	 * - true or "sq8": SQ8 4x compression, ~99% recall (RECOMMENDED)
+	 * - "rabitq": RaBitQ 8x compression, ~98% recall
+	 * - "binary": Binary 32x compression, ~95% recall
+	 * - 2, 4, 8: RaBitQ with specific bits (legacy)
+	 */
+	quantization?: boolean | string | number | null | undefined;
+	/**
+	 * Rescore candidates with exact distance (default: true when quantization enabled)
+	 * Set to false for maximum speed at the cost of ~20% recall
+	 */
+	rescore?: boolean;
+	/**
+	 * Oversampling factor for rescoring (default: 3.0)
+	 * Fetches k*oversample candidates then reranks to return top k
+	 */
+	oversample?: number;
+	/** Distance metric: "l2"/"euclidean" (default), "cosine", "dot"/"ip" */
+	metric?: string;
 }
 
 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 StatsResult {
-  dimensions: number
-  count: number
-  path: string
+	dimensions: number;
+	count: number;
+	path: string;
 }
 
 export interface TextSearchResult {
-  id: string
-  score: number
-  metadata: Record<string, unknown>
+	id: string;
+	score: number;
+	metadata: Record<string, unknown>;
 }
 
 export interface VectorItem {
-  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
+	id: string;
+	/** Vector data as number[] or Float32Array (Float32Array is more efficient) */
+	vector: number[] | Float32Array;
+	/** Optional metadata */
+	metadata?: Record<string, unknown> | undefined;
+	/** Optional document text (stored in metadata.document) */
+	document?: string;
 }
 
 export interface VectorItemWithText {
-  id: string
-  vector: Array<number>
-  text: string
-  metadata?: Record<string, unknown> | undefined
+	id: string;
+	/** Vector data as number[] or Float32Array (Float32Array is more efficient) */
+	vector: number[] | Float32Array;
+	text: string;
+	metadata?: Record<string, unknown> | undefined;
 }

package/index.js

@@ -101,7 +101,158 @@ if (!nativeBinding) {
 	throw new Error(`Failed to load native binding`);
 }
 
-const { VectorDatabase, open } = nativeBinding;
+// Convert array to Float32Array if needed
+function toFloat32Array(arr) {
+	if (arr instanceof Float32Array) {
+		return arr;
+	}
+	return new Float32Array(arr);
+}
+
+// Convert VectorItem to use Float32Array
+function convertVectorItem(item) {
+	return {
+		...item,
+		vector: toFloat32Array(item.vector),
+	};
+}
+
+// Wrap VectorDatabase to handle array conversion
+const NativeVectorDatabase = nativeBinding.VectorDatabase;
+
+class VectorDatabase {
+	constructor(nativeDb) {
+		this._native = nativeDb;
+	}
+
+	set(items) {
+		return this._native.set(items.map(convertVectorItem));
+	}
+
+	search(query, k, ef, filter, maxDistance) {
+		return this._native.search(query, k, ef, filter, maxDistance);
+	}
+
+	searchBatch(queries, k, ef) {
+		return this._native.searchBatch(queries, k, ef);
+	}
+
+	get(id) {
+		return this._native.get(id);
+	}
+
+	delete(ids) {
+		return this._native.delete(ids);
+	}
+
+	deleteWhere(filter) {
+		return this._native.deleteWhere(filter);
+	}
+
+	count(filter) {
+		return this._native.count(filter);
+	}
+
+	update(id, vector, metadata) {
+		return this._native.update(id, vector, metadata);
+	}
+
+	get length() {
+		return this._native.length;
+	}
+
+	get dimensions() {
+		return this._native.dimensions;
+	}
+
+	isEmpty() {
+		return this._native.isEmpty();
+	}
+
+	stats() {
+		return this._native.stats();
+	}
+
+	get efSearch() {
+		return this._native.efSearch;
+	}
+
+	set efSearch(value) {
+		this._native.efSearch = value;
+	}
+
+	collection(name) {
+		return new VectorDatabase(this._native.collection(name));
+	}
+
+	collections() {
+		return this._native.collections();
+	}
+
+	deleteCollection(name) {
+		return this._native.deleteCollection(name);
+	}
+
+	enableTextSearch() {
+		return this._native.enableTextSearch();
+	}
+
+	get hasTextSearch() {
+		return this._native.hasTextSearch;
+	}
+
+	setWithText(items) {
+		return this._native.setWithText(items.map(convertVectorItem));
+	}
+
+	textSearch(query, k) {
+		return this._native.textSearch(query, k);
+	}
+
+	hybridSearch(queryVector, queryText, k, filter, alpha, rrfK, subscores) {
+		return this._native.hybridSearch(
+			queryVector,
+			queryText,
+			k,
+			filter,
+			alpha,
+			rrfK,
+			subscores,
+		);
+	}
+
+	flush() {
+		return this._native.flush();
+	}
+
+	optimize() {
+		return this._native.optimize();
+	}
+
+	mergeFrom(other) {
+		return this._native.mergeFrom(other._native);
+	}
+
+	ids() {
+		return this._native.ids();
+	}
+
+	items() {
+		return this._native.items();
+	}
+
+	exists(id) {
+		return this._native.exists(id);
+	}
+
+	getMany(ids) {
+		return this._native.getMany(ids);
+	}
+}
+
+function open(path, options) {
+	return new VectorDatabase(nativeBinding.open(path, options));
+}
 
 module.exports.VectorDatabase = VectorDatabase;
 module.exports.open = open;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omendb/omendb",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "description": "Fast embedded vector database with HNSW + ACORN-1 filtered search",
   "main": "index.js",
   "types": "index.d.ts",
@@ -50,10 +50,10 @@
     "omendb.node"
   ],
   "optionalDependencies": {
-    "@omendb/omendb-darwin-x64": "0.0.19",
-    "@omendb/omendb-darwin-arm64": "0.0.19",
-    "@omendb/omendb-linux-x64-gnu": "0.0.19",
-    "@omendb/omendb-linux-arm64-gnu": "0.0.19",
-    "@omendb/omendb-win32-x64-msvc": "0.0.19"
+    "@omendb/omendb-darwin-x64": "0.0.20",
+    "@omendb/omendb-darwin-arm64": "0.0.20",
+    "@omendb/omendb-linux-x64-gnu": "0.0.20",
+    "@omendb/omendb-linux-arm64-gnu": "0.0.20",
+    "@omendb/omendb-win32-x64-msvc": "0.0.20"
   }
 }