@dittolive/ditto 4.7.4 → 4.8.0-rc.2

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

@@ -1,73 +0,0 @@
-//
-// 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>
-}

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

@@ -1,219 +0,0 @@
-//
-// Copyright © 2021 DittoLive Incorporated. All rights reserved.
-//
-
-import * as FFI from './ffi'
-import * as Environment from './@environment'
-
-import { QueryArguments } from './essentials'
-import { CBOR } from './cbor'
-import { DocumentID } from './document-id'
-import { Bridge } from './bridge'
-import { Attachment } from './attachment'
-import { AttachmentToken } from './attachment-token'
-import { AttachmentFetcher } from './attachment-fetcher'
-import { PendingCursorOperation } from './pending-cursor-operation'
-import { PendingIDSpecificOperation } from './pending-id-specific-operation'
-
-import { performAsyncToWorkaroundNonAsyncFFIAPI } from './internal'
-import { desugarJSObject } from './augment'
-
-import type { TypedAttachmentToken } from './attachment-token'
-import type { Store } from './store'
-import type { DocumentValue } from './document'
-import type { DocumentIDValue } from './document-id'
-import type { CollectionInterface, UpsertOptions } from './collection-interface'
-import type { AttachmentFetchEvent } from './attachment-fetch-event'
-
-/**
- * Represents a collection of a Ditto store.
- *
- * This is the entrypoint for inserting documents into a collection, as well as
- * querying a collection. You can get a collection by calling
- * {@link Store.collection | collection()} on a {@link Store} of a {@link Ditto}
- * object.
- */
-export class Collection implements CollectionInterface {
-  /** The name of the collection. */
-  readonly name: string
-
-  /** The store this collection belongs to. */
-  readonly store: Store
-
-  /**
-   * Generates a {@link PendingCursorOperation} using the provided query.
-   *
-   * The returned object can be used to find and return the documents or you can
-   * chain a call to `observeLocal()` or `subscribe()` if you want to get
-   * updates about the list of matching documents over time. It can also be used
-   * to update, remove or evict the matching documents.
-   *
-   * You can incorporate dynamic data into the query string with placeholders in
-   * the form of `$args.my_arg_name`, along with providing an accompanying
-   * dictionary in the form of `{ "my_arg_name": "some value" }`. The
-   * placeholders will be appropriately replaced by the corresponding argument
-   * contained in `queryArgs`. This includes handling things like wrapping
-   * strings in quotation marks and arrays in square brackets, for example.
-   *
-   * Find more information about the query string format in the documentation's
-   * section on {@link https://docs.ditto.live/javascript/common/concepts/querying Querying}
-   *
-   * @param query The query to run against the collection.
-   * @param queryArgs The arguments to use to replace placeholders in the
-   * provided query.
-   */
-  find(query: string, queryArgs?: QueryArguments): PendingCursorOperation {
-    return new PendingCursorOperation(query, queryArgs ?? null, this)
-  }
-
-  findAll(): PendingCursorOperation {
-    return this.find('true')
-  }
-
-  /**
-   * Generates a {@link PendingIDSpecificOperation} with the provided document
-   * ID.
-   *
-   * The returned object can be used to find and return the document or you can
-   * chain a call to
-   * {@link PendingIDSpecificOperation.observeLocal | observeLocal()}, or
-   * {@link PendingIDSpecificOperation.subscribe | subscribe()} if you want to
-   * get updates about the document over time. It can also be used to update,
-   * remove or evict the document.
-   *
-   * @param id The ID of the document to find.
-   */
-  findByID(id: DocumentID | DocumentIDValue): PendingIDSpecificOperation {
-    const documentID: DocumentID = id instanceof DocumentID ? id : new DocumentID(id)
-    return new PendingIDSpecificOperation(documentID, this)
-  }
-
-  async upsert(value: DocumentValue, options: UpsertOptions = {}): Promise<DocumentID> {
-    const ditto = this.store.ditto
-    const dittoHandle = Bridge.ditto.handleFor(ditto)
-
-    return ditto.deferCloseAsync(async () => {
-      const writeStrategy = options.writeStrategy ?? 'merge'
-
-      const documentValueJSON = desugarJSObject(value)
-      const documentValueCBOR = CBOR.encode(documentValueJSON)
-
-      const idCBOR = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
-        return await FFI.collectionInsertValue(dittoHandle.deref(), this.name, documentValueCBOR, writeStrategy, undefined)
-      })
-
-      return new DocumentID(idCBOR, true)
-    })
-  }
-
-  /**
-   * Creates a new {@link Attachment} object, which can then be inserted into a
-   * document. Node only, throws when running in the web browser.
-   *
-   * The file residing at the provided path will be copied into Ditto's store.
-   * The {@link Attachment} object that is returned is what you can then use to
-   * insert an attachment into a document.
-   *
-   * You can provide metadata about the attachment, which will be replicated to
-   * other peers alongside the file attachment.
-   *
-   * Below is a snippet to show how you can use the
-   * {@link newAttachment | newAttachment()} functionality to insert an
-   * attachment into a document.
-   *
-   * ``` JavaScript
-   * const attachment = await collection.newAttachment('/path/to/my/file.pdf')
-   * await collection.upsert({ _id: '123', attachment, other: 'some-string' })
-   * }
-   * ```
-   *
-   * @param pathOrData The path to the file that you want to create an
-   * attachment with or the raw data.
-   *
-   * @param metadata Metadata relating to the attachment.
-   *
-   * @deprecated Use {@link Store.newAttachment | ditto.store.newAttachment() }
-   * instead.
-   */
-  async newAttachment(pathOrData: string | Uint8Array, metadata: { [key: string]: string } = {}): Promise<Attachment> {
-    const ditto = this.store.ditto
-    const dittoHandle = Bridge.ditto.handleFor(ditto)
-
-    return ditto.deferCloseAsync(async () => {
-      const { id, len, handle } = await (async () => {
-        if (typeof pathOrData === 'string') {
-          if (Environment.isWebBuild) {
-            throw new Error(`Can't create attachment from file when running in the browser. Please pass the raw data (as a Uint8Array) instead.`)
-          }
-
-          if (Environment.isNodeBuild) {
-            return FFI.dittoNewAttachmentFromFile(dittoHandle.deref(), pathOrData as string, 'Copy')
-          }
-        }
-
-        if (pathOrData instanceof Uint8Array) {
-          return await FFI.dittoNewAttachmentFromBytes(dittoHandle.deref(), pathOrData)
-        }
-
-        throw new Error(`Can't create new attachment, only file path as string or raw data as Uint8Array are supported, but got: ${typeof pathOrData}, ${pathOrData}`)
-      })()
-
-      const attachmentTokenJSON = { _id: id, _len: len, _meta: { ...metadata } }
-      attachmentTokenJSON[FFI.DittoCRDTTypeKey] = FFI.DittoCRDTType.attachment
-
-      const attachmentToken = new AttachmentToken(attachmentTokenJSON as TypedAttachmentToken)
-      const attachment = new Attachment(ditto, attachmentToken)
-
-      return Bridge.attachment.bridge(handle, () => attachment)
-    })
-  }
-
-  /**
-   * Trigger an attachment to be downloaded locally to the device and observe
-   * its progress as it does so.
-   *
-   * When you encounter a document that contains an attachment the attachment
-   * will not automatically be downloaded along with the document. You trigger
-   * an attachment to be downloaded locally to a device by calling this method.
-   * It will report events relating to the attachment fetch attempt as it tries
-   * to download it. The `eventHandler` block may be called multiple times with
-   * progress events. It will then be called with either a  `Completed` event or
-   * a `Deleted` event. If downloading the attachment succeeds then the
-   * `Completed` event that the `eventHandler` will be called with will hold a
-   * reference to the downloaded attachment.
-   *
-   * @param token The {@link AttachmentToken} relevant to the attachment that
-   * you wish to download and observe. Throws if token is invalid.
-   *
-   * @param eventHandler An optional callback that will be called when there is
-   * an update to the status of the attachment fetch attempt.
-   *
-   * @return An `AttachmentFetcher` object, which must be kept alive for the
-   * fetch request to proceed and for you to be notified about the attachment's
-   * fetch status changes.
-   *
-   * @deprecated Use
-   * {@link Store.fetchAttachment | ditto.store.fetchAttachment() } instead.
-   */
-  fetchAttachment(token: AttachmentToken, eventHandler?: (event: AttachmentFetchEvent) => void): AttachmentFetcher {
-    if (token == null || !(token instanceof AttachmentToken)) {
-      throw new Error(`Invalid attachment token: ${token}`)
-    }
-    const ditto = this.store.ditto
-    return ditto.deferClose(() => {
-      return ditto.attachmentFetcherManager.startAttachmentFetcher(token, eventHandler)
-    })
-  }
-
-  /** @internal */
-  constructor(name: string, store: Store) {
-    this.name = name
-    this.store = store
-  }
-
-  /** @internal */
-  findByIDCBOR(idCBOR: Uint8Array): PendingIDSpecificOperation {
-    const documentID = new DocumentID(idCBOR, true, true)
-    return new PendingIDSpecificOperation(documentID, this)
-  }
-}

