@dittolive/ditto 4.5.4 → 4.6.0

package/react-native/src/sources/attachment-token.ts

@@ -3,24 +3,68 @@
 //
 
 import * as FFI from './ffi'
+import { mapFFIErrors } from './error'
+
+import type { AttachmentMetadata } from './attachment'
+import type { Store } from './store'
+
+/** @internal */
+export type UntypedAttachmentToken = { id: string; len: number | BigInt; metadata: AttachmentMetadata }
+
+/** @internal */
+export type TypedAttachmentToken = { [FFI.DittoCRDTTypeKey]?: FFI.DittoCRDTType.attachment; _id: Uint8Array; _len: number | BigInt; _meta: AttachmentMetadata }
 
 /**
  * Serves as a token for a specific attachment that you can pass to a call to
- * {@link Collection.fetchAttachment | fetchAttachment()} on a
- * {@link Collection}.
+ * {@link Store.fetchAttachment | ditto.store.fetchAttachment()}.
  */
 export class AttachmentToken {
-  /** @internal */
-  readonly id: Uint8Array
+  /** The attachment's ID. */
+  // This ID is a _non-padded_ base64-encoded version of `idBytes`.
+  readonly id: string
 
-  /** @internal */
-  readonly len: number
+  /** The attachment's size given as number of bytes. */
+  readonly len: number | BigInt
+
+  /** The attachment's metadata. */
+  readonly metadata: AttachmentMetadata
+
+  // -------------------------------------------------------------------------
 
   /** @internal */
-  readonly metadata: { [key: string]: string }
+  constructor(jsObj: UntypedAttachmentToken | TypedAttachmentToken) {
+    // There are two representations of attachment tokens:
+    // 1. The legacy typed representation is an internal format that is used by
+    //    the query builder API. It can be identified by the presence of the
+    //    [FFI.DittoCRDTTypeKey] field.
+    // 2. The untyped representation is used in our public API and was first
+    //    introduced in the HTTP API. It is now used by the DQL API as well. It
+    //    uses a non-padded base64-encoded ID.
+    let id: Uint8Array, len: number | BigInt, meta: AttachmentMetadata
+    if (jsObj[FFI.DittoCRDTTypeKey] != null) {
+      ;({ id, len, meta } = AttachmentToken.validateTypedInput(jsObj as TypedAttachmentToken))
+    } else {
+      ;({ id, len, meta } = AttachmentToken.validateUntypedInput(jsObj as UntypedAttachmentToken))
+    }
+
+    // base64-encode string and remove padding
+    this.id = mapFFIErrors(() => FFI.base64encode(id, 'Unpadded'))
+    this.idBytes = id
+    this.len = len
+    this.metadata = meta
+  }
 
   /** @internal */
-  constructor(jsObj: object) {
+  readonly idBytes: Uint8Array
+
+  /**
+   * Validate an input value that has a field `[FFI.DittoCRDTTypeKey]` and
+   * return its contents.
+   *
+   * @throws {Error} If the input is invalid.
+   * @returns {object} binary id, len and metadata of the attachment token
+   */
+  private static validateTypedInput(jsObj: TypedAttachmentToken): { id: Uint8Array; len: number | BigInt; meta: AttachmentMetadata } {
     const type = jsObj[FFI.DittoCRDTTypeKey]
     if (type !== FFI.DittoCRDTType.attachment) {
       throw new Error('Invalid attachment token')
@@ -32,8 +76,8 @@ export class AttachmentToken {
     }
 
     const len = jsObj['_len']
-    if (typeof len !== 'number' || len < 0) {
-      throw new Error('Invalid attachment token length')
+    if ((typeof len !== 'number' && typeof len !== 'bigint') || len < 0) {
+      throw new Error('Invalid attachment token length, must be a non-negative number or bigint')
     }
 
     const meta = jsObj['_meta']
@@ -41,8 +85,45 @@ export class AttachmentToken {
       throw new Error('Invalid attachment token meta')
     }
 
-    this.id = id
-    this.len = len
-    this.metadata = meta
+    return { id, len, meta }
+  }
+
+  /**
+   * Validate an untyped input value and return its contents.
+   *
+   * Converts _unpadded_ base64-encoded ID in input to _padded_ base64-encoded
+   * ID before returning it as `Uint8Array`.
+   *
+   * @throws {@link DittoError} `store/attachment-token-invalid` If the input id
+   * is not a valid base64 string.
+   * @returns {object} binary id, len and metadata of the attachment token
+   */
+  private static validateUntypedInput(jsObj: UntypedAttachmentToken): { id: Uint8Array; len: number | BigInt; meta: AttachmentMetadata } {
+    const idBase64 = jsObj['id']
+    if (typeof idBase64 !== 'string') {
+      throw new Error('Invalid attachment token id')
+    }
+
+    const id = mapFFIErrors(
+      () => FFI.tryBase64Decode(idBase64, 'Unpadded'),
+      {
+        Base64Invalid: ['store/attachment-token-invalid', 'Failed to decode attachment token id from base64 input'],
+      },
+      {
+        attachmentTokenID: idBase64,
+      },
+    )
+
+    const len = jsObj['len']
+    if ((typeof len !== 'number' && typeof len !== 'bigint') || len < 0) {
+      throw new Error('Invalid attachment token length, must be a non-negative number or bigint')
+    }
+
+    const meta = jsObj['metadata']
+    if (typeof meta !== 'object') {
+      throw new Error('Invalid attachment token meta')
+    }
+
+    return { id, len, meta }
   }
 }

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

@@ -3,17 +3,23 @@
 //
 
 import * as FFI from './ffi'
-import { Bridge } from './bridge'
 import * as Environment from './@environment'
+import { Bridge } from './bridge'
+import { DittoError } from './error'
 
 import type { Ditto } from './ditto'
 import type { AttachmentToken } from './attachment-token'
 
+/**
+ * A key-value map of user-defined metadata for an attachment.
+ */
+export type AttachmentMetadata = { [key: string]: string }
+
 /**
  * Represents an attachment and can be used to insert the associated attachment
  * into a document at a specific key-path. You can't instantiate an attachment
- * directly, please use the {@link Collection.newAttachment | newAttachment()}
- * method of {@link Collection} instead.
+ * directly, please use the
+ * {@link Store.newAttachment | ditto.store.newAttachment()} method instead.
  */
 export class Attachment {
   /** @internal */
@@ -22,6 +28,16 @@ export class Attachment {
   /** @internal */
   readonly token: AttachmentToken
 
+  /** The attachment's ID. */
+  get id(): string {
+    return this.token.id
+  }
+
+  /** The attachment's size given as number of bytes. */
+  get len(): number | BigInt {
+    return this.token.len
+  }
+
   /** The attachment's metadata. */
   get metadata(): { [key: string]: string } {
     return this.token.metadata
@@ -30,24 +46,29 @@ export class Attachment {
   /**
    * Returns the attachment's data.
    */
-  getData(): Promise<Uint8Array> {
+  data(): Promise<Uint8Array> {
     const ditto = this.ditto
     const dittoHandle = Bridge.ditto.handleFor(ditto)
     return this.ditto.deferCloseAsync(async () => {
-      // if (Environment.isWebBuild) {
-      //   const attachmentHandle = Bridge.attachment.handleFor(this)
-      //   return await FFI.dittoGetCompleteAttachmentData(dittoHandle.deref(), attachmentHandle.deref())
-      // }
-
-      // if (Environment.isNodeBuild) {
-      //   const attachmentHandle = Bridge.attachment.handleFor(this)
-      //   const attachmentPath = FFI.dittoGetCompleteAttachmentPath(dittoHandle.deref(), attachmentHandle.deref())
-      //   const fs = require('fs').promises
-      //   return await fs.readFile(attachmentPath)
-      // }
+
+
+      if (Environment.isReactNativeBuild) {
+        const attachmentHandle = Bridge.attachment.handleFor(this)
+        const attachmentPath = FFI.dittoGetCompleteAttachmentPath(dittoHandle.deref(), attachmentHandle.deref())
+        return await FFI.readFile(attachmentPath)
+      }
     })
   }
 
+  /**
+   * Returns the attachment's data.
+   *
+   * @deprecated Use `data()` instead.
+   */
+  getData(): Promise<Uint8Array> {
+    return this.data()
+  }
+
   /**
    * Copies the attachment to the specified file path. Node-only,
    * throws in the browser.
@@ -58,11 +79,14 @@ export class Attachment {
     const ditto = this.ditto
     const dittoHandle = Bridge.ditto.handleFor(ditto)
     return this.ditto.deferCloseAsync(async () => {
-      if (Environment.isWebBuild) {
-        throw new Error(`Can't copy attachment to path, not available when running in the browser.`)
-      }
 
-    
+      if (Environment.isReactNativeBuild) {
+        const attachmentHandle = Bridge.attachment.handleFor(this)
+        const attachmentPath = FFI.dittoGetCompleteAttachmentPath(dittoHandle.deref(), attachmentHandle.deref())
+        // If the file already exists, we fail. This is the same behavior as
+        // for the Swift/ObjC SDK.
+        return await FFI.copyFile(attachmentPath, path, ditto.persistenceDirectory)
+      }
     })
   }
 
@@ -72,3 +96,26 @@ export class Attachment {
     this.token = token
   }
 }
+
+/**
+ * Validates the given attachment metadata. Metadata must be a flat object with
+ * string values.
+ *
+ * This should really happen in core to make sure we use the same validation
+ * logic across SDKs but we decided to postpone that for the next iteration on
+ * attachments.
+ *
+ * @throws {@link DittoError} 'store/failed-to-create-attachment'
+ * @internal
+ */
+export function validateAttachmentMetadata(metadata: AttachmentMetadata): void {
+  if (typeof metadata !== 'object') {
+    throw new DittoError('store/failed-to-create-attachment', `Invalid attachment metadata: expected a value of type object but got ${typeof metadata}.`)
+  }
+
+  for (const key in metadata) {
+    if (typeof metadata[key] !== 'string') {
+      throw new DittoError('store/failed-to-create-attachment', `Invalid attachment metadata: metadata values must be strings but key '${key}' has a value of type ${typeof metadata[key]}.`)
+    }
+  }
+}

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

@@ -46,11 +46,16 @@ export function augmentJSONValue(json, mutDoc, workingPath) {
  * Converts objects that may contain instances of classes of this SDK, i.e.
  * `DocumentID`, `Counter`, `Register` and `Attachment`, into plain JS objects
  * that can be passed to the FFI layer.
+ *
+ * WARNING: For attachments in the input, the output can contain `BigInt`
+ * values, which are not JSON-compatible.
+ *
+ * @throws {Error} If `jsObj` contains a non-finite float value.
  */
-export function desugarJSObject(jsObj: any, atRoot: boolean = false): any {
+export function desugarJSObject(jsObj: any): any {
   if (jsObj && typeof jsObj === 'object') {
     if (Array.isArray(jsObj)) {
-      return jsObj.map((v, idx) => desugarJSObject(v, false))
+      return jsObj.map((v, idx) => desugarJSObject(v))
     } else if (jsObj instanceof DocumentID) {
       return jsObj.value
     } else if (jsObj instanceof Counter) {
@@ -65,17 +70,19 @@ export function desugarJSObject(jsObj: any, atRoot: boolean = false): any {
       return registerJSON
     } else if (jsObj instanceof Attachment) {
       const attachmentJSON = {
-        _id: jsObj.token.id,
-        _len: jsObj.token.len,
+        _id: jsObj.token.idBytes,
+        _len: jsObj.token.len, // may be a BigInt
         _meta: jsObj.token.metadata,
       }
       attachmentJSON[FFI.DittoCRDTTypeKey] = FFI.DittoCRDTType.attachment
       return attachmentJSON
     } else {
+      // Create a copy to not mutate the original object
+      const jsObjJSON = {}
       for (const [key, value] of Object.entries(jsObj)) {
-        jsObj[key] = desugarJSObject(value, false)
+        jsObjJSON[key] = desugarJSObject(value)
       }
-      return jsObj
+      return jsObjJSON
     }
   } else {
     checkForUnsupportedValues(jsObj)

package/react-native/src/sources/base-pending-cursor-operation.ts

@@ -4,6 +4,7 @@
 
 import * as FFI from './ffi'
 
+import { desugarJSObject } from './augment'
 import { Document, MutableDocument } from './document'
 import { UpdateResultsMap } from './update-results-map'
 import { CBOR } from './cbor'
@@ -39,6 +40,9 @@ export abstract class BasePendingCursorOperation implements PromiseLike<Document
    * Updates documents that match the query generated by the preceding function
    * chaining.
    *
+   * Document values must not be set to any non-finite numbers (`NaN`,
+   * `Infinity`, `-Infinity`).
+   *
    * @param closure A closure that gets called with all of the documents
    * matching the query. The documents are instances of {@link MutableDocument}
    * so you can call update-related functions on them.
@@ -64,18 +68,20 @@ export abstract class BasePendingCursorOperation implements PromiseLike<Document
    * Sorts the documents that match the query provided in the preceding
    * `find`-like function call.
    *
-   * @param query The query specifies the logic to be used when sorting the
-   * matching documents.
+   * Documents that are missing the field to sort by will appear at
+   * the beginning of the results when sorting in ascending order.
+   *
+   * @param query Name or path of the field to sort by.
    *
    * @param direction Specify whether you want the sorting order to be
-   * `Ascending` or `Descending`.
+   * `ascending` or `descending`. Defaults to `ascending`.
    *
    * @return A cursor that you can chain further function calls and then either
    * get the matching documents immediately or get updates about them over time.
    */
-  sort(propertyPath: string, direction: SortDirection = 'ascending'): BasePendingCursorOperation {
+  sort(query: string, direction: SortDirection = 'ascending'): BasePendingCursorOperation {
     this.orderBys.push({
-      query: propertyPath,
+      query,
       direction: direction === 'ascending' ? 'Ascending' : 'Descending',
     })
     return this
@@ -97,6 +103,8 @@ export abstract class BasePendingCursorOperation implements PromiseLike<Document
    * get the matching documents immediately or get updates about them over time.
    */
   offset(offset: number): BasePendingCursorOperation {
+    // REFACTOR: factor out parameter validation.
+
     if (offset < 0) throw new Error(`Can't offset by '${offset}', offset must be >= 0`)
     if (!Number.isFinite(offset)) throw new Error(`Can't offset by '${offset}', offset must be a finite number`)
     if (Number.isNaN(offset)) throw new Error(`Can't offset by '${offset}', offset must be a valid number`)
@@ -118,6 +126,8 @@ export abstract class BasePendingCursorOperation implements PromiseLike<Document
    * get the matching documents immediately or get updates about them over time.
    */
   limit(limit: number): BasePendingCursorOperation {
+    // REFACTOR: factor out parameter validation.
+
     if (limit < -1) throw new Error(`Can't limit to '${limit}', limit must be >= -1 (where -1 means unlimited)`)
     if (!Number.isFinite(limit)) throw new Error(`Can't limit to '${limit}', limit must be a finite number`)
     if (Number.isNaN(limit)) throw new Error(`Can't limit to '${limit}', limit must be a valid number`)
@@ -215,7 +225,13 @@ export abstract class BasePendingCursorOperation implements PromiseLike<Document
     this.query = validateQuery(query)
     this.queryArgs = queryArgs ? Object.freeze({ ...queryArgs }) : null
     this.collection = collection
-    this.queryArgsCBOR = queryArgs ? CBOR.encode(queryArgs) : null
+
+    if (queryArgs == null) {
+      this.queryArgsCBOR = null
+    } else {
+      const queryArgsJSON = desugarJSObject(queryArgs)
+      this.queryArgsCBOR = CBOR.encode(queryArgsJSON)
+    }
   }
 
   /** @internal */

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

@@ -42,6 +42,9 @@ export abstract class BasePendingIDSpecificOperation implements PromiseLike<Docu
   /**
    * Updates the document with the matching ID.
    *
+   * Document values must not be set to any non-finite numbers (`NaN`,
+   * `Infinity`, `-Infinity`).
+   *
    * @param closure A closure that gets called with the document matching the
    * ID. If found, the document is a {@link MutableDocument}, so you can call
    * update-related functions on it. If the document is not found then the value

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

@@ -5,11 +5,11 @@
 import * as FFI from './ffi'
 
 import { Logger } from './logger'
-import { QueryResult } from './query-result'
-import { QueryResultItem } from './query-result-item'
 
 import type { Document, MutableDocument } from './document'
 import type { Attachment } from './attachment'
+import type { QueryResult } from './query-result'
+import type { QueryResultItem } from './query-result-item'
 
 import type { StaticTCPClient } from './static-tcp-client'
 import type { WebsocketClient } from './websocket-client'

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

@@ -4,8 +4,6 @@
 
 import { CBOR as CBORRedux } from './@cbor-redux'
 
-import { DocumentID } from './document-id'
-
 /** @internal */
 export class CBOR {
   /** @internal */
@@ -20,16 +18,3 @@ export class CBOR {
     return CBORRedux.decode(arrayBuffer, reviver)
   }
 }
-
-/**
- * Custom replacer that converts `DocumentID` instances to their string
- * representation.
- *
- * @internal
- */
-export function documentIDReplacer(key: any, value: any): any {
-  if (value instanceof DocumentID) {
-    return value.toString()
-  }
-  return value
-}

package/react-native/src/sources/collection-interface.ts

@@ -10,6 +10,10 @@ import type { BasePendingCursorOperation } from './base-pending-cursor-operation
 import type { BasePendingIDSpecificOperation } from './base-pending-id-specific-operation'
 
 export type UpsertOptions = {
+  /**
+   * Specifies the desired strategy for inserting a document. The default
+   * strategy is `merge`. See {@link WriteStrategy} for more information.
+   */
   writeStrategy?: WriteStrategy
 }
 
@@ -55,13 +59,15 @@ export interface CollectionInterface {
   findByIDCBOR(idCBOR: Uint8Array): BasePendingIDSpecificOperation
 
   /**
-   * Inserts a new document into the collection and returns its ID. If the
-   * document already exists, the contents of both are merged by default. You
-   * can change this by providing a different `writeStrategy` via `options`.
+   * Inserts a new document into the collection and returns its ID.
+   *
+   * If the document already exists, the contents of both are merged by default.
+   * You can change this by providing a different `writeStrategy` via `options`.
    *
-   * @param value The content of the document to be inserted or updated.
-   * @param options.writeStrategy Specifies the desired strategy for inserting a
-   * document, defaults to `'merge'`.
+   * @param value The content of the document to be inserted or updated. Must
+   * not contain any non-finite numbers (NaN, Infinity, -Infinity).
+   * @param options Change defaults for the behavior of the operation, such as
+   * the write strategy.
    */
   upsert(value: DocumentValue, options: UpsertOptions): Promise<DocumentID>
 }

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

@@ -18,6 +18,7 @@ import { PendingIDSpecificOperation } from './pending-id-specific-operation'
 import { performAsyncToWorkaroundNonAsyncFFIAPI } from './internal'
 import { desugarJSObject } from './augment'
 
+import type { TypedAttachmentToken } from './attachment-token'
 import type { Store } from './store'
 import type { DocumentValue } from './document'
 import type { DocumentIDValue } from './document-id'
@@ -94,7 +95,7 @@ export class Collection implements CollectionInterface {
     return ditto.deferCloseAsync(async () => {
       const writeStrategy = options.writeStrategy ?? 'merge'
 
-      const documentValueJSON = desugarJSObject(value, true)
+      const documentValueJSON = desugarJSObject(value)
       const documentValueCBOR = CBOR.encode(documentValueJSON)
 
       const idCBOR = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
@@ -130,6 +131,9 @@ export class Collection implements CollectionInterface {
    * attachment with or the raw data.
    *
    * @param metadata Metadata relating to the attachment.
+   *
+   * @deprecated Use {@link Store.newAttachment | ditto.store.newAttachment() }
+   * instead.
    */
   async newAttachment(pathOrData: string | Uint8Array, metadata: { [key: string]: string } = {}): Promise<Attachment> {
     const ditto = this.store.ditto
@@ -157,7 +161,7 @@ export class Collection implements CollectionInterface {
       const attachmentTokenJSON = { _id: id, _len: len, _meta: { ...metadata } }
       attachmentTokenJSON[FFI.DittoCRDTTypeKey] = FFI.DittoCRDTType.attachment
 
-      const attachmentToken = new AttachmentToken(attachmentTokenJSON)
+      const attachmentToken = new AttachmentToken(attachmentTokenJSON as TypedAttachmentToken)
       const attachment = new Attachment(ditto, attachmentToken)
 
       return Bridge.attachment.bridge(handle, () => attachment)
@@ -187,6 +191,9 @@ export class Collection implements CollectionInterface {
    * @return An `AttachmentFetcher` object, which must be kept alive for the
    * fetch request to proceed and for you to be notified about the attachment's
    * fetch status changes.
+   *
+   * @deprecated Use
+   * {@link Store.fetchAttachment | ditto.store.fetchAttachment() } instead.
    */
   fetchAttachment(token: AttachmentToken, eventHandler?: (event: AttachmentFetchEvent) => void): AttachmentFetcher {
     if (token == null || !(token instanceof AttachmentToken)) {

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

@@ -217,9 +217,7 @@ export class Ditto {
 
     // Check if device name stays the same on sdk and core levels (#10729).
 
-    if (Environment.isWebBuild) {
-      this.deviceName = navigator.userAgent
-    }
+
 
     if (Environment.isReactNativeBuild) {
       this.deviceName = FFI.getDeviceName() as string
@@ -227,16 +225,12 @@ export class Ditto {
 
     this.keepAlive = new KeepAlive()
 
-    // NOTE: some behavior not implemented yet as compared to the ObjC/Swift
-    // version:
-    //
-    // 1. Optional `identity` parameter falling back to a default one.
-    //
-    // 2. Optional siteID of the identity, falling back to a random one if
-    //    newly created or to the stored one if already persisted.
-
-    const uninitializedDittoX = FFI.uninitializedDittoMake(this.persistenceDirectory)
-
+    // WORKAROUND: the login provider triggers the registered callback right
+    // when the auth client is being constructed. At this point, we don't have
+    // the auth client, which would be needed to perform a login, nor did we
+    // have a chance to create an authenticator. Therefore catch that first
+    // callback, store the seconds remaining and proceed with propagating
+    // it after all pieces are in place.
     let secondsRemainingUntilAuthenticationExpires: number | null = null
 
     const weakThis = new WeakRef(this)
@@ -275,7 +269,10 @@ export class Ditto {
       throw new Error(`Can't create Ditto, unsupported identity type: ${validIdentity}`)
     })()
 
-    const dittoPointer = FFI.dittoMake(uninitializedDittoX, identityConfig)
+    // History tracking is an experimental feature that is not supported in the JS SDK.
+    const historyTracking = 'Disabled'
+
+    const dittoPointer = FFI.dittoMake(this.persistenceDirectory, identityConfig, historyTracking)
 
     FFI.dittoAuthClientSetValidityListener(dittoPointer, function (...args) {
       const ditto = weakThis.deref()
@@ -294,6 +291,10 @@ export class Ditto {
 
     Bridge.ditto.bridge(dittoPointer, this)
 
+    if (Environment.isReactNativeBuild) {
+      this.disableSyncWithV3()
+    }
+
     // IMPORTANT: Keeping the auth client around accumulates run-times and
     // resources which becomes a problem specifically in tests (where we use one
     // Ditto instance per test). We therefore keep it only if needed, i.e.
@@ -312,6 +313,8 @@ export class Ditto {
         if (strongThis.auth) {
           strongThis.auth['@ditto.authenticationExpiring'](secondsRemaining)
         } else {
+          // WORKAROUND: see description above where the
+          // secondsRemainingUntilAuthenticationExpires variable is declared.
           secondsRemainingUntilAuthenticationExpires = secondsRemaining
         }
       })
@@ -364,6 +367,8 @@ export class Ditto {
 
     disableDeadlockTimeoutWhenDebugging()
 
+    // WORKAROUND: see description above where the
+    // secondsRemainingUntilAuthenticationExpires variable is declared.
     if (secondsRemainingUntilAuthenticationExpires != null) {
       this.auth['@ditto.authenticationExpiring'](secondsRemainingUntilAuthenticationExpires)
     }
@@ -468,6 +473,7 @@ export class Ditto {
       validatedPath = path
     }
 
+
     if (Environment.isReactNativeBuild) {
       validatedPath = FFI.createDirectory(validatedPath) as string
     }
@@ -666,9 +672,6 @@ export class Ditto {
    * @throws {Error} if called in a React Native environment.
    */
   async disableSyncWithV3(): Promise<void> {
-    if (Environment.isReactNativeBuild) {
-      throw new Error('Disabling sync with V3 is not supported in a React Native environment.')
-    }
     const dittoHandle = Bridge.ditto.handleFor(this)
     return this.deferCloseAsync(async () => {
       await FFI.dittoDisableSyncWithV3(dittoHandle.deref())
@@ -708,7 +711,11 @@ export class Ditto {
     // ignored because they are handled at the original call site.
     do {
       await Promise.allSettled(this.pendingOperations)
-
+      // REFACTOR: in theory, we could end up in an endless loop here if for
+      // some reason a resolved or rejected promise isn't removed from
+      // `pendingOperations`. AFAICS, this is not possible atm due to the
+      // way `deferClose` and `deferCloseAsync` is implemented. Would be
+      // great to rework this and make it more solid if possible.
     } while (this.pendingOperations.size > 0)
     this.deferCloseAllowed = false
 
@@ -975,5 +982,6 @@ export const disableDeadlockTimeoutWhenDebugging = () => {
  * @internal
  */
 const isDirectoryWritable = (directoryPath: string): boolean => {
+
   return true
 }

package/react-native/src/sources/document-id.ts

@@ -4,9 +4,10 @@
 
 import * as FFI from './ffi'
 import { CBOR } from './cbor'
+import { mapFFIErrors } from './error'
 
 /** Represents a unique identifier for a {@link Document}. */
-export type DocumentIDValue = any 
+export type DocumentIDValue = any // REFACTOR: get rid of any.
 
 /** Represents a unique identifier for a {@link Document}. */
 export class DocumentID {
@@ -113,23 +114,26 @@ export class DocumentID {
   }
 
   /**
-   * Returns a byte representation of the document ID value as base64 string.
+   * Returns the base64-encoded CBOR representation of this document ID.
+   *
+   * @deprecated
    */
   toBase64String(): string {
-    const bytes = this['@ditto.cbor']
-    return btoa(String.fromCharCode.apply(null, bytes))
+    return mapFFIErrors(() => FFI.base64encode(this['@ditto.cbor'], 'Padded'))
   }
 
   /**
    * Returns a query compatible string representation of the receiver.
    *
-   * The returned string can be used directly in queries that you use with
-   * other Ditto functions. For example you could create a query that was like
-   * this:
+   * The returned string can be used directly in queries that you use with other
+   * Ditto functions. For example you could create a query that was like this:
    *
    *  ``` TypeScript
    *  collection.find(`_id == ${documentID.toQueryCompatibleString()}`)
    *  ```
+   *
+   * @deprecated use document IDs in queries by embedding them in the query
+   * arguments parameter.
    */
   toQueryCompatibleString(): string {
     return FFI.documentIDQueryCompatible(this['@ditto.cbor'], 'WithQuotes')