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

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

@@ -0,0 +1,60 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+// IMPORTANT: this file is only for exporting public API, please don't
+// add "significant" logic in here (sort of a "Framework Header" in ObjC).
+
+export * from './keep-alive'
+export * from './observer'
+
+export * from './essentials'
+export * from './counter'
+export * from './register'
+export * from './attachment-token'
+
+export * from './init'
+export * from './logger'
+export * from './document-id'
+
+export * from './base-pending-cursor-operation'
+export * from './base-pending-id-specific-operation'
+export * from './authenticator'
+export * from './identity'
+export * from './ditto'
+export * from './store-observer'
+export * from './collection'
+export * from './collection-interface'
+export * from './collections-event'
+export * from './document-path'
+export * from './document'
+export * from './sync'
+export * from './sync-subscription'
+export * from './error'
+export * from './error-codes'
+export * from './query-result-item'
+export * from './query-result'
+export * from './live-query-event'
+export * from './live-query'
+export * from './attachment'
+export * from './attachment-fetcher'
+export * from './attachment-fetch-event'
+export * from './pending-cursor-operation'
+export * from './pending-id-specific-operation'
+export * from './pending-collections-operation'
+export * from './small-peer-info'
+export * from './store'
+export * from './presence'
+export * from './subscription'
+export * from './test-helpers'
+export * from './transport-config'
+export * from './update-result'
+export * from './update-results-map'
+export * from './write-transaction'
+export * from './write-transaction-collection'
+export * from './write-transaction-pending-cursor-operation'
+export * from './write-transaction-pending-id-specific-operation'
+export * from './epilogue'
+
+// TEMPORARY: exported to deal with non-canonical IDs.
+export * from './cbor'

package/react-native/src/sources/observer-manager.ts

@@ -0,0 +1,178 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import { generateEphemeralToken } from './internal'
+import { KeepAlive } from './keep-alive'
+
+/** @internal */
+export type ObserverToken = string
+
+/** @internal */
+export type ObserverManagerConstructorOptions = {
+  keepAlive?: KeepAlive
+  register?: (callback: (...args: any[]) => void) => void
+  unregister?: () => void
+  process?: (...args: any[]) => any[]
+}
+
+/** @internal */
+export class ObserverManager {
+  /** @internal */
+  readonly id: string
+
+  /** @internal */
+  readonly keepAlive: KeepAlive | null
+
+  /** @internal */
+  constructor(id: string, options: ObserverManagerConstructorOptions = {}) {
+    const keepAlive = options.keepAlive ?? null
+    const register = options.register ?? null
+    const unregister = options.unregister ?? null
+    const process = options.process ?? null
+
+    this.id = id
+    this.keepAlive = keepAlive
+
+    this.isClosed = false
+    this.isRegistered = false
+    this.callbacksByToken = {}
+
+    if (register !== null) {
+      this.register = register
+    }
+
+    if (unregister !== null) {
+      this.unregister = unregister
+    }
+
+    if (process !== null) {
+      this.process = process
+    }
+  }
+
+  /** @internal */
+  addObserver(callback: any): ObserverToken {
+    if (this.isClosed) {
+      throw new Error(`Internal inconsistency, can't add '${this.id}' observer, observer mananger close()-ed.`)
+    }
+
+    this.registerIfNeeded()
+
+    const token = generateEphemeralToken()
+    this.callbacksByToken[token] = callback
+
+    this.keepAlive?.retain(`${this.id}.${token}`)
+    return token
+  }
+
+  /** @internal */
+  removeObserver(token: ObserverToken): void {
+    const callback = this.callbacksByToken[token]
+
+    if (typeof callback === 'undefined') {
+      throw new Error(`Can't remove '${this.id}' observer, token '${token}' has never been registered before.`)
+    }
+
+    if (callback === null) {
+      // Observer has already been removed, no-op.
+      return
+    }
+
+    // The value is set to null to be able to discern between
+    // observers that have been removed and observers that have
+    // never been registered before.
+    this.callbacksByToken[token] = null
+
+    this.keepAlive?.release(`${this.id}.${token}`)
+    this.unregisterIfNeeded()
+  }
+
+  hasObserver(token: ObserverToken): boolean {
+    return typeof this.callbacksByToken[token] != 'undefined'
+  }
+
+  /** @internal */
+  notify(...args: any[]) {
+    if (this.isClosed) {
+      // NOTE: we don't notify observers after closing and just swallow
+      // the event.
+      return
+    }
+
+    const processedArgs = this.process(...args)
+    for (const token in this.callbacksByToken) {
+      const callback = this.callbacksByToken[token]
+      if (callback) callback(...processedArgs)
+    }
+  }
+
+  /** @internal */
+  close() {
+    this.isClosed = true
+    for (const token in this.callbacksByToken) {
+      this.removeObserver(token)
+    }
+  }
+
+  /**
+   * Can be injected and replaced via constructor options.
+   *
+   * @abstract
+   */
+  protected register(callback: (...args: any[]) => void) {
+    // No-op, subclasses may override and register.
+  }
+
+  /**
+   * Can be injected and replaced via constructor options.
+   *
+   * @abstract
+   */
+  protected unregister() {
+    // No-op, subclasses may override and unregister.
+  }
+
+  /**
+   * Can be injected and replaced via constructor options.
+   *
+   * @abstract
+   */
+  protected process(...args: any[]): any[] {
+    // No-op, subclasses may override and process/transform the callback parameters.
+    return args
+  }
+
+  private isClosed: boolean
+  private isRegistered: boolean
+  private callbacksByToken: { [key: string]: ((...args: any[]) => void) | null }
+  private constructorOptions: ObserverManagerConstructorOptions
+
+  private hasObservers(): boolean {
+    return Object.keys(this.callbacksByToken).length > 0
+  }
+
+  private registerIfNeeded() {
+    const needsToRegister = !this.isRegistered
+    if (needsToRegister) {
+      const weakThis = new WeakRef(this)
+      this.isRegistered = true
+      this.register(function (...args) {
+        const strongThis = weakThis.deref()
+        if (!strongThis) {
+          return
+        }
+
+        strongThis.notify(...args)
+      })
+    }
+  }
+
+  private unregisterIfNeeded() {
+    const needsToUnregister = !this.hasObservers() && this.isRegistered
+    if (needsToUnregister) {
+      this.isRegistered = false
+      this.unregister()
+    }
+  }
+}

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

