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

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

@@ -0,0 +1,177 @@
+//
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+
+import { Bridge } from './bridge'
+import { CBOR, documentIDReplacer } from './cbor'
+import { DittoError, mapFFIErrors } from './error'
+import { Logger } from './logger'
+import { QueryResult } from './query-result'
+
+import type { Ditto } from './ditto'
+import type { DQLQueryArguments } from './essentials'
+import type { Store } from './store'
+
+/**
+ * A store observation handler is called whenever an active store observer
+ * receives new results.
+ */
+export type StoreObservationHandler = (queryResult: QueryResult) => void
+
+/**
+ * A store observation handler is called whenever an active store observer
+ * receives new results.
+ *
+ * Call `signalNext()` to signal that the handler is ready to receive the next
+ * callback from the store observer.
+ */
+export type StoreObservationHandlerWithSignalNext = (queryResult: QueryResult, signalNext: () => void) => void
+
+/**
+ * A store observer invokes a given handler whenever results for its query
+ * change.
+ *
+ * The store observer will remain active until it is {@link cancel | cancelled},
+ * or the Ditto instance managing the observer has been
+ * {@link Ditto.close | closed}.
+ *
+ * Create a store observer by calling
+ * {@link Store.registerObserver | `ditto.store.registerObserver()`}.
+ */
+export class StoreObserver {
+  /**
+   * The Ditto instance this store observer is registered with.
+   */
+  readonly ditto: Ditto
+
+  /**
+   * The query string of the store observer (as passed when registering it).
+   */
+  readonly queryString: string
+
+  /**
+   * The query arguments of the store observer (as passed when registering it).
+   */
+  readonly queryArguments?: Readonly<DQLQueryArguments>
+
+  /**
+   * Convenience property, returns `true` once the store observer has been
+   * cancelled.
+   */
+  get isCancelled(): boolean {
+    return this._isCancelled
+  }
+
+  /**
+   * Cancels the store observer and unregisters it. No-op if the
+   * store observer has already been cancelled.
+   */
+  cancel() {
+    if (this._isCancelled) return
+    this._isCancelled = true
+    this.ditto.store.unregisterObserver(this)
+  }
+
+  // --------------------------- Internal -------------------------------------
+
+  /**
+   * The ID of this observer's live query.
+   *
+   * @internal
+   */
+  readonly liveQueryID: number
+
+  /** @internal */
+  constructor(ditto: Ditto, query: string, queryArguments: DQLQueryArguments | null, observationHandler: StoreObservationHandlerWithSignalNext) {
+    this.queryString = query
+    this.queryArguments = queryArguments ? Object.freeze({ ...queryArguments }) : undefined
+    this.ditto = ditto
+
+    let queryArgumentsCBOR: Uint8Array | null = null
+    if (queryArguments != null) {
+      try {
+        queryArgumentsCBOR = CBOR.encode(queryArguments, documentIDReplacer)
+      } catch (error: any) {
+        throw new DittoError('query/arguments-invalid')
+      }
+    }
+    let storeObserverID: number | undefined
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    this.ditto.deferClose(() => {
+      const weakThis = new WeakRef(this)
+
+      function wrappedObservationHandler(cCBParams: CCallbackParams): void {
+        const strongThis = weakThis.deref()
+        if (strongThis == null) {
+          Logger.debug(`Ignoring change event received by store observer ${storeObserverID} after it was cancelled`)
+          return
+        }
+
+        const response = Bridge.dqlResponse.bridge(cCBParams.query_result, () => new QueryResult(cCBParams.query_result))
+
+        Logger.debug(`Invoking user event handler with new event for store observer ${storeObserverID}`)
+        observationHandler(response, () => {
+          strongThis.signalNext()
+        })
+      }
+
+      const errorContext = {
+        query,
+        queryArguments,
+      }
+
+      mapFFIErrors(
+        () => {
+          storeObserverID = FFI.tryExperimentalRegisterChangeObserver(dittoHandle.deref(), query, queryArgumentsCBOR, wrappedObservationHandler)
+        },
+        undefined,
+        errorContext,
+      )
+    })
+
+    if (storeObserverID == null) {
+      throw new DittoError('internal', 'Internal inconsistency, store observer ID is undefined after registering')
+    }
+
+    this.liveQueryID = storeObserverID
+  }
+
+  // --------------------------- Private --------------------------------------
+
+  /**
+   * `true` when the store observer has been cancelled.
+   *
+   * We mark the store observer as cancelled here as an optimization to avoid a
+   * scan of all store observers in the store whenever the `isCancelled`
+   * property is checked.
+   */
+  private _isCancelled = false
+
+  /**
+   * Signals to Ditto Core that the observer is ready for the next event.
+   */
+  private signalNext() {
+    const ditto = this.ditto
+    if (!ditto || ditto.isClosed) return
+
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    const dittoPointer = dittoHandle.derefOrNull()
+    if (!dittoPointer) return
+
+    if (this.liveQueryID == null) {
+      throw new Error('live query ID is null while signaling ready for next event')
+    }
+
+    return ditto.deferCloseAsync(async () => {
+      Logger.debug(`Signaling availability for live query ${this.liveQueryID}`)
+      await FFI.liveQuerySignalAvailableNext(dittoPointer, this.liveQueryID)
+    })
+  }
+}
+
+// c.f. struct c_cb_params
+type CCallbackParams = {
+  query_result: FFI.Pointer<FFI.FFIDqlResponse>
+}

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

