@taladb/react-native 0.11.8 → 0.12.0

package/README.md

@@ -84,7 +84,7 @@ JavaScript (React Native)
 C++ HostObject (TalaDBHostObject.cpp)
         │  C FFI
         ▼
-Rust static library (taladb-core)
+Rust static library (taladb engine)
         │
         ▼
 redb B-tree (app documents directory)

package/cpp/TalaDBHostObject.cpp

@@ -542,10 +542,12 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
                 if (count < 2) throw JSError(rt, (name + " requires 2 arguments").c_str());
                 auto col   = args[0].getString(rt).utf8(rt);
                 auto field = args[1].getString(rt).utf8(rt);
-                if      (name == "createIndex")    taladb_create_index    (db_, col.c_str(), field.c_str());
-                else if (name == "dropIndex")      taladb_drop_index      (db_, col.c_str(), field.c_str());
-                else if (name == "createFtsIndex") taladb_create_fts_index(db_, col.c_str(), field.c_str());
-                else                               taladb_drop_fts_index  (db_, col.c_str(), field.c_str());
+                int32_t res;
+                if      (name == "createIndex")    res = taladb_create_index    (db_, col.c_str(), field.c_str());
+                else if (name == "dropIndex")      res = taladb_drop_index      (db_, col.c_str(), field.c_str());
+                else if (name == "createFtsIndex") res = taladb_create_fts_index(db_, col.c_str(), field.c_str());
+                else                               res = taladb_drop_fts_index  (db_, col.c_str(), field.c_str());
+                if (res < 0) throw ffiError(rt, (name + " failed").c_str());
                 return Value::undefined();
             });
     }
@@ -560,10 +562,10 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
                 if (count < 2) throw JSError(rt, (name + " requires 2 arguments").c_str());
                 auto col        = args[0].getString(rt).utf8(rt);
                 auto fieldsJson = stringify(rt, args[1]);   // string[] → JSON array
-                if (name == "createCompoundIndex")
-                    taladb_create_compound_index(db_, col.c_str(), fieldsJson.c_str());
-                else
-                    taladb_drop_compound_index(db_, col.c_str(), fieldsJson.c_str());
+                int32_t res = name == "createCompoundIndex"
+                    ? taladb_create_compound_index(db_, col.c_str(), fieldsJson.c_str())
+                    : taladb_drop_compound_index(db_, col.c_str(), fieldsJson.c_str());
+                if (res < 0) throw ffiError(rt, (name + " failed").c_str());
                 return Value::undefined();
             });
     }

package/cpp/taladb.h

@@ -2,12 +2,20 @@
  * TalaDB C FFI header.
  *
  * GENERATED FILE — do not edit. Regenerate with:
- *   pnpm --filter @taladb/react-native build:cbindgen
- * CI fails if this file and rust/src/lib.rs disagree.
+ *   packages/bindings/ffi/scripts/gen-header.sh
+ * CI fails if this file and packages/bindings/ffi/src/lib.rs disagree.
  *
- * This is the stable C interface between the Rust taladb-ffi crate and the C++
- * JSI HostObject (cpp/TalaDBHostObject.cpp, cpp/TalaDBJni.cpp) and the iOS
- * TurboModule (ios/TalaDB.mm).
+ * This is the stable C interface of the Rust taladb-ffi crate. Its consumers
+ * are the React Native JSI HostObject and TurboModule in this repository and
+ * the native Swift (taladb/taladb-swift) and Kotlin (taladb/taladb-kotlin)
+ * packages, which ship as separate repositories.
+ *
+ * Compatibility
+ * -------------
+ *  TALADB_FFI_ABI_VERSION changes whenever a signature in this file changes
+ *  incompatibly. A wrapper compiled against this header must check that
+ *  taladb_ffi_abi_version() returns the same value before calling anything
+ *  else; a mismatch means the library and header came from different releases.
  *
  * Ownership rules
  * ---------------
@@ -31,6 +39,18 @@
 #include <stdlib.h>
 
 
+/**
+ * Version of the C interface in `taladb.h`. Bumped whenever an exported
+ * signature changes incompatibly, independently of the crate version.
+ *
+ * - 1 — through 0.11.8.
+ * - 2 — the six index create/drop functions return `int32_t` instead of
+ *   `void`; `taladb_call`, `taladb_ffi_abi_version`, `taladb_last_error_code`
+ *   and the live-query functions (`taladb_watch`, `taladb_watch_next`,
+ *   `taladb_watch_close`, `taladb_watch_with_options`) added.
+ */
+#define TALADB_FFI_ABI_VERSION 2
+
 typedef struct TalaDbHandle TalaDbHandle;
 
 /**
@@ -38,6 +58,12 @@ typedef struct TalaDbHandle TalaDbHandle;
  */
 typedef struct TalaDbJob TalaDbJob;
 