package/react-native/src/sources/collections-event.ts

@@ -1,99 +0,0 @@
-//
-// Copyright (c) 2020 - 2021 DittoLive Inc. All rights reserved.
-//
-
-import type { Collection } from './collection'
-import type { LiveQueryMove } from './live-query-event'
-
-// -----------------------------------------------------------------------------
-
-/** @internal */
-export interface CollectionsEventParams {
-  isInitial: boolean
-  collections: Collection[]
-  oldCollections: Collection[]
-  insertions: number[]
-  deletions: number[]
-  updates: number[]
-  moves: LiveQueryMove[]
-}
-
-// -----------------------------------------------------------------------------
-
-/**
- * Provides information about the changes that have occurred in relation to an
- * event delivered when observing the collections in a {@link Store}.
- *
- * It contains information about the collections that are known about as well as
- * the collections that were previously known about in the previous event, along
- * with information about what collections have been inserted, deleted, updated,
- * or moved since the last event.
- */
-export class CollectionsEvent {
-  /**
-   * Indicates whether or not this is the first event to be delivered when
-   * observing collections in the store.
-   */
-  readonly isInitial: boolean
-
-  /**
-   * A list of all of the known collections.
-   */
-  readonly collections: Collection[]
-
-  /**
-   * A list of all of the known collections at the time the previous event was
-   * delivered.
-   */
-  readonly oldCollections: Collection[]
-
-  /**
-   * A list of the indexes in the list of currently known about collections at
-   * which new collections have been inserted.
-   */
-  readonly insertions: number[]
-
-  /**
-   * A list of the indexes in the list of previously known about collections at
-   * which collections have been removed.
-   */
-  readonly deletions: number[]
-
-  /**
-   * A list of the indexes in the list of currently known about collections at
-   * which pre-existing collections have been updated.
-   */
-  readonly updates: number[]
-
-  /**
-   * A list of the tuples that provides the indexes, in relation to the list of
-   * previously known about collections, that already known about collections
-   * have moved from and the indexes, in relation to the list of currently known
-   * about collections, that the collections have moved to.
-   */
-  readonly moves: LiveQueryMove[]
-
-  /** @internal */
-  static initial(collections: Collection[]): CollectionsEvent {
-    return new CollectionsEvent({
-      isInitial: true,
-      collections: collections,
-      oldCollections: [],
-      insertions: [],
-      deletions: [],
-      updates: [],
-      moves: [],
-    })
-  }
-
-  /** @internal */
-  constructor(params: CollectionsEventParams) {
-    this.isInitial = params.isInitial
-    this.collections = params.collections
-    this.oldCollections = params.oldCollections
-    this.insertions = params.insertions
-    this.deletions = params.deletions
-    this.updates = params.updates
-    this.moves = params.moves
-  }
-}

