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

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

@@ -0,0 +1,35 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import { CBOR as CBORRedux } from './@cbor-redux'
+
+import { DocumentID } from './document-id'
+
+/** @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)
+  }
+}
+
+/**
+ * Custom replacer that converts `DocumentID` instances to their string
+ * representation.
+ *
+ * @internal
+ */
+export function documentIDReplacer(key: any, value: any): any {
+  if (value instanceof DocumentID) {
+    return value.toString()
+  }
+  return value
+}

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

@@ -0,0 +1,67 @@
+//
+// 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 = {
+  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.
+   * @param options.writeStrategy Specifies the desired strategy for inserting a
+   * document, defaults to `'merge'`.
+   */
+  upsert(value: DocumentValue, options: UpsertOptions): Promise<DocumentID>
+}

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

@@ -0,0 +1,212 @@
+//
+// 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 { 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, true)
+      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.
+   */
+  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)
+      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.
+   */
+  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

@@ -0,0 +1,99 @@
+//
+// 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/counter.ts

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