@@ -0,0 +1,79 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import type { ObserverToken } from './observer-manager'
+
+/** @internal */
+interface ObserverManaging {
+  hasObserver(token: ObserverToken): boolean
+  removeObserver(token: ObserverToken): void
+}
+
+/** @internal */
+export type ObserverOptions = {
+  stopsWhenFinalized?: boolean
+}
+
+/**
+ * Generic observer handle returned by various observation APIs. The observation
+ * remains active until the {@link stop | stop()} method is called explicitly or
+ * the observer instance is garbage collected. Therefore, to keep the observation
+ * alive, you have to keep a reference to the corresponding observer.
+ */
+export class Observer {
+  // NOTE: the core functionality of the observer manager is token-based. We use
+  // the `Observer` class merely as a public API wrapper around the token
+  // exposing a convenience `stop()` method plus life-cycle tracking.
+
+  /** @internal */
+  readonly observerManager: ObserverManaging
+
+  /** @internal */
+  get token(): ObserverToken | undefined {
+    return this._token
+  }
+
+  /** @internal */
+  readonly options?: ObserverOptions
+
+  /** @internal */
+  constructor(observerManager: ObserverManaging, token: any, options: ObserverOptions = {}) {
+    this.observerManager = observerManager
+    this._token = token
+    this.options = options
+
+    if (options.stopsWhenFinalized) {
+      Observer.finalizationRegistry.register(this, { observerManager, token }, this)
+    }
+  }
+
+  /**
+   * Returns `true` if the observer has been explicitly stopped via the `stop()`
+   * method. Otherwise returns `false`.
+   */
+  get isStopped(): boolean {
+    return this.token !== undefined && this.observerManager.hasObserver(this.token)
+  }
+
+  /**
+   * Stops the observation. Calling this method multiple times has no effect.
+   */
+  stop() {
+    const token = this.token
+    if (token) {
+      delete this._token
+      Observer.finalizationRegistry.unregister(this)
+      this.observerManager.removeObserver(token)
+    }
+  }
+
+  private static finalizationRegistry = new FinalizationRegistry(Observer.finalize)
+
+  private _token?: ObserverToken
+
+  private static finalize(observerManagerAndToken: { observerManager: ObserverManaging; token: ObserverToken }) {
+    const { observerManager, token } = observerManagerAndToken
+    observerManager.removeObserver(token)
+  }
+}

