@dittolive/ditto 4.4.5 → 4.5.0

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

@@ -0,0 +1,175 @@
+//
+// 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
+    }
+
+    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) {
+
+      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,77 @@
+//
+// 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 {
+
+
+  /** @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
+}

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

@@ -0,0 +1,218 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+
+import { Bridge } from './bridge'
+import { Subscription } from './subscription'
+import { DocumentID } from './document-id'
+import { LiveQuery } from './live-query'
+import { performAsyncToWorkaroundNonAsyncFFIAPI } from './internal'
+import { BasePendingCursorOperation } from './base-pending-cursor-operation'
+
+import type { QueryArguments, SortDirection } from './essentials'
+import type { Document, MutableDocument } from './document'
+import type { UpdateResultsMap } from './update-results-map'
+import type { LiveQueryEvent } from './live-query-event'
+import type { Collection } from './collection'
+
+// -----------------------------------------------------------------------------
+
+/**
+ * The closure that is called whenever the documents covered by a live query
+ * change.
+ */
+export type QueryObservationHandler = (documents: Document[], event: LiveQueryEvent, signalNext?: () => void) => void | Promise<void>
+
+// -----------------------------------------------------------------------------
+
+/**
+ * These objects are returned when using `find`-like functionality on
+ * {@link Collection}.
+ *
+ * They allow chaining of further query-related functions to do things like add
+ * a limit to the number of documents you want returned or specify how you want
+ * the documents to be sorted and ordered.
+ *
+ * You can either call {@link exec | exec()} on the object to get an array of
+ * {@link Document | documents} 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 PendingCursorOperation.observeLocal | observeLocal()}, will notify you
+ * every time there's an update to a document that matches the query you
+ * provided in the preceding `find`-like call.
+ *
+ * A subscription, established by calling
+ * {@link PendingCursorOperation.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 documents that match the query you provided in the
+ * preceding `find`-like call.
+ *
+ * Update and remove functionality is also exposed through this object.
+ */
+export class PendingCursorOperation extends BasePendingCursorOperation {
+  sort(propertyPath: string, direction: SortDirection = 'ascending'): PendingCursorOperation {
+    return super.sort(propertyPath, direction) as PendingCursorOperation
+  }
+
+  offset(offset: number): PendingCursorOperation {
+    return super.offset(offset) as PendingCursorOperation
+  }
+
+  limit(limit: number): PendingCursorOperation {
+    return super.limit(limit) as PendingCursorOperation
+  }
+
+  async remove(): Promise<DocumentID[]> {
+    const ditto = this.collection.store.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    return ditto.deferCloseAsync(async () => {
+      const query = this.query
+      const documentsX = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
+        const writeTransactionX = await FFI.writeTransaction(dittoHandle.deref())
+        const results = await FFI.collectionRemoveQueryStr(dittoHandle.deref(), this.collection.name, writeTransactionX, query, this.queryArgsCBOR, this.orderBys, this.currentLimit, this.currentOffset)
+        await FFI.writeTransactionCommit(dittoHandle.deref(), writeTransactionX)
+        return results
+      })
+
+      return documentsX.map((idCBOR: Uint8Array) => {
+        return new DocumentID(idCBOR, true)
+      })
+    })
+  }
+
+  async evict(): Promise<DocumentID[]> {
+    const ditto = this.collection.store.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    return ditto.deferCloseAsync(async () => {
+      const query = this.query
+      const documentsX = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
+        const writeTransactionX = await FFI.writeTransaction(dittoHandle.deref())
+        const results = await FFI.collectionEvictQueryStr(dittoHandle.deref(), this.collection.name, writeTransactionX, query, this.queryArgsCBOR, this.orderBys, this.currentLimit, this.currentOffset)
+        await FFI.writeTransactionCommit(dittoHandle.deref(), writeTransactionX)
+        return results
+      })
+
+      return documentsX.map((idCBOR: Uint8Array) => {
+        return new DocumentID(idCBOR, true)
+      })
+    })
+  }
+
+  async update(closure: (documents: MutableDocument[]) => void): Promise<UpdateResultsMap> {
+    const ditto = this.collection.store.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    return ditto.deferCloseAsync(async () => {
+      return await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
+        const writeTransactionX = await FFI.writeTransaction(dittoHandle.deref())
+        const results = await super.updateWithTransaction(closure, writeTransactionX)
+        await FFI.writeTransactionCommit(dittoHandle.deref(), writeTransactionX)
+        return results
+      })
+    })
+  }
+
+  /**
+   * Enables you to subscribe to changes that occur in a collection remotely.
+   *
+   * Having a subscription acts as a signal to other peers that you are
+   * interested in receiving updates when local or remote changes are made to
+   * documents that match the query generated by the chain of operations that
+   * precedes the call to {@link subscribe | subscribe()}.
+   *
+   * The returned {@link Subscription} object must be kept in scope for as long
+   * as you want to keep receiving updates.
+   *
+   * @returns A {@link Subscription} object that must be kept in scope for as
+   * long as you want to keep receiving updates for documents that match the
+   * query specified in the preceding chain.
+   */
+  subscribe(): Subscription {
+    const subscription = new Subscription(this.collection as Collection, this.query, this.queryArgsCBOR, this.orderBys, this.currentLimit, this.currentOffset)
+    this.collection.store.ditto.subscriptionManager.add(subscription)
+    return subscription
+  }
+
+  /**
+   * Enables you to listen for changes that occur in a collection locally.
+   *
+   * The `handler` block will be called when local changes are
+   * made to documents that match the query generated by the chain of operations
+   * that precedes the call to {@link PendingCursorOperation.observeLocal | observeLocal()}.
+   * 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 changes made remotely by others and so it
+   * will only fire updates when a local change is made. If you want to receive
+   * remotely performed updates as well, you'll have to create a subscription
+   * via {@link PendingCursorOperation.subscribe | subscribe()} with the
+   * relevant query. The returned {@link LiveQuery} object must be kept in scope
+   * for as long as you want the provided `eventHandler` to be called when an
+   * update occurs.
+   *
+   * @param handler A closure that will be called every time there is a
+   * transaction committed to the store that involves modifications to documents
+   * matching the query in the collection this method was called on.
+   *
+   * @return A {@link LiveQuery} object that must be kept in scope for as long
+   * as you want to keep receiving updates.
+   */
+  observeLocal(handler: QueryObservationHandler): LiveQuery {
+    return this._observe(handler, false)
+  }
+
+  /**
+   * Enables you to listen for changes that occur in a collection locally and
+   * to signal when you are ready for the live query to deliver the next event.
+   *
+   * The `handler` block will be called when local changes are
+   * made to documents that match the query generated by the chain of operations
+   * that precedes the call to {@link PendingCursorOperation.observeLocalWithNextSignal | observeLocalWithNextSignal()}.
+   * 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 changes made remotely by others and so it
+   * will only fire updates when a local change is made. If you want to receive
+   * remotely performed updates as well, you'll have to create a subscription
+   * via {@link PendingCursorOperation.subscribe | subscribe()} with the
+   * relevant query. The returned {@link LiveQuery} object must be kept in scope
+   * for as long as you want the provided `eventHandler` to be called when an
+   * update occurs.
+   *
+   * @param handler A closure that will be called every time there is a
+   * transaction committed to the store that involves modifications to
+   * documents matching the query in the collection that this method was called
+   * on.
+   *
+   * @return A {@link LiveQuery} object that must be kept in scope for as long
+   * as you want to keep receiving updates.
+   */
+  observeLocalWithNextSignal(handler: QueryObservationHandler): LiveQuery {
+    return this._observe(handler, true)
+  }
+
+  // ----------------------------------------------------------- Internal ------
+
+  /** @internal */
+  constructor(query: string, queryArgs: QueryArguments | null, collection: Collection) {
+    super(query, queryArgs, collection)
+  }
+
+  /** @internal */
+  _observe(handler: QueryObservationHandler, waitForNextSignal: boolean): LiveQuery {
+    function wrappedHandler(documents, event, nextSignal) {
+      try {
+        return handler.call(this, documents, event)
+      } finally {
+        nextSignal()
+      }
+    }
+
+    const handlerOrWrapped: QueryObservationHandler = waitForNextSignal ? handler : wrappedHandler
+    const liveQuery = new LiveQuery(this.query, this.queryArgs, this.queryArgsCBOR, this.orderBys, this.currentLimit, this.currentOffset, this.collection as Collection, handlerOrWrapped)
+    this.collection.store.ditto.liveQueryManager.startLiveQuery(liveQuery)
+    return liveQuery
+  }
+}