@dittolive/ditto 4.7.4-rc.2 → 4.7.4

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

@@ -0,0 +1,557 @@
+//
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+
+import { Logger } from './logger'
+
+import type { Document, MutableDocument } from './document'
+import type { Attachment } from './attachment'
+import type { ConnectionRequest } from './connection-request'
+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'
+
+import type { Ditto } from './ditto'
+
+// Add bridged type name to debug, for example 'Ditto'.
+const DEBUG_TYPE_NAMES: string[] = []
+const DEBUG_ALL_TYPES = false
+
+// -----------------------------------------------------------------------------
+
+/**
+ * A JavaScript class that identifies a bridge's type and may be  used to create
+ * new instances.
+ */
+export type BridgeType<T extends object> = new (...args: any[]) => T
+
+/**
+ * A handle serves as a safe wrapper around a pointer to a native object.
+ *
+ * A bridge keeps track of all handles that have been created on its
+ * {@link Bridge.handlesByAddress | `handlesByAddress`} property, which allows
+ * enumerating all objects that are currently managed by the bridge.
+ *
+ * @internal */
+export class Handle<T extends object, FFIType> {
+  readonly bridge: Bridge<T, FFIType>
+  readonly pointer: FFI.Pointer<FFIType>
+
+  private objectWeakRef: WeakRef<T>
+
+  readonly isClosed: boolean = false
+  readonly isFinalized: boolean = false
+  readonly isUnregistered: boolean = false
+
+  /**
+   * Warning: Do not call this constructor directly. Use
+   * {@link Bridge.handleFor | `Bridge.<type>.handleFor()`} instead.
+   *
+   * @internal
+   */
+  constructor(bridge: Bridge<T, FFIType>, object: T, pointer: FFI.Pointer<FFIType>) {
+    this.bridge = bridge
+    this.objectWeakRef = new WeakRef(object)
+    this.pointer = pointer
+  }
+
+  /** The type of this handle's bridge */
+  get type(): BridgeType<T> {
+    return this.bridge.type
+  }
+
+  /**
+   * Returns the pointer associated with this handle.
+   *
+   * @throws {Error} if the object has already been closed, garbage collected,
+   * or unregistered from the bridge.
+   */
+  deref(): FFI.Pointer<FFIType> {
+    if (this.isClosed) {
+      throw new Error(`Bridging error: can't get pointer for an object that has been closed.`)
+    }
+
+    if (this.isFinalized) {
+      throw new Error(`Bridging error: can't get pointer for an object that has been finalized.`)
+    }
+
+    if (this.isUnregistered) {
+      throw new Error(`Bridging error: can't get pointer for an object that has been unregistered.`)
+    }
+
+    return this.pointer
+  }
+
+  /**
+   * Returns the pointer associated with this handle or `null` if the object
+   * has been closed, garbage collected, or unregistered.
+   */
+  derefOrNull(): FFI.Pointer<FFIType> | null {
+    if (this.isClosed) {
+      return null
+    }
+
+    if (this.isFinalized) {
+      return null
+    }
+
+    if (this.isUnregistered) {
+      return null
+    }
+
+    return this.pointer ?? null
+  }
+
+  /**
+   * Returns the object associated with this handle.
+   *
+   * @throws {Error} if the object has been closed, unregistered, or garbage collected,
+   * closed or unregistered.
+   */
+  object(): T {
+    const object = this.objectWeakRef.deref()
+    if (object == null) {
+      throw new Error(`Bridging error: ${this.bridge.type.name} object has been garbage collected.`)
+    }
+
+    if (this.isClosed) {
+      throw new Error(`Bridging error: ${this.bridge.type.name} object has been closed.`)
+    }
+
+    if (this.isUnregistered) {
+      throw new Error(`Bridging error: ${this.bridge.type.name} object has been unregistered.`)
+    }
+
+    return object
+  }
+
+  /**
+   * Returns the object associated with this handle or `null` if the object
+   * has been closed, unregistered, or garbage collected.
+   */
+  objectOrNull(): T | null {
+    return this.objectWeakRef.deref() ?? null
+  }
+
+  /** @internal */
+  toString(): string {
+    const pointer = this.derefOrNull()
+    return `{ Handle | type: ${this.bridge.type}, object: ${this.objectWeakRef.deref()}, FFI address: ${pointer?.addr}, FFI type: ${pointer?.type} }`
+  }
+
+  /** @internal */
+  bridgeWillClose() {
+    // @ts-expect-error setting readonly property
+    this.isClosed = true
+  }
+
+  /** @internal */
+  bridgeDidClose() {
+    // @ts-expect-error setting readonly property
+    this.pointer = null
+  }
+
+  /** @internal */
+  bridgeWillFinalize() {
+    // @ts-expect-error setting readonly property
+    this.isFinalized = true
+  }
+
+  /** @internal */
+  bridgeDidFinalize() {
+    // @ts-expect-error setting readonly property
+    this.pointer = null
+  }
+
+  /** @internal */
+  bridgeWillUnregister() {
+    // @ts-expect-error setting readonly property
+    this.isUnregistered = true
+  }
+
+  /** @internal */
+  bridgeDidUnregister() {
+    // @ts-expect-error setting readonly property
+    this.pointer = null
+  }
+}
+
+/**
+ * Use this for passing arrays of pointers to the FFI.
+ */
+export class Handles<T extends object, FFIType> {
+  readonly handles: Handle<T, FFIType>[]
+
+  /**
+   * @throws {Error} if any of the objects are not registered in the bridge.
+   * @throws {Error} if any of the objects have already been garbage collected.
+   */
+  constructor(bridge: Bridge<T, FFIType>, objects: T[]) {
+    this.handles = objects.map((object) => bridge.handleFor(object))
+  }
+
+  deref(): FFI.Pointer<FFIType>[] {
+    return this.handles.map((handle) => handle.deref())
+  }
+}
+
+/**
+ * A bridge manages memory allocated by the FFI that is used in the JS SDK.
+ *
+ * The main purpose of a bridge is keeping track of JavaScript objects that
+ * require access to memory allocated by the FFI. When such objects are
+ * garbage collected in JavaScript, the bridge instructs the FFI to free the
+ * corresponding memory. Every managed memory pointer corresponds to exactly
+ * one JS Object.
+ *
+ * There is a static `Bridge` instance for every class of objects that can be
+ * managed:
+ *
+ * - {@link Attachment}: `Bridge.attachment`
+ * - {@link Ditto}: `Bridge.ditto`
+ * - {@link Document}: `Bridge.document`
+ * - {@link MutableDocument}: `Bridge.mutableDocument`
+ * - {@link StaticTCPClient}: `Bridge.staticTCPClient`
+ * - {@link WebsocketClient}: `Bridge.websocketClient`
+ *
+ * Use `Bridge.<type>.handleFor()` to obtain a handle, which is a wrapper around
+ * the raw pointer, and `Bridge.<type>.bridge()` to get or create the matching
+ * object for a memory address.
+ *
+ * @internal */
+export class Bridge<T extends object, FFIType> {
+  readonly release: (pointer: FFI.Pointer<FFIType>) => void | Promise<void>
+
+  /**
+   * Creates a new bridge for objects of `type`. Requires a `release` function
+   * that is called whenever a registered object is garbage collected, passing
+   * the associated `pointer` to it. The release function is then responsible
+   * to free or drop the corresponding native object.
+   *
+   * **IMPORTANT**: The `type` of all bridges needs to be set in `epilogue.ts`
+   * after initiating the bridge instance. This helps avoid import cycles
+   * (otherwise anything importing the bridge instance, would also have to
+   * import the type, which usually leads to import cycles).
+   *
+   * @private
+   */
+  constructor(release: (pointer: FFI.Pointer<FFIType>) => void | Promise<void>) {
+    this.release = release
+    this.handlesByAddress = {}
+    this.handlesByObject = new WeakMap()
+    this.finalizationRegistry = new FinalizationRegistry(this.finalize.bind(this))
+
+    Bridge.all.push(new WeakRef(this))
+  }
+
+  /**
+   * The type of a bridge is the JavaScript `Class` of objects it represents.
+   *
+   * @internal */
+  get type(): BridgeType<T> {
+    if (this.internalType == null) {
+      throw new Error('Bridge type has not been registered yet.')
+    }
+    return this.internalType
+  }
+
+  /**
+   * All bridges' types have to be registered in `epilogue.ts` before using
+   * them.
+   *
+   * @internal */
+  registerType(value: BridgeType<T>) {
+    if (this.internalType === value) {
+      // Nothing to do.
+      return
+    }
+
+    if (this.internalType) {
+      throw new Error(`Can't register bridged type '${value.name}', another type was already registered: ${this.internalType}`)
+    }
+
+    this.internalType = value
+  }
+
+  /**
+   * Returns the handle for a bridged object.
+   *
+   * Use `handle.deref()` to get the pointer for the object at the time of use.
+   *
+   * @throws {Error} if the object is not registered.
+   *
+   * @internal
+   */
+  handleFor(object: T): Handle<T, FFIType> {
+    const handle = this.handlesByObject.get(object)
+    if (handle == null) {
+      throw new Error(`Bridging error: ${this.type.name} object is not currently registered in this bridge.`)
+    }
+
+    return handle
+  }
+
+  /**
+   * Returns a `Handles` instance for an array of objects.
+   *
+   * @internal
+   */
+  handlesFor(objects: T[]): Handles<T, FFIType> {
+    return new Handles(this, objects)
+  }
+
+  /**
+   * Convenience method, returns the object for the FFI `pointer` if registered,
+   * otherwise returns `undefined`. If the object associated with the `pointer`
+   * has been unregistered before, returns `undefined`, too.
+   *
+   * @internal
+   */
+  objectFor(pointer: FFI.Pointer<FFIType>): T | undefined {
+    const handle = this.handlesByAddress[pointer.addr]
+    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()
+  }
+
+  /**
+   * Returns the object for the FFI `pointer` if registered. Otherwise, calls
+   * the passed in `create` function to create a new object, which it then
+   * returns after registering. If no `create` function is given, uses the
+   * type of the bridge as a constructor and creates a new instance of it
+   * without passing any parameters.
+   *
+   * @param pointer reference to the FFi instance for the object
+   * @param objectOrCreate can either be the JS object, or a function that returns the instance when called. If undefined, an object is created based on the Bridge type.
+   * @throws {Error} if `objectOrCreate` is a function that returns an object that is not an instance of the bridge's type.
+   * @internal
+   */
+  bridge(pointer: FFI.Pointer<FFIType>, objectOrCreate?: T | (() => T)): T {
+    const existingObject = this.objectFor(pointer)
+    if (existingObject) {
+      return existingObject
+    }
+
+    if (!objectOrCreate) {
+      objectOrCreate = () => {
+        return Reflect.construct(this.type, [])
+      }
+    }
+
+    let object: T
+    if (typeof objectOrCreate === 'function') {
+      object = objectOrCreate()
+      if (!(object instanceof this.type)) {
+        throw new Error(`Can't bridge, expected passed in create function to return a ${this.type.name} object but got: ${object}`)
+      }
+    } else {
+      object = objectOrCreate
+    }
+
+    this.register(object, pointer)
+    return object
+  }
+
+  /**
+   * Registers an instance in this bridge's {@link FinalizationRegistry}.
+   *
+   * This causes the FFI to drop the memory linked to the object as soon as it
+   * is garbage collected in JavaScript.
+   *
+   * If you want to control the order with which a number of objects' memory is
+   * dropped, use {@link Bridge.unregister | Bridge.unregister()}
+   *
+   * @private */
+  register(object: T, pointer: FFI.Pointer<FFIType>) {
+    const objectType = object.constructor as BridgeType<T>
+    if (objectType !== this.type) throw new Error(`Can't register, bridge is configured for type ${this.type.name} but passed in object is of type ${objectType.name}`)
+
+    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}`)
+    if (existingPointer == null && existingHandle != null) throw new Error(`Internal inconsistency, trying to register an object which has a handle entry but no associated pointer: ${objectType.name} ${object}`)
+
+    const handle = new Handle<T, FFIType>(this, object, pointer)
+    this.handlesByAddress[pointer.addr] = handle
+    this.handlesByObject.set(object, handle)
+
+    this.finalizationRegistry.register(object as object, handle, object as object)
+
+    if (DEBUG_TYPE_NAMES.includes(this.type.name) || DEBUG_ALL_TYPES) {
+      Logger.debug(`[VERBOSE] Bridge REGISTERED a new instance of ${this.type.name}, current count: ${Object.keys(this.handlesByAddress).length}`)
+    }
+  }
+
+  /**
+   * Removes an instance from this bridge's {@link FinalizationRegistry}.
+   *
+   * This lets you control the order with which memory is dropped in the FFI.
+   * After calling this function, manually call the FFI function to drop the
+   * memory then finally delete the JavaScript instance.
+   *
+   * @internal */
+  unregister(object: T) {
+    const objectType = object.constructor
+    const bridgeType = this.type
+    if (objectType !== bridgeType) throw new Error(`Can't unregister, bridge is configured for type ${bridgeType.name} but passed in object is of type ${objectType.name}`)
+
+    const handle = this.handlesByObject.get(object)
+    if (handle == null) throw new Error(`Can't unregister, object has not been registered before: ${object}`)
+    if (handle.type !== bridgeType) throw new Error(`Internal inconsistency, trying to unregister an object that has a handle with a different type than that of the bridge: ${handle}`)
+    if (handle.objectOrNull() !== object) throw new Error(`Internal inconsistency, trying to unregister an object whose associated handle holds a different object: ${handle}`)
+
+    if (handle.isClosed) throw new Error(`Can't unregister, object has been closed before: ${object}`)
+    if (handle.isFinalized) throw new Error(`Can't unregister, object has been finalized before: ${object}`)
+    if (handle.isUnregistered) throw new Error(`Can't unregister, object has been unregistered already: ${object}`)
+
+    handle.bridgeWillUnregister()
+    this.finalizationRegistry.unregister(object as object)
+    delete this.handlesByAddress[handle.pointer.addr]
+    this.handlesByObject.delete(object)
+    handle.bridgeDidUnregister()
+
+    if (DEBUG_TYPE_NAMES.includes(this.type.name) || DEBUG_ALL_TYPES) {
+      Logger.debug(`[VERBOSE] Bridge UNREGISTERED an instance of ${this.type.name}, current count: ${Object.keys(this.handlesByAddress).length}`)
+    }
+  }
+
+  /** @internal */
+  unregisterAll() {
+    if (DEBUG_TYPE_NAMES.includes(this.type.name) || DEBUG_ALL_TYPES) {
+      Logger.debug(`[VERBOSE] Unregistering ALL bridged instances of type ${this.type.name}.`)
+    }
+
+    for (const handle of Object.values(this.handlesByAddress)) {
+      const object = handle.object()
+      if (object) {
+        this.unregister(object)
+      }
+    }
+  }
+
+  /**
+   * Closes the object by calling `release()` and `null`-ing its pointer, such
+   * that its handle can't be `deref()`-ed afterwards.
+   *
+   * @internal */
+  async close(object: T): Promise<void> {
+    const objectType = object.constructor
+    const bridgeType = this.type
+    if (objectType !== bridgeType) throw new Error(`Can't close, bridge is configured for type ${bridgeType.name} but passed in object is of type ${objectType.name}`)
+
+    const handle = this.handlesByObject.get(object)
+    if (handle == null) throw new Error(`Can't close an object that has not been registered before: ${object}`)
+    if (handle.type !== bridgeType) throw new Error(`Internal inconsistency, trying to close an object that has a handle with a different type than that of the bridge: ${handle}`)
+
+    if (handle.isUnregistered) throw new Error(`Can't close object, object has been unregistered.`)
+    if (handle.isFinalized) throw new Error(`Internal inconsistency, trying to close an object that has already been finalized.`)
+    if (handle.isClosed) return
+
+    const pointer = handle.pointer
+    if (!pointer) throw new Error(`Internal inconsistency, trying to close an object whose pointer is null.`)
+
+    handle.bridgeWillClose()
+    delete this.handlesByAddress[pointer.addr]
+    await this.release(pointer)
+    handle.bridgeDidClose()
+
+    if (DEBUG_TYPE_NAMES.includes(this.type.name) || DEBUG_ALL_TYPES) {
+      Logger.debug(`[VERBOSE] Bridge CLOSED an instance of ${this.type.name}, current count: ${Object.keys(this.handlesByAddress).length}`)
+    }
+  }
+
+  /** @internal */
+  get count(): number {
+    return Object.keys(this.handlesByAddress).length
+  }
+
+  /**
+   * Keeps track of all bridges for debugging and test purposes. With this, we
+   * can iterate over all bridges and make sure everything is deallocated after
+   * a test, or a suite of tests, has run.
+   *
+   * @internal */
+  static readonly all: Array<WeakRef<Bridge<any, any>>> = []
+
+  /** @internal */
+  static readonly attachment = new Bridge<Attachment, FFI.AttachmentHandle>(FFI.freeAttachmentHandle)
+
+  /** @internal */
+  static readonly connectionRequest = new Bridge<ConnectionRequest, FFI.FFIConnectionRequest>(FFI.connectionRequestFree)
+
+  /** @internal */
+  static readonly document = new Bridge<Document, FFI.FFIDocument>(FFI.documentFree)
+
+  /** @internal */
+  static readonly mutableDocument = new Bridge<MutableDocument, FFI.FFIDocument>(FFI.documentFree)
+
+  /** @internal */
+  static readonly queryResult = new Bridge<QueryResult, FFI.FFIQueryResult>(FFI.queryResultFree)
+
+  /** @internal */
+  static readonly queryResultItem = new Bridge<QueryResultItem, FFI.FFIQueryResultItem>(FFI.queryResultItemFree)
+
+  /** @internal */
+  static readonly staticTCPClient = new Bridge<StaticTCPClient, FFI.FFIStaticTCPClient>(FFI.staticTCPClientFreeHandle)
+
+  /** @internal */
+  static readonly websocketClient = new Bridge<WebsocketClient, FFI.FFIWebsocketClient>(FFI.websocketClientFreeHandle)
+
+  /** @internal */
+  static readonly ditto = new Bridge<Ditto, FFI.FFIDitto>(async (dittoPointer) => {
+    await FFI.dittoClearPresenceCallback(dittoPointer)
+    await FFI.dittoShutdown(dittoPointer)
+    FFI.dittoFree(dittoPointer)
+  })
+
+  // ------ Private ------
+
+  private internalType: BridgeType<T> | null = null
+
+  /**
+   * All bridged objects' {@link Handle} entries for lookup by pointer address.
+   */
+  private handlesByAddress: { [key: FFI.Pointer<T>['addr']]: Handle<T, FFIType> }
+
+  /**
+   * Look up a handle given its object.
+   *
+   * As `WeakMap` does not allow for enumeration, use `this.handlesByAddress` to
+   * iterate over all handles.
+   */
+  private handlesByObject: WeakMap<T, Handle<T, FFIType>>
+
+  private finalizationRegistry: FinalizationRegistry<any>
+
+  private async finalize(handle: Handle<T, FFIType>): Promise<void> {
+    if (handle.isFinalized) throw new Error(`Internal inconsistency, trying to finalize an object that has already been finalized.`)
+    if (handle.isUnregistered) throw new Error(`Internal inconsistency, trying to finalize an object that has been unregistered before.`)
+
+    handle.bridgeWillFinalize()
+
+    if (!handle.isClosed) {
+      const pointer = handle.pointer
+      if (!pointer) throw new Error(`Internal inconsistency, trying to finalize an object whose pointer is null.`)
+
+      delete this.handlesByAddress[pointer.addr]
+      await this.release(pointer)
+    }
+
+    handle.bridgeDidFinalize()
+
+    if (DEBUG_TYPE_NAMES.includes(this.type.name) || DEBUG_ALL_TYPES) {
+      Logger.debug(`[VERBOSE] Bridge FINALIZED an instance of ${this.type.name}, current count: ${Object.keys(this.handlesByAddress).length}`)
+    }
+  }
+}

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

