@dittolive/ditto 4.7.3 → 4.7.4-rc.2

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

@@ -1,427 +0,0 @@
-//
-// Copyright © 2021 DittoLive Incorporated. All rights reserved.
-//
-
-import * as FFI from './ffi'
-import { Bridge } from './bridge'
-import { ConnectionRequestHandler } from './connection-request'
-import { Logger } from './logger'
-import { Observer } from './observer'
-import { ObserverManager } from './observer-manager'
-import { DittoError, mapFFIErrors, mapFFIErrorsAsync } from './error'
-
-import type { Ditto } from './ditto'
-import type { ConnectionRequestAuthorization } from './connection-request'
-
-/** 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.
-   *
-   * @deprecated Use {@link peerKeyString} instead.
-   */
-  peerKey: Uint8Array
-
-  /**
-   * 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.
-   */
-  peerKeyString: string
-
-  /**
-   * Metadata associated with the peer, empty dictionary by default.
-   *
-   * Use `ditto.presence.setPeerMetadata()` or
-   * `ditto.presence.setPeerMetadataJSONData()` to set this value.
-   *
-   * This will be empty when a peer is only connected via a WebSocket
-   * connection.
-   *
-   * @see {@link Presence.peerMetadata | `ditto.presence.peerMetadata`} for
-   * details on usage of metadata.
-   */
-  peerMetadata: Record<string, any>
-
-  /**
-   * Metadata associated with the peer by the identity service.
-   *
-   * Use an authentication webhook to set this value. See Ditto's online
-   * documentation for more information on how to configure an authentication
-   * webhook.
-   */
-  identityServiceMetadata: Record<string, any>
-
-  /**
-   * 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
-
-  /**
-   * Set this handler to control which peers in a Ditto mesh can connect to the
-   * current peer.
-   *
-   * Each peer in a Ditto mesh will attempt to connect to other peers that it
-   * can reach. By default, the mesh will try and establish connections that
-   * optimize for the best overall connectivity between peers. However, you can
-   * set this handler to assert some control over which peers you connect to.
-   *
-   * If set, this handler is called for every incoming connection request from a
-   * remote peer and is passed the other peer's `peerKey`, `peerMetadata`, and
-   * `identityServiceMetadata`. The handler can then accept or reject the
-   * request by returning an according {@link ConnectionRequestAuthorization}
-   * value. When the connection request is rejected, the remote peer may retry
-   * the connection request after a short delay.
-   *
-   * Connection request handlers must reliably respond to requests within a
-   * short time. If a handler takes too long to respond or throws an exception,
-   * the connection request will be denied. The response timeout is currently 10
-   * seconds but may be subject to change in future releases.
-   *
-   * @see {@link peerMetadata | peerMetadata()}
-   */
-  get connectionRequestHandler(): ConnectionRequestHandler | null {
-    return this._connectionRequestHandler
-  }
-
-  /**
-   * @throws TypeError: if the given handler is not a function.
-   */
-  set connectionRequestHandler(handler: ConnectionRequestHandler | null) {
-    let wrappedHandler = null
-
-    if (handler != null) {
-      if (typeof handler !== 'function') {
-        throw new TypeError(`Expected parameter 'handler' to be a function but got ${typeof handler} instead`)
-      }
-
-      wrappedHandler = async (connectionRequest: FFI.Pointer<FFI.FFIConnectionRequest>) => {
-        const request = Bridge.connectionRequest.bridge(connectionRequest)
-
-        // Any errors will be caught by ffi.ts and passed to `handleError` below
-        const authorization = await handler(request)
-
-        if (authorization !== 'allow' && authorization !== 'deny') {
-          Logger.error(`The connection request handler must return "allow" or "deny" but returned "${authorization}" instead. The connection request will be denied.`)
-          return 'Deny'
-        }
-
-        FFI.connectionRequestAuthorize(connectionRequest, authorization === 'allow' ? 'Allow' : 'Deny')
-      }
-    }
-
-    this._connectionRequestHandler = handler
-
-    const handleError = (error: any) => {
-      Logger.error(`The connection request handler threw an error while handling a connection request, the connection request will be denied. ${error}`)
-    }
-
-    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
-    this.ditto.deferClose(() => {
-      FFI.presenceSetConnectionRequestHandler(dittoHandle.deref(), wrappedHandler, handleError)
-    })
-  }
-
-  /**
-   * 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)
-    })
-  }
-
-  /**
-   * Metadata associated with the current peer. Other peers in the same mesh can
-   * access this user-provided object of metadata via the presence {@link graph}
-   * and when evaluating connection requests using
-   * {@link connectionRequestHandler | connectionRequestHandler()}.
-   *
-   * This is not made available to peers only connected via WebSocket.
-   *
-   * Uses UTF-8 encoding.
-   *
-   * @see {@link peerMetadata | peerMetadata()} for a convenience property that
-   * provides access to parsed metadata.
-   */
-  get peerMetadataJSONString(): string {
-    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
-    return this.ditto.deferClose(() => {
-      return mapFFIErrors(() => {
-        return FFI.presencePeerMetadataJSON(dittoHandle.deref())
-      })
-    })
-  }
-
-  /**
-   * Set arbitrary metadata to be associated with the current peer.
-   *
-   * The metadata must not exceed 4 KB in size when JSON-encoded.
-   *
-   * @param {string} jsonString: JSON-encoded metadata.
-   *
-   * @throws {@link DittoError} `validation/invalid-json`: if `jsonString` does
-   * not contain valid JSON.
-   *
-   * @throws {@link DittoError} `validation/not-an-object`: if `jsonString` does
-   * not contain an object.
-   *
-   * @throws {@link DittoError} `validation/size-limit-exceeded`: if the size
-   *  limit for `jsonString` has been exceeded.
-   *
-   * @see {@link peerMetadataJSONString | peerMetadataJSONString()} for details
-   * on usage of metadata.
-   */
-  async setPeerMetadataJSONString(jsonString: string): Promise<void> {
-    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
-    await this.ditto.deferCloseAsync(async () => {
-      return mapFFIErrorsAsync(async () => {
-        return FFI.presenceTrySetPeerMetadataJSON(dittoHandle.deref(), jsonString)
-      })
-    })
-  }
-
-  /**
-   * This is a convenience property that wraps
-   * {@link peerMetadataJSONString | peerMetadataJSONString()}.
-   *
-   * @see {@link peerMetadataJSONString | peerMetadataJSONString()} for details.
-   */
-  get peerMetadata(): Record<string, any> {
-    return JSON.parse(this.peerMetadataJSONString)
-  }
-
-  /**
-   * This is a convenience method that wraps
-   * {@link setPeerMetadataJSONString | setPeerMetadataJSONString()}.
-   *
-   * @throws {@link DittoError} `validation/not-an-object`: if `peerMetadata` is
-   * not an object.
-   *
-   * @throws {@link DittoError} `validation/not-json-compatible`: if
-   * `peerMetadata` is not JSON serializable.
-   *
-   * @throws {@link DittoError} `validation/size-limit-exceeded`: if the size
-   *  limit for `peerMetadata` has been exceeded.
-   *
-   * @see {@link setPeerMetadataJSONString | setPeerMetadataJSONString()} for
-   * details.
-   */
-  async setPeerMetadata(peerMetadata: Record<string, any>): Promise<void> {
-    let jsonString: string
-    try {
-      jsonString = JSON.stringify(peerMetadata)
-    } catch (error: any) {
-      throw new DittoError('validation/not-json-compatible', `Failed encoding peer metadata to JSON. ${error}`)
-    }
-
-    await this.setPeerMetadataJSONString(jsonString)
-  }
-
-  /**
-   * 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)
-        void ditto.deferCloseAsync(async () => {
-          return FFI.dittoClearPresenceV3Callback(dittoHandle.deref())
-        })
-      },
-
-      process: (presenceGraphJSONString) => {
-        const presenceGraph = JSON.parse(presenceGraphJSONString)
-        return [presenceGraph]
-      },
-    })
-  }
-
-  /** @internal */
-  close() {
-    this.observerManager.close()
-  }
-
-  private observerManager: ObserverManager
-  private _connectionRequestHandler: ConnectionRequestHandler | null = null
-}

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

