@dittolive/ditto 4.5.1-experimental.aarch64-linux.1.aarch64 → 4.5.2-rc.2

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

@@ -0,0 +1,233 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+import { Bridge } from './bridge'
+import { Observer } from './observer'
+import { ObserverManager } from './observer-manager'
+import type { Ditto } from './ditto'
+
+/** Types of connections that can be established between two peers. */
+export type ConnectionType = 'P2PWiFi' | 'WebSocket' | 'AccessPoint' | 'Bluetooth'
+
+// -----------------------------------------------------------------------------
+
+/**
+ * An opaque address uniquely identifying another peer on the Ditto mesh
+ * network.
+ *
+ * IMPORTANT: You should not rely on the individual components of the address,
+ * those can change at any time. Please use
+ * {@link addressToString | addressToString()} to compare individual addresses
+ * with each other.
+ */
+export type Address = {
+  siteId: number | BigInt
+  pubkey: Uint8Array
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Returns a string representation of the given address. Use this function
+ * to compare multiple addresses or whenever you need the address to be a key
+ * in a hash object.
+ */
+export function addressToString(address: Address) {
+  return `${address.siteId}-${address.pubkey}`
+}
+
+// -----------------------------------------------------------------------------
+
+/** Represents a connection between two peers on the Ditto mesh network. */
+export type Connection = {
+  /** Unique identifier for the connection.
+   *
+   * These IDs are stable for any two peer keys and a given connection type.
+   *
+   * **Example ID**
+   *
+   * "1<->2:Bluetooth"
+   */
+  id: string
+
+  /** Type of transport enabling this connection. */
+  connectionType: ConnectionType
+
+  /**
+   * Peer key of the peer at one end of the connection.
+   *
+   * This peer key is lexicographically smaller than `peer2`.
+   */
+  peer1: Uint8Array
+
+  /**
+   * Peer key of the peer at the other end of the connection.
+   *
+   * This peer key is lexicographically larger than `peer1`.
+   */
+  peer2: Uint8Array
+
+  /*
+   * Gets an estimate of distance to the remote peer. This value is inaccurate.
+   * The environment, hardware, and several other factors can greatly affect
+   * this value. It is currently derived from RSSI. Can be (yet) unknown and
+   * therefore not set.
+   */
+  approximateDistanceInMeters?: number
+}
+
+// -----------------------------------------------------------------------------
+
+/** An instance of Ditto taking part in the Ditto mesh network. */
+export type Peer = {
+  /**
+   * Address to contact this peer via Ditto Bus, unique with a Ditto mesh
+   * network.
+   */
+  address: Address
+
+  /**
+   * The peer key is a unique identifier for a given peer, equal to or derived
+   * from the cryptographic public key used to authenticate it.
+   *
+   * NOTE: This will be be empty when a peer is not updated to the latest
+   * version of the SDK.
+   */
+  peerKey: Uint8Array
+
+  /**
+   * The human-readable device name of the peer. This defaults to the hostname
+   * but can be manually set by the application developer of the other peer.
+   * It is not necessarily unique.
+   */
+  deviceName: string
+
+  /**
+   * Currently active connections of the peer.
+   */
+  connections: Connection[]
+
+  /**
+   * Indicates whether the peer is connected to Ditto Cloud.
+   */
+  isConnectedToDittoCloud: boolean
+
+  /** The operating system the peer is running on, `undefined` if (yet) unknown. */
+  os?: string
+
+  /** The Ditto SDK version the peer is running with, `undefined` if (yet) unknown. */
+  dittoSDKVersion?: string
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Represents the Ditto mesh network of peers and their connections between each
+ * other. The `localPeer` is the entry point, all others are remote peers known
+ * by the local peer (either directly or via other remote peers).
+ */
+export type PresenceGraph = {
+  /**
+   * Returns the local peer (usually the peer that is represented by the
+   * currently running Ditto instance). The `localPeer` is the entry point, all
+   * others are remote peers known by the local peer (either directly or via
+   * other remote peers).
+   */
+  localPeer: Peer
+
+  /**
+   * Returns all remote peers known by the `localPeer`, either directly or via
+   * other remote peers.
+   */
+  remotePeers: Peer[]
+
+  /**
+   * Returns the underlying CBOR data if the presence graph has been initialized
+   * with CBOR. All of Ditto API returning a presence graph has this property
+   * set.
+   */
+  underlyingCBOR?: Uint8Array
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * The entrypoint for all actions that relate presence of other peers known by
+ * the current peer, either directly or through other peers.
+ *
+ * You don't create one directly but can access it from a particular `Ditto`
+ * instance via its `presence` property.
+ */
+export class Presence {
+  /** The Ditto instance this object belongs to. */
+  readonly ditto: Ditto
+
+  /**
+   * Returns the current presence graph capturing all known peers and
+   * connections between them.
+   */
+  get graph(): PresenceGraph {
+    const ditto = this.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    return ditto.deferClose(() => {
+      const graphJSONString = FFI.dittoPresenceV3(dittoHandle.deref())
+      return JSON.parse(graphJSONString)
+    })
+  }
+
+  /**
+   * Request information about Ditto peers in range of this device.
+   *
+   * This method returns an observer which should be held as long as updates are
+   * required. A newly registered observer will have a peers update delivered to
+   * it immediately. From then on it will be invoked repeatedly when Ditto
+   * devices come and go, or the active connections to them change.
+   */
+  observe(didChangeHandler: (presenceGraph: PresenceGraph) => void): Observer {
+    const observerToken = this.observerManager.addObserver(didChangeHandler)
+    const observer = new Observer(this.observerManager, observerToken, { stopsWhenFinalized: true })
+
+    didChangeHandler(this.graph)
+
+    return observer
+  }
+
+  /** @internal */
+  constructor(ditto: Ditto) {
+    this.ditto = ditto
+
+    this.observerManager = new ObserverManager('PresenceObservation', {
+      keepAlive: ditto.keepAlive,
+
+      register: (callback) => {
+        const ditto = this.ditto
+        const dittoHandle = Bridge.ditto.handleFor(ditto)
+        ditto.deferClose(() => {
+          FFI.dittoRegisterPresenceV3Callback(dittoHandle.deref(), callback)
+        })
+      },
+
+      unregister: () => {
+        const ditto = this.ditto
+        const dittoHandle = Bridge.ditto.handleFor(ditto)
+        ditto.deferClose(() => {
+          FFI.dittoClearPresenceV3Callback(dittoHandle.deref())
+        })
+      },
+
+      process: (presenceGraphJSONString) => {
+        const presenceGraph = JSON.parse(presenceGraphJSONString)
+        return [presenceGraph]
+      },
+    })
+  }
+
+  /** @internal */
+  close() {
+    this.observerManager.close()
+  }
+
+  private observerManager: ObserverManager
+}

package/react-native/src/sources/query-result-item.ts

@@ -0,0 +1,116 @@
+//
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+import { CBOR } from './cbor'
+import { Bridge } from './bridge'
+import { Document } from './document'
+
+/**
+ * Represents a single match of a DQL query, similar to a “row” in SQL terms.
+ * It’s a reference type serving as a “cursor”, allowing for efficient access of
+ * the underlying data in various formats.
+ *
+ * The {@link QueryResultItem.value | value } property is lazily
+ * materialized and kept in memory until it goes out of scope. To reduce the
+ * memory footprint, structure your code such that items can be processed as a
+ * stream, i.e. one by one (or in batches) and
+ * {@link QueryResultItem.dematerialize | dematerialize() } them
+ * right after use.
+ */
+export class QueryResultItem {
+  /**
+   * Returns the content as a materialized object.
+   *
+   * The item's value is
+   * {@link QueryResultItem.materialize | materialized() } on first access
+   * and subsequently on each access after performing
+   * {@link QueryResultItem.dematerialize | dematerialize() }. Once
+   * materialized, the value is kept in memory until explicitly
+   * {@link QueryResultItem.dematerialize | dematerialize() }-ed or the item
+   * goes out of scope.
+   *
+   * Note: This property is very similar to {@link Document.value}.
+   */
+  get value(): any {
+    this.materialize()
+    if (this.materializedValue === undefined) {
+      throw new Error('Internal Error: Materialized value is undefined')
+    }
+    return this.materializedValue
+  }
+
+  /**
+   * Returns `true` if value is currently held materialized in memory, otherwise
+   * returns `false`.
+   *
+   * See {@link QueryResultItem.materialize | materialize()} and
+   * {@link QueryResultItem.dematerialize | dematerialize()}.
+   */
+  get isMaterialized(): boolean {
+    return this.materializedValue !== undefined
+  }
+
+  /**
+   * Loads the CBOR representation of the item's content, decodes it as an
+   * object so it can be accessed via {@link QueryResultItem.value | value }.
+   * Keeps the object in memory until
+   * {@link QueryResultItem.dematerialize | dematerialize() } is called. No-op
+   * if {@link QueryResultItem.value | value } is already materialized.
+   */
+  materialize(): void {
+    if (!this.isMaterialized) {
+      const cborValue = this.cborData()
+      let materializedValue: any
+      try {
+        materializedValue = CBOR.decode(cborValue)
+      } catch (error: any) {
+        throw new Error(`Internal inconsistency: CBOR decoding error while materializing result item: ${error.message}`)
+      }
+
+      if (materializedValue === undefined) {
+        throw new Error('Internal inconsistency: Materialized value is undefined')
+      }
+
+      this.materializedValue = materializedValue
+    }
+  }
+
+  /**
+   * Releases the materialized value from memory. No-op if item is not
+   * materialized.
+   */
+  dematerialize(): void {
+    this.materializedValue = undefined
+  }
+
+  /**
+   * Returns the content of the item as CBOR data.
+   *
+   * Important: The returned CBOR data is not cached, make sure to call this
+   * method once and keep it for as long as needed.
+   */
+  cborData(): Uint8Array {
+    const resultHandle = Bridge.dqlResult.handleFor(this)
+    return FFI.dqlResultCBOR(resultHandle.deref())
+  }
+
+  /**
+   * Returns the content of the item as a JSON string.
+   *
+   * Important: The returned JSON string is not cached, make sure to call this
+   * method once and keep it for as long as needed.
+   */
+  jsonString(): string {
+    const resultHandle = Bridge.dqlResult.handleFor(this)
+    return FFI.dqlResultJSON(resultHandle.deref())
+  }
+
+  // ----------------------------------------------------------- Internal ------
+
+  private materializedValue: any
+
+  /** @internal */
+  constructor() {}
+}

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

@@ -0,0 +1,55 @@
+//
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
+//
+import * as FFI from './ffi'
+
+import { Bridge } from './bridge'
+import { QueryResultItem } from './query-result-item'
+import { DocumentID } from './document-id'
+
+import type { Store } from './store'
+
+/**
+ * Represents results returned when executing a DQL query containing a
+ * {@link QueryResultItem} for each match.
+ *
+ * More info, such as metrics, will be provided in the near future.
+ */
+export class QueryResult {
+  /**
+   * Individual items matching a DQL query.
+   */
+  readonly items: QueryResultItem[]
+
+  /**
+   * IDs of documents that were mutated _locally_ by a _mutating_ DQL query
+   * passed to {@link Store.execute | `execute()`}. Empty array if no documents
+   * have been mutated.
+   *
+   * **Note: Query results received from a {@link StoreObserver} never contain
+   * mutated document IDs because a store observer is always registered using a
+   * non-mutating `SELECT` query.
+   *
+   * **Important:** The returned document IDs are not cached, make sure to call
+   * this method once and keep the return value for as long as needed.
+   *
+   * @returns an array of document IDs
+   */
+  mutatedDocumentIDs(): DocumentID[] {
+    const responseHandle = Bridge.dqlResponse.handleFor(this)
+    const affectedCBORIDs = FFI.dqlMutatedDocumentIDs(responseHandle.deref())
+    return affectedCBORIDs.map((id) => new DocumentID(id, true))
+  }
+
+  // ----------------------------------------------------- Internal ------------
+
+  /** @internal */
+  constructor(responsePointer: FFI.Pointer<FFI.FFIDqlResponse>) {
+    if (responsePointer == null) {
+      throw new Error('Internal inconsistency, failed to initialize query result without a response pointer')
+    }
+
+    const results = FFI.dqlResponseResults(responsePointer)
+    this.items = results.map((r) => Bridge.dqlResult.bridge(r))
+  }
+}

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

@@ -0,0 +1,95 @@
+//
+// 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'
+
+/**
+ * Represents a CRDT register that can be upserted as part of a document or
+ * assigned to a property during an update of a document.
+ */
+export class Register {
+  /** Returns the value of the register. */
+  get value(): any {
+    return this['@ditto.value']
+  }
+
+  /**
+   * Creates a new Register that can be used as part of a document's content.
+   */
+  constructor(value: any) {
+    this['@ditto.value'] = value
+  }
+
+  /** @internal */
+  static '@ditto.create'(mutableDocument, path, value) {
+    const register = mutableDocument ? new (MutableRegister as any)(value, privateToken) : new Register(value)
+    register['@ditto.mutableDocument'] = mutableDocument
+    register['@ditto.path'] = path
+    register['@ditto.value'] = value
+    return register
+  }
+
+  /** @internal */
+  protected '@ditto.mutableDocument': any
+
+  /** @internal */
+  protected '@ditto.path': any
+
+  /** @internal */
+  protected '@ditto.value': any
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Represents a mutable CRDT register that can be set to a specific value when
+ * updating a document.
+ *
+ * This class can't be instantiated directly, it's returned automatically for
+ * any register property of a document within an update block via {@link MutableDocumentPath.register}.
+ */
+export class MutableRegister extends Register {
+  /** Returns the value of the register. */
+  get value(): any {
+    return super.value
+  }
+
+  /**
+   * Convenience setter, equivalent to {@link set | set()}.
+   */
+  set value(value: any) {
+    this.set(value)
+  }
+
+  /**
+   * Sets the register to the provided value.
+   *
+   * Only valid within the `update` closure of
+   * {@link PendingCursorOperation.update | PendingCursorOperation.update()} and
+   * {@link PendingIDSpecificOperation.update | PendingIDSpecificOperation.update()},
+   * otherwise an exception is thrown.
+   */
+  set(value: any) {
+    const mutableDocument = this['@ditto.mutableDocument']
+    const path = this['@ditto.path']
+
+    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
+  }
+
+  /** @internal */
+  constructor(value: any) {
+    if (arguments[1] === privateToken) {
+      super(value)
+    } else {
+      throw new Error(`MutableRegister constructor is for internal use only.`)
+    }
+  }
+}

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

@@ -0,0 +1,177 @@
+//
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+
+import { Bridge } from './bridge'
+import { Ditto } from './ditto'
+
+/**
+ * Specifies which peers to replicate the small peer info to when enabled.
+ *
+ * Possible values are:
+ *
+ * - `LocalPeerOnly`: no replication (default)
+ * - `BigPeerOnly`: replicate to the Big Peer
+ */
+export type SmallPeerInfoSyncScope = 'LocalPeerOnly' | 'BigPeerOnly'
+
+/**
+ * The entrypoint for small peer user info collection. Small peer info consists
+ * of information gathered into a system collection on a regular interval and
+ * optionally synced to the Big Peer for device dashboard and debugging
+ * purposes.
+ *
+ * An instance of this class is available on each `Ditto` instance via its
+ * {@link Ditto.smallPeerInfo | `smallPeerInfo`} property. Instantiating this
+ * class directly is not supported.
+ */
+export class SmallPeerInfo {
+  /**
+   * Indicates whether small peer info collection is currently enabled, defaults
+   * to `false`.
+   *
+   * **Note**: whether the background ingestion process is enabled or not is a
+   * separate decision to whether this information is allowed to sync to other
+   * peers (including the big peer). This is controlled by
+   * {@link getSyncScope | getSyncScope()} and
+   * {@link setSyncScope | setSyncScope()}.
+   */
+  get isEnabled(): boolean {
+    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
+    return this.ditto.deferClose(() => {
+      return FFI.dittoSmallPeerInfoGetIsEnabled(dittoHandle.deref())
+    })
+  }
+
+  /**
+   * Set whether small peer info collection is enabled.
+   *
+   * @throws when set to a non-boolean value.
+   */
+  set isEnabled(newValue: boolean) {
+    if (typeof newValue !== 'boolean') {
+      throw new TypeError(`Expected boolean, got ${typeof newValue}`)
+    }
+
+    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
+    this.ditto.deferClose(() => {
+      FFI.dittoSmallPeerInfoSetEnabled(dittoHandle.deref(), newValue)
+    })
+  }
+
+  /**
+   * The metadata associated with the small peer info.
+   *
+   * Small peer info metadata is a free-form, user-provided JSON object that
+   * is inserted into the small peer info system document at each collection
+   * interval.
+   */
+  get metadata(): Record<string, any> {
+    return JSON.parse(this.metadataJSONString)
+  }
+
+  /**
+   * Set the metadata associated with the small peer info.
+   *
+   * The metadata must be a JSON-serializable object that conforms to the
+   * following constraints:
+   *
+   * - Must be a JSON object (not an array, string, number, etc.)
+   * - The size when encoded as JSON must be less than 128 KB
+   * - May only be nested up to 2 levels deep
+   *
+   * @example <caption>Valid metadata</caption>
+   * ditto.smallPeerInfo.metadata = {
+   *  "foo": "bar",
+   *  "nested": {
+   *    "inner": "value"
+   *   }
+   * }
+   *
+   * @example <caption>Invalid metadata</caption>
+   * // This is invalid and results in an error.
+   * ditto.smallPeerInfo.metadata = {
+   *   "foo": "bar",
+   *   "nested": {
+   *     "illegal": {
+   *       "inner": "value"
+   *     }
+   *   }
+   * }
+   *
+   * @throws when set to a value that violates any of the constraints listed
+   * above.
+   */
+  set metadata(metadata: Record<string, any>) {
+    this.metadataJSONString = JSON.stringify(metadata)
+  }
+
+  /**
+   * The metadata associated with the small peer info, as a JSON string.
+   */
+  get metadataJSONString(): string {
+    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
+    return this.ditto.deferClose(() => {
+      return FFI.dittoSmallPeerInfoGetMetadata(dittoHandle.deref())
+    })
+  }
+
+  /**
+   * Set the metadata associated with the small peer info, as a JSON string.
+   *
+   * @see {@link SmallPeerInfo.metadata | `metadata`} for more information on
+   * valid values.
+   * @throws when set to a value that violates any of the constraints listed in
+   * {@link SmallPeerInfo.metadata | `metadata`}.
+   */
+  set metadataJSONString(metadata: string) {
+    if (typeof metadata !== 'string') {
+      throw new TypeError(`Expected string, got ${typeof metadata}`)
+    }
+    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
+    this.ditto.deferClose(() => {
+      // throws if any validation errors occur
+      FFI.dittoSmallPeerInfoSetMetadata(dittoHandle.deref(), metadata)
+    })
+  }
+
+  /**
+   * Determines which "kind" of peers the small peer info will be
+   * replicated to.
+   *
+   * Defaults to `LocalPeerOnly`, which means no replication. Set this to
+   * `BigPeerOnly` to replicate collected info to the Big Peer.
+   */
+  async getSyncScope(): Promise<SmallPeerInfoSyncScope> {
+    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
+    return this.ditto.deferCloseAsync(async () => {
+      return FFI.dittoSmallPeerInfoGetSyncScope(dittoHandle.deref())
+    })
+  }
+
+  /**
+   * Set the sync scope.
+   *
+   * See {@link getSyncScope} for more information.
+   *
+   * @param syncScope the new sync scope.
+   * @throws when set to a value other than `BigPeerOnly` or `LocalPeerOnly`.
+   */
+  async setSyncScope(syncScope: SmallPeerInfoSyncScope): Promise<void> {
+    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
+    return this.ditto.deferCloseAsync(async () => {
+      return FFI.dittoSmallPeerInfoSetSyncScope(dittoHandle.deref(), syncScope as any)
+    })
+  }
+
+  // ----------------------------------------------------------- Internal ------
+
+  private ditto: Ditto
+
+  /** @internal */
+  constructor(ditto: Ditto) {
+    this.ditto = ditto
+  }
+}

package/react-native/src/sources/static-tcp-client.ts

@@ -0,0 +1,6 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+/** @internal */
+export class StaticTCPClient {}