react-native-nitro-sqlite-vec 9.8.1 → 10.0.0

package/README.md

@@ -10,10 +10,11 @@ Install both this package and `react-native-nitro-sqlite`, then enable the nativ
 npm install react-native-nitro-sqlite react-native-nitro-sqlite-vec
 ```
 
-- **iOS:**
+- **Apple platforms (iOS, macOS, visionOS):**
   ```bash
   NITRO_SQLITE_VEC=1 npx pod-install
   ```
+  For React Native macOS, run `NITRO_SQLITE_VEC=1 pod install` from `macos/`.
 - **Android:** add this to `android/gradle.properties` and rebuild:
   ```properties
   nitroSqliteVec=true

package/RNNitroSqliteVec.podspec

@@ -2,7 +2,7 @@ require "json"
 
 package = JSON.parse(File.read(File.join(__dir__, "package.json")))
 
-# iOS opt-in (NITRO_SQLITE_VEC=1); compile sqlite-vec and static-link into the core's sqlite3.
+# Apple-platform opt-in (NITRO_SQLITE_VEC=1); compile sqlite-vec and static-link into the core's sqlite3.
 nitro_sqlite_vec = ENV['NITRO_SQLITE_VEC'] == '1'
 
 # The core's bundled sqlite3.h (compiled with SQLITE_CORE to link it directly).
@@ -15,7 +15,11 @@ Pod::Spec.new do |s|
   s.homepage     = "https://github.com/margelo/react-native-nitro-sqlite"
   s.license      = "MIT"
   s.authors      = "Margelo"
-  s.platforms    = { :ios => min_ios_version_supported, :visionos => "1.0" }
+  s.platforms    = {
+    :ios => min_ios_version_supported,
+    :visionos => "1.0",
+    :osx => "10.13",
+  }
   s.source       = { :git => "https://github.com/margelo/react-native-nitro-sqlite.git", :tag => "#{s.version}" }
 
   if nitro_sqlite_vec

package/cpp/{registerVectorExtensions.cpp → NitroSQLiteVecRegisterVectorExtensions.cpp}

@@ -1,4 +1,4 @@
-#include "registerVectorExtensions.hpp"
+#include "NitroSQLiteVecRegisterVectorExtensions.hpp"
 
 #include <mutex>
 #include <sqlite3.h>

package/cpp/NitroSQLiteVecRegisterVectorExtensions.hpp

@@ -0,0 +1,10 @@
+#pragma once
+
+namespace margelo::rnnitrosqlitevec {
+
+/** Register the statically linked sqlite-vec initializer as a SQLite auto-extension.
+ * A process-wide once flag makes repeated calls safe before each database open.
+ */
+void registerVectorExtensions();
+
+} // namespace margelo::rnnitrosqlitevec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-sqlite-vec",
-  "version": "9.8.1",
+  "version": "10.0.0",
   "description": "Vector search (sqlite-vec) for react-native-nitro-sqlite. Native sqlite-vec is statically linked into the core's single sqlite3 — no second SQLite, no runtime extension loading.",
   "source": "./src/index",
   "react-native": "./src/index",
@@ -29,12 +29,14 @@
     "vector-search",
     "nitro-modules",
     "ios",
+    "macos",
     "android"
   ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/margelo/react-native-nitro-sqlite.git"
   },