@@ -1,131 +0,0 @@
-//
-// Copyright © 2023 DittoLive Incorporated. All rights reserved.
-//
-
-import * as FFI from './ffi'
-import { CBOR } from './cbor'
-import { Bridge } from './bridge'
-import { Document } from './document'
-import { customInspectRepresentation } from './internal'
-
-// Used to define a custom inspect function for Node.js that will be used when
-// the object is inspected with console.log() or util.inspect().
-const CUSTOM_INSPECT_SYMBOL = Symbol.for('nodejs.util.inspect.custom')
-
-/**
- * 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 resultItemHandle = Bridge.queryResultItem.handleFor(this)
-    return FFI.queryResultItemCBOR(resultItemHandle.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 resultItemHandle = Bridge.queryResultItem.handleFor(this)
-    return FFI.queryResultItemJSON(resultItemHandle.deref())
-  }
-
-  // ----------------------------------------------------------- Internal ------
-
-  /**
-   * Defines a custom inspect representation for Node.js that will be used when
-   * the object is inspected with console.log() or util.inspect().
-   *
-   * @internal
-   */
-  [CUSTOM_INSPECT_SYMBOL](_depth: number, _inspectOptions: any, inspect: any): string {
-    return customInspectRepresentation(this, inspect)
-  }
-
-  private materializedValue: any
-
-  /** @internal */
-  constructor() {}
-}

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

@@ -1,55 +0,0 @@
-//
-// 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 queryResultHandle = Bridge.queryResult.handleFor(this)
-    const affectedCBORIDs = FFI.queryResultMutatedDocumentIDs(queryResultHandle.deref())
-    return affectedCBORIDs.map((id) => new DocumentID(id, true))
-  }
-
-  // ----------------------------------------------------- Internal ------------
-
-  /** @internal */
-  constructor(queryResultPointer: FFI.Pointer<FFI.FFIQueryResult>) {
-    if (queryResultPointer == null) {
-      throw new Error('Internal inconsistency, failed to initialize query result without a response pointer')
-    }
-
-    const resultItems = FFI.queryResultItems(queryResultPointer)
-    this.items = resultItems.map((r) => Bridge.queryResultItem.bridge(r))
-  }
-}

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

@@ -1,95 +0,0 @@
-//
-// 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.`)
-    }
-  }
-}