@dittolive/ditto 4.4.5 → 4.5.1

package/react-native/src/sources/document-id.ts

@@ -0,0 +1,159 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+import { CBOR } from './cbor'
+
+/** Represents a unique identifier for a {@link Document}. */
+export type DocumentIDValue = any // REFACTOR: get rid of any.
+
+/** Represents a unique identifier for a {@link Document}. */
+export class DocumentID {
+  /**
+   * Returns the value of the receiver, lazily decoded from its CBOR
+   * representation if needed.
+   */
+  get value(): any {
+    let value = this['@ditto.value']
+    if (typeof value === 'undefined') {
+      value = CBOR.decode(this['@ditto.cbor'])
+      this['@ditto.value'] = value
+    }
+    return value
+  }
+
+  /**
+   * Returns `false` if validation has been skipped at construction time,
+   * otherwise returns `true`. This is mostly for internal use only, you
+   * shouldn't need this in client code.
+   */
+  readonly isValidated: boolean
+
+  /**
+   * Creates a new `DocumentID`.
+   *
+   * A document ID can be created from any of the following:
+   *
+   * - `string`
+   * - `number` (integer)
+   * - `boolean`
+   * - `null`
+   * - raw data in the form of a JS [Typed Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays)
+   * - `Array` (containing any of the items in this list)
+   * - Map (a raw JS `object`, where the keys must be strings and the values
+   *   can be made up of any of the items in this list)
+   *
+   * Note that you cannot use floats or other custom types to create a document
+   * ID.
+   *
+   * Document IDs are also limited in size, based on their serialized
+   * representation, to 256 bytes. You will receive an error if you try to
+   * create a document ID that exceeds the size limit.
+   *
+   * @param value The value that represents the document identifier.
+   * @param skipCBOREncoding If `true, skips CBOR encoding and assumes
+   * the passed in `value` is already CBOR encoded. You shouldn't need to ever
+   * pass this parameter, it's only used internally for certain edge cases.
+   * @param skipValidation If `true, skips validation of the passed in value or
+   * CBOR. You shouldn't need to ever pass this parameter, it's only used
+   * internally for certain edge cases.
+   */
+  constructor(value: any, skipCBOREncoding: boolean = false, skipValidation: boolean = false) {
+    const cbor = skipCBOREncoding ? value : CBOR.encode(value)
+    const validatedCBOR = skipValidation ? cbor : validateDocumentIDCBOR(cbor)
+
+    if (!validatedCBOR) {
+      throw new Error(`Can't create DocumentID, passed in value is not valid: ${value}`)
+    }
+
+    this.isValidated = !skipValidation
+    this['@ditto.cbor'] = validatedCBOR
+  }
+
+  /**
+   * Returns `true` if passed in `documentID` is equal to the receiver,
+   * otherwise returns `false`.
+   */
+  equals(documentID: DocumentID): boolean {
+    const left = this['@ditto.cbor']
+    const right = documentID['@ditto.cbor']
+
+    if (left === right) {
+      return true
+    }
+
+    if (!(left instanceof Uint8Array)) {
+      return false
+    }
+
+    if (!(right instanceof Uint8Array)) {
+      return false
+    }
+
+    if (left.length !== right.length) {
+      return false
+    }
+
+    for (let i = 0; i < left.length; i += 1) {
+      if (left[i] !== right[i]) return false
+    }
+
+    return true
+  }
+
+  /**
+   * Returns a string representation of the receiver.
+   *
+   * If you need a string representation to be used directly in a query,
+   * please use `toQueryCompatibleString()` instead.
+   */
+  toString(): string {
+    return FFI.documentIDQueryCompatible(this['@ditto.cbor'], 'WithoutQuotes')
+  }
+
+  /**
+   * Returns a byte representation of the document ID value as base64 string.
+   */
+  toBase64String(): string {
+    const bytes = this['@ditto.cbor']
+    return btoa(String.fromCharCode.apply(null, bytes))
+  }
+
+  /**
+   * Returns a query compatible string representation of the receiver.
+   *
+   * The returned string can be used directly in queries that you use with
+   * other Ditto functions. For example you could create a query that was like
+   * this:
+   *
+   *  ``` TypeScript
+   *  collection.find(`_id == ${documentID.toQueryCompatibleString()}`)
+   *  ```
+   */
+  toQueryCompatibleString(): string {
+    return FFI.documentIDQueryCompatible(this['@ditto.cbor'], 'WithQuotes')
+  }
+
+  /** @internal */
+  toCBOR(): Uint8Array {
+    return this['@ditto.cbor']
+  }
+}
+
+// -----------------------------------------------------------------------------
+
+/** @internal */
+export function validateDocumentIDValue(id: DocumentIDValue): DocumentIDValue {
+  if (typeof id === 'undefined') {
+    throw new Error(`Invalid document ID: ${id}`)
+  }
+
+  return id
+}
+
+/** @internal */
+export function validateDocumentIDCBOR(idCBOR: Uint8Array): Uint8Array {
+  const validatedIDCBOROrNull = FFI.validateDocumentID(idCBOR)
+  return validatedIDCBOROrNull ?? idCBOR
+}

