@ruvector/node 0.1.15

package/index.d.ts

@@ -0,0 +1,345 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/** Distance metric for similarity calculation */
+export const enum JsDistanceMetric {
+  /** Euclidean (L2) distance */
+  Euclidean = 'Euclidean',
+  /** Cosine similarity (converted to distance) */
+  Cosine = 'Cosine',
+  /** Dot product (converted to distance for maximization) */
+  DotProduct = 'DotProduct',
+  /** Manhattan (L1) distance */
+  Manhattan = 'Manhattan'
+}
+/** Quantization configuration */
+export interface JsQuantizationConfig {
+  /** Quantization type: "none", "scalar", "product", "binary" */
+  type: string
+  /** Number of subspaces (for product quantization) */
+  subspaces?: number
+  /** Codebook size (for product quantization) */
+  k?: number
+}
+/** HNSW index configuration */
+export interface JsHnswConfig {
+  /** Number of connections per layer (M) */
+  m?: number
+  /** Size of dynamic candidate list during construction */
+  efConstruction?: number
+  /** Size of dynamic candidate list during search */
+  efSearch?: number
+  /** Maximum number of elements */
+  maxElements?: number
+}
+/** Database configuration options */
+export interface JsDbOptions {
+  /** Vector dimensions */
+  dimensions: number
+  /** Distance metric */
+  distanceMetric?: JsDistanceMetric
+  /** Storage path */
+  storagePath?: string
+  /** HNSW configuration */
+  hnswConfig?: JsHnswConfig
+  /** Quantization configuration */
+  quantization?: JsQuantizationConfig
+}
+/** Vector entry */
+export interface JsVectorEntry {
+  /** Optional ID (auto-generated if not provided) */
+  id?: string
+  /** Vector data as Float32Array or array of numbers */
+  vector: Float32Array
+}
+/** Search query parameters */
+export interface JsSearchQuery {
+  /** Query vector as Float32Array or array of numbers */
+  vector: Float32Array
+  /** Number of results to return (top-k) */
+  k: number
+  /** Optional ef_search parameter for HNSW */
+  efSearch?: number
+}
+/** Search result with similarity score */
+export interface JsSearchResult {
+  /** Vector ID */
+  id: string
+  /** Distance/similarity score (lower is better for distance metrics) */
+  score: number
+}
+/** Get the version of the Ruvector library */
+export declare function version(): string
+/** Test function to verify the bindings are working */
+export declare function hello(): string
+/** Filter for metadata-based search */
+export interface JsFilter {
+  /** Field name to filter on */
+  field: string
+  /** Operator: "eq", "ne", "gt", "gte", "lt", "lte", "in", "match" */
+  operator: string
+  /** Value to compare against (JSON string) */
+  value: string
+}
+/** Collection configuration */
+export interface JsCollectionConfig {
+  /** Vector dimensions */
+  dimensions: number
+  /** Distance metric */
+  distanceMetric?: JsDistanceMetric
+  /** HNSW configuration */
+  hnswConfig?: JsHnswConfig
+  /** Quantization configuration */
+  quantization?: JsQuantizationConfig
+}
+/** Collection statistics */
+export interface JsCollectionStats {
+  /** Number of vectors in the collection */
+  vectorsCount: number
+  /** Disk space used in bytes */
+  diskSizeBytes: number
+  /** RAM space used in bytes */
+  ramSizeBytes: number
+}
+/** Collection alias */
+export interface JsAlias {
+  /** Alias name */
+  alias: string
+  /** Collection name */
+  collection: string
+}
+/** Health response */
+export interface JsHealthResponse {
+  /** Status: "healthy", "degraded", or "unhealthy" */
+  status: string
+  /** Version string */
+  version: string
+  /** Uptime in seconds */
+  uptimeSeconds: number
+}
+/**
+ * Get Prometheus metrics
+ *
+ * # Example
+ * ```javascript
+ * const metrics = getMetrics();
+ * console.log(metrics);
+ * ```
+ */
+export declare function getMetrics(): string
+/**
+ * Get health status
+ *
+ * # Example
+ * ```javascript
+ * const health = getHealth();
+ * console.log(`Status: ${health.status}`);
+ * console.log(`Uptime: ${health.uptimeSeconds}s`);
+ * ```
+ */
+export declare function getHealth(): JsHealthResponse
+export type VectorDB = VectorDb
+/** High-performance vector database with HNSW indexing */
+export declare class VectorDb {
+  /**
+   * Create a new vector database with the given options
+   *
+   * # Example
+   * ```javascript
+   * const db = new VectorDB({
+   *   dimensions: 384,
+   *   distanceMetric: 'Cosine',
+   *   storagePath: './vectors.db',
+   *   hnswConfig: {
+   *     m: 32,
+   *     efConstruction: 200,
+   *     efSearch: 100
+   *   }
+   * });
+   * ```
+   */
+  constructor(options: JsDbOptions)
+  /**
+   * Create a vector database with default options
+   *
+   * # Example
+   * ```javascript
+   * const db = VectorDB.withDimensions(384);
+   * ```
+   */
+  static withDimensions(dimensions: number): VectorDb
+  /**
+   * Insert a vector entry into the database
+   *
+   * Returns the ID of the inserted vector (auto-generated if not provided)
+   *
+   * # Example
+   * ```javascript
+   * const id = await db.insert({
+   *   vector: new Float32Array([1.0, 2.0, 3.0]),
+   *   metadata: { text: 'example' }
+   * });
+   * ```
+   */
+  insert(entry: JsVectorEntry): Promise<string>
+  /**
+   * Insert multiple vectors in a batch
+   *
+   * Returns an array of IDs for the inserted vectors
+   *
+   * # Example
+   * ```javascript
+   * const ids = await db.insertBatch([
+   *   { vector: new Float32Array([1, 2, 3]) },
+   *   { vector: new Float32Array([4, 5, 6]) }
+   * ]);
+   * ```
+   */
+  insertBatch(entries: Array<JsVectorEntry>): Promise<Array<string>>
+  /**
+   * Search for similar vectors
+   *
+   * Returns an array of search results sorted by similarity
+   *
+   * # Example
+   * ```javascript
+   * const results = await db.search({
+   *   vector: new Float32Array([1, 2, 3]),
+   *   k: 10,
+   *   filter: { category: 'example' }
+   * });
+   * ```
+   */
+  search(query: JsSearchQuery): Promise<Array<JsSearchResult>>
+  /**
+   * Delete a vector by ID
+   *
+   * Returns true if the vector was deleted, false if not found
+   *
+   * # Example
+   * ```javascript
+   * const deleted = await db.delete('vector-id');
+   * ```
+   */
+  delete(id: string): Promise<boolean>
+  /**
+   * Get a vector by ID
+   *
+   * Returns the vector entry if found, null otherwise
+   *
+   * # Example
+   * ```javascript
+   * const entry = await db.get('vector-id');
+   * if (entry) {
+   *   console.log('Found:', entry.metadata);
+   * }
+   * ```
+   */
+  get(id: string): Promise<JsVectorEntry | null>
+  /**
+   * Get the number of vectors in the database
+   *
+   * # Example
+   * ```javascript
+   * const count = await db.len();
+   * console.log(`Database contains ${count} vectors`);
+   * ```
+   */
+  len(): Promise<number>
+  /**
+   * Check if the database is empty
+   *
+   * # Example
+   * ```javascript
+   * if (await db.isEmpty()) {
+   *   console.log('Database is empty');
+   * }
+   * ```
+   */
+  isEmpty(): Promise<boolean>
+}
+/** Collection manager for multi-collection support */
+export declare class CollectionManager {
+  /**
+   * Create a new collection manager
+   *
+   * # Example
+   * ```javascript
+   * const manager = new CollectionManager('./collections');
+   * ```
+   */
+  constructor(basePath?: string | undefined | null)
+  /**
+   * Create a new collection
+   *
+   * # Example
+   * ```javascript
+   * await manager.createCollection('my_vectors', {
+   *   dimensions: 384,
+   *   distanceMetric: 'Cosine'
+   * });
+   * ```
+   */
+  createCollection(name: string, config: JsCollectionConfig): Promise<void>
+  /**
+   * List all collections
+   *
+   * # Example
+   * ```javascript
+   * const collections = await manager.listCollections();
+   * console.log('Collections:', collections);
+   * ```
+   */
+  listCollections(): Promise<Array<string>>
+  /**
+   * Delete a collection
+   *
+   * # Example
+   * ```javascript
+   * await manager.deleteCollection('my_vectors');
+   * ```
+   */
+  deleteCollection(name: string): Promise<void>
+  /**
+   * Get collection statistics
+   *
+   * # Example
+   * ```javascript
+   * const stats = await manager.getStats('my_vectors');
+   * console.log(`Vectors: ${stats.vectorsCount}`);
+   * ```
+   */
+  getStats(name: string): Promise<JsCollectionStats>
+  /**
+   * Create an alias for a collection
+   *
+   * # Example
+   * ```javascript
+   * await manager.createAlias('latest', 'my_vectors_v2');
+   * ```
+   */
+  createAlias(alias: string, collection: string): Promise<void>
+  /**
+   * Delete an alias
+   *
+   * # Example
+   * ```javascript
+   * await manager.deleteAlias('latest');
+   * ```
+   */
+  deleteAlias(alias: string): Promise<void>
+  /**
+   * List all aliases
+   *
+   * # Example
+   * ```javascript
+   * const aliases = await manager.listAliases();
+   * for (const alias of aliases) {
+   *   console.log(`${alias.alias} -> ${alias.collection}`);
+   * }
+   * ```
+   */
+  listAliases(): Promise<Array<JsAlias>>
+}

