taladb 0.9.4 → 0.10.0

package/dist/index.d.ts

@@ -36,6 +36,67 @@ interface VectorSearchResult<T extends Document = Document> {
      */
     score: number;
 }
+interface TextSearchResult<T extends Document = Document> {
+    /** The matched document. */
+    document: T;
+    /**
+     * BM25 relevance score — higher means more relevant. Unbounded above, and
+     * only meaningful for ordering within a single query's result set.
+     */
+    score: number;
+}
+/** Tuning for `searchText`'s BM25 ranking. */
+interface TextSearchOptions {
+    /**
+     * Term-frequency saturation (BM25 `k1`, default `1.2`). Higher values let a
+     * repeated term keep adding relevance for longer.
+     */
+    k1?: number;
+    /**
+     * Length normalisation (BM25 `b`, default `0.75`). `0` ignores document
+     * length; `1` normalises fully by length relative to the corpus average.
+     */
+    b?: number;
+}
+interface HybridSearchResult<T extends Document = Document> {
+    /** The matched 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 position in the text ranking, or `null` if the text retriever
+     * did not return this document.
+     */
+    textRank: number | null;
+    /**
+     * Zero-based position in the vector ranking, or `null` if the vector
+     * retriever did not return this document.
+     */
+    vectorRank: number | null;
+}
+/** Tuning for `hybridSearch`'s fusion and per-retriever scoring. */
+interface HybridSearchOptions extends TextSearchOptions {
+    /**
+     * Reciprocal rank fusion smoothing constant (default `60`). Larger values
+     * flatten the advantage of the very top ranks.
+     */
+    rrfK?: number;
+    /** Relative weight of the text ranking (default `1`). Set `0` to disable it. */
+    textWeight?: number;
+    /** Relative weight of the vector ranking (default `1`). Set `0` to disable it. */
+    vectorWeight?: number;
+    /**
+     * How many candidates to pull from each retriever before fusing
+     * (default `max(topK * 4, 20)`). Raise it for better recall at more cost;
+     * fusing only `topK` from each side drops documents that rank just outside
+     * one retriever but high in the other.
+     */
+    candidates?: number;
+}
 type Value = null | boolean | number | string | Uint8Array | Value[] | {
     [key: string]: Value;
 };
@@ -221,12 +282,42 @@ interface CollectionOptions<T extends Document = Document> {
      * });
      */
     migrateDocument?: (doc: T, fromVersion: number) => T;
+    /**
+     * Lazy, read-time **downcast** — the mirror of {@link migrateDocument}, for a
+     * document written by a *newer* peer. When set, every document returned by
+     * `find` / `findOne` whose `_v` is **above** `syncSchema.version` is passed
+     * through `downgradeDocument(doc, fromVersion)` and projected into the shape
+     * this build understands, so application code on an old client sees a shape
+     * it can actually read instead of an unexpected future one.
+     *
+     * Requires `syncSchema.version`. Must be pure and deterministic.
+     *
+     * **The projection is view-only and is never persisted**, regardless of
+     * {@link persistMigrations}. The stored document keeps its original `_v` and
+     * its newer fields intact, because this replica must continue to replicate
+     * that document faithfully to other peers — an old client is a *reader* of a
+     * newer shape, never its editor. For the same reason the returned document
+     * keeps its original (higher) `_v`: it is a projection of a v-N document, not
+     * a v-M one, and writing it back wholesale would tell the fleet otherwise.
+     *
+     * @example
+     * // This build understands v1. A v2 peer split `name` into first/last.
+     * const users = db.collection<User>('users', {
+     *   syncSchema: { version: 1 },
+     *   downgradeDocument: (doc) => ({ ...doc, name: `${doc.first} ${doc.last}` }),
+     * });
+     */
+    downgradeDocument?: (doc: Readonly<T>, fromVersion: number) => T;
     /**
      * When `true`, a document upgraded by {@link migrateDocument} on read is
-     * **written back** to storage (a best-effort `updateOne` computing the
-     * `$set`/`$unset` diff) so the migration becomes permanent — after which
-     * filters and indexes on the new shape match it. Default `false` (the
-     * migrated shape is returned but not persisted).
+     * **written back** to storage (a best-effort `updateOne` computing a `$set`
+     * diff) so the migration becomes permanent — after which filters and indexes
+     * on the new shape match it. Default `false` (the migrated shape is returned
+     * but not persisted).
+     *
+     * The write-back is **additive-only** except for fields explicitly listed in
+     * {@link retiredFields}. A field present in storage but absent from the
+     * migrated document is otherwise left alone rather than `$unset`.
      *
      * Trade-offs: reads that encounter un-migrated documents now issue writes
      * (which fire live-query and sync-hook notifications like any other write);
@@ -234,6 +325,35 @@ interface CollectionOptions<T extends Document = Document> {
      * one-shot eager rewrite instead, prefer `openDB({ migrations })`.
      */
     persistMigrations?: boolean;