@@ -0,0 +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/cbor.ts

@@ -0,0 +1,20 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import { CBOR as CBORRedux } from './@cbor-redux'
+
+/** @internal */
+export class CBOR {
+  /** @internal */
+  static encode(data: any, replacer?: (key: any, value: any) => any): Uint8Array {
+    const arrayBuffer = CBORRedux.encode(data, replacer)
+    return new Uint8Array(arrayBuffer)
+  }
+
+  /** @internal */
+  static decode(data: Uint8Array, reviver?: (key: any, value: any) => any): any {
+    const arrayBuffer = data.buffer
+    return CBORRedux.decode(arrayBuffer, reviver)
+  }
+}

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

@@ -0,0 +1,73 @@
+//
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
+//
+
+import type { DocumentValue } from './document'
+import type { DocumentID, DocumentIDValue } from './document-id'
+import type { WriteStrategy, QueryArguments } from './essentials'
+import type { Store } from './store'
+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
+}
+
+export interface CollectionInterface {
+  /** The name of the collection. */
+  readonly name: string
+
+  /**
+   * The store this collection belongs to.
+   * @internal
+   */
+  readonly store: Store
+
+  /**
+   * Search for documents in this collection using the provided query string.
+   *
+   * @param query The query to run against the collection.
+   * @param queryArgs These arguments replace placeholders in the provided
+   * query.
+   */
+  find(query: string, queryArgs?: QueryArguments): BasePendingCursorOperation
+
+  /**
+   * Convenience method, equivalent to calling {@link find | find()} and passing
+   * the query `"true"`.
+   */
+  findAll(): BasePendingCursorOperation
+
+  /**
+   * Find documents given a specific ID.
+   *
+   * Use the returned cursor instance to chain operations on the search result.
+   *
+   * @param id The document's identifier
+   */
+  findByID(id: DocumentID | DocumentIDValue): BasePendingIDSpecificOperation
+
+  /**
+   * TEMPORARY: helper to deal with non-canonical IDs.
+   *
+   * @internal
+   */
+  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`.
+   *
+   * @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>
+}