package/react-native/src/sources/document-path.ts

@@ -0,0 +1,303 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+import { CBOR } from './cbor'
+import { Bridge } from './bridge'
+import { Counter, MutableCounter } from './counter'
+import { Register, MutableRegister } from './register'
+import { AttachmentToken } from './attachment-token'
+import { UpdateResult } from './update-result'
+import { desugarJSObject, augmentJSONValue } from './augment'
+import { validateNumber } from './internal'
+import { KeyPath } from './key-path'
+import type { Document, MutableDocument } from './document'
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Represents a portion of the document at a specific key-path.
+ *
+ * Provides an interface to specify a path to a key in a document that you can
+ * then call a function on to get the value at the specified key as a specific
+ * type. You don't create a `DocumentPath` directly but obtain one via the
+ * {@link Document.path | path} property or the {@link Document.at | at()}
+ * method of {@link Document}.
+ */
+export class DocumentPath {
+  /** The document this path belongs to. */
+  readonly document: Document
+
+  /** The full document path so far. */
+  readonly path: string
+
+  /**
+   * Returns a new document path instance with the passed in key-path or
+   * index appended.
+   *
+   * A key-path can be a single property name or multiple property names
+   * separated by a dot. Indexes can also be specified as part of the key
+   * path using the square bracket syntax. The empty string returns a document
+   * path representing the same portion of the document as the receiver. If a
+   * key-path starts with a property name and is prefixed by a dot, the dot is
+   * ignored.
+   *
+   * Examples:
+   *
+   *    - `documentPath.at('mileage')`
+   *    - `documentPath.at('driver.name')`
+   *    - `documentPath.at('passengers[2]')`
+   *    - `documentPath.at('passengers[2].belongings[1].kind')`
+   *    - `documentPath.at('.mileage')`
+   */
+  at(keyPathOrIndex: string | number): DocumentPath {
+    if (typeof keyPathOrIndex === 'string') {
+      const keyPath: string = keyPathOrIndex
+      const validatedKeyPath = KeyPath.validate(keyPath)
+      const absoluteKeyPath = KeyPath.withoutLeadingDot(`${this.path}${validatedKeyPath}`)
+      return new DocumentPath(this.document, absoluteKeyPath, false)
+    }
+
+    if (typeof keyPathOrIndex === 'number') {
+      const index: number = keyPathOrIndex
+      const validatedIndex = validateNumber(index, { integer: true, min: 0, errorMessagePrefix: 'DocumentPath.at() validation failed index:' })
+      return new DocumentPath(this.document, `${this.path}[${validatedIndex.toString()}]`, false)
+    }
+
+    throw new Error(`Can't return document path at key-path or index, string or number expected but got ${typeof keyPathOrIndex}: ${keyPathOrIndex}`)
+  }
+
+  /**
+   * Traverses the document with the key-path represented by the receiver and
+   * returns the corresponding object or value.
+   */
+  get value(): any | undefined {
+    return this.underlyingValueForPathType('Any')
+  }
+
+  /**
+   * Returns the value at the previously specified key in the document as a
+   * {@link Counter} if possible, otherwise returns `null`.
+   */
+  get counter(): Counter | null {
+    const underlyingValue = this.underlyingValueForPathType('Counter')
+    return typeof underlyingValue !== 'undefined' ? Counter['@ditto.create'](null, this.path, underlyingValue) : null
+  }
+
+  /**
+   * Returns the value at the previously specified key in the document as a
+   * {@link Register} if possible, otherwise returns `null`.
+   */
+  get register(): Register | null {
+    const underlyingValue = this.underlyingValueForPathType('Register')
+    return typeof underlyingValue !== 'undefined' ? Register['@ditto.create'](null, this.path, underlyingValue) : null
+  }
+
+  /**
+   * Returns the value at the previously specified key in the document as an
+   * {@link AttachmentToken} if possible, otherwise returns `null`.
+   */
+  get attachmentToken(): AttachmentToken | null {
+    const underlyingValue = this.underlyingValueForPathType('Attachment')
+    return typeof underlyingValue !== 'undefined' ? new AttachmentToken(underlyingValue) : null
+  }
+
+  /** @internal */
+  constructor(document: Document, path: string, validate: boolean) {
+    this.document = document
+    this.path = validate ? KeyPath.validate(path, { isInitial: true }) : path
+  }
+
+  /** @internal */
+  underlyingValueForPathType(pathType: FFI.PathAccessorType): any | undefined {
+    const path = this.path
+    const document = this.document
+    const documentHandle = Bridge.document.handleFor(document)
+    const cborPathResult = FFI.documentGetCBORWithPathType(documentHandle.deref(), path, pathType)
+    return cborPathResult.cbor !== null ? CBOR.decode(cborPathResult.cbor) : undefined
+  }
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Mutable version of {@link DocumentPath} allowing you to mutate a document at
+ * a specific key-path. You don't create a `MutableDocumentPath` directly but
+ * obtain one via the {@link MutableDocument.path | path} property or the
+ * {@link MutableDocument.at | at()} method of {@link MutableDocument}.
+ */
+export class MutableDocumentPath {
+  /** The (mutable) document this path belongs to. */
+  readonly mutableDocument: MutableDocument
+
+  /** The full document path so far. */
+  readonly path: string
+
+  /**
+   * Returns a new mutable document path instance with the passed in key-path or
+   * index appended.
+   *
+   * A key-path can be a single property name or multiple property names
+   * separated by a dot. Indexes can also be specified as part of the key
+   * path using square brackets syntax. The empty string returns a document path
+   * representing the same portion of the document as the receiver. If a key
+   * path starts with a property name and is prefixed by a dot, the dot is
+   * ignored.
+   *
+   * Examples:
+   *
+   *    - `mutableDocumentPath.at('mileage')`
+   *    - `mutableDocumentPath.at('driver.name')`
+   *    - `mutableDocumentPath.at('passengers[2]')`
+   *    - `mutableDocumentPath.at('passengers[2].belongings[1].kind')`
+   *    - `mutableDocumentPath.at('.mileage')`
+   */
+  at(keyPathOrIndex: string | number): MutableDocumentPath {
+    if (typeof keyPathOrIndex === 'string') {
+      const keyPath: string = keyPathOrIndex
+      const validatedKeyPath = KeyPath.validate(keyPath)
+      const absoluteKeyPath = KeyPath.withoutLeadingDot(`${this.path}${validatedKeyPath}`)
+      return new MutableDocumentPath(this.mutableDocument, absoluteKeyPath, false)
+    }
+
+    if (typeof keyPathOrIndex === 'number') {
+      const index: number = keyPathOrIndex
+      const validatedIndex = validateNumber(index, { integer: true, min: 0, errorMessagePrefix: 'MutableDocumentPath.at() validation failed index:' })
+      return new MutableDocumentPath(this.mutableDocument, `${this.path}[${validatedIndex.toString()}]`, false)
+    }
+
+    throw new Error(`Can't return mutable document path at key-path or index, string or number expected but got ${typeof keyPathOrIndex}: ${keyPathOrIndex}`)
+  }
+
+  /**
+   * Traverses the document with the key-path represented by the receiver and
+   * returns the corresponding object or value.
+   */
+  get value(): any | undefined {
+    return this.underlyingValueForPathType('Any')
+  }
+
+  /**
+   * Returns the value at the previously specified key in the document as a
+   * {@link MutableCounter} if possible, otherwise returns `null`.
+   */
+  get counter(): MutableCounter | null {
+    const underlyingValue = this.underlyingValueForPathType('Counter')
+    return typeof underlyingValue !== 'undefined' ? Counter['@ditto.create'](this.mutableDocument, this.path, underlyingValue) : null
+  }
+
+  /**
+   * Returns the value at the previously specified key in the document as a
+   * {@link MutableRegister} if possible, otherwise returns `null`.
+   */
+  get register(): MutableRegister | null {
+    const underlyingValue = this.underlyingValueForPathType('Register')
+    return typeof underlyingValue !== 'undefined' ? Register['@ditto.create'](this.mutableDocument, this.path, underlyingValue) : null
+  }
+
+  /**
+   * Returns the value at the previously specified key in the document as a
+   * {@link AttachmentToken} if possible, otherwise returns `null`.
+   */
+  get attachmentToken(): AttachmentToken | null {
+    const underlyingValue = this.underlyingValueForPathType('Attachment')
+    return typeof underlyingValue !== 'undefined' ? new AttachmentToken(underlyingValue) : null
+  }
+
+  /**
+   * Sets a value at the document's key-path defined by the receiver.
+   *
+   * @param isDefault Represents whether or not the value should be set as a
+   * default value. Set this to `true` if you want to set a default value that
+   * you expect to be overwritten by other devices in the network. The default
+   * value is `false`.
+   */
+  set(value: any, isDefault?: boolean) {
+    return this['@ditto.set'](value, isDefault)
+  }
+
+  /**
+   * Removes a value at the document's key-path defined by the receiver.
+   */
+  remove() {
+    return this['@ditto.remove']()
+  }
+
+  /** @internal */
+  constructor(mutableDocument: MutableDocument, path: string, validate: boolean) {
+    this.mutableDocument = mutableDocument
+    this.path = validate ? KeyPath.validate(path, { isInitial: true }) : path
+  }
+
+  /** @internal */
+  underlyingValueForPathType(pathType: FFI.PathAccessorType): any | null {
+    const path = this.path
+    const document = this.mutableDocument
+    const documentHandle = Bridge.mutableDocument.handleFor(document)
+    const cborPathResult = FFI.documentGetCBORWithPathType(documentHandle.deref(), path, pathType)
+    return cborPathResult.cbor !== null ? CBOR.decode(cborPathResult.cbor) : undefined
+  }
+
+  /** @internal */
+  '@ditto.increment'(amount: number) {
+   
+    const documentHandle = Bridge.mutableDocument.handleFor(this.mutableDocument)
+    FFI.documentIncrementCounter(documentHandle.deref(), this.path, amount)
+
+    const updateResult = UpdateResult.incremented(this.mutableDocument.id, this.path, amount)
+    this.recordUpdateResult(updateResult)
+  }
+
+  /** @internal */
+  '@ditto.set'(value: any, isDefault?: boolean) {
+    const documentHandle = Bridge.mutableDocument.handleFor(this.mutableDocument)
+    const valueJSON = desugarJSObject(value, false)
+    const valueCBOR = CBOR.encode(valueJSON)
+
+    if (isDefault) {
+      FFI.documentSetCBORWithTimestamp(documentHandle.deref(), this.path, valueCBOR, 0)
+    } else {
+      FFI.documentSetCBOR(documentHandle.deref(), this.path, valueCBOR)
+    }
+
+    const valueJSONCopy = CBOR.decode(valueCBOR)
+    const valueCopy = augmentJSONValue(valueJSONCopy, this.mutableDocument, this.path)
+
+    const updateResult = UpdateResult.set(this.mutableDocument.id, this.path, valueCopy)
+    this.recordUpdateResult(updateResult)
+  }
+
+  /** @internal */
+  '@ditto.remove'() {
+    const documentHandle = Bridge.mutableDocument.handleFor(this.mutableDocument)
+    FFI.documentRemove(documentHandle.deref(), this.path)
+
+    this.updateInMemory((container, lastPathComponent) => {
+      if (Array.isArray(container) && typeof lastPathComponent === 'number') {
+        container.splice(lastPathComponent, 1)
+      } else {
+        delete container[lastPathComponent]
+      }
+    })
+
+    const updateResult = UpdateResult.removed(this.mutableDocument.id, this.path)
+    this.recordUpdateResult(updateResult)
+  }
+
+  /** @private */
+  private updateInMemory(block: (container: any, lastPathComponent: any) => void) {
+    const mutableDocumentValue = this.mutableDocument.value
+    const evaluationResult = KeyPath.evaluate(this.path, mutableDocumentValue, { stopAtLastContainer: true })
+    block(evaluationResult.value, evaluationResult.nextPathComponent)
+  }
+
+  /** @private */
+  private recordUpdateResult(updateResult: UpdateResult) {
+
+    const updateResults = this.mutableDocument['@ditto.updateResults'].slice()
+    updateResults.push(updateResult)
+    Object.freeze(updateResults)
+    this.mutableDocument['@ditto.updateResults' as any] = updateResults
+  }
+}

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

@@ -0,0 +1,192 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+import { Bridge } from './bridge'
+import { DocumentID } from './document-id'
+import { validateDocumentIDCBOR } from './document-id'
+import { DocumentPath, MutableDocumentPath } from './document-path'
+
+import type { UpdateResult } from './update-result'
+
+// -----------------------------------------------------------------------------
+
+/**
+ * A document value is a JavaScript object containing values for keys that
+ * can be serialized via CBOR.
+ */
+export type DocumentValue = Record<string, any>
+
+// -----------------------------------------------------------------------------
+
+/** A document belonging to a {@link Collection} with an inner value. */
+export class Document {
+  /**
+   * Returns a hash that represents the passed in document(s).
+   */
+  static hash(documentOrMany: Document | Document[]): BigInt {
+    const documents = documentsFrom(documentOrMany)
+    const documentHandles = documents.map((doc) => Bridge.document.handleFor(doc))
+    return FFI.documentsHash(documentHandles.map((handle) => handle.deref()))
+  }
+
+  /**
+   * Returns a pattern of words that together create a mnemonic, which
+   * represents the passed in document(s).
+   */
+  static hashMnemonic(documentOrMany: Document | Document[]): string {
+    const documents = documentsFrom(documentOrMany)
+    const documentHandles = Bridge.document.handlesFor(documents)
+    return FFI.documentsHashMnemonic(documentHandles.deref())
+  }
+
+  /**
+   * Returns the document ID.
+   */
+  get id(): DocumentID {
+    let id = this['@ditto.id']
+    if (typeof id === 'undefined') {
+      const documentHandle = Bridge.document.handleFor(this)
+      const documentIDCBOR = FFI.documentID(documentHandle.deref())
+      id = new DocumentID(documentIDCBOR, true)
+      this['@ditto.id'] = id
+    }
+    return id
+  }
+
+  /**
+   * Returns the document path at the root of the document.
+   */
+  get path(): DocumentPath {
+    return new DocumentPath(this, '', false)
+  }
+
+  /**
+   * Convenience property, same as calling `path.value`. The value is cached on
+   * first access and returned on subsequent calls without calling `path.value`
+   * again.
+   */
+  get value(): DocumentValue {
+    let value = this['@ditto.value']
+    if (typeof value === 'undefined') {
+      value = this.path.value
+      this['@ditto.value'] = value
+    }
+    return value
+  }
+
+  /**
+   * Convenience method, same as calling `path.at()`.
+   */
+  at(keyPathOrIndex: string | number): DocumentPath {
+    return this.path.at(keyPathOrIndex)
+  }
+
+  /** @internal */
+  constructor() {}
+
+
+  /** @internal */
+  static idCBOR(document: Document): Uint8Array {
+    const documentHandle = Bridge.document.handleFor(document)
+    return FFI.documentID(documentHandle.deref())
+  }
+
+  /** @internal */
+  static canonicalizedIDCBOR(idCBOR: Uint8Array): Uint8Array {
+    return validateDocumentIDCBOR(idCBOR)
+  }
+
+  /** @internal */
+  static isIDCBORCanonical(idCBOR: Uint8Array): boolean {
+    const canonicalIDCBOR = this.canonicalizedIDCBOR(idCBOR)
+    return idCBOR === canonicalIDCBOR
+  }
+}
+
+// -----------------------------------------------------------------------------
+
+
+/**
+ * A representation of a {@link Document} that can be mutated via
+ * {@link MutableDocumentPath}. You don't create or interact with
+ * a `MutableDocument` directly but rather through our proxy-based
+ * subscripting API exposed within the `update()` methods of
+ * {@link PendingCursorOperation.update | PendingCursorOperation} and
+ * {@link PendingIDSpecificOperation.update | PendingIDSpecificOperation}.
+ */
+export class MutableDocument {
+  /**
+   * Returns the ID of the document.
+   */
+  get id(): DocumentID {
+    let id = this['@ditto.id']
+    if (typeof id === 'undefined') {
+      const documentHandle = Bridge.mutableDocument.handleFor(this)
+      const documentIDCBOR = FFI.documentID(documentHandle.deref())
+      id = new DocumentID(documentIDCBOR, true)
+      this['@ditto.id'] = id
+    }
+    return id
+  }
+
+  /**
+   * Returns the document path at the root of the document.
+   */
+  get path(): MutableDocumentPath {
+    return new MutableDocumentPath(this, '', false)
+  }
+
+  /**
+   * Convenience property, same as `path.value`.
+   */
+  get value(): DocumentValue {
+    return this.path.value
+  }
+
+  /**
+   * Convenience method, same as calling `path.at()`.
+   */
+  at(keyPathOrIndex: string | number): MutableDocumentPath {
+    return this.path.at(keyPathOrIndex)
+  }
+
+  /** @internal */
+  constructor() {}
+
+  /** @internal */
+  readonly '@ditto.updateResults': UpdateResult[] = []
+
+
+  /** @internal */
+  static idCBOR(mutableDocument: MutableDocument): Uint8Array {
+    const documentHandle = Bridge.mutableDocument.handleFor(mutableDocument)
+    return FFI.documentID(documentHandle.deref())
+  }
+
+  /** @internal */
+  static canonicalizedIDCBOR = Document.canonicalizedIDCBOR
+
+  /** @internal */
+  static isIDCBORCanonical = Document.isIDCBORCanonical
+}
+
+// -----------------------------------------------------------------------------
+
+/** @private */
+function documentsFrom(documentOrMany: Document | Document[] | null): Document[] {
+  if (!documentOrMany) {
+    return []
+  }
+
+  if (documentOrMany instanceof Document) {
+    return [documentOrMany]
+  }
+
+  if (documentOrMany instanceof Array) {
+    return documentOrMany as Document[]
+  }
+
+  throw new Error(`Expected null, a single document, or an array of documents but got value of type ${typeof documentOrMany}: ${documentOrMany}`)
+}

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

@@ -0,0 +1,24 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+
+import { Attachment } from './attachment'
+import { Document, MutableDocument } from './document'
+
+import { StaticTCPClient } from './static-tcp-client'
+import { WebsocketClient } from './websocket-client'
+
+import { Ditto } from './ditto'
+import { Bridge } from './bridge'
+import { QueryResult } from './query-result'
+import { QueryResultItem } from './query-result-item'
+
+Bridge.attachment.registerType(Attachment)
+Bridge.document.registerType(Document)
+Bridge.dqlResult.registerType(QueryResultItem)
+Bridge.dqlResponse.registerType(QueryResult)
+Bridge.mutableDocument.registerType(MutableDocument)
+Bridge.staticTCPClient.registerType(StaticTCPClient)
+Bridge.websocketClient.registerType(WebsocketClient)
+Bridge.ditto.registerType(Ditto)