+    /**
+     * Fields an upcast is explicitly allowed to remove during persist-on-read.
+     * Prefer this precise list to {@link allowFieldRemoval}: omissions of any
+     * other field remain additive and are preserved.
+     */
+    retiredFields?: (keyof T & string)[];
+    /**
+     * How to read a field that {@link migrateDocument} left out of its output:
+     * as an intentional removal (`true`), or as a field the migration simply
+     * never heard of (`false`, the default).
+     *
+     * Default `false` — omitted fields are **preserved**: kept on the document
+     * returned to your code, and left in storage by the {@link persistMigrations}
+     * write-back rather than `$unset`.
+     *
+     * This default exists because on a synced collection the two cases are
+     * indistinguishable from the migration's output, and guessing "removal" is
+     * the destructive guess. A migration written today cannot mention a field a
+     * *newer* peer will add tomorrow, so an innocent `(doc) => ({ id, name })`
+     * becomes a deletion of a field its author never heard of — and under
+     * whole-document LWW that deletion replicates to the whole fleet. An old
+     * replica has to stay a faithful carrier of shapes it does not understand.
+     *
+     * Set `true` only on a collection that never syncs, or during a deliberate
+     * add → backfill → dual-read → **retire** rollout, where you already know the
+     * whole fleet has stopped writing the field.
+     */
+    /** @deprecated Prefer {@link retiredFields}; this treats every omission as removal. */
+    allowFieldRemoval?: boolean;
 }
 /** A single MongoDB-style aggregation stage. */
 type AggregateStage<T extends Document = Document> = {
@@ -351,6 +471,44 @@ interface Collection<T extends Document = Document> {
     createFtsIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
     /** Drop a full-text search index. */
     dropFtsIndex(field: keyof Omit<T, '_id'> & string): Promise<void>;
+    /**
+     * Rank documents against a free-text `query` using BM25, most relevant first.
+     *
+     * Unlike the `$contains` filter, which requires **every** token to be
+     * present, this uses OR semantics — a document that matches more of the
+     * query simply scores higher. Requires an FTS index on `field`.
+     *
+     * @example
+     * const hits = await articles.searchText('body', 'reset my password', 5);
+     * // hits: Array<{ document: Article, score: number }>
+     */
+    searchText(field: keyof Omit<T, '_id'> & string, query: string, topK: number, filter?: Filter<T>, options?: TextSearchOptions): Promise<TextSearchResult<T>[]>;
+    /**
+     * Hybrid retrieval: rank by keyword relevance (BM25) **and** vector
+     * similarity, then fuse the two rankings with reciprocal rank fusion.
+     *
+     * The two retrievers fail differently — keyword search misses paraphrases,
+     * vector search misses exact identifiers and rare proper nouns — so fusing
+     * them recovers both. A document both retrievers rank well outranks one that
+     * only a single retriever found. Requires an FTS index on `textField` and a
+     * vector index on `vectorField`.
+     *
+     * The optional `filter` is applied to both retrievers before ranking.
+     *
+     * @example
+     * const hits = await articles.hybridSearch(
+     *   { textField: 'body', text: 'reset my password' },
+     *   { vectorField: 'embedding', vector: queryVec },
+     *   5,
+     * );
+     */
+    hybridSearch(text: {
+        textField: keyof Omit<T, '_id'> & string;
+        text: string;
+    }, vector: {
+        vectorField: keyof Omit<T, '_id'> & string;
+        vector: number[];
+    }, topK: number, filter?: Filter<T>, options?: HybridSearchOptions): Promise<HybridSearchResult<T>[]>;
     /**
      * Return the indexes that currently exist on this collection.
      *
@@ -1321,4 +1479,4 @@ interface OpenDBOptions {
  */
 declare function openDB(dbName?: string, options?: OpenDBOptions): Promise<TalaDB>;
 
-export { type AggregatePipeline, type AggregateStage, type BootstrapPage, type BootstrapRequest, type BridgeQuery, type BridgeResult, COVERAGE_COLLECTION, type Collection, type CollectionIndexInfo, type CollectionOptions, type CoordinatorOptions, type CoverageKey, type CoverageState, CoverageStore, type CursorSyncAdapter, type DeltaPage, type Document, type DurabilityConfig, type Filter, HttpSyncAdapter, type Migration, type OpenDBOptions, type PullResult, REPLICA_REVISION_FIELD, REPLICA_SCOPE_FIELD, type RemoteKey, ReplicationCoordinator, type ReplicationSource, type RestSourceOptions, type Schema, type SerializedChangeset, type SyncAdapter, type SyncConfig, type SyncDirection, type SyncOptions, type SyncResult, type TalaDB, type TalaDbConfig, TalaDbValidationError, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, type WriteOrigin, applySchema, coverageKey, createRestSource, deriveDocId, isAuthoritative, openDB, progress, rowsApplied, runMigrations };
+export { type AggregatePipeline, type AggregateStage, type BootstrapPage, type BootstrapRequest, type BridgeQuery, type BridgeResult, COVERAGE_COLLECTION, type Collection, type CollectionIndexInfo, type CollectionOptions, type CoordinatorOptions, type CoverageKey, type CoverageState, CoverageStore, type CursorSyncAdapter, type DeltaPage, type Document, type DurabilityConfig, type Filter, HttpSyncAdapter, type HybridSearchOptions, type HybridSearchResult, type Migration, type OpenDBOptions, type PullResult, REPLICA_REVISION_FIELD, REPLICA_SCOPE_FIELD, type RemoteKey, ReplicationCoordinator, type ReplicationSource, type RestSourceOptions, type Schema, type SerializedChangeset, type SyncAdapter, type SyncConfig, type SyncDirection, type SyncOptions, type SyncResult, type TalaDB, type TalaDbConfig, TalaDbValidationError, type TextSearchOptions, type TextSearchResult, type Update, type Value, type VectorIndexOptions, type VectorMetric, type VectorSearchResult, type WriteOrigin, applySchema, coverageKey, createRestSource, deriveDocId, isAuthoritative, openDB, progress, rowsApplied, runMigrations };

package/dist/index.js

@@ -768,18 +768,52 @@ function deepEqual(a, b) {
   );
 }
 function applySchema(col, options) {
-  const { schema, validateOnRead = false, migrateDocument, syncSchema, persistMigrations = false } = options;
+  const {
+    schema,
+    validateOnRead = false,
+    migrateDocument,
+    downgradeDocument,
+    syncSchema,
+    persistMigrations = false,
+    allowFieldRemoval = false,
+    retiredFields = []
+  } = options;
   const targetVersion = syncSchema?.version ?? 0;
   if (migrateDocument && targetVersion < 1) {
     throw new Error("CollectionOptions.migrateDocument requires syncSchema.version (the migration target)");
   }
+  if (downgradeDocument && targetVersion < 1) {
+    throw new Error("CollectionOptions.downgradeDocument requires syncSchema.version (the shape this build reads)");
+  }
   if (syncSchema && targetVersion < 1 && (syncSchema.renames || syncSchema.defaults)) {
     throw new Error(
       "CollectionOptions.syncSchema.renames/defaults require syncSchema.version >= 1 \u2014 without a version the import migration step never runs and documents missing the renamed/defaulted fields are quarantined instead of upgraded"
     );
   }
   const stampVersion = targetVersion > 0;
-  if (!schema && !migrateDocument && !stampVersion) return col;
+  if (!schema && !migrateDocument && !downgradeDocument && !stampVersion) return col;
+  const retired = new Set(retiredFields);
+  const engineOwned = /* @__PURE__ */ new Set([
+    "_id",
+    "_v",
+    "_changed_at",
+    "_remote",
+    "_remote_rev",
+    "_replica_scope"
+  ]);
+  const downcastViews = /* @__PURE__ */ new WeakSet();
+  function preserveFields(original, next, preserveUnknown, preserveVersion = true) {
+    let out = null;
+    for (const k of Object.keys(original)) {
+      const ownedField = engineOwned.has(k) && (k !== "_v" || preserveVersion);
+      const mustRestore = ownedField || preserveUnknown && !retired.has(k) && !(k in next);
+      if (!mustRestore) continue;
+      if (!ownedField && k in next) continue;
+      out ?? (out = { ...next });
+      out[k] = original[k];
+    }
+    return out ?? next;
+  }
   function parseWrite(doc, label) {
     try {
       return schema.parse(doc);
@@ -787,6 +821,43 @@ function applySchema(col, options) {
       throw new TalaDbValidationError(err, label);
     }
   }
+  function assertWritableDocument(doc, label) {
+    if (doc && typeof doc === "object" && downcastViews.has(doc)) {
+      throw new Error(`${label}: a downgradeDocument result is a read-only compatibility view`);
+    }
+    const version = doc?._v;
+    if (targetVersion > 0 && typeof version === "number" && version > targetVersion) {
+      throw new Error(
+        `${label}: this client supports schema v${targetVersion}, but the document is v${version}`
+      );
+    }
+  }
+  function writableFilter(filter) {
+    if (targetVersion < 1) return filter;
+    return {
+      $and: [
+        filter,
+        {
+          $or: [
+            { _v: { $exists: false } },
+            { _v: { $lte: targetVersion } }
+          ]
+        }
+      ]
+    };
+  }
+  function assertSafeUpdate(update) {
+    const record = update;
+    for (const op of ["$set", "$unset", "$inc", "$push", "$pull"]) {
+      const fields = record[op];
+      if (!fields) continue;
+      for (const field of Object.keys(fields)) {
+        if (engineOwned.has(field)) {
+          throw new Error(`update cannot modify engine-owned field '${field}'`);
+        }
+      }
+    }
+  }
   function stamp(doc) {
     if (!stampVersion || doc._v !== void 0) return doc;
     return { ...doc, _v: targetVersion };
@@ -802,50 +873,86 @@ function applySchema(col, options) {
       if (k === "_id") continue;
       if (!deepEqual(migrated[k], original[k])) $set[k] = migrated[k];
     }
-    for (const k of Object.keys(original)) {
-      if (k !== "_id" && !(k in migrated)) $unset[k] = true;
+    if (allowFieldRemoval || retired.size > 0) {
+      for (const k of Object.keys(original)) {
+        if (k !== "_id" && !(k in migrated) && (allowFieldRemoval || retired.has(k))) $unset[k] = true;
+      }
     }
     const update = {};
     if (Object.keys($set).length) update.$set = $set;
     if (Object.keys($unset).length) update.$unset = $unset;
     return Object.keys(update).length ? update : null;
   }
-  function migrateRead(doc) {
-    if (!migrateDocument) return doc;
+  function normalizeRead(doc) {
     const fromVersion = typeof doc._v === "number" ? doc._v : 0;
-    if (fromVersion >= targetVersion) return doc;
-    return { ...migrateDocument(doc, fromVersion), _v: targetVersion };
+    if (migrateDocument && fromVersion < targetVersion) {
+      const up = { ...migrateDocument(doc, fromVersion), _v: targetVersion };
+      return {
+        // The migration owns the version transition, while every other
+        // engine-owned field continues to come from the stored document.
+        value: allowFieldRemoval ? preserveFields(doc, up, false, false) : preserveFields(doc, up, true, false),
+        persistable: true
+      };
+    }
+    if (downgradeDocument && fromVersion > targetVersion) {
+      const projected = {
+        ...downgradeDocument(doc, fromVersion),
+        ...doc._id !== void 0 ? { _id: doc._id } : {},
+        _v: fromVersion
+      };
+      downcastViews.add(projected);
+      return { value: projected, persistable: false };
+    }
+    return { value: doc, persistable: true };
   }
   function validateRead(doc) {
     if (!validateOnRead || !schema) return doc;
     try {
-      return schema.parse(doc);
+      const parsed = schema.parse(doc);
+      const fromVersion = typeof doc._v === "number" ? doc._v : 0;
+      return preserveFields(doc, parsed, targetVersion > 0 && fromVersion > targetVersion);
     } catch (err) {
       throw new TalaDbValidationError(err, "read");
     }
   }
-  async function persistAll(originals, migrated) {
+  async function persistAll(originals, normalized) {
     if (!persistMigrations) return;
     for (let i = 0; i < originals.length; i++) {
       const original = originals[i];
-      if (migrated[i] === original || typeof original._id !== "string") continue;
-      const update = diffUpdate(original, migrated[i]);
+      if (!normalized[i].persistable) continue;
+      const migrated = normalized[i].value;
+      if (migrated === original || typeof original._id !== "string") continue;
+      const update = diffUpdate(original, migrated);
       if (!update) continue;
       try {
-        await col.updateOne({ _id: original._id }, update);
+        const guards = [{ _id: original._id }];
+        if (original._v === void 0) guards.push({ _v: { $exists: false } });
+        else guards.push({ _v: original._v });
+        if (original._changed_at !== void 0) {
+          guards.push({ _changed_at: original._changed_at });
+        }
+        await col.updateOne({ $and: guards }, update);
       } catch {
       }
     }
   }
-  const wrapReads = Boolean(migrateDocument) || validateOnRead && Boolean(schema);
+  const wrapReads = Boolean(migrateDocument) || Boolean(downgradeDocument) || validateOnRead && Boolean(schema);
   const wrapWrites = Boolean(schema) || stampVersion;
+  function pipelinePreservesDocuments(pipeline) {
+    return pipeline.every((stage) => !("$group" in stage) && !("$project" in stage));
+  }
+  function normalizeViewRows(docs) {
+    return docs.map((doc) => validateRead(normalizeRead(doc).value));
+  }
   return {
     ...col,
     insert: wrapWrites ? async (doc) => {
+      assertWritableDocument(doc, "insert");
       if (schema) parseWrite(doc, "insert");
       return col.insert(stamp(doc));
     } : col.insert.bind(col),
     insertMany: wrapWrites ? async (docs) => {
+      docs.forEach((doc, i) => assertWritableDocument(doc, `insertMany[${i}]`));
       if (schema) docs.forEach((doc, i) => parseWrite(doc, `insertMany[${i}]`));
       return col.insertMany(docs.map(stamp));
     } : col.insertMany.bind(col),
@@ -854,6 +961,14 @@ function applySchema(col, options) {
     // runtime schema check have to be the same seam, or a malformed server
     // response walks straight into a typed collection.
     replaceManyWithIds: wrapWrites ? async (docs, origin) => {
+      if (origin !== "remote") {
+        docs.forEach((doc, i) => assertWritableDocument(doc, `replaceManyWithIds[${i}]`));
+        if (targetVersion > 0) {
+          throw new Error(
+            "local replaceManyWithIds is disabled on versioned collections; use updateOne/updateMany so schema-version guards are atomic"
+          );
+        }
+      }
       if (schema) docs.forEach((doc, i) => {
         const { _replica_scope, _remote_rev, ...schemaDoc } = doc;
         void _replica_scope;
@@ -862,38 +977,75 @@ function applySchema(col, options) {
       });
       return col.replaceManyWithIds(docs.map((d) => stampDoc(d)), origin);
     } : col.replaceManyWithIds.bind(col),
+    deleteManyWithIds: stampVersion ? async (ids, origin) => {
+      if (origin !== "remote") {
+        throw new Error(
+          "local deleteManyWithIds is disabled on versioned collections; use deleteOne/deleteMany so schema-version guards are atomic"
+        );
+      }
+      return col.deleteManyWithIds(ids, origin);
+    } : col.deleteManyWithIds.bind(col),
+    updateOne: wrapWrites ? async (filter, update) => {
+      assertSafeUpdate(update);
+      return col.updateOne(writableFilter(filter), update);
+    } : col.updateOne.bind(col),
+    updateMany: wrapWrites ? async (filter, update) => {
+      assertSafeUpdate(update);
+      return col.updateMany(writableFilter(filter), update);
+    } : col.updateMany.bind(col),
+    deleteOne: stampVersion ? (filter) => col.deleteOne(writableFilter(filter)) : col.deleteOne.bind(col),
+    deleteMany: stampVersion ? (filter) => col.deleteMany(writableFilter(filter)) : col.deleteMany.bind(col),
     find: wrapReads ? async (filter) => {
       const docs = await col.find(filter);
-      const migrated = docs.map(migrateRead);
-      await persistAll(docs, migrated);
-      return migrated.map(validateRead);
+      const normalized = docs.map(normalizeRead);
+      await persistAll(docs, normalized);
+      return normalized.map((n) => validateRead(n.value));
     } : col.find.bind(col),
     findOne: wrapReads ? async (filter) => {
       const doc = await col.findOne(filter);
       if (doc === null) return null;
-      const migrated = migrateRead(doc);
-      await persistAll([doc], [migrated]);
-      return validateRead(migrated);
+      const normalized = normalizeRead(doc);
+      await persistAll([doc], [normalized]);
+      return validateRead(normalized.value);
     } : col.findOne.bind(col),
+    aggregate: wrapReads ? async (pipeline) => {
+      const docs = await col.aggregate(pipeline);
+      return pipelinePreservesDocuments(pipeline) ? normalizeViewRows(docs) : docs;
+    } : col.aggregate.bind(col),
     // Live queries feed every @taladb/react hook (useFind, useFindOne,
     // useQueries). Leaving them unwrapped meant React components received the
     // un-migrated shape while a direct find() returned the migrated one.
     subscribe: wrapReads ? (filter, callback, onError) => col.subscribe(
       filter,
       (docs) => {
-        const migrated = docs.map(migrateRead);
+        const normalized = docs.map(normalizeRead);
         let out;
         try {
-          out = migrated.map(validateRead);
+          out = normalized.map((n) => validateRead(n.value));
         } catch (err) {
           onError?.(err);
           return;
         }
         callback(out);
-        void persistAll(docs, migrated);
+        void persistAll(docs, normalized);
       },
       onError
-    ) : col.subscribe.bind(col)
+    ) : col.subscribe.bind(col),
+    subscribeAggregate: wrapReads ? (pipeline, callback, onError) => col.subscribeAggregate(
+      pipeline,
+      (docs) => {
+        if (!pipelinePreservesDocuments(pipeline)) {
+          callback(docs);
+          return;
+        }
+        try {
+          callback(normalizeViewRows(docs));
+        } catch (error) {
+          onError?.(error);
+        }
+      },
+      onError
+    ) : col.subscribeAggregate.bind(col)
   };
 }
 function detectPlatform() {
@@ -1103,6 +1255,30 @@ async function createBrowserDB(dbName, config, passphrase, migrations) {
         });
         return JSON.parse(json);
       },
+      searchText: async (field, query, topK, filter, options) => {
+        const json = await proxy.send("searchText", {
+          collection: name,
+          field,
+          query,
+          topK,
+          filterJson: filter ? JSON.stringify(filter) : "null",
+          optionsJson: options ? JSON.stringify(options) : "null"
+        });
+        return JSON.parse(json);
+      },
+      hybridSearch: async (text, vector, topK, filter, options) => {
+        const json = await proxy.send("hybridSearch", {
+          collection: name,
+          textField: text.textField,
+          text: text.text,
+          vectorField: vector.vectorField,
+          vectorJson: JSON.stringify(vector.vector),
+          topK,
+          filterJson: filter ? JSON.stringify(filter) : "null",
+          optionsJson: options ? JSON.stringify(options) : "null"
+        });
+        return JSON.parse(json);
+      },
       subscribe: (filter, callback, onError) => nudgedPoller(
         () => proxy.send("find", {
           collection: name,
@@ -1247,6 +1423,12 @@ async function createNodeDB(dbName, config, passphrase, migrations) {
         const raw = await col.findNearest(field, vector, topK, filter ?? null);
         return raw;
       },
+      searchText: async (field, query, topK, filter, options) => {
+        return col.searchText(field, query, topK, filter ?? null, options ?? null);
+      },
+      hybridSearch: async (text, vector, topK, filter, options) => {
+        return col.hybridSearch(text.textField, text.text, vector.vectorField, vector.vector, topK, filter ?? null, options ?? null);
+      },
       subscribe: (filter, callback, onError) => makePoller(async () => col.find(filter ?? null), callback, onError),
       subscribeAggregate: (pipeline, callback, onError) => makePoller(async () => wrapped.aggregate(pipeline), callback, onError)
     };
@@ -1329,6 +1511,18 @@ async function createNativeDB(_dbName, migrations) {
         const raw = native.findNearest(name, field, vector, topK, filter ?? null);
         return raw;
       },
+      searchText: async (field, query, topK, filter, options) => {
+        if (!native.searchText) {
+          throw new Error("searchText requires @taladb/react-native \u2265 0.10 \u2014 rebuild the native module");
+        }
+        return native.searchText(name, field, query, topK, filter ?? null, options ?? null);
+      },
+      hybridSearch: async (text, vector, topK, filter, options) => {
+        if (!native.hybridSearch) {
+          throw new Error("hybridSearch requires @taladb/react-native \u2265 0.10 \u2014 rebuild the native module");
+        }
+        return native.hybridSearch(name, text.textField, text.text, vector.vectorField, vector.vector, topK, filter ?? null, options ?? null);
+      },
       subscribe: (filter, callback, onError) => makePoller(async () => native.find(name, filter ?? {}), callback, onError),
       subscribeAggregate: (pipeline, callback, onError) => makePoller(async () => native.aggregate(name, pipeline), callback, onError)
     };