@dittolive/ditto 4.5.4-alpha.1 → 4.6.0

package/react-native/src/sources/ffi.ts

@@ -12,7 +12,7 @@
 
 import * as dittoCore from './@ditto.core'
 import * as Environment from './@environment'
-import { throwOnErrorResult } from './ffi-error'
+import { DittoFFIError, throwOnErrorResult } from './ffi-error'
 
 // -------------------------------------------------------------- Prelude ------
 
@@ -40,10 +40,10 @@ export type FFIWriteStrategy = 'merge' | 'insertIfAbsent' | 'insertDefaultIfAbse
 export type FFIDocument = 'CDocument_t'
 
 /** @internal */
-export type FFIDqlResult = 'CDqlResult_t'
+export type FFIDqlResult = 'dittoffi_query_result_item_t'
 
 /** @internal */
-export type FFIDqlResponse = 'CDqlResponse_t'
+export type FFIDqlResponse = 'dittoffi_query_result_t'
 
 /** @internal */
 export type FFIReadTransaction = 'CReadTransaction_t'
@@ -141,6 +141,9 @@ export enum DittoCRDTType {
   rwMap = 4,
 }
 
+/** @internal */
+export type Base64PaddingMode = 'Padded' | 'Unpadded'
+
 /** @internal */
 export type CBParamsDocs = {
   documents: Pointer<FFIDocument>[]
@@ -180,7 +183,7 @@ export type RawAttachment = {
   handle: Pointer<AttachmentHandle>
 }
 
-// -------------------------------------- Linux & Windows Transports ------
+// -------------------------------------- Linux & Windows Transports Hack ------
 
 export function dittoAddInternalBLEClientTransport(ditto: Pointer<FFIDitto>): any {
   if (Environment.isNodeBuild) {
@@ -290,6 +293,7 @@ export function documentID(self: Pointer<FFIDocument>): Uint8Array {
   trace()
   ensureInitialized()
 
+  // REFACTOR: add proper error handling.
   const documentIDX = dittoCore.ditto_document_id(self)
   return dittoCore.boxCBytesIntoBuffer(documentIDX)
 }
@@ -344,6 +348,7 @@ export function documentFree(self: Pointer<FFIDocument>) {
   trace()
   ensureInitialized()
 
+  // REFACTOR: add proper error handling.
   dittoCore.ditto_document_free(self)
 }
 
@@ -379,6 +384,7 @@ export async function collectionGet(ditto: Pointer<FFIDitto>, collectionName: st
   trace()
   ensureInitialized()
 
+  // REFACTOR: add proper error handling.
   const collectionNameX = bytesFromString(collectionName)
 
   const { status_code: errorCode, document } = await dittoCore.ditto_collection_get(ditto, collectionNameX, documentID, readTransaction)
@@ -392,6 +398,7 @@ export async function collectionInsertValue(ditto: Pointer<FFIDitto>, collection
   trace()
   ensureInitialized()
 
+  // REFACTOR: add proper error handling.
   const collectionNameX = bytesFromString(collectionName)
 
   let strategy
@@ -419,6 +426,7 @@ export async function collectionRemove(ditto: Pointer<FFIDitto>, collectionName:
   trace()
   ensureInitialized()
 
+  // REFACTOR: add proper error handling.
   const collectionNameX = bytesFromString(collectionName)
 
   const { status_code: errorCode, bool_value: didRemove } = await dittoCore.ditto_collection_remove(ditto, collectionNameX, writeTransaction, documentID)
@@ -431,6 +439,7 @@ export async function collectionEvict(ditto: Pointer<FFIDitto>, collectionName:
   trace()
   ensureInitialized()
 
+  // REFACTOR: add proper error handling.
   const collectionNameX = bytesFromString(collectionName)
 
   const { status_code: errorCode, bool_value: didEvict } = await dittoCore.ditto_collection_evict(ditto, collectionNameX, writeTransaction, documentID)
@@ -502,8 +511,8 @@ export async function tryExperimentalExecQueryStr(ditto: Pointer<FFIDitto>, writ
   ensureInitialized()
 
   const queryBytesPointer = bytesFromString(query)
-  const result = await dittoCore.dittoffi_try_experimental_exec_statement_str(ditto, writeTransaction, queryBytesPointer, queryArgsCBOR)
-  throwOnErrorResult(result.error, 'dittoffi_try_experimental_exec_statement_str')
+  const result = await dittoCore.dittoffi_try_exec_statement(ditto, writeTransaction, queryBytesPointer, queryArgsCBOR)
+  throwOnErrorResult(result.error, 'dittoffi_try_exec_statement')
   return result.success
 }
 
@@ -533,8 +542,8 @@ export function tryExperimentalAddDQLSubscription(dittoPointer: Pointer<FFIDitto
   ensureInitialized()
 
   const queryBuffer = bytesFromString(query)
-  const result = dittoCore.dittoffi_try_experimental_add_dql_subscription(dittoPointer, queryBuffer, queryArgsCBOR)
-  throwOnErrorResult(result.error, 'dittoffi_try_experimental_add_dql_subscription')
+  const result = dittoCore.dittoffi_try_add_sync_subscription(dittoPointer, queryBuffer, queryArgsCBOR)
+  throwOnErrorResult(result.error, 'dittoffi_try_add_sync_subscription')
   return
 }
 
@@ -544,8 +553,8 @@ export function tryExperimentalRemoveDQLSubscription(dittoPointer: Pointer<FFIDi
   ensureInitialized()
 
   const queryBuffer = bytesFromString(query)
-  const result = dittoCore.dittoffi_try_experimental_remove_dql_subscription(dittoPointer, queryBuffer, queryArgsCBOR)
-  throwOnErrorResult(result.error, 'dittoffi_try_experimental_remove_dql_subscription')
+  const result = dittoCore.dittoffi_try_remove_sync_subscription(dittoPointer, queryBuffer, queryArgsCBOR)
+  throwOnErrorResult(result.error, 'dittoffi_try_remove_sync_subscription')
   return
 }
 
@@ -560,7 +569,7 @@ export function dqlResponseFree(responsePointer: Pointer<FFIDqlResponse>) {
   trace()
   ensureInitialized()
 
-  dittoCore.ditto_dql_response_free(responsePointer)
+  dittoCore.dittoffi_query_result_free(responsePointer)
 }
 
 /**
@@ -572,7 +581,7 @@ export function dqlResultFree(resultPointer: Pointer<FFIDqlResult>) {
   trace()
   ensureInitialized()
 
-  dittoCore.ditto_dql_result_free(resultPointer)
+  dittoCore.dittoffi_query_result_item_free(resultPointer)
 }
 
 /**
@@ -584,9 +593,9 @@ export function dqlResponseResults(responsePointer: Pointer<FFIDqlResponse>): Po
   ensureInitialized()
 
   const rv = []
-  const resultCount = dittoCore.ditto_dql_response_result_count(responsePointer)
+  const resultCount = dittoCore.dittoffi_query_result_item_count(responsePointer)
   for (let i = 0; i < resultCount; i++) {
-    rv.push(dittoCore.ditto_dql_response_result_at(responsePointer, i))
+    rv.push(dittoCore.dittoffi_query_result_item_at(responsePointer, i))
   }
   return rv
 }
@@ -601,9 +610,9 @@ export function dqlMutatedDocumentIDs(responsePointer: Pointer<FFIDqlResponse>):
   ensureInitialized()
 
   const rv = []
-  const resultCount = dittoCore.ditto_dql_response_affected_document_id_count(responsePointer)
+  const resultCount = dittoCore.dittoffi_query_result_mutated_document_id_count(responsePointer)
   for (let i = 0; i < resultCount; i++) {
-    const cborBytes = dittoCore.ditto_dql_response_affected_document_id_at(responsePointer, i)
+    const cborBytes = dittoCore.dittoffi_query_result_mutated_document_id_at(responsePointer, i)
     rv.push(dittoCore.boxCBytesIntoBuffer(cborBytes))
   }
   return rv
@@ -624,7 +633,7 @@ export function dqlResultCBOR(resultPointer: Pointer<FFIDqlResult>): Uint8Array
   trace()
   ensureInitialized()
 
-  const cborBytes = dittoCore.ditto_result_cbor(resultPointer)
+  const cborBytes = dittoCore.dittoffi_query_result_item_cbor(resultPointer)
   return dittoCore.boxCBytesIntoBuffer(cborBytes)
 }
 
@@ -641,7 +650,7 @@ export function dqlResultJSON(resultPointer: Pointer<FFIDqlResult>): string {
   trace()
   ensureInitialized()
 
-  const jsonBytes = dittoCore.ditto_result_json(resultPointer)
+  const jsonBytes = dittoCore.dittoffi_query_result_item_json(resultPointer)
   return dittoCore.boxCStringIntoString(jsonBytes)
 }
 
@@ -741,8 +750,8 @@ export async function tryExperimentalWebhookRegisterDqlLiveQuery(ditto: Pointer<
   const queryBuffer = bytesFromString(query)
   const urlBuffer = bytesFromString(url)
 
-  const result = await dittoCore.dittoffi_try_experimental_webhook_register_dql_live_query_str(ditto, queryBuffer, queryArgsCBOR, urlBuffer)
-  throwOnErrorResult(result.error, 'dittoffi_try_experimental_webhook_register_dql_live_query_str')
+  const result = await dittoCore.dittoffi_try_register_store_observer_webhook(ditto, queryBuffer, queryArgsCBOR, urlBuffer)
+  throwOnErrorResult(result.error, 'dittoffi_try_register_store_observer_webhook')
   const documentIdCBOR = result.success
 
   return dittoCore.boxCBytesIntoBuffer(documentIdCBOR)
@@ -755,6 +764,8 @@ export async function readTransaction(ditto: Pointer<FFIDitto>): Promise<Pointer
   trace()
   ensureInitialized()
 
+  // REFACTOR: add proper error handling.
+
   const { status_code: errorCode, txn: readTransaction } = await dittoCore.ditto_read_transaction(ditto)
   if (errorCode !== 0) throw new Error(errorMessage() || `\`ditto_read_transaction()\` failed with error code: ${errorCode}`)
   return readTransaction
@@ -765,6 +776,7 @@ export function readTransactionFree(self: Pointer<FFIReadTransaction>) {
   trace()
   ensureInitialized()
 
+  // REFACTOR: add proper error handling.
   return dittoCore.ditto_read_transaction_free(self)
 }
 
@@ -775,6 +787,8 @@ export async function writeTransaction(ditto: Pointer<FFIDitto>): Promise<Pointe
   trace()
   ensureInitialized()
 
+  // REFACTOR: add proper error handling.
+
   const { status_code: errorCode, txn: writeTransaction } = await dittoCore.ditto_write_transaction(ditto, null)
   if (errorCode !== 0) throw new Error(errorMessage() || `ditto_write_transaction() failed with error code: ${errorCode}`)
   return writeTransaction
@@ -1060,18 +1074,12 @@ export async function dittoAuthClientLogout(ditto: Pointer<FFIDitto>) {
 // ---------------------------------------------------------------- Ditto ------
 
 /** @internal */
-export function uninitializedDittoMake(path: string): Pointer<FFIUninitializedDitto> {
+export function dittoMake(path: string, identityConfig: Pointer<FFIIdentityConfig>, historyTracking: string): Pointer<FFIDitto> {
   trace()
   ensureInitialized()
-  const pathX = bytesFromString(path)
-  return dittoCore.ditto_uninitialized_ditto_make(pathX)
-}
 
-/** @internal */
-export function dittoMake(uninitializedDitto: Pointer<FFIUninitializedDitto>, identityConfig: Pointer<FFIIdentityConfig>): Pointer<FFIDitto> {
-  trace()
-  ensureInitialized()
-  return dittoCore.ditto_make(uninitializedDitto, identityConfig, 'Disabled')
+  const pathPointer = bytesFromString(path)
+  return dittoCore.ditto_make(pathPointer, identityConfig, historyTracking)
 }
 
 /** @internal */
@@ -1093,6 +1101,7 @@ export function dittoFree(self: Pointer<FFIDitto>) {
   trace()
   ensureInitialized()
 
+  // REFACTOR: add proper error handling.
   return dittoCore.ditto_free(self)
 }
 
@@ -1255,6 +1264,7 @@ export function dittoSetDeviceName(dittoPointer: Pointer<FFIDitto>, deviceName:
 
   if (Environment.isWebBuild) {
     if (deviceNameCString.length > 64) {
+  
       const sanitizedDeviceName = deviceName.replace(/[^ -~]+/g, '')
       deviceNameCString = bytesFromString(sanitizedDeviceName.substr(0, 63))
 
@@ -1301,7 +1311,7 @@ export function dittoNewAttachmentFromFile(ditto: Pointer<FFIDitto>, sourcePath:
   const outAttachment: any = {}
   const errorCode = dittoCore.ditto_new_attachment_from_file(ditto, sourcePathCString, fileOperation, outAttachment)
   if (errorCode !== 0) {
-    throw new Error(errorMessage() || `ditto_new_attachment_from_file() failed with error code: ${errorCode}`)
+    throw new DittoFFIError(errorCode, null, `ditto_new_attachment_from_file() failed with error code: ${errorCode}`)
   }
   return outAttachment
 }
@@ -1314,12 +1324,15 @@ export async function dittoNewAttachmentFromBytes(ditto: Pointer<FFIDitto>, byte
   const outAttachment: any = {}
   const errorCode = await dittoCore.ditto_new_attachment_from_bytes(ditto, bytes, outAttachment)
   if (errorCode !== 0) {
-    throw new Error(errorMessage() || `ditto_new_attachment_from_bytes() failed with error code: ${errorCode}`)
+    throw new DittoFFIError(errorCode, null, `ditto_new_attachment_from_bytes() failed with error code: ${errorCode}`)
   }
   return outAttachment
 }
 
-/** @internal */
+/**
+ * @throws {@link DittoFFIError}
+ * @internal
+ */
 export async function dittoResolveAttachment(
   ditto: Pointer<FFIDitto>,
   id: Uint8Array,
@@ -1337,14 +1350,16 @@ export async function dittoResolveAttachment(
 
   const { onComplete, onProgress, onDelete } = namedCallbacks
   const { status_code: errorCode, cancel_token: cancelToken } = await dittoCore.ditto_resolve_attachment(ditto, id, wrapBackgroundCbForFFI(onError, onComplete), wrapBackgroundCbForFFI(onError, onProgress), wrapBackgroundCbForFFI(onError, onDelete))
+
   if (errorCode !== 0) {
-    throw new Error(errorMessage() || `ditto_resolve_attachment() failed with error code: ${errorCode}`)
+    throw new DittoFFIError(errorCode, null, `ditto_resolve_attachment() failed with error code: ${errorCode}`)
   }
+
   return cancelToken
 }
 
 /** @internal */
-export function dittoCancelResolveAttachment(dittoPointer: Pointer<FFIDitto>, id: Uint8Array, cancelToken: any) {
+export function dittoCancelResolveAttachment(dittoPointer: Pointer<FFIDitto>, id: Uint8Array, cancelToken: number | BigInt) {
   trace()
   ensureInitialized()
 
@@ -1552,6 +1567,25 @@ export function documentsHashMnemonic(documents: Pointer<FFIDocument>[]): string
   return dittoCore.boxCStringIntoString(c_string)
 }
 
+// ------------------------------------------------------------- base64 --------
+
+/** @internal */
+export function base64encode(bytes: Uint8Array, paddingMode: Base64PaddingMode): string {
+  const base64CString = dittoCore.dittoffi_base64_encode(bytes, paddingMode)
+  return dittoCore.boxCStringIntoString(base64CString)
+}
+
+/**
+ * @throws {@link DittoFFIError} if the base64 string is invalid
+ * @internal
+ */
+export function tryBase64Decode(base64: string, paddingMode?: Base64PaddingMode): Uint8Array {
+  const base64BytesPointer = bytesFromString(base64)
+  const result = dittoCore.dittoffi_try_base64_decode(base64BytesPointer, paddingMode || null)
+  throwOnErrorResult(result.error, 'dittoffi_try_base64_decode')
+  return dittoCore.boxCBytesIntoBuffer(result.success)
+}
+
 // ------------------------------------------------------------- Auth ----------
 
 /** @internal */
@@ -1664,12 +1698,10 @@ export function transportsInit(): void {
   trace()
   ensureInitialized()
 
-  const transportsErrorPointer = dittoCore.ditto_sdk_transports_error_new()
-  const wasInitialized = dittoCore.ditto_sdk_transports_init(transportsErrorPointer)
-
-  const errorType: TransportsError = dittoCore.ditto_sdk_transports_error_value(transportsErrorPointer)
-  dittoCore.ditto_sdk_transports_error_free(transportsErrorPointer)
+  // The symbols called below are not exported in the Wasm build.
+  if (Environment.isWebBuild) return
 
+  const { output: wasInitialized, errorType } = withTransportsError(dittoCore.ditto_sdk_transports_init)
   if (wasInitialized === false) {
     throw new Error(`Failed to initialize transports (${errorType} error)`)
   }
@@ -1680,7 +1712,10 @@ export function transportsBLEIsAvailable(ditto: Pointer<FFIDitto>): boolean {
   trace()
   ensureInitialized()
 
-  return dittoCore.ditto_sdk_transports_ble_is_available(ditto)
+  if (Environment.isNodeBuild) {
+    return dittoCore.ditto_sdk_transports_ble_is_available(ditto)
+  }
+  return false
 }
 
 /** @internal */
@@ -1688,19 +1723,17 @@ export function transportsBLECreate(ditto: Pointer<FFIDitto>): Pointer<Transport
   trace()
   ensureInitialized()
 
-  const transportsErrorPointer = dittoCore.ditto_sdk_transports_error_new()
-  const blePointer: Pointer<TransportBluetooth> = dittoCore.ditto_sdk_transports_ble_create(ditto, transportsErrorPointer)
+  if (Environment.isNodeBuild) {
+    const { output: blePointer, errorType } = withTransportsError(dittoCore.ditto_sdk_transports_ble_create, ditto)
 
-  const errorType: TransportsError = dittoCore.ditto_sdk_transports_error_value(transportsErrorPointer)
-  dittoCore.ditto_sdk_transports_error_free(transportsErrorPointer)
+    if (blePointer != null) {
+      log('Info', `Bluetooth transport created.`)
+    } else {
+      log('Error', `Can't create bluetooth transport (${errorType} error).`)
+    }
 
-  if (blePointer != null) {
-    log('Info', `Bluetooth transport created.`)
-  } else {
-    log('Error', `Can't create bluetooth transport (${errorType} error).`)
+    return blePointer
   }
-
-  return blePointer
 }
 
 /** @internal */
@@ -1708,18 +1741,16 @@ export function transportsBLEDestroy(ble: Pointer<TransportBluetooth>): boolean
   trace()
   ensureInitialized()
 
-  const ffiError = dittoCore.ditto_sdk_transports_error_new()
-  const wasDestroyed = dittoCore.ditto_sdk_transports_ble_destroy(ble, ffiError)
-
-  const errorType: TransportsError = dittoCore.ditto_sdk_transports_error_value(ffiError)
-  dittoCore.ditto_sdk_transports_error_free(ffiError)
+  if (Environment.isNodeBuild) {
+    const { output: wasDestroyed, errorType } = withTransportsError(dittoCore.ditto_sdk_transports_ble_destroy, ble)
 
-  if (wasDestroyed === true) {
-    log('Info', 'Bluetooth transport disabled.')
-  } else {
-    log('Error', `Bluetooth transport could not be disabled (${errorType} error).`)
+    if (wasDestroyed === true) {
+      log('Info', 'Bluetooth transport disabled.')
+    } else {
+      log('Error', `Bluetooth transport could not be disabled (${errorType} error).`)
+    }
+    return wasDestroyed
   }
-  return wasDestroyed
 }
 
 /** @internal */
@@ -1727,7 +1758,10 @@ export function transportsLANIsAvailable(ditto: Pointer<FFIDitto>): boolean {
   trace()
   ensureInitialized()
 
-  return dittoCore.ditto_sdk_transports_lan_is_available(ditto)
+  if (Environment.isNodeBuild) {
+    return dittoCore.ditto_sdk_transports_lan_is_available(ditto)
+  }
+  return false
 }
 
 /** @internal */
@@ -1735,19 +1769,17 @@ export function transportsLANCreate(ditto: Pointer<FFIDitto>): Pointer<Transport
   trace()
   ensureInitialized()
 
-  const transportsErrorPointer = dittoCore.ditto_sdk_transports_error_new()
-  const lanPointer: Pointer<TransportLAN> = dittoCore.ditto_sdk_transports_lan_create(ditto, transportsErrorPointer)
+  if (Environment.isNodeBuild) {
+    const { output: lanPointer, errorType } = withTransportsError(dittoCore.ditto_sdk_transports_lan_create, ditto)
 
-  const errorType: TransportsError = dittoCore.ditto_sdk_transports_error_value(transportsErrorPointer)
-  dittoCore.ditto_sdk_transports_error_free(transportsErrorPointer)
+    if (lanPointer != null) {
+      log('Info', `LAN transport created.`)
+    } else {
+      log('Error', `Can't create LAN transport (${errorType} error).`)
+    }
 
-  if (lanPointer != null) {
-    log('Info', `LAN transport created.`)
-  } else {
-    log('Error', `Can't create LAN transport (${errorType} error).`)
+    return lanPointer
   }
-
-  return lanPointer
 }
 
 /** @internal */
@@ -1755,18 +1787,16 @@ export function transportsLANDestroy(lan: Pointer<TransportLAN>): boolean | void
   trace()
   ensureInitialized()
 
-  const ffiError = dittoCore.ditto_sdk_transports_error_new()
-  const wasDestroyed = dittoCore.ditto_sdk_transports_lan_destroy(lan, ffiError)
-
-  const error: TransportsError = dittoCore.ditto_sdk_transports_error_value(ffiError)
-  dittoCore.ditto_sdk_transports_error_free(ffiError)
+  if (Environment.isNodeBuild) {
+    const { output: wasDestroyed, errorType } = withTransportsError(dittoCore.ditto_sdk_transports_lan_destroy, lan)
 
-  if (wasDestroyed === true) {
-    log('Info', 'LAN transport disabled.')
-  } else {
-    log('Error', `LAN transport could not be disabled (${error} error).`)
+    if (wasDestroyed === true) {
+      log('Info', 'LAN transport disabled.')
+    } else {
+      log('Error', `LAN transport could not be disabled (${errorType} error).`)
+    }
+    return wasDestroyed
   }
-  return wasDestroyed
 }
 
 /** @internal */
@@ -1774,7 +1804,10 @@ export function transportsAWDLIsAvailable(ditto: Pointer<FFIDitto>): boolean {
   trace()
   ensureInitialized()
 
-  return dittoCore.ditto_sdk_transports_awdl_is_available(ditto)
+  if (Environment.isNodeBuild) {
+    return dittoCore.ditto_sdk_transports_awdl_is_available(ditto)
+  }
+  return false
 }
 
 /** @internal */
@@ -1782,19 +1815,17 @@ export function transportsAWDLCreate(ditto: Pointer<FFIDitto>): Pointer<Transpor
   trace()
   ensureInitialized()
 
-  const transportsErrorPointer = dittoCore.ditto_sdk_transports_error_new()
-  const awdlPointer: Pointer<TransportAWDL> = dittoCore.ditto_sdk_transports_awdl_create(ditto, transportsErrorPointer)
+  if (Environment.isNodeBuild) {
+    const { output: awdlPointer, errorType } = withTransportsError(dittoCore.ditto_sdk_transports_awdl_create, ditto)
 
-  const errorType: TransportsError = dittoCore.ditto_sdk_transports_error_value(transportsErrorPointer)
-  dittoCore.ditto_sdk_transports_error_free(transportsErrorPointer)
+    if (awdlPointer != null) {
+      log('Info', `AWDL transport created.`)
+    } else {
+      log('Error', `Can't create AWDL transport (${errorType} error).`)
+    }
 
-  if (awdlPointer != null) {
-    log('Info', `AWDL transport created.`)
-  } else {
-    log('Error', `Can't create AWDL transport (${errorType} error).`)
+    return awdlPointer
   }
-
-  return awdlPointer
 }
 
 /** @internal */
@@ -1802,18 +1833,48 @@ export function transportsAWDLDestroy(awdl: Pointer<TransportAWDL>): boolean | v
   trace()
   ensureInitialized()
 
-  const ffiError = dittoCore.ditto_sdk_transports_error_new()
-  const wasDestroyed = dittoCore.ditto_sdk_transports_awdl_destroy(awdl, ffiError)
-
-  const errorType: TransportsError = dittoCore.ditto_sdk_transports_error_value(ffiError)
-  dittoCore.ditto_sdk_transports_error_free(ffiError)
+  if (Environment.isNodeBuild) {
+    const { output: wasDestroyed, errorType } = withTransportsError(dittoCore.ditto_sdk_transports_awdl_destroy, awdl)
 
-  if (wasDestroyed === true) {
-    log('Info', 'AWDL transport disabled.')
-  } else {
-    log('Error', `AWDL transport could not be disabled (${errorType} error).`)
+    if (wasDestroyed === true) {
+      log('Info', 'AWDL transport disabled.')
+    } else {
+      log('Error', `AWDL transport could not be disabled (${errorType} error).`)
+    }
+    return wasDestroyed
   }
-  return wasDestroyed
+}
+
+/**
+ * Helper type that extracts all but the last parameter from a function type.
+ *
+ * NOTE: will accept any parameters for functions that don't have typed parameters.
+ */
+// prettier-ignore
+type ParametersExceptLast<F extends (...args: any[]) => any> = Parameters<F> extends [...infer U, any]
+  ? U
+  : any // FIXME: this should really be `never` but we don't have proper types for the FFI functions yet.
+
+/**
+ * Calls the given FFI function with the passed in arguments and a newly
+ * allocated `transportsErrorPointer` as the last argument, then returns its
+ * result.
+ *
+ * The given function MUST take a `transportsErrorPointer` as its last argument.
+ *
+ * @param ffiFunction The FFI function to wrap.
+ * @param args The arguments to pass to the FFI function, excluding the
+ * `transportsErrorPointer`.
+ * @returns An object with two properties: `output` and `errorType`. `output` is
+ * the return value of the FFI function, and `errorType` is the value of the
+ * `transportsErrorPointer` after the FFI function has been called.
+ */
+function withTransportsError<T extends (...args: any[]) => any>(ffiFunction: T, ...args: ParametersExceptLast<T>): { output: ReturnType<T>; errorType: TransportsError } {
+  const transportsErrorPointer = dittoCore.ditto_sdk_transports_error_new()
+  const output = ffiFunction(...args, transportsErrorPointer)
+  const errorType: TransportsError = dittoCore.ditto_sdk_transports_error_value(transportsErrorPointer)
+  dittoCore.ditto_sdk_transports_error_free(transportsErrorPointer)
+  return { output, errorType }
 }
 
 // ---------------------------------------------------------------- Other ------
@@ -1902,8 +1963,25 @@ export function createDirectory(path: string): string | void {
   }
 }
 
+/** @internal */
+export function readFile(path: string): string {
+  if (Environment.isReactNativeBuild) {
+    // @ts-expect-error Throws method not-found on non-RN envs.
+    return dittoCore.readFile(path)
+  }
+}
+
+/** @internal */
+export function copyFile(source: string, destination: string, dittoPath: string): string {
+  if (Environment.isReactNativeBuild) {
+    // @ts-expect-error Throws method not-found on non-RN envs.
+    return dittoCore.copyFile(source, destination, dittoPath)
+  }
+}
+
 // -------------------------------------------------------------- Private ------
 
+
 /** @internal */
 const NOT_FOUND_ERROR_CODE = -30798
 

package/react-native/src/sources/internal.ts

@@ -82,14 +82,32 @@ export function validateQuery(query, options = {}): string {
 export function generateEphemeralToken(): string {
 
   let data = new Uint16Array(16)
-  // Note: Replacing conditional with polymorphism. (#10731)
-
-  data = FFI.getRandomValues(data) as Uint16Array
+  if (Environment.isReactNativeBuild) {
+    data = FFI.getRandomValues(data) as Uint16Array
+  } else {
+    throw new Error('Internal inconsistency, incorrect environment to run getRandomValues()')
+  }
 
   const doublets = Array.from(data)
   return doublets.map((doublet) => doublet.toString(16)).join('')
 }
 
+/**
+ * Can be used to implement a custom Node.js `inspect` representation for
+ * objects that have a `value` property.
+ *
+ * Node.js < 16.14.0 and Electron < 19.0.0 do not provide the `inspect`
+ * parameter used below, which is when we fall back to `JSON.stringify`.
+ *
+ * See https://nodejs.org/api/util.html#custom-inspection-functions-on-objects
+ */
+export function customInspectRepresentation(documentLike: { value: any }, inspect?: any): string {
+  if (inspect === undefined) {
+    return `${documentLike.constructor.name} ${JSON.stringify({ value: documentLike.value }, null, 2)}`
+  }
+  return `${documentLike.constructor.name} ${inspect({ value: documentLike.value })}`
+}
+
 // --------------------------------------------------------------- System ------
 
 /** @internal */
@@ -106,4 +124,20 @@ export async function step<T>(closure: () => T): Promise<T> {
 }
 
 /** @internal */
+// WORKAROUND: the corresponding FFI function(s) is not async at the
+// moment, we therefore artificially make it async via step() until an
+// async variant becomes available.
+//
+// Why? Any function marked as async that isn't under the hood appears to be
+// yield-ing on the use site but isn't. This may lead to blocking the
+// event loop for a long time, which in turn can lead to excessive memory
+// consumption and other side-effects. Plus, WebAssembly limitations may
+// lead to deadlocks and other crashes.
+//
+// The function alias here is to be able to easily see that its use is
+// a workaround, plus easily finding all of those workarounds to fix
+// them all once the FFI API is properly asyncified.
+//
+// See PR #4833 for details:
+// https://github.com/getditto/ditto/pull/4833
 export const performAsyncToWorkaroundNonAsyncFFIAPI = step

package/react-native/src/sources/live-query-manager.ts

@@ -26,7 +26,16 @@ export class LiveQueryManager {
   startLiveQuery(liveQuery: LiveQuery) {
     const ditto = this.ditto
     const dittoHandle = Bridge.ditto.handleFor(ditto)
-    
+
+    // REFACTOR: the starting closure runs detached from here which is a smell.
+    // Can we make this whole starting mechanism non-async? The culprit is
+    // the workaround for a zalgo with `ditto_live_query_start()` FFI function:
+    // It immediately triggers the live query handler making it run "in-line"
+    // when creating a live query, while subsequent invocations are async
+    // (by definition). This is a classic zalgo case. Fix by making
+    // `ditto_live_query_start()` trigger the first live query callback `async`,
+    // just like the subsequent ones.
+
     ditto.deferCloseAsync(async () => {
       const liveQueryID = liveQuery.liveQueryID
       if (!liveQueryID) {

package/react-native/src/sources/live-query.ts

@@ -5,11 +5,11 @@
 import * as FFI from './ffi'
 
 import { Bridge } from './bridge'
-import { Collection } from './collection'
 
 import { LiveQueryEventInitial } from './live-query-event'
 import { LiveQueryEventUpdate } from './live-query-event'
 
+import type { Collection } from './collection'
 import type { QueryArguments } from './essentials'
 import type { LiveQueryEvent } from './live-query-event'
 import type { LiveQueryManager } from './live-query-manager'