package/index.js

@@ -0,0 +1,321 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'ruvector.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./ruvector.android-arm64.node')
+          } else {
+            nativeBinding = require('@ruvector/node-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'ruvector.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./ruvector.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@ruvector/node-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'ruvector.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./ruvector.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@ruvector/node-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'ruvector.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./ruvector.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@ruvector/node-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'ruvector.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./ruvector.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@ruvector/node-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'ruvector.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./ruvector.darwin-universal.node')
+      } else {
+        nativeBinding = require('@ruvector/node-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'ruvector.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./ruvector.darwin-x64.node')
+          } else {
+            nativeBinding = require('@ruvector/node-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'ruvector.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./ruvector.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@ruvector/node-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'ruvector.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./ruvector.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@ruvector/node-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'ruvector.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./ruvector.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@ruvector/node-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'ruvector.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./ruvector.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@ruvector/node-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'ruvector.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./ruvector.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@ruvector/node-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'ruvector.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./ruvector.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@ruvector/node-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'ruvector.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./ruvector.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@ruvector/node-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'ruvector.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./ruvector.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@ruvector/node-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'ruvector.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./ruvector.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@ruvector/node-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'ruvector.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./ruvector.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@ruvector/node-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'ruvector.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./ruvector.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@ruvector/node-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { JsDistanceMetric, VectorDb, version, hello, CollectionManager, getMetrics, getHealth } = nativeBinding
+
+module.exports.JsDistanceMetric = JsDistanceMetric
+module.exports.VectorDb = VectorDb
+module.exports.version = version
+module.exports.hello = hello
+module.exports.CollectionManager = CollectionManager
+module.exports.getMetrics = getMetrics
+module.exports.getHealth = getHealth