@@ -0,0 +1,385 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+import { Bridge } from './bridge'
+
+import { CBOR, documentIDReplacer } from './cbor'
+import { Collection } from './collection'
+import { StoreObserver } from './store-observer'
+import { DocumentID } from './document-id'
+import { DittoError, mapFFIErrors, mapFFIErrorsAsync } from './error'
+import { performAsyncToWorkaroundNonAsyncFFIAPI, step, validateQuery } from './internal'
+import { Logger } from './logger'
+import { PendingCollectionsOperation } from './pending-collections-operation'
+import { QueryResult } from './query-result'
+import { WriteTransaction } from './write-transaction'
+
+import type { StoreObservationHandlerWithSignalNext, StoreObservationHandler } from './store-observer'
+import type { Ditto } from './ditto'
+import type { DQLQueryArguments } from './essentials'
+import type { QueryResultItem } from './query-result-item'
+import type { WriteTransactionResult } from './write-transaction'
+
+/**
+ * The entrypoint for all actions that relate to data stored by Ditto. Provides
+ * access to collections, a write transaction API, and a query hash API.
+ *
+ * You don't create one directly but can access it from a particular
+ * {@link Ditto} instance via its {@link Ditto.store | store} property.
+ */
+export class Store {
+  /** The {@link Ditto} instance this store belongs to. */
+  readonly ditto: Ditto
+
+  /**
+   * All currently active store observers.
+   *
+   * **Note:** Manage store observers using
+   * {@link registerObserver | registerObserver()} to register a new store
+   * observer and {@link StoreObserver.cancel | StoreObserver.cancel()} to
+   * remove an existing store observer.
+   */
+  readonly observers: Readonly<Array<StoreObserver>> = Object.freeze([])
+
+  /**
+   * Register a handler to be called whenever a query's results change in the
+   * local store.
+   *
+   * Convenience method, same as
+   * {@link registerObserverWithSignalNext | registerObserverWithSignalNext()},
+   * except that here, the next invocation of the observation handler is
+   * triggered automatically instead of having to call the passed in
+   * `signalNext` function.
+   *
+   * @param query a string containing a valid query expressed in DQL.
+   * @param observationHandler a function that is called whenever the query's results
+   * change. The function is passed a {@link QueryResult} containing a
+   * {@link QueryResultItem} for each match.
+   * @param queryArguments an object of values keyed by the placeholder name
+   * without the leading `:`. Example: `{ "name": "Joanna" }` for a query like
+   * `SELECT * FROM people WHERE name = :name`.
+   * @returns a {@link StoreObserver} that can be used to cancel the
+   * observation.
+   * @throws {@link DittoError} `query/invalid`: if `query` argument is not a
+   * string or not valid DQL.
+   * @throws {@link DittoError} `query/arguments-invalid`: if `queryArguments`
+   * argument is invalid (e.g. contains unsupported types).
+   * @throws {@link DittoError} `query/unsupported`: if the query is not a
+   * `SELECT` query.
+   * @throws {@link DittoError} may throw other errors.
+   */
+  registerObserver(query: string, observationHandler: StoreObservationHandler, queryArguments?: DQLQueryArguments): StoreObserver {
+    const changeHandlerWithSignalNext: StoreObservationHandlerWithSignalNext = (queryResult: QueryResult, signalNext: () => void) => {
+      try {
+        observationHandler(queryResult)
+      } finally {
+        signalNext()
+      }
+    }
+    return this.registerObserverWithSignalNext(query, changeHandlerWithSignalNext, queryArguments)
+  }
+
+  /**
+   * Registers and returns a store observer for a query, configuring Ditto to
+   * trigger the passed in observation handler whenever documents in the local
+   * store change such that the result of the matching query changes. The passed
+   * in query must be a `SELECT` query.
+   *
+   * Here, a function is passed as an additional argument to the observation
+   * handler. Call this function as soon as the observation handler is ready to
+   * process the the next change event. This allows the observation handler to
+   * control how frequently it is called. See
+   * {@link registerObserver | registerObserver()} for a convenience method that
+   * automatically signals the next invocation.
+   *
+   * The first invocation of `observationHandler` will always happen after this
+   * method has returned.
+   *
+   * @param query a string containing a valid query expressed in DQL.
+   * @param observationHandler an observation handler function that is called
+   * whenever the query's results change. The function is passed a
+   * {@link QueryResult} containing a {@link QueryResultItem} for each match.
+   * @param queryArguments an object of values keyed by the placeholder name
+   * without the leading `:`. Example: `{ "name": "Joanna" }` for a query like
+   * `SELECT * FROM people WHERE name = :name`.
+   * @returns a {@link StoreObserver} that can be used to cancel the
+   * observation.
+   * @throws {@link DittoError} `query/invalid`: if `query` argument is not a
+   * string or not valid DQL.
+   * @throws {@link DittoError} `query/arguments-invalid`: if `queryArguments`
+   * argument is invalid (e.g. contains unsupported types).
+   * @throws {@link DittoError} `query/unsupported`: if the query is not a
+   * `SELECT` query.
+   * @throws {@link DittoError} may throw other errors.
+   */
+  registerObserverWithSignalNext(query: string, observationHandler: StoreObservationHandlerWithSignalNext, queryArguments?: DQLQueryArguments): StoreObserver {
+    if (typeof query !== 'string') {
+      throw new DittoError('query/invalid', `Expected parameter 'query' to be of type 'string', found: ${typeof query}`)
+    }
+
+    const storeObserver = new StoreObserver(this.ditto, query, queryArguments ?? null, observationHandler)
+
+    // @ts-expect-error modifying readonly property
+    this.observers = Object.freeze([...this.observers, storeObserver])
+
+    // We have two requirements for this step: (1) we want to be able to wait
+    // for the call to FFI to finish while closing ditto and (2) we want to
+    // return from this function without waiting for the call to FFI to finish.
+    // If we would await the call here, we could end up in a situation where
+    // the first callback to the event handler is emitted before we return from
+    // the method call that started the observer.
+
+    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
+    this.ditto.deferCloseAsync(async () => {
+      return new Promise<void>((resolve) => {
+        step(async () => {
+          try {
+            // prettier-ignore
+            await mapFFIErrorsAsync(
+              async () => await FFI.liveQueryStart(dittoHandle.deref(), storeObserver.liveQueryID)
+            )
+          } catch (error: any) {
+            // As this closure executes after the surrounding method has returned we don't throw
+            // the error here. Instead we log the error.
+            Logger.error(`Failed to start live query: ${error.message}`)
+          }
+          resolve()
+        })
+      })
+    })
+
+    return storeObserver
+  }
+
+  /**
+   * Returns the collection for the given name. If the collection doesn't
+   * exist yet, it will be created automatically as soon as the first
+   * entry is inserted.
+   * A collection name is valid if:
+   * * its length is less than 100
+   * * it is not empty
+   * * it does not contain the char '\0'
+   * * it does not begin with "$TS_"
+   */
+  collection(name: string): Collection {
+    return new Collection(name, this)
+  }
+
+  /**
+   * Returns an object that lets you fetch or observe the collections in the
+   * store.
+   *
+   * @return A {@link PendingCollectionsOperation} object that you can use to
+   * fetch or observe the collections in the store
+   */
+  collections(): PendingCollectionsOperation {
+    return new PendingCollectionsOperation(this)
+  }
+
+  /**
+   * Returns the names of all available collections in the store of the
+   * related {@link Ditto} instance.
+   */
+  collectionNames(): Promise<string[]> {
+    const ditto = this.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    return ditto.deferClose(() => {
+      return mapFFIErrors(() => FFI.dittoGetCollectionNames(dittoHandle.deref()))
+    })
+  }
+
+  /**
+   * Executes a DQL query and returns matching items as a query result.
+   *
+   * @param query a string containing a valid query expressed in DQL.
+   * @param queryArguments an object of values keyed by the placeholder name
+   * without the leading `:`. Example: `{ "name": "John" }` for a query like
+   * `SELECT * FROM people WHERE name = :name`.
+   * @returns a promise for a {@link QueryResult} containing a
+   * {@link QueryResultItem} for each match.
+   * @throws {@link DittoError} `query/invalid`: if `query` argument is not a
+   * string or not valid DQL.
+   * @throws {@link DittoError} `query/arguments-invalid`: if `queryArguments`
+   * argument is invalid (e.g. contains unsupported types).
+   * @throws {@link DittoError} may throw other errors.
+   */
+  async execute(query: string, queryArguments?: DQLQueryArguments): Promise<QueryResult> {
+    if (typeof query !== 'string') {
+      throw new DittoError('query/invalid', `Expected parameter 'query' to be of type 'string', found: ${typeof query}`)
+    }
+
+    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
+    return this.ditto.deferCloseAsync(async () => {
+      // A one-off query execution uses a transaction internally but a
+      // transaction API is not implemented yet.
+      const writeTransaction = null
+
+      let queryArgumentsCBOR: Uint8Array | null = null
+      if (queryArguments != null) {
+        try {
+          queryArgumentsCBOR = CBOR.encode(queryArguments, documentIDReplacer)
+        } catch (error: any) {
+          throw new DittoError('query/arguments-invalid', `Unable to encode query arguments: ${error.message}`)
+        }
+      }
+
+      const errorContext = { query, queryArguments }
+
+      // prettier-ignore
+      const responsePointer: FFI.Pointer<FFI.FFIDqlResponse> = await mapFFIErrorsAsync(
+        async () => await performAsyncToWorkaroundNonAsyncFFIAPI(
+          () => FFI.tryExperimentalExecQueryStr(dittoHandle.deref(), writeTransaction, query, queryArgumentsCBOR)
+        ),
+        undefined,
+        errorContext
+      )
+
+      return Bridge.dqlResponse.bridge(responsePointer, () => new QueryResult(responsePointer))
+    })
+  }
+
+  /**
+   * Initiate a write transaction in a callback.
+   *
+   * Allows you to group multiple operations together that affect multiple documents, potentially across multiple collections.
+   *
+   * @param callback is given access to a {@link WriteTransaction | write transaction object} that can be used to perform operations on the store.
+   * @returns a list of `WriteTransactionResult`s. There is a result for each operation performed as part of the write transaction.
+   */
+  async write(callback: (transaction: WriteTransaction) => Promise<void>): Promise<WriteTransactionResult[]> {
+    // Run caller's callback, rolling back if needed.
+    return this.ditto.deferCloseAsync(async () => {
+      const transaction = await WriteTransaction.init(this.ditto)
+
+      try {
+        await callback(transaction)
+      } catch (error: any) {
+        await transaction.rollback()
+        Logger.warning(`Transaction rolled back due to an error: ${error?.message}`)
+        throw error
+      }
+      await transaction.commit()
+
+      return transaction.results
+    })
+  }
+
+  // ----------------------------------------------------------- Internal ------
+
+  /** @internal */
+  constructor(ditto: Ditto) {
+    this.ditto = ditto
+  }
+
+  /**
+   * Registers a URL to be called whenever the given `SELECT` query observes
+   * changes.
+   *
+   * No validation is performed on the URL, so it is up to the caller to ensure
+   * that the URL is valid and can be reached.
+   *
+   * @internal
+   * @returns a promise for a document id that acts as a webhook id
+   * @throws {@link DittoError} `store/query-invalid`: if the query is invalid
+   * @throws {@link DittoError} `store/query-arguments-invalid`: if the query arguments
+   * are invalid
+   * @throws {@link DittoError} `store/query-unsupported`: if the query is not a
+   * `SELECT` query
+   * @throws {@link DittoError} for any other error that occurs during query execution
+   */
+  async registerObserverWebhook(query: string, url: string, queryArguments?: DQLQueryArguments): Promise<DocumentID> {
+    let queryArgumentsCBOR: Uint8Array | null = null
+    if (queryArguments != null) {
+      try {
+        queryArgumentsCBOR = CBOR.encode(queryArguments, documentIDReplacer)
+      } catch (error: any) {
+        throw new DittoError('query/arguments-invalid', `Invalid query arguments: ${error.message}`)
+      }
+    }
+
+    const errorContext = { query, queryArguments }
+
+    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
+    // prettier-ignore
+    return this.ditto.deferCloseAsync(async () => {
+      const webhookIDCBOR = await mapFFIErrorsAsync(
+        async () => await FFI.tryExperimentalWebhookRegisterDqlLiveQuery(dittoHandle.deref(), query, queryArgumentsCBOR, url),
+        undefined,
+        errorContext
+      )
+      return new DocumentID(webhookIDCBOR, true)
+    })
+  }
+
+  /**
+   * Unregister a store observer. No-op if the change observer has already
+   * been removed.
+   *
+   * This must only be called by the store observer itself.
+   *
+   * @param changeObserver the store observer to unregister
+   * @returns true if the store observer was found and removed, false otherwise
+   * @throws {@link DittoError} `internal`: if the store observer does not belong to
+   * this store
+   * @throws {@link DittoError} `internal`: if the store observer has not been
+   * cancelled yet
+   * @throws {@link DittoError} `internal`: for any other error that occurs while
+   * trying to unregister the store observer
+   * @internal
+   */
+  unregisterObserver(storeObserver: StoreObserver): boolean {
+    if (storeObserver.ditto !== this.ditto) {
+      throw new DittoError('internal', `Internal inconsistency, can't remove store observer that does not belong to this store`)
+    }
+
+    if (!storeObserver.isCancelled) {
+      throw new DittoError('internal', "Internal inconsistency, can't remove store observer that has not been cancelled")
+    }
+
+    // Return early if the store observer has already been removed.
+    const indexToDelete = this.observers.findIndex((observer) => observer === storeObserver)
+    if (indexToDelete === -1) {
+      return false
+    }
+
+    const newObservers = [...this.observers]
+    newObservers.splice(indexToDelete, 1)
+    // @ts-expect-error modifying readonly property
+    this.observers = Object.freeze(newObservers)
+
+    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
+    this.ditto.deferClose(() => {
+      // prettier-ignore
+      mapFFIErrors(
+        () => FFI.liveQueryStop(dittoHandle.deref(), storeObserver.liveQueryID)
+      )
+    })
+    return true
+  }
+
+  /** @internal */
+  close() {
+    for (const observer of this.observers) {
+      observer.cancel()
+    }
+
+    // NOTE: live query webhook is taken care of by the FFI's
+    // `ditto_shutdown()`, no need to unregister it here.
+  }
+
+  /**
+   * Private method, used only by the Portal https://github.com/getditto/ditto/pull/3652
+   * @internal
+   */
+  async registerLiveQueryWebhook(collectionName: string, query: string, url: string): Promise<DocumentID> {
+    const ditto = this.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    return ditto.deferCloseAsync(async () => {
+      const validatedQuery = validateQuery(query)
+      const idCBOR = await FFI.liveQueryWebhookRegister(dittoHandle.deref(), collectionName, validatedQuery, [], 0, 0, url)
+      return new DocumentID(idCBOR, true)
+    })
+  }
+}

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