+  "author": "Christoph Pader",
   "license": "MIT",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -44,7 +46,7 @@
     "react-native-nitro-sqlite": ">=9.0.0"
   },
   "devDependencies": {
-    "react-native-nitro-sqlite": "9.8.1",
+    "react-native-nitro-sqlite": "10.0.0",
     "typescript": "^5.8.3"
   },
   "jest": {

package/react-native.config.js

@@ -1,8 +1,9 @@
-// Android compiles these sources via the core's CMake, so autolink iOS only.
+// CocoaPods autolinks this package on Apple platforms; Android compiles it via the core's CMake.
 module.exports = {
   dependency: {
     platforms: {
       ios: {},
+      macos: {},
       android: null,
     },
   },

package/src/index.ts

@@ -1,30 +1,36 @@
 import type { NitroSQLiteConnection } from 'react-native-nitro-sqlite'
 
-/** Optional typed helpers over react-native-nitro-sqlite's execute() for sqlite-vec. */
-
+/** Vector storage types accepted by a `vec0` column. */
 export type VectorColumnType = 'float' | 'int8' | 'bit'
+
+/** Distance metrics accepted by a `vec0` column. */
 export type VectorDistanceMetric = 'L2' | 'cosine' | 'L1'
 
-/** A KNN result row: always `rowid` + `distance`, plus any selected columns. */
+/** One nearest-neighbor match returned by {@link knnSearch}. */
 export interface KnnMatch {
+  /** SQLite row ID of the matching vector. */
   rowid: number
+  /** Distance from the query vector, ordered from smallest to largest. */
   distance: number
+  /** Allows additional columns when using this row shape with custom queries. */
   [column: string]: unknown
 }
 
+/** Settings for a `vec0` virtual table created by {@link createVectorTable}. */
 export interface CreateVectorTableOptions {
-  /** Number of dimensions of the vector column. */
+  /** Number of dimensions passed to `vec0` for the vector column. */
   dimensions: number
   /** Vector storage type. Defaults to `'float'` (float32). */
   type?: VectorColumnType
-  /** Distance metric. Defaults to sqlite-vec's default (L2). */
+  /** Distance metric. Omit to use sqlite-vec's default (L2). */
   distanceMetric?: VectorDistanceMetric
-  /** Vector column name. Defaults to `'embedding'`. */
+  /** Trusted SQL column identifier. Defaults to `'embedding'`. */
   column?: string
 }
 
+/** Settings for {@link knnSearch}. */
 export interface KnnSearchOptions {
-  /** Vector column name. Defaults to `'embedding'`. */
+  /** Trusted SQL column identifier. Defaults to `'embedding'`. */
   column?: string
 }
 
@@ -33,12 +39,19 @@ function firstValue<T>(db: NitroSQLiteConnection, sql: string): T {
   return row?.value as T
 }
 
-/** Returns the linked sqlite-vec version string, e.g. `"v0.1.9"`. */
+/** Query the sqlite-vec version on an open connection.
+ * @param db Open NitroSQLite connection. The query runs synchronously.
+ * @returns The linked version string, for example `"v0.1.9"`.
+ * @throws If `vec_version()` is unavailable or the query fails.
+ */
 export function vecVersion(db: NitroSQLiteConnection): string {
   return firstValue<string>(db, 'SELECT vec_version() AS value')
 }
 
-/** True if sqlite-vec is linked into the active build (vector flag enabled). */
+/** Check whether the version query succeeds on this connection.
+ * @param db Open NitroSQLite connection. The check runs synchronously.
+ * @returns `false` if the version query throws for any reason, including a closed connection.
+ */
 export function isVecAvailable(db: NitroSQLiteConnection): boolean {
   try {
     vecVersion(db)
@@ -48,7 +61,13 @@ export function isVecAvailable(db: NitroSQLiteConnection): boolean {
   }
 }
 
-/** Creates a `vec0` virtual table for the given vector column. */
+/** Create a `vec0` virtual table if it does not already exist.
+ * Executes synchronously. An existing table is left as it is, even if its
+ * definition differs from `options`.
+ * @param db Open NitroSQLite connection with sqlite-vec enabled.
+ * @param table Trusted SQL table identifier, interpolated into the statement.
+ * @param options Vector dimensions, storage type, metric, and trusted column identifier.
+ */
 export function createVectorTable(
   db: NitroSQLiteConnection,
   table: string,
@@ -63,7 +82,15 @@ export function createVectorTable(
   )
 }
 
-/** Runs a KNN search; `query` is a JSON string `'[0.1,0.2]'` or a numeric array. */
+/** Search a `vec0` table for the nearest vectors.
+ * Executes synchronously and returns matches ordered by increasing distance.
+ * @param db Open NitroSQLite connection with sqlite-vec enabled.
+ * @param table Trusted SQL table identifier, interpolated into the statement.
+ * @param query JSON vector string passed through unchanged, or a numeric array serialized as JSON.
+ * @param k Maximum number of matches requested.
+ * @param options Optional trusted vector column identifier.
+ * @returns Matching row IDs and distances, or an empty array when no rows are returned.
+ */
 export function knnSearch(
   db: NitroSQLiteConnection,
   table: string,

package/cpp/registerVectorExtensions.hpp

@@ -1,8 +0,0 @@
-#pragma once
-
-namespace margelo::rnnitrosqlitevec {
-
-// Idempotent; safe to call on every database open.
-void registerVectorExtensions();
-
-} // namespace margelo::rnnitrosqlitevec