@dittolive/ditto 4.5.1 → 4.5.2-rc.2

package/react-native/lib/module/index.js

@@ -1,13 +1,27 @@
-export {getMissingAndroidPermissions} from './ditto.rn';
-export {TransportConfig} from '../../sources/transport-config';
-export {Ditto} from '../../sources/ditto';
-export {Logger} from '../../sources/logger';
+// RN API
 
-export type {AuthenticationHandler} from '../../sources/authenticator';
-export type {Identity} from '../../sources/identity';
-export type {QueryResult} from '../../sources/query-result';
-export type {QueryResultItem} from '../../sources/query-result-item';
-export type {LogLevel} from '../../sources/logger';
+export { getMissingAndroidPermissions } from './ditto.rn';
 
+// JS API
+
+export * from '../../sources/essentials';
+export * from '../../sources/logger';
+export * from '../../sources/document-id';
+export * from '../../sources/observer';
+export * from '../../sources/authenticator';
+export * from '../../sources/identity';
+export * from '../../sources/ditto';
+export * from '../../sources/store-observer';
+export * from '../../sources/sync';
+export * from '../../sources/sync-subscription';
+export * from '../../sources/error';
+export * from '../../sources/error-codes';
+export * from '../../sources/query-result-item';
+export * from '../../sources/query-result';
+export * from '../../sources/small-peer-info';
+export * from '../../sources/store';
+export * from '../../sources/presence';
+export * from '../../sources/transport-config';
 export * from '../../sources/epilogue';
-//# sourceMappingURL=index.js.map
+
+# sourceMappingURL=index.js.map

package/react-native/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":[],"sourceRoot":"../../src","sources":["index.ts"],"mappings":"AAAA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;;AAEA"}
+{"version":3,"names":[],"sourceRoot":"../../src","sources":["index.ts"],"mappings":"AAAA;;AAEA;;AAEA;;AAEA;;AAEA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA"}