package/react-native/src/sources/connection-request.ts

@@ -1,142 +0,0 @@
-//
-// Copyright © 2024 DittoLive Incorporated. All rights reserved.
-//
-
-import { Bridge } from './bridge'
-import * as FFI from './ffi'
-
-import type { ConnectionType, Peer, Presence } from './presence'
-
-/**
- * Indicates whether a connection request should be authorized.
- *
- * `allow` if the request should be authorized, `deny` otherwise.
- */
-export type ConnectionRequestAuthorization = 'allow' | 'deny'
-
-/**
- * A handler for connection requests from other peers.
- *
- * Set a `ConnectionRequestHandler` on
- * {@link Presence.connectionRequestHandler | `ditto.presence.connectionRequestHandler`}
- * to allow or deny connection requests from other peers.
- *
- * @param connectionRequest - Contains information about the remote peer that
- *   can be used to make an authorization decision.
- *
- * @returns `allow` if the request should be authorized, `deny` otherwise.
- *
- * @see
- * {@link Presence.connectionRequestHandler | `ditto.presence.connectionRequestHandler`}
- * for details on the connection request API.
- */
-export type ConnectionRequestHandler = (connectionRequest: ConnectionRequest) => Promise<ConnectionRequestAuthorization>
-
-/**
- * Contains information about a remote peer that has requested a connection.
- *
- * Connection requests and their authorization are scoped to a specific Ditto
- * peer and connection type.
- */
-export class ConnectionRequest {
-  /**
-   * The unique peer key of the remote peer.
-   *
-   * @see field `peerKeyString` on {@link Peer} for more information on peer
-   * keys.
-   */
-  get peerKeyString(): string {
-    return FFI.connectionRequestPeerKeyString(this.deref())
-  }
-
-  /**
-   * Metadata associated with the remote peer.
-   *
-   * This is an empty object if the remote peer has not set any metadata, or
-   * when this request is for a WebSocket connection (which does not currently
-   * support peer metadata).
-   *
-   * Set peer metadata for the local peer using {@link Presence.peerMetadata} or
-   * {@link Presence.peerMetadataJSONString}.
-   *
-   * This is a convenience property that wraps
-   * {@link peerMetadataJSONString | `peerMetadataJSONString()`}.
-   */
-  get peerMetadata(): Record<string, any> {
-    return JSON.parse(this.peerMetadataJSONString)
-  }
-
-  /**
-   * JSON-encoded metadata associated with the remote peer.
-   *
-   * This is a JSON string representing an empty dictionary if the remote peer
-   * has not set any metadata or when this request is for a WebSocket
-   * connection.
-   *
-   * Set peer metadata for the local peer using {@link Presence.peerMetadata} or
-   * {@link Presence.peerMetadataJSONString}.
-   *
-   * Uses UTF-8 encoding.
-   */
-  get peerMetadataJSONString(): string {
-    return FFI.connectionRequestPeerMetadataJSON(this.deref())
-  }
-
-  /**
-   * Metadata for the remote peer that is provided 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.
-   *
-   * Convenience property that wraps {@link identityServiceMetadataJSONString}.
-   */
-  get identityServiceMetadata(): Record<string, any> {
-    return JSON.parse(this.identityServiceMetadataJSONString)
-  }
-
-  /**
-   * JSON-encoded metadata for the remote peer that is provided 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.
-   *
-   * Uses UTF-8 encoding.
-   */
-  get identityServiceMetadataJSONString(): string {
-    return FFI.connectionRequestIdentityServiceMetadataJSON(this.deref())
-  }
-
-  /**
-   * The network transport of this connection request.
-   *
-   * Expect to receive separate connection requests for each network
-   * transport that connects the local and remote peer.
-   */
-  get connectionType(): ConnectionType {
-    return FFI.connectionRequestConnectionType(this.deref())
-  }
-
-  /** @internal */
-  toString(): string {
-    return `ConnectionRequest(${this.peerKeyString} via ${this.connectionType})`
-  }
-
-  /**
-   * Defines a custom inspect function for Node.js that will be used when the
-   * object is inspected with console.log() or util.inspect().
-   *
-   * @internal
-   */
-  [Symbol.for('nodejs.util.inspect.custom')](_depth: number, _inspectOptions: any, inspect: any): string {
-    return this.toString()
-  }
-
-  // --------------------------------------------------------------------------
-
-  private deref(): FFI.Pointer<FFI.FFIConnectionRequest> {
-    return Bridge.connectionRequest.handleFor(this).deref()
-  }
-}

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

