@taladb/react-native 0.11.3 → 0.11.4

package/src/NativeTalaDB.ts

@@ -4,6 +4,18 @@
  * This file is the Codegen source. It defines the native interface that
  * both the iOS JSI HostObject (TalaDB.mm) and the Android JNI bridge
  * (TalaDBModule.kt) must implement.
+ *
+ * # This is not the public API
+ *
+ * Only `initialize` and `close` are ever called through the TurboModule. Every
+ * other method below is a stub that exists so Codegen sees a complete surface;
+ * at runtime JS goes straight to the JSI HostObject at `global.__TalaDB__`.
+ *
+ * So do **not** add methods here to expose new functionality — each one
+ * generates an abstract member that `TalaDBModule.kt` and `TalaDB.mm` must
+ * override, and forgetting either breaks the native build for a stub nothing
+ * calls. The real surface is registered in `cpp/TalaDBHostObject.cpp` and typed
+ * by `JsiTalaDB` in `index.tsx`; extend those two together.
  */
 import type { TurboModule } from 'react-native';
 import { TurboModuleRegistry } from 'react-native';

package/src/index.tsx

@@ -1,6 +1,11 @@
 /** TalaDB React Native public API. CRUD is synchronous through the JSI host. */
 import {
   createWebhookDispatcher,
+  createVectorClient,
+  type VectorClient,
+  type HybridSearchOptions,
+  type TextSearchOptions,
+  type VectorMetric,
   type WebhookConfig,
   type WebhookDispatcher,
   type WebhookEvent,
@@ -8,6 +13,13 @@ import {
 } from 'taladb';
 import NativeTalaDB from './NativeTalaDB';
 
+export type {
+  HybridSearchOptions,
+  TextSearchOptions,
+  VectorMetric,
+  VectorClient, VectorQueryOptions, VectorRebuildOptions, VectorBuildProgress, VectorIndexStatus, VectorQueryResult, VectorRecall, VectorGraphOptions, VectorQuantization,
+} from 'taladb';
+
 export const TalaDBModule = {
   /** Open the native database. The config controls durability/encryption only. */
   initialize: (dbName: string, configJson?: string) =>
@@ -24,7 +36,75 @@ export type InsertDocument<T extends Document> = Omit<T, '_id'> & { _id?: string
 export type Filter = Record<string, unknown>;
 export type Update = Record<string, unknown>;
 
-export interface Collection<T extends Document = Document> {
+/** A query vector. `Float32Array` takes a zero-copy path across JSI. */
+export type QueryVector = Float32Array | number[];
+
+/** An ordered MongoDB-style aggregation pipeline. */
+export type AggregatePipeline = Record<string, unknown>[];
+
+/** A single result from `findNearest`. */
+export interface VectorSearchResult<T extends Document = Document> {
+  document: T;
+  /**
+   * Similarity score — higher means more similar. Range depends on the
+   * metric: cosine ∈ [-1,1], dot ∈ ℝ, euclidean ∈ (0,1].
+   */
+  score: number;
+}
+
+/** A single result from `searchText`. */
+export interface TextSearchResult<T extends Document = Document> {
+  document: T;
+  /**
+   * BM25 relevance — higher is more relevant. Unbounded above and only
+   * meaningful for ordering within one query's result set.
+   */
+  score: number;
+}
+
+/** A single result from `hybridSearch`. */
+export interface HybridSearchResult<T extends Document = Document> {
+  document: T;
+  /**
+   * Fused reciprocal-rank-fusion score. Small by construction and meaningful
+   * only as an ordering within one result set — never a similarity or a
+   * confidence.
+   */
+  score: number;
+  /** Zero-based rank in the text ranking, or `null` if text did not return it. */
+  textRank: number | null;
+  /** Zero-based rank in the vector ranking, or `null` if vector did not return it. */
+  vectorRank: number | null;
+}
+
+/**
+ * HNSW build parameters.
+ *
+ * The native binding validates these values and reports malformed options.
+ * `ef_construction` is retained for compatibility with the direct native API;
+ * the shared asynchronous vector API uses `efConstruction`.
+ */
+export interface HnswBuildOptions {
+  /** Bi-directional links per node (2–128). */
+  m: number;
+  /** Build-time quality (ef during construction). Must be ≥ `m`. Typically 200. */
+  ef_construction: number;
+  quantization?: import("taladb").VectorQuantization;
+}
+
+export interface VectorIndexOptions {
+  /** Similarity metric. Defaults to `"cosine"`. */
+  metric?: VectorMetric;
+  /**
+   * Supply this to build an HNSW (approximate) index instead of a flat one.
+   *
+   * Nodes and links persist in the database and update with document writes.
+   * Reopening requires no warm-up.
+   */
+  hnsw?: HnswBuildOptions;
+}
+
+export interface Collection<T extends Document = Document> extends VectorClient<T> {
   insert(doc: InsertDocument<T>): string;
   insertMany(docs: InsertDocument<T>[]): string[];
   find(filter?: Filter): T[];
@@ -38,6 +118,95 @@ export interface Collection<T extends Document = Document> {
   dropIndex(field: string): void;
   createFtsIndex(field: string): void;
   dropFtsIndex(field: string): void;
+
+  /**
+   * Find documents on a background thread. Prefer this over `find` for scans
+   * large enough to be felt as a dropped frame — every synchronous method here
+   * runs on the JS thread.
+   */
+  findAsync(filter?: Filter): Promise<T[]>;
+
+  /**
+   * Run a MongoDB-style aggregation pipeline: `$match`, `$group`, `$sort`,
+   * `$skip`, `$limit`, `$project`, with `$sum` / `$avg` / `$min` / `$max` /
+   * `$count` accumulators. `$match` uses an index where one exists.
+   *
+   * @example
+   * const [{ total }] = repairs.aggregate<{ total: number }>([
+   *   { $match: { thingId } },
+   *   { $group: { _id: null, total: { $sum: '$cost' } } },
+   * ]);
+   */
+  aggregate<R extends Document = Document>(pipeline: AggregatePipeline): R[];
+
+  /**
+   * Rank documents by BM25 keyword relevance. OR semantics — a document
+   * matching more of the query scores higher. Requires an FTS index on `field`.
+   *
+   * @example
+   * const hits = notes.searchText('body', 'chain replacement', 5);
+   */
+  searchText(
+    field: string,
+    query: string,
+    topK: number,
+    filter?: Filter | null,
+    options?: TextSearchOptions,
+  ): TextSearchResult<T>[];
+
+  /**
+   * Rank by keyword relevance (BM25) **and** vector similarity, then fuse the
+   * two rankings with reciprocal rank fusion.
+   *
+   * The retrievers fail differently — keyword search misses paraphrases,
+   * vector search misses exact identifiers and rare proper nouns — so fusing
+   * them recovers both. Requires an FTS index on `textField` and a vector
+   * index on `vectorField`. `filter` applies to both retrievers before ranking.
+   */
+  hybridSearch(
+    text: { textField: string; text: string },
+    vector: { vectorField: string; vector: QueryVector },
+    topK: number,
+    filter?: Filter | null,
+    options?: HybridSearchOptions,
+  ): HybridSearchResult<T>[];
+
+  /**
+   * Nearest neighbours by vector similarity.
+   *
+   * Passing a `filter` always takes the exact path: the graph cannot be
+   * traversed under an arbitrary predicate, so matching IDs are scored
+   * directly. That is usually what you want for a scoped search — it is exact,
+   * and it reads only the vectors that survive the filter.
+   */
+  findNearest(
+    field: string,
+    query: QueryVector,
+    topK: number,
+    filter?: Filter | null,
+  ): VectorSearchResult<T>[];
+
+  /** `findNearest` on a background thread. Prefer it for unfiltered searches. */
+  findNearestAsync(
+    field: string,
+    query: QueryVector,
+    topK: number,
+    filter?: Filter | null,
+  ): Promise<VectorSearchResult<T>[]>;
+
+  /**
+   * Create a vector index on a numeric-array field. `dimensions` is enforced
+   * on every insert and every query.
+   */
+  createVectorIndex(field: string, dimensions: number, options?: VectorIndexOptions): void;
+  dropVectorIndex(field: string): void;
+
+  /**
+   * Promote a flat/legacy index or compact a persistent graph. This synchronous
+   * call may be expensive; prefer rebuildVectorIndex for background batches,
+   * progress and AbortSignal cancellation on mobile.
+   */
+  upgradeVectorIndex(field: string): void;
 }
 
 export interface OpenDBOptions {
@@ -50,9 +219,48 @@ export interface DB {
   webhookStats(): WebhookStats;
   flushWebhook(timeoutMs?: number): Promise<boolean>;
   close(): Promise<void>;
+
+  /** Names of every collection that currently holds documents. */
+  listCollectionNames(): string[];
+
+  /**
+   * Force a durable sync of everything written so far.
+   *
+   * Only meaningful when the database was opened with
+   * `durability.flush_every_write: false`, which trades an fsync per write for
+   * throughput. The default is `true` — every acknowledged write is already
+   * durable — so most apps never need this. Batch importers should turn the
+   * flag off, import, then call `flush()`.
+   */
+  flush(): void;
+
+  /** Reclaim space from deleted documents. Expensive; run it off the hot path. */
+  compact(): void;
+
+  /**
+   * Warm every HNSW vector index in the database.
+   *
+   * Graphs persist across app launches. This is maintenance, not a startup
+   * requirement. Prefer per-field rebuildVectorIndex for progress/cancellation.
+   */
+  rebuildVectorIndexes(): void;
+
+  /** The application-defined schema version stored in the database file. */
+  userVersion(): number;
+  setUserVersion(version: number): void;
 }
 
+/**
+ * The JSI host object installed as `global.__TalaDB__`.
+ *
+ * This mirrors the methods registered in `cpp/TalaDBHostObject.cpp`, which is
+ * the real runtime surface. The TurboModule spec in `NativeTalaDB.ts` is
+ * deliberately narrower: every method there generates an abstract member that
+ * `TalaDBModule.kt` and `TalaDB.mm` must stub out, and those stubs are never
+ * called. Add new methods here, not there.
+ */
 interface JsiTalaDB {
+  callAsync(op: string, args: unknown[]): Promise<any>;
   insert(collection: string, doc: Object): string;
   insertMany(collection: string, docs: Object[]): string[];
   find(collection: string, filter: Object | null): Object[];
@@ -66,6 +274,54 @@ interface JsiTalaDB {
   dropIndex(collection: string, field: string): void;
   createFtsIndex(collection: string, field: string): void;
   dropFtsIndex(collection: string, field: string): void;
+  findAsync(collection: string, filter: Object | null): Promise<Object[]>;
+  aggregate(collection: string, pipeline: Object[]): Object[];
+  searchText(
+    collection: string,
+    field: string,
+    query: string,
+    topK: number,
+    filter: Object | null,
+    options?: Object,
+  ): Object[];
+  hybridSearch(
+    collection: string,
+    textField: string,
+    text: string,
+    vectorField: string,
+    vector: QueryVector,
+    topK: number,
+    filter: Object | null,
+    options?: Object,
+  ): Object[];
+  findNearest(
+    collection: string,
+    field: string,
+    query: QueryVector,
+    topK: number,
+    filter: Object | null,
+  ): Object[];
+  findNearestAsync(
+    collection: string,
+    field: string,
+    query: QueryVector,
+    topK: number,
+    filter: Object | null,
+  ): Promise<Object[]>;
+  createVectorIndex(
+    collection: string,
+    field: string,
+    dimensions: number,
+    opts?: Object,
+  ): void;
+  dropVectorIndex(collection: string, field: string): void;
+  upgradeVectorIndex(collection: string, field: string): void;
+  listCollectionNames(): string[];
+  rebuildVectorIndexes(): void;
+  flush(): void;
+  compact(): void;
+  userVersion(): number;
+  setUserVersion(version: number): void;
 }
 
 function native(): JsiTalaDB {
@@ -117,6 +373,7 @@ function collection<T extends Document>(
   webhook: WebhookDispatcher | null,
 ): Collection<T> {
   return {
+    ...createVectorClient<T>(request => native().callAsync('vectorCommand', [colName, request])),
     insert(doc) {
       const id = native().insert(colName, doc as Object);
       const committedAt = Date.now();
@@ -174,6 +431,51 @@ function collection<T extends Document>(
     dropIndex: (field) => native().dropIndex(colName, field),
     createFtsIndex: (field) => native().createFtsIndex(colName, field),
     dropFtsIndex: (field) => native().dropFtsIndex(colName, field),
+
+    findAsync: async (filter) =>
+      (await native().findAsync(colName, filter ?? null)) as T[],
+
+    aggregate: <R extends Document = Document>(pipeline: AggregatePipeline) =>
+      native().aggregate(colName, pipeline as Object[]) as R[],
+
+    searchText: (field, query, topK, filter, options) =>
+      native().searchText(
+        colName,
+        field,
+        query,
+        topK,
+        filter ?? null,
+        options as Object | undefined,
+      ) as TextSearchResult<T>[],
+
+    hybridSearch: (text, vector, topK, filter, options) =>
+      native().hybridSearch(
+        colName,
+        text.textField,
+        text.text,
+        vector.vectorField,
+        vector.vector,
+        topK,
+        filter ?? null,
+        options as Object | undefined,
+      ) as HybridSearchResult<T>[],
+
+    findNearest: (field, query, topK, filter) =>
+      native().findNearest(colName, field, query, topK, filter ?? null) as VectorSearchResult<T>[],
+
+    findNearestAsync: async (field, query, topK, filter) =>
+      (await native().findNearestAsync(
+        colName,
+        field,
+        query,
+        topK,
+        filter ?? null,
+      )) as VectorSearchResult<T>[],
+
+    createVectorIndex: (field, dimensions, options) =>
+      native().createVectorIndex(colName, field, dimensions, options as Object | undefined),
+    dropVectorIndex: (field) => native().dropVectorIndex(colName, field),
+    upgradeVectorIndex: (field) => native().upgradeVectorIndex(colName, field),
   };
 }
 
@@ -184,6 +486,12 @@ export function openDB(_dbName: string, options?: OpenDBOptions): DB {
     collection: <T extends Document>(name: string) => collection<T>(name, webhook),
     webhookStats: () => webhook?.stats() ?? { ...EMPTY_STATS },
     flushWebhook: (timeoutMs) => webhook?.flush(timeoutMs) ?? Promise.resolve(true),
+    listCollectionNames: () => native().listCollectionNames(),
+    flush: () => native().flush(),
+    compact: () => native().compact(),
+    rebuildVectorIndexes: () => native().rebuildVectorIndexes(),
+    userVersion: () => native().userVersion(),
+    setUserVersion: (version) => native().setUserVersion(version),
     close: async () => {
       await webhook?.flush();
       await NativeTalaDB.close();