package/react-native/lib/typescript/ditto.rn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ditto.rn.d.ts","sourceRoot":"","sources":["../../src/ditto.rn.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAKxE,OAAO,mCAAmC,CAAC;AA+D3C,wBAAgB,yBAAyB,CACvC,sBAAsB,EAAE,GAAG,GAC1B,OAAO,CAWT;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI,UAAU,EAAE,CAK3D;AAED,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,GAAG,OAElD;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,GAAG,qBAIjD;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,GAAG,OAEhD"}
+{"version":3,"file":"ditto.rn.d.ts","sourceRoot":"","sources":["../../src/ditto.rn.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAOxE,OAAO,mCAAmC,CAAC;AAuE3C,wBAAgB,yBAAyB,CACvC,sBAAsB,EAAE,GAAG,GAC1B,OAAO,CAUT;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI,UAAU,EAAE,CAK3D;AAMD,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,GAAG,OAElD;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,GAAG,qBAGjD;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,GAAG,OAEhD"}

package/react-native/src/sources/@environment.ts

@@ -1,2 +1 @@
-
 export * from '../environment/environment.fallback';

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

@@ -1,3 +1,7 @@
+//
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
+//
+
 import * as FFI from './ffi'
 
 import { AttachmentFetcher } from './attachment-fetcher'
@@ -10,8 +14,12 @@ import type { AttachmentFetchEvent } from './attachment-fetch-event'
 /** @internal */
 type AttachmentFetcherContextInfo = {
   attachmentFetcher: WeakRef<AttachmentFetcher>
+  // Attachment token is unique per attachment.
   attachmentTokenID: Uint8Array
+  // This id is unique per attachment fetcher.
   id: string
+  // Promise for a token that can be used to cancel the fetch. If `null`, the
+  // fetch has already completed, errored, or been canceled.
   cancelTokenPromise: Promise<unknown | null> | null
 }
 
@@ -37,6 +45,7 @@ export class AttachmentFetcherManager {
     return this.ditto.deferClose(() => {
       const attachmentFetcher = new AttachmentFetcher(this.ditto, token, this, eventHandler)
 
+      // Register in finalization registry.
       const contextInfo: AttachmentFetcherContextInfo = {
         id: attachmentFetcher.id,
         attachmentTokenID: token.id,
@@ -45,8 +54,10 @@ export class AttachmentFetcherManager {
       }
       this.finalizationRegistry.register(attachmentFetcher, contextInfo, attachmentFetcher)
 
+      // Keep a reference to the context info so that we can stop the fetcher.
       this.contextInfoByID[attachmentFetcher.id] = contextInfo
 
+      // Prevent cancellation of the fetch once it was fulfilled or rejected.
       const resetCancelToken = () => {
         if (this.contextInfoByID[attachmentFetcher.id] != null) {
           this.contextInfoByID[attachmentFetcher.id].cancelTokenPromise = null
@@ -63,6 +74,7 @@ export class AttachmentFetcherManager {
         },
       )
 
+      // Keep the attachment fetcher alive until it is stopped.
       this.ditto.keepAlive.retain(`AttachmentFetcher.${attachmentFetcher.id})`)
 
       return attachmentFetcher
@@ -113,13 +125,16 @@ export class AttachmentFetcherManager {
   private stopWithContextInfo(contextInfo: AttachmentFetcherContextInfo): Promise<void> {
     const dittoHandle = Bridge.ditto.handleFor(this.ditto)
     return this.ditto.deferCloseAsync(async () => {
+      // Remove the manager's own record of the context info.
       if (this.contextInfoByID[contextInfo.id] == null) {
         throw new Error(`Internal inconsistency: attachment fetcher ${contextInfo.id} not found in active attachment fetchers.`)
       }
       delete this.contextInfoByID[contextInfo.id]
 
+      // Release the keep-alive.
       this.ditto.keepAlive.release(`AttachmentFetcher.${contextInfo.id})`)
 
+      // Cancel the fetcher if it is still running.
       const cancelToken = await contextInfo.cancelTokenPromise
       if (cancelToken) {
         FFI.dittoCancelResolveAttachment(dittoHandle.deref(), contextInfo.attachmentTokenID, cancelToken)

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

@@ -37,6 +37,9 @@ export class AttachmentFetcher implements PromiseLike<Attachment | null> {
    * the attachment to be made available locally to the device.
    */
   stop() {
+    // No need for synchronicity here: we let the "stop promise" float / run in
+    // a detached fashion since there is no point in awaiting the "stop
+    // signaling" itself.
     step(async () => {
       await this.manager.stopAttachmentFetcher(this)
       if (this.rejectPendingFetch != null) {
@@ -106,10 +109,17 @@ export class AttachmentFetcher implements PromiseLike<Attachment | null> {
         }
       }
 
+      // The core doesn't call any of the handlers defined above when a fetch is
+      // cancelled through `this.stop()` so we use this function to reject the
+      // promise from the outside.
       this.rejectPendingFetch = () => {
         reject(new Error('Attachment fetch was canceled'))
       }
 
+      // Not awaited yet; only needs to be fully resolved (and `await`ed over)
+      // when using the actual `cancelTokenPromise`, which only happens in
+      // `AttachmentFetcherManager.stopWithContextInfo()`.
+      // @ts-expect-error setting readonly property
       this.cancelTokenPromise = FFI.dittoResolveAttachment(dittoHandle.deref(), token.id, { onComplete, onProgress, onDelete }, onError)
     })
   }

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

@@ -34,6 +34,17 @@ export class Attachment {
     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)
+      // }
     })
   }
 
@@ -47,7 +58,11 @@ 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.`)
+      }
 
+    
     })
   }
 

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

@@ -2,6 +2,13 @@
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
 //
 
+// NOTE: proxy was originally written in pure JS rather than TypeScript. We'll
+// gradually port it to TypeScript and until done, we've renamed the pure JS
+// file to proxy.raw.js and introduced proxy.ts that'll contain all parts ported
+// to TypeScript or type declarations for the JS parts.
+
+// import * as proxyRaw from './proxy.raw'
+
 import * as FFI from './ffi'
 import { DocumentID } from './document-id'
 import { AttachmentToken } from './attachment-token'
@@ -9,6 +16,11 @@ import { Attachment } from './attachment'
 import { Counter } from './counter'
 import { Register } from './register'
 
+// Takes an annotated JSON representation of a document (see CRDT's Document
+// class for more info about what an annotated representation is) and turns it
+// into a JavaScript-appropriate version. This means that counters get
+// represented by `Counter` objects and attachments get represented by
+// `Attachment` objects.
 export function augmentJSONValue(json, mutDoc, workingPath) {
   if (json && typeof json === 'object') {
     if (Array.isArray(json)) {

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

@@ -201,6 +201,8 @@ export abstract class BasePendingCursorOperation implements PromiseLike<Document
           Bridge.mutableDocument.unregister(mutableDocument)
         }
 
+        // NOTE: ownership of documentsX (and contained documents)
+        // is transferred to Rust at this point.
         await FFI.collectionUpdateMultiple(dittoHandle.deref(), this.collection.name, writeTransactionX, documentsX)
 
         return new UpdateResultsMap(updateResultsDocumentIDs, updateResultsByDocumentIDString)

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

@@ -16,6 +16,7 @@ import type { WebsocketClient } from './websocket-client'
 
 import type { Ditto } from './ditto'
 
+// Add bridged type name to debug, for example 'Ditto'.
 const DEBUG_TYPE_NAMES: string[] = []
 const DEBUG_ALL_TYPES = false
 
@@ -264,6 +265,7 @@ export class Bridge<T extends object, FFIType> {
    * @internal */
   registerType(value: BridgeType<T>) {
     if (this.internalType === value) {
+      // Nothing to do.
       return
     }
 
@@ -313,7 +315,8 @@ export class Bridge<T extends object, FFIType> {
     if (!handle) return undefined
     if (handle.type !== this.type) throw new Error(`Can't return object for pointer, pointer is associated with an object of type ${handle.type} but this bridge is configured for ${this.type}`)
 
-
+    // This throws an error if the object has been garbage collected but the
+    // finalizer has not been called yet.
     return handle.object()
   }
 
@@ -372,6 +375,7 @@ export class Bridge<T extends object, FFIType> {
     const existingHandle = this.handlesByObject.get(object)
     const existingPointer = existingHandle ? existingHandle.pointer : null
 
+    // Check that both pointer and handle are undefined at this point.
     if (existingPointer != null && existingHandle != null) throw new Error(`Can't register, an object for the passed in pointer has previously been registered: ${existingHandle.object()}`)
 
     if (existingPointer != null && existingHandle == null) throw new Error(`Internal inconsistency, trying to register an object which has an associated pointer but no handle entry: ${objectType.name} at ${existingPointer.type} ${existingPointer.addr}`)

package/react-native/src/sources/build-time-constants.ts

@@ -1,4 +1,8 @@
-
+// NOTE: this is patched up with the actual build version by Jake task
+// build:package and has to be a valid semantic version as defined here: https://semver.org.
 export const fullBuildVersionString = '{full-build-version-string}'
 
+// NOTE: this is patched up with the default URL for the ditto.wasm by Jake task
+// build:package. Usually it looks something like this:
+// https://software.ditto.live/js/Ditto/1.2.3-alpha.456/ditto.wasm
 export const defaultDittoWasmFileURL = '{default-ditto-wasm-file-url}'

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

@@ -2,6 +2,9 @@
 // Copyright © 2021 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 = Symbol('privateConstructorToken')
 
 /**
@@ -63,6 +66,8 @@ export class MutableCounter extends Counter {
     }
 
     mutDoc.at(path)['@ditto.increment'](amount)
+    // We also increment the local value to make sure that the change is
+    // reflected locally as well as in the underlying document
     this._value += amount
   }
 

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

@@ -60,6 +60,8 @@ export type RemotePeer = {
 
 // -----------------------------------------------------------------------------
 
+// The name of the directory, relative to cwd, that will be used for persistence
+// if no other directory is specified.
 const DEFAULT_PERSISTENCE_DIRECTORY = 'ditto'
 
 /**
@@ -70,6 +72,7 @@ export class Ditto {
    * A string containing the semantic version of the Ditto SDK. Example: 4.4.3
    */
   static get VERSION(): string {
+    // Requires having called FFI.initSDKVersion() first.
     return FFI.dittoGetSDKSemver()
   }
 
@@ -212,12 +215,26 @@ export class Ditto {
 
     this.identity = Object.freeze(validIdentity)
 
+    // 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
     }
 
     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)
 
     let secondsRemainingUntilAuthenticationExpires: number | null = null
@@ -277,6 +294,11 @@ export class Ditto {
 
     Bridge.ditto.bridge(dittoPointer, this)
 
+    // 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.
+    // _only_ for the onlineWithAuthentication and online identities and
+    // transfer ownership of it to the authenticator.
     if (validIdentity.type === 'onlineWithAuthentication') {
       this.auth = new OnlineAuthenticator(this.keepAlive, this, validIdentity.authHandler)
 
@@ -290,11 +312,13 @@ export class Ditto {
         if (strongThis.auth) {
           strongThis.auth['@ditto.authenticationExpiring'](secondsRemaining)
         } else {
-
           secondsRemainingUntilAuthenticationExpires = secondsRemaining
         }
       })
-
+      // We don't need to worry about awaiting the result of this call because
+      // auth all happens in the background and so there are no guarantees we
+      // need to uphold by making sure things are in a certain state before the
+      // constructor finishes
       FFI.dittoAuthSetLoginProvider(dittoPointer, loginProviderX)
     } else if (validIdentity.type === 'onlinePlayground') {
       this.auth = new OnlineAuthenticator(this.keepAlive, this, {
@@ -310,12 +334,14 @@ export class Ditto {
       this.auth = new NotAvailableAuthenticator(this.keepAlive)
     }
 
-    const transportConfig = this.makeDefaultTransportConfig()
+    const transportConfig = this.makeDefaultTransportConfig().freeze()
 
+    //
+    // Assign instance properties.
+    //
 
     this.appID = appID
     this.siteID = siteID
-    this._transportConfig = transportConfig.copy().freeze()
 
     this.isX509Valid = isX509Valid
     this.isWebValid = isWebValid
@@ -323,7 +349,8 @@ export class Ditto {
     this.sync = new Sync(this)
     this.sync.update({ isSyncActive: false, isX509Valid, isWebValid, identity: validIdentity, ditto: this, transportConfig })
 
-
+    // We don't need a license when running in the browser, so we
+    // mark the instance as activated from the get-go in that case.
     this._isActivated = Environment.isWebBuild || !IdentityTypesRequiringOfflineLicenseToken.includes(validIdentity.type)
 
     this.store = new Store(this)
@@ -404,6 +431,7 @@ export class Ditto {
    * @returns `true` if the environment is supported
    */
   static isEnvironmentSupported(): boolean {
+    // From https://stackoverflow.com/questions/21825157/internet-explorer-11-detection
     let isIE = false
     if (typeof window !== 'undefined' && window.navigator && window.navigator.userAgent && window.navigator.appVersion) {
       isIE = window.navigator.userAgent.indexOf('MSIE') !== -1 || window.navigator.appVersion.indexOf('Trident/') > -1
@@ -459,7 +487,8 @@ export class Ditto {
    */
   setOfflineOnlyLicenseToken(licenseToken: string) {
     if (Environment.isWebBuild) {
-    
+      // We don't need a license when running in the browser. Web builds mark the instance as activated
+      // inside the constructor.
       Logger.info('Offline license token are ignored on web builds. Token validation will be skipped.')
     }
     if (Environment.isReactNativeBuild) {
@@ -491,7 +520,7 @@ export class Ditto {
    * @see {@link updateTransportConfig | updateTransportConfig()}
    */
   get transportConfig(): TransportConfig {
-    return this._transportConfig
+    return this.sync.parameters.transportConfig
   }
 
   /**
@@ -504,8 +533,7 @@ export class Ditto {
    * @see {@link updateTransportConfig | updateTransportConfig()}
    */
   setTransportConfig(transportConfig: TransportConfig) {
-    this._transportConfig = transportConfig.copy().freeze()
-    const transportConfigNew = this.transportConfig
+    const transportConfigNew = transportConfig.copy().freeze()
 
     const identity = this.identity
     const isWebValid = this.isWebValid
@@ -676,7 +704,8 @@ export class Ditto {
       throw new Error('Internal inconsistency, still kept alive after the Ditto object has been close()-ed. ')
     }
 
-
+    // Await all pending operations before closing. Rejected promises are
+    // ignored because they are handled at the original call site.
     do {
       await Promise.allSettled(this.pendingOperations)
 
@@ -748,7 +777,8 @@ export class Ditto {
     try {
       result = await pendingOperation
     } finally {
-   
+      // Remove the promise from the set of pending operations even if it
+      // rejected.
       this.pendingOperations.delete(pendingOperation)
     }
 
@@ -767,7 +797,6 @@ export class Ditto {
   private _isActivated: boolean
   private _isSyncActive: boolean = false
   private _isClosed: boolean = false
-  private _transportConfig: TransportConfig
 
   /** Set of pending operations that need to complete before the Ditto instance can be closed in a safe manner. */
   private pendingOperations = new Set<Promise<any>>()
@@ -790,6 +819,7 @@ export class Ditto {
   private validateIdentity(identity: Identity): Identity {
     const validIdentity = { ...identity }
 
+    // @ts-expect-error we validate the existence of the value below.
     const appID = identity.appID
 
     if (!['offlinePlayground', 'sharedKey', 'manual', 'onlinePlayground', 'onlineWithAuthentication'].includes(identity.type)) {
@@ -814,9 +844,11 @@ export class Ditto {
     }
 
     if (identity.type === 'sharedKey') {
+      // No validations yet.
     }
 
     if (identity.type === 'manual') {
+      // No validations yet.
     }
 
     if (identity.type === 'onlinePlayground') {
@@ -832,6 +864,7 @@ export class Ditto {
     }
 
     if (identity.type === 'onlineWithAuthentication') {
+      // No validations yet.
     }
 
     return validIdentity
@@ -913,6 +946,7 @@ export const disableDeadlockTimeoutWhenDebugging = () => {
   if (Environment.isNodeBuild) {
     const hasInspector = process && process?.execArgv?.some((arg) => arg.includes('--inspect') || arg.includes('--debug'))
 
+    // @ts-ignore - v8debug may be undefined
     const hasLegacyDebugMode = (process && process?.execArgv?.some((arg) => arg.includes('--debug'))) || typeof v8debug === 'object'
 
     if (hasInspector || hasLegacyDebugMode) {

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

@@ -6,7 +6,7 @@ import * as FFI from './ffi'
 import { CBOR } from './cbor'
 
 /** Represents a unique identifier for a {@link Document}. */
-export type DocumentIDValue = any // REFACTOR: get rid of any.
+export type DocumentIDValue = any 
 
 /** Represents a unique identifier for a {@link Document}. */
 export class DocumentID {

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

@@ -55,6 +55,7 @@ export class DocumentPath {
     if (typeof keyPathOrIndex === 'string') {
       const keyPath: string = keyPathOrIndex
       const validatedKeyPath = KeyPath.validate(keyPath)
+      // this.path can be an empty string.
       const absoluteKeyPath = KeyPath.withoutLeadingDot(`${this.path}${validatedKeyPath}`)
       return new DocumentPath(this.document, absoluteKeyPath, false)
     }
@@ -157,6 +158,7 @@ export class MutableDocumentPath {
     if (typeof keyPathOrIndex === 'string') {
       const keyPath: string = keyPathOrIndex
       const validatedKeyPath = KeyPath.validate(keyPath)
+      // this.path can be an empty string.
       const absoluteKeyPath = KeyPath.withoutLeadingDot(`${this.path}${validatedKeyPath}`)
       return new MutableDocumentPath(this.mutableDocument, absoluteKeyPath, false)
     }
@@ -241,7 +243,7 @@ export class MutableDocumentPath {
 
   /** @internal */
   '@ditto.increment'(amount: number) {
-   
+
     const documentHandle = Bridge.mutableDocument.handleFor(this.mutableDocument)
     FFI.documentIncrementCounter(documentHandle.deref(), this.path, amount)
 
@@ -294,7 +296,8 @@ export class MutableDocumentPath {
 
   /** @private */
   private recordUpdateResult(updateResult: UpdateResult) {
-
+    // OPTIMIZE: not sure how much of a performance hit this
+    // clone-modify-freeze dance implies. Investigate and fix.
     const updateResults = this.mutableDocument['@ditto.updateResults'].slice()
     updateResults.push(updateResult)
     Object.freeze(updateResults)

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

@@ -86,6 +86,7 @@ export class Document {
   /** @internal */
   constructor() {}
 
+  // TEMPORARY: helpers to deal with non-canonical IDs.
 
   /** @internal */
   static idCBOR(document: Document): Uint8Array {
@@ -107,7 +108,6 @@ export class Document {
 
 // -----------------------------------------------------------------------------
 
-
 /**
  * A representation of a {@link Document} that can be mutated via
  * {@link MutableDocumentPath}. You don't create or interact with
@@ -158,6 +158,7 @@ export class MutableDocument {
   /** @internal */
   readonly '@ditto.updateResults': UpdateResult[] = []
 
+  // TEMPORARY: helpers to deal with non-canonical IDs.
 
   /** @internal */
   static idCBOR(mutableDocument: MutableDocument): Uint8Array {

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

@@ -2,6 +2,12 @@
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
 //
 
+// NOTE: this is the last file to be rolled up. Typically, you'll use this to
+// tie up certain associations that would otherwise lead to import cycles. The
+// bridges are a good example of this: the type constructors for the bridged
+// types need to be registered with it, but can't do it at creation time of the
+// bridges, because anything that would require a certain bridge would
+// immediately require the bridged type, oftentimes leading to an import cycle.
 
 import { Attachment } from './attachment'
 import { Document, MutableDocument } from './document'

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

@@ -16,13 +16,16 @@ export type ErrorContext = Record<string, any>
 
 /** @see {@link FFIErrorMapping} */
 const DEFAULT_STATUS_CODE_MAPPING: FFIErrorMapping = {
+  // SDK-specific errors
   JsFloatingStoreOperation: ['internal', 'Internal inconsistency, an outstanding store operation was not awaited.'],
 
+  // DQL errors
   DqlQueryCompilation: ['query/invalid'],
   DqlInvalidQueryArgs: ['query/arguments-invalid'],
   DqlUnsupported: ['query/unsupported'],
   StoreQuery: ['query/execution'],
 
+  // Store errors
   StoreDocumentNotFound: ['store/document-not-found'],
   StoreDatabase: ['store/backend'],
   Crdt: ['store/crdt'],
@@ -185,12 +188,14 @@ export async function mapFFIErrorsAsync<T>(closure: () => Promise<T>, statusCode
  * @internal
  */
 type FFIErrorMapping = {
-
+  // statusCode needs to be `string` because it may be a negative number, which
+  // can't be used as an object key.
   [statusCode: string]: [ErrorCode, string?]
 }
 
 const translateFFIError = (ffiError: DittoFFIError, customStatusCodeMapping?: FFIErrorMapping, context?: ErrorContext): DittoError => {
-
+  // Convert the status code to a string because it may be a negative number,
+  // which can't be used as an index into an object.
   const statusCode = ffiError.code.toString()
 
   let code: ErrorCode, message: string | undefined

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

@@ -1,6 +1,9 @@
 //
 // Copyright © 2023 DittoLive Incorporated. All rights reserved.
 //
+// This internal module contains the Ditto FFI error type and helper functions
+// for working with it. Except for the feature flag helper, this module should
+// not depend on any other parts of the Ditto Javascript SDK.
 
 import * as dittoCore from './@ditto.core'
 
@@ -57,7 +60,8 @@ export class DittoFFIError extends Error {
    * message is empty
    */
   constructor(code: number | FFIResultErrorCode, messageOverride?: string, messageFallback?: string) {
-
+    // Call `ffiErrorMessage()` even when an override is provided to ensure that
+    // the thread-local error message is cleared.
     const threadLocalErrorMessage = ffiErrorMessage()
     super(messageOverride || threadLocalErrorMessage || messageFallback)
     this.code = code
@@ -92,6 +96,7 @@ export function throwOnErrorResult(ffiError: Pointer<FFIError> | null, ffiFuncti
     if (errorMsg == null) {
       errorMsg = `${ffiFunctionName}() failed with error code: ${errorCode}`
     } else {
+      // Remove prefix from error message, e.g. `<dql> ...`.
       errorMsg = errorMsg.replace(PREFIX_REGEX, '')
     }