package/react-native/src/sources/pending-collections-operation.ts

@@ -0,0 +1,232 @@
+//
+// Copyright (c) 2020 - 2021 DittoLive Inc. All rights reserved.
+//
+
+import { Collection } from './collection'
+import { Document } from './document'
+import { Store } from './store'
+import { Subscription } from './subscription'
+import { PendingCursorOperation } from './pending-cursor-operation'
+
+import { CollectionsEvent } from './collections-event'
+import { LiveQuery } from './live-query'
+
+import type { SortDirection } from './essentials'
+// -----------------------------------------------------------------------------
+
+/**
+ * The closure that is called whenever the collections covered by a live query
+ * change.
+ */
+export type CollectionsObservationHandler = (event: CollectionsEvent, signalNext?: () => void) => void | Promise<void>
+
+// -----------------------------------------------------------------------------
+
+/**
+ * These objects are returned when calling
+ * {@link Store.collections | collections()} on {@link Store}.
+ *
+ * They allow chaining of further collections-related functions. You can either
+ * call {@link exec | exec()} on the object to get an array of
+ * {@link Collection}s as an immediate return value, or you can establish either
+ * a live query or a subscription, which both work over time.
+ *
+ * A live query, established by calling
+ * {@link PendingCollectionsOperation.observeLocal | observeLocal()}, will
+ * notify you every time there's a change in the collections that the device
+ * knows about.
+ *
+ * A subscription, established by calling {@link subscribe | subscribe()}, will
+ * act as a signal to other peers that the device connects to that you would
+ * like to receive updates from them about the collections that they know about.
+ */
+export class PendingCollectionsOperation implements PromiseLike<Collection[]> {
+  /**
+   * Sort the collections based on a property of the collection.
+   *
+   * @param propertyPath The property path specifies the logic to be used when
+   * sorting the matching collections.
+   *
+   * @param direction Specify whether you want the sorting order to be
+   * `Ascending` or `Descending`.
+   *
+   * @return A {@link PendingCollectionsOperation} that you can chain further
+   * function calls to.
+   */
+  sort(propertyPath: string, direction: SortDirection = 'ascending'): PendingCollectionsOperation {
+    this.pendingCursorOperation.sort(propertyPath, direction)
+    return this
+  }
+
+  /**
+   * Offset the resulting set of collections.
+   *
+   * This is useful if you aren't interested in the first N collections for one
+   * reason or another. For example, you might already have obtained the first
+   * 20 collections and so you might want to get the next 20 collections, and
+   * that is when you would use {@link offset | offset()}.
+   *
+   * @param offset The number of collections that you want the eventual
+   * resulting set of collections to be offset by (and thus not include).
+   *
+   * @return A {@link PendingCollectionsOperation} that you can chain further
+   * function calls to.
+   */
+  offset(offset: number): PendingCollectionsOperation {
+    this.pendingCursorOperation.offset(offset)
+    return this
+  }
+
+  /**
+   * Limit the number of collections that get returned.
+   *
+   * @param limit The maximum number of collections that will be returned.
+   *
+   * @return A {@link PendingCollectionsOperation} that you can chain further
+   * function calls to.
+   */
+  limit(limit: number): PendingCollectionsOperation {
+    this.pendingCursorOperation.limit(limit)
+    return this
+  }
+
+  /**
+   * Subscribes the device to updates about collections that other devices know
+   * about.
+   *
+   * The returned {@link Subscription} object must be kept in scope for as long
+   * as you want to keep receiving updates.
+   *
+   * @return A {@link Subscription} object that must be kept in scope for as
+   * long as you want to keep receiving updates from other devices about the
+   * collections that they know about.
+   */
+  subscribe(): Subscription {
+    return this.pendingCursorOperation.subscribe()
+  }
+
+  /**
+   * Enables you to listen for changes that occur in relation to the collections
+   * that are known about locally.
+   *
+   * The returned {@link LiveQuery} object must be kept in scope for as long as
+   * you want the provided `handler` to be called when an update occurs.
+   *
+   * This won't subscribe to receive updates from other devices and so it will
+   * only fire when a local change to the known about collections occurs. If
+   * you want to receive remote updates as well, then create a subscription via
+   * {@link PendingCollectionsOperation.subscribe | subscribe()}.
+   *
+   * @param handler A closure that will be called every time there is an update
+   * about the list of known about collections.
+   *
+   * @return A {@link LiveQuery} object that must be kept in scope for as long
+   * as you want to keep receiving updates.
+   */
+  observeLocal(handler: CollectionsObservationHandler): LiveQuery {
+    return this._observe(handler, false)
+  }
+
+  /**
+   * Enables you to listen for changes that occur in relation to the collections
+   * that are known about locally.
+   *
+   * The returned {@link LiveQuery} object must be kept in scope for as long as
+   * you want the provided `handler` to be called when an update occurs.
+   *
+   * This won't subscribe to receive updates from other devices and so it will
+   * only fire when a local change to the known about collections occurs. If
+   * you want to receive remote updates as well, then create a subscription via
+   * {@link PendingCollectionsOperation.subscribe | subscribe()}.
+   *
+   * @param handler A closure that will be called every time there is an update
+   * about the list of known about collections.
+   *
+   * @return A {@link LiveQuery} object that must be kept in scope for as long
+   * as you want to keep receiving updates.
+   */
+  observeLocalWithNextSignal(handler: CollectionsObservationHandler): LiveQuery {
+    return this._observe(handler, true)
+  }
+
+  /**
+   * Return the list of collections requested based on the preceding function
+   * chaining.
+   *
+   * @return A list of {@link Collection}s based on the preceding function
+   * chaining.
+   */
+  async exec(): Promise<Collection[]> {
+    const documents = await this.pendingCursorOperation.exec()
+    return collectionsFromDocuments(documents, this.store)
+  }
+
+  /** @internal */
+  readonly store: Store
+
+  /** @internal */
+  constructor(store: Store) {
+    this.store = store
+    this.pendingCursorOperation = new PendingCursorOperation('true', null, new Collection('__collections', store))
+  }
+
+  /** @internal */
+  then<TResult1 = any, TResult2 = never>(onfulfilled?: ((value: any) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): PromiseLike<TResult1 | TResult2> {
+    return this.exec().then(onfulfilled, onrejected)
+  }
+
+  // ----------------------------------------------------------- Internal ------
+
+  /** @internal */
+  _observe(handler: CollectionsObservationHandler, waitForNextSignal: boolean): LiveQuery {
+    const weakStore = new WeakRef(this.store)
+    const collectionsObservationHandler = function (documents, event, nextSignal) {
+      const strongStore = weakStore.deref()
+      if (!strongStore) {
+        return
+      }
+
+      const collections = collectionsFromDocuments(documents, strongStore)
+      let collEvent: CollectionsEvent
+
+      if (event.isInitial === true) {
+        collEvent = CollectionsEvent.initial(collections)
+      } else {
+        const oldCollections = collectionsFromDocuments(event.oldDocuments, strongStore)
+        collEvent = new CollectionsEvent({
+          isInitial: false,
+          collections,
+          oldCollections,
+          insertions: event.insertions,
+          deletions: event.deletions,
+          updates: event.updates,
+          moves: event.moves,
+        })
+      }
+
+      if (waitForNextSignal) {
+        handler(collEvent, nextSignal)
+      } else {
+        handler(collEvent)
+      }
+    }
+
+    return this.pendingCursorOperation._observe(collectionsObservationHandler, waitForNextSignal)
+  }
+
+  // ------------------------------------------------------------ Private ------
+
+  private readonly pendingCursorOperation: PendingCursorOperation
+}
+
+/** @private */
+function collectionsFromDocuments(documents: Document[], store: Store): Collection[] {
+  const collections: Collection[] = []
+  for (const document of documents) {
+    const collectionName = document.at('name').value
+    if (collectionName !== undefined && typeof collectionName === 'string') {
+      collections.push(new Collection(collectionName, store))
+    }
+  }
+  return collections
+}