+/**
+ * A live query: a subscription to the documents in one collection that match
+ * one filter. Opaque to the caller.
+ */
+typedef struct TalaDbWatch TalaDbWatch;
+
 #ifdef __cplusplus
 extern "C" {
 #endif // __cplusplus
@@ -54,6 +80,30 @@ extern "C" {
  */
 const char *taladb_last_error(void);
 
+/**
+ * The engine's stable code for the error [`taladb_last_error`] describes —
+ * `"Encryption"` for a wrong passphrase, `"InvalidFilter"`, `"DuplicateId"`,
+ * and the rest of `TalaDbError::code` — or NULL when the last call succeeded
+ * or failed outside the engine (a null pointer, malformed arguments).
+ *
+ * Codes are a public contract shared with the JavaScript bindings' `error.code`:
+ * new ones may be added, an existing one never changes meaning. Read it in the
+ * same native call as the message; like the message, it is thread-local.
+ * The returned string is static. Do NOT free it.
+ */
+const char *taladb_last_error_code(void);
+
+/**
+ * The [`TALADB_FFI_ABI_VERSION`] this library was built with.
+ *
+ * The Swift and Kotlin packages live in their own repositories and load a
+ * prebuilt library, so the header they compiled against and the library they
+ * load can come from different releases. Each checks this once at load time
+ * and refuses to continue on a mismatch, because a changed signature links
+ * fine and then corrupts the stack at run time.
+ */
+uint32_t taladb_ffi_abi_version(void);
+
 /**
  * Open (or create) a TalaDB database at `path`.
  *
@@ -205,40 +255,48 @@ int32_t taladb_set_user_version(struct TalaDbHandle *handle, uint32_t version);
 int32_t taladb_flush(struct TalaDbHandle *handle);
 
 /**
- * Create a secondary index on `field`. No-op if already exists.
+ * Create a secondary index on `field`. No-op if it already exists.
+ * Returns 1 on success, -1 on error.
  */
-void taladb_create_index(struct TalaDbHandle *handle, const char *collection, const char *field);
+int32_t taladb_create_index(struct TalaDbHandle *handle, const char *collection, const char *field);
 
 /**
- * Drop a secondary index on `field`.
+ * Drop a secondary index on `field`. Returns 1 on success, -1 on error
+ * (including when no such index exists).
  */
-void taladb_drop_index(struct TalaDbHandle *handle, const char *collection, const char *field);
+int32_t taladb_drop_index(struct TalaDbHandle *handle, const char *collection, const char *field);
 
 /**
  * Create a compound index over `fields_json` (a JSON array of field names).
+ * Returns 1 on success, -1 on error.
  */
-void taladb_create_compound_index(struct TalaDbHandle *handle,
-                                  const char *collection,
-                                  const char *fields_json);
+int32_t taladb_create_compound_index(struct TalaDbHandle *handle,
+                                     const char *collection,
+                                     const char *fields_json);
 
 /**
  * Drop a compound index by its ordered field list (`fields_json`).
+ * Returns 1 on success, -1 on error.
  */
-void taladb_drop_compound_index(struct TalaDbHandle *handle,
-                                const char *collection,
-                                const char *fields_json);
+int32_t taladb_drop_compound_index(struct TalaDbHandle *handle,
+                                   const char *collection,
+                                   const char *fields_json);
 
 /**
- * Create a full-text search index on `field`.
+ * Create a full-text search index on `field`. No-op if it already exists.
+ * Returns 1 on success, -1 on error.
  */
-void taladb_create_fts_index(struct TalaDbHandle *handle,
-                             const char *collection,
-                             const char *field);
+int32_t taladb_create_fts_index(struct TalaDbHandle *handle,
+                                const char *collection,
+                                const char *field);
 
 /**
- * Drop a full-text search index on `field`.
+ * Drop a full-text search index on `field`. Returns 1 on success, -1 on
+ * error (including when no such index exists).
  */
-void taladb_drop_fts_index(struct TalaDbHandle *handle, const char *collection, const char *field);
+int32_t taladb_drop_fts_index(struct TalaDbHandle *handle,
+                              const char *collection,
+                              const char *field);
 
 /**
  * Rank documents against a free-text query using BM25 (OR semantics).
@@ -368,6 +426,72 @@ struct TalaDbJob *taladb_call_start(struct TalaDbHandle *handle,
                                     const char *op,
                                     const char *args_json);
 
+/**
+ * Run a JSON operation synchronously on the calling thread.
+ *
+ * Takes the same `op` names and `args_json` array as [`taladb_call_start`]
+ * and returns the result JSON directly, or NULL on error (see
+ * `taladb_last_error`). Caller must free the result with `taladb_free_string`.
+ *
+ * For callers that do their own threading — the Swift and Kotlin packages run
+ * it on a background executor — this reaches every operation in the dispatch
+ * table, including ones with no dedicated export (`listIndexes`,
+ * `vectorCommand`), without a job handle to poll.
+ */
+char *taladb_call(struct TalaDbHandle *handle, const char *op, const char *args_json);
+
+/**
+ * Subscribe to the documents in `collection` matching `filter_json` (NULL,
+ * `"{}"` or `"null"` for all).
+ *
+ * Writes made through any handle of the same database wake the watch. It
+ * delivers no initial snapshot — read the current state with `taladb_find`
+ * *after* this returns, so no write can fall between the two.
+ *
+ * The watch reads from the database it was created on and keeps its storage
+ * open until `taladb_watch_close`, even after `taladb_close`. Returns NULL on
+ * error.
+ */
+struct TalaDbWatch *taladb_watch(struct TalaDbHandle *handle,
+                                 const char *collection,
+                                 const char *filter_json);
+
+/**
+ * [`taladb_watch`], with each snapshot projected like `find`'s options:
+ * `{"fields": [..]}` keeps only those fields, `{"exclude": [..]}` drops them.
+ * A NULL or `"null"` `options_json` is the same as `taladb_watch`.
+ *
+ * Every write sends a fresh snapshot across to the caller, so excluding a
+ * large field the caller does not display (an embedding) keeps each update
+ * small.
+ *
+ * # Safety
+ * As for [`taladb_watch`]; `options_json` may be NULL.
+ */
+struct TalaDbWatch *taladb_watch_with_options(struct TalaDbHandle *handle,
+                                              const char *collection,
+                                              const char *filter_json,
+                                              const char *options_json);
+
+/**
+ * Wait up to `timeout_ms` for a write to the watched collection.
+ *
+ * Returns 1 and sets `*out_json` to a JSON array of the matching documents
+ * (free with `taladb_free_string`) if a write occurred — several writes since
+ * the last call coalesce into one snapshot of the latest state. Returns 0 and
+ * sets `*out_json` to NULL on timeout, and -1 on error.
+ *
+ * The timeout is what lets a caller stop a subscription: loop on this with a
+ * short timeout and check for cancellation between calls. Do not call
+ * `taladb_watch_close` while a call on the same watch is in progress.
+ */
+int32_t taladb_watch_next(struct TalaDbWatch *watch, uint32_t timeout_ms, char **out_json);
+
+/**
+ * Close a watch and release the storage it holds open. NULL is a no-op.
+ */
+void taladb_watch_close(struct TalaDbWatch *watch);
+
 /**
  * Start a `find_nearest` in a background thread. Returns a job handle, or
  * NULL on immediate error (bad args). The Float32 query vector is copied

package/ios/TalaDBFfi.xcframework/Info.plist

@@ -6,38 +6,38 @@
 	<array>
 		<dict>
 			<key>BinaryPath</key>
-			<string>libtaladb_ffi_sim.a</string>
+			<string>libtaladb_ffi.a</string>
 			<key>HeadersPath</key>
 			<string>Headers</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64_x86_64-simulator</string>
+			<string>ios-arm64</string>
 			<key>LibraryPath</key>
-			<string>libtaladb_ffi_sim.a</string>
+			<string>libtaladb_ffi.a</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
-				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
-			<key>SupportedPlatformVariant</key>
-			<string>simulator</string>
 		</dict>
 		<dict>
 			<key>BinaryPath</key>
-			<string>libtaladb_ffi.a</string>
+			<string>libtaladb_ffi_sim.a</string>
 			<key>HeadersPath</key>
 			<string>Headers</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64</string>
+			<string>ios-arm64_x86_64-simulator</string>
 			<key>LibraryPath</key>
-			<string>libtaladb_ffi.a</string>
+			<string>libtaladb_ffi_sim.a</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
+				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
 		</dict>
 	</array>
 	<key>CFBundlePackageType</key>

package/ios/TalaDBFfi.xcframework/ios-arm64/Headers/TalaDBHostObject.cpp

@@ -542,10 +542,12 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
                 if (count < 2) throw JSError(rt, (name + " requires 2 arguments").c_str());
                 auto col   = args[0].getString(rt).utf8(rt);
                 auto field = args[1].getString(rt).utf8(rt);
-                if      (name == "createIndex")    taladb_create_index    (db_, col.c_str(), field.c_str());
-                else if (name == "dropIndex")      taladb_drop_index      (db_, col.c_str(), field.c_str());
-                else if (name == "createFtsIndex") taladb_create_fts_index(db_, col.c_str(), field.c_str());
-                else                               taladb_drop_fts_index  (db_, col.c_str(), field.c_str());
+                int32_t res;
+                if      (name == "createIndex")    res = taladb_create_index    (db_, col.c_str(), field.c_str());
+                else if (name == "dropIndex")      res = taladb_drop_index      (db_, col.c_str(), field.c_str());
+                else if (name == "createFtsIndex") res = taladb_create_fts_index(db_, col.c_str(), field.c_str());
+                else                               res = taladb_drop_fts_index  (db_, col.c_str(), field.c_str());
+                if (res < 0) throw ffiError(rt, (name + " failed").c_str());
                 return Value::undefined();
             });
     }
@@ -560,10 +562,10 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
                 if (count < 2) throw JSError(rt, (name + " requires 2 arguments").c_str());
                 auto col        = args[0].getString(rt).utf8(rt);
                 auto fieldsJson = stringify(rt, args[1]);   // string[] → JSON array
-                if (name == "createCompoundIndex")
-                    taladb_create_compound_index(db_, col.c_str(), fieldsJson.c_str());
-                else
-                    taladb_drop_compound_index(db_, col.c_str(), fieldsJson.c_str());
+                int32_t res = name == "createCompoundIndex"
+                    ? taladb_create_compound_index(db_, col.c_str(), fieldsJson.c_str())
+                    : taladb_drop_compound_index(db_, col.c_str(), fieldsJson.c_str());
+                if (res < 0) throw ffiError(rt, (name + " failed").c_str());
                 return Value::undefined();
             });
     }

package/ios/TalaDBFfi.xcframework/ios-arm64/Headers/taladb.h

@@ -2,12 +2,20 @@
  * TalaDB C FFI header.
  *
  * GENERATED FILE — do not edit. Regenerate with:
- *   pnpm --filter @taladb/react-native build:cbindgen
- * CI fails if this file and rust/src/lib.rs disagree.
+ *   packages/bindings/ffi/scripts/gen-header.sh
+ * CI fails if this file and packages/bindings/ffi/src/lib.rs disagree.
  *
- * This is the stable C interface between the Rust taladb-ffi crate and the C++
- * JSI HostObject (cpp/TalaDBHostObject.cpp, cpp/TalaDBJni.cpp) and the iOS
- * TurboModule (ios/TalaDB.mm).
+ * This is the stable C interface of the Rust taladb-ffi crate. Its consumers
+ * are the React Native JSI HostObject and TurboModule in this repository and
+ * the native Swift (taladb/taladb-swift) and Kotlin (taladb/taladb-kotlin)
+ * packages, which ship as separate repositories.
+ *
+ * Compatibility
+ * -------------
+ *  TALADB_FFI_ABI_VERSION changes whenever a signature in this file changes
+ *  incompatibly. A wrapper compiled against this header must check that
+ *  taladb_ffi_abi_version() returns the same value before calling anything
+ *  else; a mismatch means the library and header came from different releases.
  *
  * Ownership rules
  * ---------------
@@ -31,6 +39,18 @@
 #include <stdlib.h>
 
 
+/**
+ * Version of the C interface in `taladb.h`. Bumped whenever an exported
+ * signature changes incompatibly, independently of the crate version.
+ *
+ * - 1 — through 0.11.8.
+ * - 2 — the six index create/drop functions return `int32_t` instead of
+ *   `void`; `taladb_call`, `taladb_ffi_abi_version`, `taladb_last_error_code`
+ *   and the live-query functions (`taladb_watch`, `taladb_watch_next`,
+ *   `taladb_watch_close`, `taladb_watch_with_options`) added.
+ */
+#define TALADB_FFI_ABI_VERSION 2
+
 typedef struct TalaDbHandle TalaDbHandle;
 
 /**
@@ -38,6 +58,12 @@ typedef struct TalaDbHandle TalaDbHandle;
  */
 typedef struct TalaDbJob TalaDbJob;
 
+/**
+ * A live query: a subscription to the documents in one collection that match
+ * one filter. Opaque to the caller.
+ */
+typedef struct TalaDbWatch TalaDbWatch;
+
 #ifdef __cplusplus
 extern "C" {
 #endif // __cplusplus
@@ -54,6 +80,30 @@ extern "C" {
  */
 const char *taladb_last_error(void);
 
+/**
+ * The engine's stable code for the error [`taladb_last_error`] describes —
+ * `"Encryption"` for a wrong passphrase, `"InvalidFilter"`, `"DuplicateId"`,
+ * and the rest of `TalaDbError::code` — or NULL when the last call succeeded
+ * or failed outside the engine (a null pointer, malformed arguments).
+ *
+ * Codes are a public contract shared with the JavaScript bindings' `error.code`:
+ * new ones may be added, an existing one never changes meaning. Read it in the
+ * same native call as the message; like the message, it is thread-local.
+ * The returned string is static. Do NOT free it.
+ */
+const char *taladb_last_error_code(void);
+
+/**
+ * The [`TALADB_FFI_ABI_VERSION`] this library was built with.
+ *
+ * The Swift and Kotlin packages live in their own repositories and load a
+ * prebuilt library, so the header they compiled against and the library they
+ * load can come from different releases. Each checks this once at load time
+ * and refuses to continue on a mismatch, because a changed signature links
+ * fine and then corrupts the stack at run time.
+ */
+uint32_t taladb_ffi_abi_version(void);
+
 /**
  * Open (or create) a TalaDB database at `path`.
  *
@@ -205,40 +255,48 @@ int32_t taladb_set_user_version(struct TalaDbHandle *handle, uint32_t version);
 int32_t taladb_flush(struct TalaDbHandle *handle);
 
 /**
- * Create a secondary index on `field`. No-op if already exists.
+ * Create a secondary index on `field`. No-op if it already exists.
+ * Returns 1 on success, -1 on error.
  */
-void taladb_create_index(struct TalaDbHandle *handle, const char *collection, const char *field);
+int32_t taladb_create_index(struct TalaDbHandle *handle, const char *collection, const char *field);
 
 /**
- * Drop a secondary index on `field`.
+ * Drop a secondary index on `field`. Returns 1 on success, -1 on error
+ * (including when no such index exists).
  */
-void taladb_drop_index(struct TalaDbHandle *handle, const char *collection, const char *field);
+int32_t taladb_drop_index(struct TalaDbHandle *handle, const char *collection, const char *field);
 
 /**
  * Create a compound index over `fields_json` (a JSON array of field names).
+ * Returns 1 on success, -1 on error.
  */
-void taladb_create_compound_index(struct TalaDbHandle *handle,
-                                  const char *collection,
-                                  const char *fields_json);
+int32_t taladb_create_compound_index(struct TalaDbHandle *handle,
+                                     const char *collection,
+                                     const char *fields_json);
 
 /**
  * Drop a compound index by its ordered field list (`fields_json`).
+ * Returns 1 on success, -1 on error.
  */
-void taladb_drop_compound_index(struct TalaDbHandle *handle,
-                                const char *collection,
-                                const char *fields_json);
+int32_t taladb_drop_compound_index(struct TalaDbHandle *handle,
+                                   const char *collection,
+                                   const char *fields_json);
 
 /**
- * Create a full-text search index on `field`.
+ * Create a full-text search index on `field`. No-op if it already exists.
+ * Returns 1 on success, -1 on error.
  */
-void taladb_create_fts_index(struct TalaDbHandle *handle,
-                             const char *collection,
-                             const char *field);
+int32_t taladb_create_fts_index(struct TalaDbHandle *handle,
+                                const char *collection,
+                                const char *field);
 
 /**
- * Drop a full-text search index on `field`.
+ * Drop a full-text search index on `field`. Returns 1 on success, -1 on
+ * error (including when no such index exists).
  */
-void taladb_drop_fts_index(struct TalaDbHandle *handle, const char *collection, const char *field);
+int32_t taladb_drop_fts_index(struct TalaDbHandle *handle,
+                              const char *collection,
+                              const char *field);
 
 /**
  * Rank documents against a free-text query using BM25 (OR semantics).
@@ -368,6 +426,72 @@ struct TalaDbJob *taladb_call_start(struct TalaDbHandle *handle,
                                     const char *op,
                                     const char *args_json);
 
+/**
+ * Run a JSON operation synchronously on the calling thread.
+ *
+ * Takes the same `op` names and `args_json` array as [`taladb_call_start`]
+ * and returns the result JSON directly, or NULL on error (see
+ * `taladb_last_error`). Caller must free the result with `taladb_free_string`.
+ *
+ * For callers that do their own threading — the Swift and Kotlin packages run
+ * it on a background executor — this reaches every operation in the dispatch
+ * table, including ones with no dedicated export (`listIndexes`,
+ * `vectorCommand`), without a job handle to poll.
+ */
+char *taladb_call(struct TalaDbHandle *handle, const char *op, const char *args_json);
+
+/**
+ * Subscribe to the documents in `collection` matching `filter_json` (NULL,
+ * `"{}"` or `"null"` for all).
+ *
+ * Writes made through any handle of the same database wake the watch. It
+ * delivers no initial snapshot — read the current state with `taladb_find`
+ * *after* this returns, so no write can fall between the two.
+ *
+ * The watch reads from the database it was created on and keeps its storage
+ * open until `taladb_watch_close`, even after `taladb_close`. Returns NULL on
+ * error.
+ */
+struct TalaDbWatch *taladb_watch(struct TalaDbHandle *handle,
+                                 const char *collection,
+                                 const char *filter_json);
+
+/**
+ * [`taladb_watch`], with each snapshot projected like `find`'s options:
+ * `{"fields": [..]}` keeps only those fields, `{"exclude": [..]}` drops them.
+ * A NULL or `"null"` `options_json` is the same as `taladb_watch`.
+ *
+ * Every write sends a fresh snapshot across to the caller, so excluding a
+ * large field the caller does not display (an embedding) keeps each update
+ * small.
+ *
+ * # Safety
+ * As for [`taladb_watch`]; `options_json` may be NULL.
+ */
+struct TalaDbWatch *taladb_watch_with_options(struct TalaDbHandle *handle,
+                                              const char *collection,
+                                              const char *filter_json,
+                                              const char *options_json);
+
+/**
+ * Wait up to `timeout_ms` for a write to the watched collection.
+ *
+ * Returns 1 and sets `*out_json` to a JSON array of the matching documents
+ * (free with `taladb_free_string`) if a write occurred — several writes since
+ * the last call coalesce into one snapshot of the latest state. Returns 0 and
+ * sets `*out_json` to NULL on timeout, and -1 on error.
+ *
+ * The timeout is what lets a caller stop a subscription: loop on this with a
+ * short timeout and check for cancellation between calls. Do not call
+ * `taladb_watch_close` while a call on the same watch is in progress.
+ */
+int32_t taladb_watch_next(struct TalaDbWatch *watch, uint32_t timeout_ms, char **out_json);
+
+/**
+ * Close a watch and release the storage it holds open. NULL is a no-op.
+ */
+void taladb_watch_close(struct TalaDbWatch *watch);
+
 /**
  * Start a `find_nearest` in a background thread. Returns a job handle, or
  * NULL on immediate error (bad args). The Float32 query vector is copied

package/ios/TalaDBFfi.xcframework/ios-arm64/libtaladb_ffi.a

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/ios/TalaDBFfi.xcframework/ios-arm64/libtaladb_ffi.a
-size: 40403976 bytes
-sha256: 91a188721976d13afd1532ce4b0157d0bcf4580544dadfbdd4034eb61f3ddf0d
+size: 41650952 bytes
+sha256: 6a9fbc9f3746b965dc0352436eaf2eef34d2b5f99b08b47c114d0390d91cfca1

package/ios/TalaDBFfi.xcframework/ios-arm64_x86_64-simulator/Headers/TalaDBHostObject.cpp

@@ -542,10 +542,12 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
                 if (count < 2) throw JSError(rt, (name + " requires 2 arguments").c_str());
                 auto col   = args[0].getString(rt).utf8(rt);
                 auto field = args[1].getString(rt).utf8(rt);
-                if      (name == "createIndex")    taladb_create_index    (db_, col.c_str(), field.c_str());
-                else if (name == "dropIndex")      taladb_drop_index      (db_, col.c_str(), field.c_str());
-                else if (name == "createFtsIndex") taladb_create_fts_index(db_, col.c_str(), field.c_str());
-                else                               taladb_drop_fts_index  (db_, col.c_str(), field.c_str());
+                int32_t res;
+                if      (name == "createIndex")    res = taladb_create_index    (db_, col.c_str(), field.c_str());
+                else if (name == "dropIndex")      res = taladb_drop_index      (db_, col.c_str(), field.c_str());
+                else if (name == "createFtsIndex") res = taladb_create_fts_index(db_, col.c_str(), field.c_str());
+                else                               res = taladb_drop_fts_index  (db_, col.c_str(), field.c_str());
+                if (res < 0) throw ffiError(rt, (name + " failed").c_str());
                 return Value::undefined();
             });
     }
@@ -560,10 +562,10 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
                 if (count < 2) throw JSError(rt, (name + " requires 2 arguments").c_str());
                 auto col        = args[0].getString(rt).utf8(rt);
                 auto fieldsJson = stringify(rt, args[1]);   // string[] → JSON array
-                if (name == "createCompoundIndex")
-                    taladb_create_compound_index(db_, col.c_str(), fieldsJson.c_str());
-                else
-                    taladb_drop_compound_index(db_, col.c_str(), fieldsJson.c_str());
+                int32_t res = name == "createCompoundIndex"
+                    ? taladb_create_compound_index(db_, col.c_str(), fieldsJson.c_str())
+                    : taladb_drop_compound_index(db_, col.c_str(), fieldsJson.c_str());
+                if (res < 0) throw ffiError(rt, (name + " failed").c_str());
                 return Value::undefined();
             });
     }

package/ios/TalaDBFfi.xcframework/ios-arm64_x86_64-simulator/Headers/taladb.h

@@ -2,12 +2,20 @@
  * TalaDB C FFI header.
  *
  * GENERATED FILE — do not edit. Regenerate with:
- *   pnpm --filter @taladb/react-native build:cbindgen
- * CI fails if this file and rust/src/lib.rs disagree.
+ *   packages/bindings/ffi/scripts/gen-header.sh
+ * CI fails if this file and packages/bindings/ffi/src/lib.rs disagree.
  *
- * This is the stable C interface between the Rust taladb-ffi crate and the C++
- * JSI HostObject (cpp/TalaDBHostObject.cpp, cpp/TalaDBJni.cpp) and the iOS
- * TurboModule (ios/TalaDB.mm).
+ * This is the stable C interface of the Rust taladb-ffi crate. Its consumers
+ * are the React Native JSI HostObject and TurboModule in this repository and
+ * the native Swift (taladb/taladb-swift) and Kotlin (taladb/taladb-kotlin)
+ * packages, which ship as separate repositories.
+ *
+ * Compatibility
+ * -------------
+ *  TALADB_FFI_ABI_VERSION changes whenever a signature in this file changes
+ *  incompatibly. A wrapper compiled against this header must check that
+ *  taladb_ffi_abi_version() returns the same value before calling anything
+ *  else; a mismatch means the library and header came from different releases.
  *
  * Ownership rules
  * ---------------
@@ -31,6 +39,18 @@
 #include <stdlib.h>
 
 
+/**
+ * Version of the C interface in `taladb.h`. Bumped whenever an exported
+ * signature changes incompatibly, independently of the crate version.
+ *
+ * - 1 — through 0.11.8.
+ * - 2 — the six index create/drop functions return `int32_t` instead of
+ *   `void`; `taladb_call`, `taladb_ffi_abi_version`, `taladb_last_error_code`
+ *   and the live-query functions (`taladb_watch`, `taladb_watch_next`,
+ *   `taladb_watch_close`, `taladb_watch_with_options`) added.
+ */
+#define TALADB_FFI_ABI_VERSION 2
+
 typedef struct TalaDbHandle TalaDbHandle;
 
 /**
@@ -38,6 +58,12 @@ typedef struct TalaDbHandle TalaDbHandle;
  */
 typedef struct TalaDbJob TalaDbJob;
 
+/**
+ * A live query: a subscription to the documents in one collection that match
+ * one filter. Opaque to the caller.
+ */
+typedef struct TalaDbWatch TalaDbWatch;
+
 #ifdef __cplusplus
 extern "C" {
 #endif // __cplusplus
@@ -54,6 +80,30 @@ extern "C" {
  */
 const char *taladb_last_error(void);
 
+/**
+ * The engine's stable code for the error [`taladb_last_error`] describes —
+ * `"Encryption"` for a wrong passphrase, `"InvalidFilter"`, `"DuplicateId"`,
+ * and the rest of `TalaDbError::code` — or NULL when the last call succeeded
+ * or failed outside the engine (a null pointer, malformed arguments).
+ *
+ * Codes are a public contract shared with the JavaScript bindings' `error.code`:
+ * new ones may be added, an existing one never changes meaning. Read it in the
+ * same native call as the message; like the message, it is thread-local.
+ * The returned string is static. Do NOT free it.
+ */
+const char *taladb_last_error_code(void);
+
+/**
+ * The [`TALADB_FFI_ABI_VERSION`] this library was built with.
+ *
+ * The Swift and Kotlin packages live in their own repositories and load a
+ * prebuilt library, so the header they compiled against and the library they
+ * load can come from different releases. Each checks this once at load time
+ * and refuses to continue on a mismatch, because a changed signature links
+ * fine and then corrupts the stack at run time.
+ */
+uint32_t taladb_ffi_abi_version(void);
+
 /**
  * Open (or create) a TalaDB database at `path`.
  *
@@ -205,40 +255,48 @@ int32_t taladb_set_user_version(struct TalaDbHandle *handle, uint32_t version);
 int32_t taladb_flush(struct TalaDbHandle *handle);
 
 /**
- * Create a secondary index on `field`. No-op if already exists.
+ * Create a secondary index on `field`. No-op if it already exists.
+ * Returns 1 on success, -1 on error.
  */
-void taladb_create_index(struct TalaDbHandle *handle, const char *collection, const char *field);
+int32_t taladb_create_index(struct TalaDbHandle *handle, const char *collection, const char *field);
 
 /**
- * Drop a secondary index on `field`.
+ * Drop a secondary index on `field`. Returns 1 on success, -1 on error
+ * (including when no such index exists).
  */
-void taladb_drop_index(struct TalaDbHandle *handle, const char *collection, const char *field);
+int32_t taladb_drop_index(struct TalaDbHandle *handle, const char *collection, const char *field);
 
 /**
  * Create a compound index over `fields_json` (a JSON array of field names).
+ * Returns 1 on success, -1 on error.
  */
-void taladb_create_compound_index(struct TalaDbHandle *handle,
-                                  const char *collection,
-                                  const char *fields_json);
+int32_t taladb_create_compound_index(struct TalaDbHandle *handle,
+                                     const char *collection,
+                                     const char *fields_json);
 
 /**
  * Drop a compound index by its ordered field list (`fields_json`).
+ * Returns 1 on success, -1 on error.
  */
-void taladb_drop_compound_index(struct TalaDbHandle *handle,
-                                const char *collection,
-                                const char *fields_json);
+int32_t taladb_drop_compound_index(struct TalaDbHandle *handle,
+                                   const char *collection,
+                                   const char *fields_json);
 
 /**
- * Create a full-text search index on `field`.
+ * Create a full-text search index on `field`. No-op if it already exists.
+ * Returns 1 on success, -1 on error.
  */
-void taladb_create_fts_index(struct TalaDbHandle *handle,
-                             const char *collection,
-                             const char *field);
+int32_t taladb_create_fts_index(struct TalaDbHandle *handle,
+                                const char *collection,
+                                const char *field);
 
 /**
- * Drop a full-text search index on `field`.
+ * Drop a full-text search index on `field`. Returns 1 on success, -1 on
+ * error (including when no such index exists).
  */
-void taladb_drop_fts_index(struct TalaDbHandle *handle, const char *collection, const char *field);
+int32_t taladb_drop_fts_index(struct TalaDbHandle *handle,
+                              const char *collection,
+                              const char *field);
 
 /**
  * Rank documents against a free-text query using BM25 (OR semantics).
@@ -368,6 +426,72 @@ struct TalaDbJob *taladb_call_start(struct TalaDbHandle *handle,
                                     const char *op,
                                     const char *args_json);
 
+/**
+ * Run a JSON operation synchronously on the calling thread.
+ *
+ * Takes the same `op` names and `args_json` array as [`taladb_call_start`]
+ * and returns the result JSON directly, or NULL on error (see
+ * `taladb_last_error`). Caller must free the result with `taladb_free_string`.
+ *
+ * For callers that do their own threading — the Swift and Kotlin packages run
+ * it on a background executor — this reaches every operation in the dispatch
+ * table, including ones with no dedicated export (`listIndexes`,
+ * `vectorCommand`), without a job handle to poll.
+ */
+char *taladb_call(struct TalaDbHandle *handle, const char *op, const char *args_json);
+
+/**
+ * Subscribe to the documents in `collection` matching `filter_json` (NULL,
+ * `"{}"` or `"null"` for all).
+ *
+ * Writes made through any handle of the same database wake the watch. It
+ * delivers no initial snapshot — read the current state with `taladb_find`
+ * *after* this returns, so no write can fall between the two.
+ *
+ * The watch reads from the database it was created on and keeps its storage
+ * open until `taladb_watch_close`, even after `taladb_close`. Returns NULL on
+ * error.
+ */
+struct TalaDbWatch *taladb_watch(struct TalaDbHandle *handle,
+                                 const char *collection,
+                                 const char *filter_json);
+
+/**
+ * [`taladb_watch`], with each snapshot projected like `find`'s options:
+ * `{"fields": [..]}` keeps only those fields, `{"exclude": [..]}` drops them.
+ * A NULL or `"null"` `options_json` is the same as `taladb_watch`.
+ *
+ * Every write sends a fresh snapshot across to the caller, so excluding a
+ * large field the caller does not display (an embedding) keeps each update
+ * small.
+ *
+ * # Safety
+ * As for [`taladb_watch`]; `options_json` may be NULL.
+ */
+struct TalaDbWatch *taladb_watch_with_options(struct TalaDbHandle *handle,
+                                              const char *collection,
+                                              const char *filter_json,
+                                              const char *options_json);
+
+/**
+ * Wait up to `timeout_ms` for a write to the watched collection.
+ *
+ * Returns 1 and sets `*out_json` to a JSON array of the matching documents
+ * (free with `taladb_free_string`) if a write occurred — several writes since
+ * the last call coalesce into one snapshot of the latest state. Returns 0 and
+ * sets `*out_json` to NULL on timeout, and -1 on error.
+ *
+ * The timeout is what lets a caller stop a subscription: loop on this with a
+ * short timeout and check for cancellation between calls. Do not call
+ * `taladb_watch_close` while a call on the same watch is in progress.
+ */
+int32_t taladb_watch_next(struct TalaDbWatch *watch, uint32_t timeout_ms, char **out_json);
+
+/**
+ * Close a watch and release the storage it holds open. NULL is a no-op.
+ */
+void taladb_watch_close(struct TalaDbWatch *watch);
+
 /**
  * Start a `find_nearest` in a background thread. Returns a job handle, or
  * NULL on immediate error (bad args). The Float32 query vector is copied

package/ios/TalaDBFfi.xcframework/ios-arm64_x86_64-simulator/libtaladb_ffi_sim.a

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/ios/TalaDBFfi.xcframework/ios-arm64_x86_64-simulator/libtaladb_ffi_sim.a
-size: 80836688 bytes
-sha256: f48e8da5f520ac6c990c1b6311ff0ae0d1de3385a7313366d0be2ce7a6118209
+size: 83429344 bytes
+sha256: 574fc31442ad389ab6e93e5889d5717aa767469e248280a014df2bb7fa0757cf

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taladb/react-native",
-  "version": "0.11.8",
+  "version": "0.12.0",
   "description": "TalaDB React Native module — document and vector database via JSI HostObject",
   "main": "src/index",
   "types": "src/index.tsx",
@@ -25,12 +25,12 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/tala-sh/taladb.git",
+    "url": "https://github.com/taladb/taladb.git",
     "directory": "packages/bindings/react-native"
   },
   "homepage": "https://taladb.dev/guide/react-native",
   "bugs": {
-    "url": "https://github.com/tala-sh/taladb/issues"
+    "url": "https://github.com/taladb/taladb/issues"
   },
   "engines": {
     "node": ">=18"
@@ -49,12 +49,12 @@
     "react-native": "^0.83.0"
   },
   "dependencies": {
-    "taladb": "0.11.8"
+    "taladb": "0.12.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build:ios": "sh scripts/build-ios.sh",
     "build:android": "sh scripts/build-android.sh",
-    "build:cbindgen": "cd rust && cbindgen --config cbindgen.toml --crate taladb-ffi --output ../cpp/taladb.h"
+    "build:cbindgen": "../ffi/scripts/gen-header.sh"
   }
 }

package/src/index.tsx

@@ -17,11 +17,11 @@ export type {
   HybridSearchOptions,
   TextSearchOptions,
   VectorMetric,
-  VectorClient, VectorQueryOptions, VectorRebuildOptions, VectorBuildProgress, VectorIndexStatus, VectorQueryResult, VectorRecall, VectorGraphOptions, VectorQuantization,
+  MemoryPressure, VectorCacheStats, VectorClient, VectorQueryOptions, VectorRebuildOptions, VectorBuildProgress, VectorIndexStatus, VectorQueryResult, VectorRecall, VectorGraphOptions, VectorQuantization,
 } from 'taladb';
 
 export const TalaDBModule = {
-  /** Open the native database. The config controls durability/encryption only. */
+  /** Open the native database with durability, encryption and vector cache settings. */
   initialize: (dbName: string, configJson?: string) =>
     NativeTalaDB.initialize(dbName, configJson),
   close: () => NativeTalaDB.close(),

package/taladb-react-native.podspec

@@ -6,12 +6,12 @@ Pod::Spec.new do |s|
   s.name          = "taladb-react-native"
   s.version       = package["version"]
   s.summary       = package["description"]
-  s.homepage      = "https://github.com/tala-sh/taladb"
+  s.homepage      = "https://github.com/taladb/taladb"
   s.license       = package["license"]
   s.authors       = { "taladb" => "hello@thinkgrid.io" }
 
   s.platforms     = { :ios => "13.0" }
-  s.source        = { :git => "https://github.com/tala-sh/taladb.git",
+  s.source        = { :git => "https://github.com/taladb/taladb.git",
                       :tag => "v#{s.version}" }
 
   # TypeScript / JS sources (not compiled by Xcode, just bundled)