@@ -0,0 +1,99 @@
+//
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+import { Bridge } from './bridge'
+
+import type { Ditto } from './ditto'
+import type { Subscription } from './subscription'
+
+/** @internal */
+export type SubscriptionContextInfo = {
+  id: string
+  collectionName: string
+  query: string
+  queryArgsCBOR: Uint8Array | null
+  orderBys: FFI.OrderBy[]
+  limit: number
+  offset: number
+}
+
+/**
+ * Tracks `Subscription` instances in order to remove them when Ditto is
+ * closed.
+ *
+ * @internal
+ */
+export class SubscriptionManager {
+  /** @internal */
+  constructor(ditto: Ditto) {
+    this.ditto = ditto
+    this.subscriptions = {}
+    this.finalizationRegistry = new FinalizationRegistry(this.removeWithContextInfo.bind(this))
+  }
+
+  /**
+   * Begin tracking a subscription instance and start it.
+   *
+   * @internal */
+  add(subscription: Subscription) {
+    const ditto = this.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    const contextInfo = subscription.contextInfo
+    ditto.deferClose(async () => {
+      this.subscriptions[contextInfo.id] = new WeakRef(subscription)
+      this.finalizationRegistry.register(subscription, subscription.contextInfo, subscription)
+      FFI.addSubscription(dittoHandle.deref(), contextInfo.collectionName, contextInfo.query, contextInfo.queryArgsCBOR, contextInfo.orderBys, contextInfo.limit, contextInfo.offset)
+    })
+  }
+
+  /**
+   * Stop tracking a subscription instance and cancel it.
+   *
+   * @internal */
+  remove(subscription: Subscription) {
+    if (this.subscriptions[subscription.contextInfo.id] == null) {
+      throw new Error(`Internal inconsistency, tried to remove a subscription that is not tracked: ${subscription.contextInfo.id}`)
+    }
+    this.finalizationRegistry.unregister(subscription)
+    this.removeWithContextInfo(subscription.contextInfo)
+  }
+
+  /**
+   * Stop tracking all subscriptions and cancel them.
+   *
+   * @internal */
+  close() {
+    this.ditto.deferClose(async () => {
+      for (const subscriptionID in this.subscriptions) {
+        const subscription = this.subscriptions[subscriptionID].deref()
+        if (subscription != null) {
+          // This doesn't call `Subscription.cancel()` because that is not
+          // async and we want to wait for all subscriptions to be removed.
+          this.remove(subscription)
+        }
+      }
+    })
+  }
+
+  // ----------------------------------------------------------- Internal ------
+
+  private ditto: Ditto
+  private subscriptions: { [subscriptionID: string]: WeakRef<Subscription> }
+  private finalizationRegistry: FinalizationRegistry<SubscriptionContextInfo>
+
+  /**
+   * Remove tracked subscription without unregistering from finalization
+   * registry.
+   *
+   * @internal */
+  private removeWithContextInfo(contextInfo: SubscriptionContextInfo) {
+    const ditto = this.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    ditto.deferClose(() => {
+      delete this.subscriptions[contextInfo.id]
+      FFI.removeSubscription(dittoHandle.deref(), contextInfo.collectionName, contextInfo.query, contextInfo.queryArgsCBOR, contextInfo.orderBys, contextInfo.limit, contextInfo.offset)
+    })
+  }
+}