@@ -1,82 +0,0 @@
-//
-// 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')
-
-/**
- * Represents a CRDT counter that can be upserted as part of a document or
- * assigned to a property during an update of a document.
- */
-export class Counter {
-  /** The value of the counter. */
-  get value(): number {
-    return this._value
-  }
-
-  /**
-   * Creates a new counter that can be used as part of a document's content.
-   */
-  constructor() {
-    this._value = 0.0
-  }
-
-  /** @internal */
-  static '@ditto.create'(mutDoc, path, value) {
-    // @ts-expect-error - using hidden argument
-    const counter = mutDoc ? new MutableCounter(privateToken) : new Counter()
-    counter.mutDoc = mutDoc
-    counter.path = path
-    counter._value = value
-    return counter
-  }
-
-  protected mutDoc: any
-  protected path: any
-  protected _value: number
-}
-
-// -----------------------------------------------------------------------------
-
-/**
- * Represents a mutable CRDT counter that can be incremented by a specific
- * amount while updating a document.
- *
- * This class can't be instantiated directly, it's returned automatically for
- * any counter property within an update block via {@link MutableDocumentPath.counter}.
- */
-export class MutableCounter extends Counter {
-  /**
-   * Increments the counter by `amount`, which can be any valid number.
-   *
-   * Only valid within the `update` closure of
-   * {@link PendingCursorOperation.update | PendingCursorOperation.update()} and
-   * {@link PendingIDSpecificOperation.update | PendingIDSpecificOperation.update()},
-   * otherwise an exception is thrown.
-   */
-  increment(amount: number) {
-    const mutDoc = this.mutDoc
-    const path = this.path
-
-    if (!mutDoc) {
-      throw new Error(`Can't increment counter, only possible within the closure of a collection's update() method.`)
-    }
-
-    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
-  }
-
-  /** @internal */
-  protected constructor() {
-    if (arguments[0] === privateToken) {
-      super()
-    } else {
-      throw new Error(`MutableCounter constructor is for internal use only.`)
-    }
-  }
-}