@dittolive/ditto 4.5.1 → 4.5.2-rc.2

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

@@ -2,6 +2,14 @@
 // Copyright © 2023 DittoLive Incorporated. All rights reserved.
 //
 
+// NOTE: This is a temporary *hand-written* shim file for glue code for the
+// Ditto native Node module. Mid to long term, we'll either move all of this
+// code to the native side or generate this file via a companion CLI tool or
+// something equivalent.
+//
+// IMPORTANT: please leave this file self-contained and do not import any
+// sources from the JS SDK.
+
 import * as dittoCore from './@ditto.core'
 import * as Environment from './@environment'
 import { throwOnErrorResult } from './ffi-error'
@@ -162,6 +170,7 @@ export type WebAssemblyModule = RequestInfo | URL | Response | BufferSource | We
 export type AttachmentFileOperation = 'Copy' | 'Move'
 
 /** @internal */
+// IDEA: rename to AttachmentHandleType for consistency.
 export type AttachmentHandle = 'AttachmentHandle_t'
 
 /** @internal */
@@ -171,7 +180,7 @@ export type RawAttachment = {
   handle: Pointer<AttachmentHandle>
 }
 
-// -------------------------------------- Linux & Windows Transports Hack ------
+// -------------------------------------- Linux & Windows Transports ------
 
 export function dittoAddInternalBLEClientTransport(ditto: Pointer<FFIDitto>): any {
   if (Environment.isNodeBuild) {
@@ -270,6 +279,7 @@ export function documentSetCBOR(document: Pointer<FFIDocument>, path: string, cb
   trace()
   ensureInitialized()
 
+  // NOTE: not sure if this should be async or not.
   const pathX = bytesFromString(path)
   const errorCode = dittoCore.ditto_document_set_cbor(document, pathX, cbor)
   if (errorCode !== 0) throw new Error(errorMessage() || `ditto_document_set_cbor() failed with error code: ${errorCode}`)
@@ -647,6 +657,8 @@ export function liveQueryRegister(
   limit: number,
   offset: number,
   eventHandler: (cbParams: CBParamsDocs) => any,
+  // Cb may be called in parallel at any point, so let's use
+  // an optional error handler (which defaults to the ditto logger at 'Error' level).
   onError?: (error: any) => void,
 ): number {
   trace()
@@ -654,6 +666,10 @@ export function liveQueryRegister(
 
   const collectionNameBuffer = bytesFromString(collectionName)
   const queryBuffer = bytesFromString(query)
+  // Note(Daniel): the callback is now registered to be called in a detached
+  // manner: if the FFI / Rust does `cb()`, then when that call returns, the js
+  // callback itself may not have completed. This is fine, since `signalNext()`
+  // shall be the proper way to let the Rust core know the FFI call completed.
   const { status_code: errorCode, i64: id } = dittoCore.ditto_live_query_register_str_detached(ditto, collectionNameBuffer, queryBuffer, queryArgsCBOR, orderBy, limit, offset, wrapBackgroundCbForFFI(onError, eventHandler))
   if (errorCode !== 0) throw new Error(errorMessage() || `\`ditto_live_query_register_str()\` failed with error code: ${errorCode}`)
   return id
@@ -667,6 +683,10 @@ export function tryExperimentalRegisterChangeObserver(ditto: Pointer<FFIDitto>,
   const errorHandler = (err: any) => log('Error', `The registered store observer callback failed with ${err}`)
   const wrappedCallback = wrapBackgroundCbForFFI(errorHandler, changeHandler)
   const queryBuffer = bytesFromString(query)
+  // Note(Daniel): the callback is registered to be called in a detached manner:
+  // if the FFI / Rust does `cb()`, then when that call returns, the js callback
+  // itself may not have completed. This is fine, since `signalNext()` shall be
+  // the proper way to let the Rust core know the FFI call completed.
   const result = dittoCore.dittoffi_try_experimental_register_change_observer_str_detached(ditto, queryBuffer, queryArgsCBOR, wrappedCallback)
   throwOnErrorResult(result.error, 'dittoffi_try_experimental_register_change_observer_str_detached')
   return result.success
@@ -735,7 +755,6 @@ export async function readTransaction(ditto: Pointer<FFIDitto>): Promise<Pointer
   trace()
   ensureInitialized()
 
-
   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
@@ -756,7 +775,6 @@ export async function writeTransaction(ditto: Pointer<FFIDitto>): Promise<Pointe
   trace()
   ensureInitialized()
 
-
   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
@@ -832,6 +850,7 @@ export async function loggerSetCustomLogCb(cb: null | ((lvl: LogLevel, msg: stri
   if (null === cb) {
     await dittoCore.ditto_logger_set_custom_log_cb(null)
   } else {
+    // IDEA: pass custom error handler here instead of null?
     const wrappedCallback = wrapBackgroundCbForFFI(null, (loglevel: LogLevel, cMsg: Pointer<'char'>) => {
       try {
         const msg: string = dittoCore.boxCStringIntoString(cMsg)
@@ -1045,7 +1064,7 @@ export function uninitializedDittoMake(path: string): Pointer<FFIUninitializedDi
   trace()
   ensureInitialized()
   const pathX = bytesFromString(path)
-  return dittoCore.uninitialized_ditto_make(pathX)
+  return dittoCore.ditto_uninitialized_ditto_make(pathX)
 }
 
 /** @internal */
@@ -1236,10 +1255,15 @@ 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))
 
+      // NOTE: to reproduce the issue, comment the following two in. You'll see
+      // that an ASCII string of 64 characters and more will make prevent sync
+      // from working.
+      //
+      // const demoDeviceName = "123456789-10-456789-20-456789-30-456789-40-456789-50-456789-60-4" //56789-70-456789-80-456789-90-456789" // 100
+      // deviceNameCString = bytesFromString(demoDeviceName)
     }
   }
 
@@ -1251,7 +1275,9 @@ export function dittoSetConnectRetryInterval(dittoPointer: Pointer<FFIDitto>, re
   trace()
   ensureInitialized()
 
+  // Unfortunately JS doesn't have a u32::MAX const...
   const UINT32_MAX = 4_294_967_295
+  // Clamp the provided interval to u32 range (0 .. 2^32-1).
   const clampedInterval = Math.min(Math.max(0, retryInterval), UINT32_MAX)
 
   return dittoCore.ditto_set_connect_retry_interval(dittoPointer, clampedInterval)
@@ -1265,6 +1291,7 @@ export function dittoSetSyncGroup(dittoPointer: Pointer<FFIDitto>, syncGroup: nu
   return dittoCore.ditto_set_sync_group(dittoPointer, syncGroup)
 }
 
+// Not supported on Wasm.
 /** @internal */
 export function dittoNewAttachmentFromFile(ditto: Pointer<FFIDitto>, sourcePath: string, fileOperation: AttachmentFileOperation): RawAttachment {
   trace()
@@ -1301,6 +1328,8 @@ export async function dittoResolveAttachment(
     onProgress: (downloaded: number | BigInt, toDownload: number | BigInt) => void
     onDelete: () => void
   },
+  // Cb may be called in parallel at any point, so let's use
+  // an optional error handler (which defaults to the ditto logger at 'Error' level).
   onError?: (error: any) => void,
 ): Promise<number | BigInt> {
   trace()
@@ -1483,14 +1512,12 @@ export function dittoSetStaticTCPClients(ditto: Pointer<FFIDitto>, listOfServers
   trace()
   ensureInitialized()
 
-
   if (Environment.isNodeBuild) {
     const listOfServersBytes = listOfServers.map((server) => bytesFromString(server))
     dittoCore.ditto_set_static_tcp_clients(ditto, listOfServersBytes)
   }
 
   if (Environment.isWebBuild) {
-
     if (listOfServers.length > 0) {
       throw new Error(`Web variant of Ditto does not support connecting to TCP servers: ${listOfServers.join(', ')}`)
     }
@@ -1512,6 +1539,7 @@ export function documentsHash(documents: Pointer<FFIDocument>[]): BigInt {
   ensureInitialized()
   const { status_code: errorCode, u64: hash } = dittoCore.ditto_documents_hash(documents)
   if (errorCode !== 0) throw new Error(errorMessage() || `\`ditto_documents_hash()\` failed with error code: ${errorCode}`)
+  // `hash` is of type `number | BigInt`, let's unify it to `BigInt` to keep it simple.
   return BigInt(hash)
 }
 
@@ -1569,6 +1597,8 @@ export function dittoRegisterLocalAuthServer(namedArgs: {
   caKeyPem?: string
   authCb: (authRequest: Pointer<FFIAuthServerAuthRequest>, cbor: Uint8Array) => void
   refreshCb: (authRequest: Pointer<FFIAuthServerRefreshRequest>, cbor: Uint8Array) => void
+  // Cb may be called in parallel at any point, so let's use
+  // an optional error handler
   onError?: (error: any) => void
 }): void {
   const { ditto, signingKeyPem, verifyingKeysPem, caKeyPem, authCb, refreshCb, onError } = namedArgs
@@ -1594,6 +1624,7 @@ export async function dittoAuthSetLoginProvider(ditto: Pointer<FFIDitto>, loginP
 /** @internal */
 export function dittoAuthClientMakeLoginProvider(
   expiringCb: (secs_until_expiry: number) => void,
+  // Cb may be called in parallel at any point, so let's use an optional error handler
   onError?: (error: any) => void,
 ): Pointer<FFILoginProvider> {
   trace()
@@ -1606,6 +1637,7 @@ export function dittoAuthClientMakeLoginProvider(
 export function dittoAuthClientSetValidityListener(
   ditto: Pointer<FFIDitto>,
   validityUpdateCb: (isWebValid: boolean, isX509Valid: boolean) => void,
+  // Cb may be called in parallel at any point, so let's use an optional error handler
   onError?: (error: any) => void,
 ): void {
   trace()
@@ -1836,7 +1868,7 @@ export function verifyLicense(license: string): { result: LicenseVerificationRes
   const licenseBuffer = bytesFromString(license)
   let result: LicenseVerificationResult
   const errorMessageCString = withOutPtr('char *', (outErrorMessage) => {
-    result = dittoCore.verify_license(licenseBuffer, outErrorMessage)
+    result = dittoCore.ditto_verify_license(licenseBuffer, outErrorMessage)
     return outErrorMessage
   })
 
@@ -1849,6 +1881,7 @@ export function verifyLicense(license: string): { result: LicenseVerificationRes
 /** @internal */
 export function getDeviceName(): string | void {
   if (Environment.isReactNativeBuild) {
+    // @ts-expect-error Throws method not-found on non-RN envs.
     return dittoCore.getDeviceName()
   }
 }
@@ -1856,6 +1889,7 @@ export function getDeviceName(): string | void {
 /** @internal */
 export function getRandomValues<T extends ArrayBufferView>(array: T): T | void {
   if (Environment.isReactNativeBuild) {
+    // @ts-expect-error Throws method not-found on non-RN envs.
     return dittoCore.getRandomValues(array)
   }
 }
@@ -1863,6 +1897,7 @@ export function getRandomValues<T extends ArrayBufferView>(array: T): T | void {
 /** @internal */
 export function createDirectory(path: string): string | void {
   if (Environment.isReactNativeBuild) {
+    // @ts-expect-error Throws method not-found on non-RN envs.
     return dittoCore.createDirectory(path)
   }
 }
@@ -1874,10 +1909,12 @@ const NOT_FOUND_ERROR_CODE = -30798
 
 /** @internal */
 function wrapBackgroundCbForFFI(onError: null | ((err: any) => void), cb: any): any {
-
+  // There's no need to wrap callbacks through JSI while they are not returning
+  // anything.
   if (Environment.isReactNativeBuild) {
     return cb
   }
+  // Basic fallback based off: https://stackoverflow.com/a/3390635
   if (onError === undefined) {
     onError = (err: any) => log('Error', `The registered callback failed with ${err}`)
   }
@@ -1950,16 +1987,19 @@ function errorMessage(): string {
 /** @internal */
 function trace() {
   if (isTracingEnabled) {
-
+    // Copied and adapted from a Stack Overflow comment:
+    // https://stackoverflow.com/a/38435618
     const error = new Error()
     const stack = error.stack
     let caller = '<unknown>'
     try {
       caller = stack.split('\n')[2].trim().split(/\s+/)[1].replace('Module.', '')
     } catch (error) {
+      // Nothing to do, caller remains unknown.
     }
 
-
+    // We use use `console.log()` instead of `log()` here to avoid infinite recursion.
+    // eslint-disable-next-line no-console
     console.log(`💗 [TRACE] ${caller}()`)
   }
 }

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

@@ -33,7 +33,8 @@ export type InitOptions = {
 export async function init(options: InitOptions = {}): Promise<void> {
   if (!isInitialized) {
     if (Environment.isWebBuild) {
-
+      // IDEA: throw or log a warning if init() was called a second time with
+      // different options (because those wouldn't have any effect).
 
       const webAssemblyModule = options.webAssemblyModule || defaultDittoWasmFileURL
 

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

@@ -80,14 +80,11 @@ export function validateQuery(query, options = {}): string {
  *
  * @internal */
 export function generateEphemeralToken(): string {
-  let webcrypto = undefined
 
   let data = new Uint16Array(16)
-  if (Environment.isReactNativeBuild) {
-    data = FFI.getRandomValues(data) as Uint16Array
-  } else {
-    throw new Error('Internal inconsistency, incorrect environment to run getRandomValues()')
-  }
+  // Note: Replacing conditional with polymorphism. (#10731)
+
+  data = FFI.getRandomValues(data) as Uint16Array
 
   const doublets = Array.from(data)
   return doublets.map((doublet) => doublet.toString(16)).join('')
@@ -109,5 +106,4 @@ export async function step<T>(closure: () => T): Promise<T> {
 }
 
 /** @internal */
-
 export const performAsyncToWorkaroundNonAsyncFFIAPI = step

package/react-native/src/sources/keep-alive.ts

@@ -24,7 +24,10 @@ export class KeepAlive {
     this.countsByID[id] += 1
 
     if (this.intervalID === null) {
-      const maxDelay = 2147483647
+      // Keep the process alive as long as there is at least one ID being
+      // tracked by setting a time interval with the maximum delay. This will
+      // prevent the process from exiting.
+      const maxDelay = 2147483647 // Signed 32 bit integer, see docs: https://developer.mozilla.org/en-US/docs/Web/API/setInterval
       this.intervalID = setInterval(() => {
         /* no-op */
       }, maxDelay)
@@ -45,7 +48,8 @@ export class KeepAlive {
     }
 
     if (Object.keys(this.countsByID).length === 0) {
-
+      // Nothing is tracked anymore, it's safe to clear the interval
+      // and let the process do what it wants.
       KeepAlive.finalizationRegistry.unregister(this)
       clearInterval(this.intervalID)
       this.intervalID = null

package/react-native/src/sources/key-path.ts

@@ -123,7 +123,10 @@ export class KeyPath {
         throw new Error(`Can't return value at given keyPath, expected keyPath to be a string or a number but got ${typeof keyPath}: ${keyPath}`)
       }
 
-
+      // NOTE: `nextPathComponentRaw` represents next path component plus all
+      // of its surrounding delimiters, i.e. given a path `["abc"].blah.blub`,
+      // `nextPathComponentRaw` would be `["abc"]` while nextPathComponent
+      // would just yield 'abc'.
 
       const regularKeyMatch = keyPath.match(regularKeyRegExp)
       if (regularKeyMatch !== null) {

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

@@ -26,9 +26,7 @@ export class LiveQueryManager {
   startLiveQuery(liveQuery: LiveQuery) {
     const ditto = this.ditto
     const dittoHandle = Bridge.ditto.handleFor(ditto)
-
-
-
+    
     ditto.deferCloseAsync(async () => {
       const liveQueryID = liveQuery.liveQueryID
       if (!liveQueryID) {
@@ -48,9 +46,12 @@ export class LiveQueryManager {
       ditto.keepAlive.retain(`LiveQuery.${liveQueryID}`)
 
       return new Promise((resolve, reject) => {
-
+        // not awaited on purpose; let the invocation of the initial observation
+        // happen in a "fire-and-forget" / detached / escaping fashion, to be
+        // consistent with the subsequent invocations.
         step(async () => {
           await FFI.liveQueryStart(dittoHandle.deref(), liveQueryID)
+          // @ts-ignore
           resolve()
         })
       })

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

@@ -89,6 +89,7 @@ export class LiveQuery {
 
   /** @internal */
   constructor(query: string, queryArgs: QueryArguments | null, queryArgsCBOR: Uint8Array | null, orderBys: FFI.OrderBy[], limit: number, offset: number, collection: Collection, handler: QueryObservationHandler) {
+    // Query should be validated at this point.
     this.query = query
     this.queryArgs = queryArgs ? Object.freeze({ ...queryArgs }) : null
     this.queryArgsCBOR = queryArgsCBOR
@@ -148,6 +149,7 @@ export class LiveQuery {
 
   /** @internal */
   async signalNext() {
+    // IDEA: make this public?
     const ditto = this.collection.store.ditto
     const dittoHandle = Bridge.ditto.handleFor(ditto)
     const dittoPointer = dittoHandle.derefOrNull()

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

@@ -0,0 +1,60 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+// IMPORTANT: this file is only for exporting public API, please don't
+// add "significant" logic in here (sort of a "Framework Header" in ObjC).
+
+export * from './keep-alive'
+export * from './observer'
+
+export * from './essentials'
+export * from './counter'
+export * from './register'
+export * from './attachment-token'
+
+export * from './init'
+export * from './logger'
+export * from './document-id'
+
+export * from './base-pending-cursor-operation'
+export * from './base-pending-id-specific-operation'
+export * from './authenticator'
+export * from './identity'
+export * from './ditto'
+export * from './store-observer'
+export * from './collection'
+export * from './collection-interface'
+export * from './collections-event'
+export * from './document-path'
+export * from './document'
+export * from './sync'
+export * from './sync-subscription'
+export * from './error'
+export * from './error-codes'
+export * from './query-result-item'
+export * from './query-result'
+export * from './live-query-event'
+export * from './live-query'
+export * from './attachment'
+export * from './attachment-fetcher'
+export * from './attachment-fetch-event'
+export * from './pending-cursor-operation'
+export * from './pending-id-specific-operation'
+export * from './pending-collections-operation'
+export * from './small-peer-info'
+export * from './store'
+export * from './presence'
+export * from './subscription'
+export * from './test-helpers'
+export * from './transport-config'
+export * from './update-result'
+export * from './update-results-map'
+export * from './write-transaction'
+export * from './write-transaction-collection'
+export * from './write-transaction-pending-cursor-operation'
+export * from './write-transaction-pending-id-specific-operation'
+export * from './epilogue'
+
+// TEMPORARY: exported to deal with non-canonical IDs.
+export * from './cbor'

package/react-native/src/sources/observer-manager.ts

@@ -54,7 +54,6 @@ export class ObserverManager {
   /** @internal */
   addObserver(callback: any): ObserverToken {
     if (this.isClosed) {
-
       throw new Error(`Internal inconsistency, can't add '${this.id}' observer, observer mananger close()-ed.`)
     }
 
@@ -80,6 +79,9 @@ export class ObserverManager {
       return
     }
 
+    // The value is set to null to be able to discern between
+    // observers that have been removed and observers that have
+    // never been registered before.
     this.callbacksByToken[token] = null
 
     this.keepAlive?.release(`${this.id}.${token}`)
@@ -93,7 +95,8 @@ export class ObserverManager {
   /** @internal */
   notify(...args: any[]) {
     if (this.isClosed) {
-
+      // NOTE: we don't notify observers after closing and just swallow
+      // the event.
       return
     }
 

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

@@ -22,7 +22,9 @@ export type ObserverOptions = {
  * alive, you have to keep a reference to the corresponding observer.
  */
 export class Observer {
-
+  // NOTE: the core functionality of the observer manager is token-based. We use
+  // the `Observer` class merely as a public API wrapper around the token
+  // exposing a convenience `stop()` method plus life-cycle tracking.
 
   /** @internal */
   readonly observerManager: ObserverManaging

package/react-native/src/sources/pending-id-specific-operation.ts

@@ -88,7 +88,8 @@ export class PendingIDSpecificOperation extends BasePendingIDSpecificOperation {
       const mutableDocument = Bridge.mutableDocument.bridge(documentX, () => new MutableDocument())
       closure(mutableDocument)
 
-
+      // Ownership is transferred back to the FFI layer via collectionUpdate(),
+      // we therefore need to explicitly unregister the instance.
       Bridge.mutableDocument.unregister(mutableDocument)
 
       const writeTransactionX = await FFI.writeTransaction(dittoHandle.deref())
@@ -194,7 +195,8 @@ export class PendingIDSpecificOperation extends BasePendingIDSpecificOperation {
       const totalNumberOfManipulations = event.isInitial === true ? 0 : event.insertions.length + event.deletions.length + event.updates.length
       if (totalNumberOfManipulations > 1) throw new Error(`Internal inconsistency, single document live query returned a combination of inserts, updates, and/or deletes, which doesn't make sense for single document observation. Query ${this.query}.`)
 
-
+      // IDEA: use `undefined` instead of `null` and
+      // adapt Wasm variant plus API definition.
       const document = documents[0] || null
       const oldDocument = event.isInitial === true ? undefined : event.oldDocuments[0]
 

package/react-native/src/sources/presence-manager.ts

@@ -39,7 +39,6 @@ export class PresenceManager {
     this.callbacksByPresenceToken[token] = callback
     this.ditto.keepAlive.retain(`PresenceObservation.${token}`)
 
-
     callback(this.currentRemotePeers)
 
     return token
@@ -125,6 +124,7 @@ export class PresenceManager {
 
   private notify() {
     if (this.isClosed) {
+      // NOTE: we don't notify observers after closing.
       return
     }
 
@@ -148,6 +148,7 @@ export class PresenceManager {
   }
 
   private compareRemotePeers(left: RemotePeer, right: RemotePeer) {
+    // NOTE: we use the exact same sort order here as in the ObjC version.
 
     if (left.connections.length === 0 && right.connections.length > 0) return +1
     if (left.connections.length > 0 && right.connections.length === 0) return -1

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

@@ -189,11 +189,6 @@ export class Presence {
     const observerToken = this.observerManager.addObserver(didChangeHandler)
     const observer = new Observer(this.observerManager, observerToken, { stopsWhenFinalized: true })
 
-    // REFACTOR: make the initial callback call async, too (othewise we'd be
-    // mixing sync with async, which is a bit problematic in general but might
-    // be OK with single-threaded JS). This is a bit tricky, simply
-    // setTimeout(..., 0) here could lead us to a situation where the initial
-    // call would be sent AFTER the regular notification.
     didChangeHandler(this.graph)
 
     return observer

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

@@ -2,7 +2,9 @@
 // Copyright © 2022 DittoLive Incorporated. All rights reserved.
 //
 
-
+// NOTE: we use a token to detect private invocation of the constructor. This is
+// not secure and just to prevent accidental private invocation on the client
+// side.
 const privateToken = '@ditto.ff82dae89821c5ab822a8b539056bce4'
 
 /**
@@ -77,7 +79,8 @@ export class MutableRegister extends Register {
 
     mutableDocument.at(path)['@ditto.set'](value)
 
-
+    // We also set the local value to make sure that the change is
+    // reflected locally as well as in the underlying document.
     this['@ditto.value'] = value
   }
 

package/react-native/src/sources/small-peer-info.ts

@@ -132,6 +132,7 @@ export class SmallPeerInfo {
     }
     const dittoHandle = Bridge.ditto.handleFor(this.ditto)
     this.ditto.deferClose(() => {
+      // throws if any validation errors occur
       FFI.dittoSmallPeerInfoSetMetadata(dittoHandle.deref(), metadata)
     })
   }

package/react-native/src/sources/store-observer.ts

@@ -171,6 +171,7 @@ export class StoreObserver {
   }
 }
 
+// c.f. struct c_cb_params
 type CCallbackParams = {
   query_result: FFI.Pointer<FFI.FFIDqlResponse>
 }

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

@@ -72,8 +72,11 @@ export class Store {
    */
   registerObserver(query: string, observationHandler: StoreObservationHandler, queryArguments?: DQLQueryArguments): StoreObserver {
     const changeHandlerWithSignalNext: StoreObservationHandlerWithSignalNext = (queryResult: QueryResult, signalNext: () => void) => {
-      observationHandler(queryResult)
-      signalNext()
+      try {
+        observationHandler(queryResult)
+      } finally {
+        signalNext()
+      }
     }
     return this.registerObserverWithSignalNext(query, changeHandlerWithSignalNext, queryArguments)
   }
@@ -118,8 +121,15 @@ export class Store {
 
     const storeObserver = new StoreObserver(this.ditto, query, queryArguments ?? null, observationHandler)
 
+    // @ts-expect-error modifying readonly property
     this.observers = Object.freeze([...this.observers, storeObserver])
 
+    // We have two requirements for this step: (1) we want to be able to wait
+    // for the call to FFI to finish while closing ditto and (2) we want to
+    // return from this function without waiting for the call to FFI to finish.
+    // If we would await the call here, we could end up in a situation where
+    // the first callback to the event handler is emitted before we return from
+    // the method call that started the observer.
 
     const dittoHandle = Bridge.ditto.handleFor(this.ditto)
     this.ditto.deferCloseAsync(async () => {
@@ -131,7 +141,8 @@ export class Store {
               async () => await FFI.liveQueryStart(dittoHandle.deref(), storeObserver.liveQueryID)
             )
           } catch (error: any) {
-
+            // As this closure executes after the surrounding method has returned we don't throw
+            // the error here. Instead we log the error.
             Logger.error(`Failed to start live query: ${error.message}`)
           }
           resolve()
@@ -201,6 +212,8 @@ export class Store {
 
     const dittoHandle = Bridge.ditto.handleFor(this.ditto)
     return this.ditto.deferCloseAsync(async () => {
+      // A one-off query execution uses a transaction internally but a
+      // transaction API is not implemented yet.
       const writeTransaction = null
 
       let queryArgumentsCBOR: Uint8Array | null = null
@@ -214,6 +227,7 @@ export class Store {
 
       const errorContext = { query, queryArguments }
 
+      // prettier-ignore
       const responsePointer: FFI.Pointer<FFI.FFIDqlResponse> = await mapFFIErrorsAsync(
         async () => await performAsyncToWorkaroundNonAsyncFFIAPI(
           () => FFI.tryExperimentalExecQueryStr(dittoHandle.deref(), writeTransaction, query, queryArgumentsCBOR)
@@ -235,6 +249,7 @@ export class Store {
    * @returns a list of `WriteTransactionResult`s. There is a result for each operation performed as part of the write transaction.
    */
   async write(callback: (transaction: WriteTransaction) => Promise<void>): Promise<WriteTransactionResult[]> {
+    // Run caller's callback, rolling back if needed.
     return this.ditto.deferCloseAsync(async () => {
       const transaction = await WriteTransaction.init(this.ditto)
 
@@ -287,6 +302,7 @@ export class Store {
     const errorContext = { query, queryArguments }
 
     const dittoHandle = Bridge.ditto.handleFor(this.ditto)
+    // prettier-ignore
     return this.ditto.deferCloseAsync(async () => {
       const webhookIDCBOR = await mapFFIErrorsAsync(
         async () => await FFI.tryExperimentalWebhookRegisterDqlLiveQuery(dittoHandle.deref(), query, queryArgumentsCBOR, url),
@@ -322,6 +338,7 @@ export class Store {
       throw new DittoError('internal', "Internal inconsistency, can't remove store observer that has not been cancelled")
     }
 
+    // Return early if the store observer has already been removed.
     const indexToDelete = this.observers.findIndex((observer) => observer === storeObserver)
     if (indexToDelete === -1) {
       return false
@@ -329,10 +346,12 @@ export class Store {
 
     const newObservers = [...this.observers]
     newObservers.splice(indexToDelete, 1)
+    // @ts-expect-error modifying readonly property
     this.observers = Object.freeze(newObservers)
 
     const dittoHandle = Bridge.ditto.handleFor(this.ditto)
     this.ditto.deferClose(() => {
+      // prettier-ignore
       mapFFIErrors(
         () => FFI.liveQueryStop(dittoHandle.deref(), storeObserver.liveQueryID)
       )
@@ -346,7 +365,8 @@ export class Store {
       observer.cancel()
     }
 
-
+    // NOTE: live query webhook is taken care of by the FFI's
+    // `ditto_shutdown()`, no need to unregister it here.
   }
 
   /**