@dittolive/ditto 4.4.5 → 4.5.0

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

@@ -0,0 +1,365 @@
+//
+// 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) => {
+      observationHandler(queryResult)
+      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)
+
+    this.observers = Object.freeze([...this.observers, storeObserver])
+
+
+    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) {
+
+            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 () => {
+      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 }
+
+      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[]> {
+    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)
+    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")
+    }
+
+    const indexToDelete = this.observers.findIndex((observer) => observer === storeObserver)
+    if (indexToDelete === -1) {
+      return false
+    }
+
+    const newObservers = [...this.observers]
+    newObservers.splice(indexToDelete, 1)
+    this.observers = Object.freeze(newObservers)
+
+    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
+    this.ditto.deferClose(() => {
+      mapFFIErrors(
+        () => FFI.liveQueryStop(dittoHandle.deref(), storeObserver.liveQueryID)
+      )
+    })
+    return true
+  }
+
+  /** @internal */
+  close() {
+    for (const observer of this.observers) {
+      observer.cancel()
+    }
+
+
+  }
+
+  /**
+   * 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,98 @@
+//
+// 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.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)
+    })
+  }
+}

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

@@ -0,0 +1,88 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+import { generateEphemeralToken } from './internal'
+
+import type { Collection } from './collection'
+import type { SubscriptionManager, SubscriptionContextInfo } from './subscription-manager'
+
+/**
+ * Used to subscribe to receive updates from remote peers about matching
+ * documents.
+ *
+ * While {@link Subscription} objects remain in scope they ensure that
+ * documents in the collection specified and that match the query provided will
+ * try to be kept up-to-date with the latest changes from remote peers.
+ */
+export class Subscription {
+  /**
+   * The query that the subscription is based on.
+   */
+  readonly query: string
+
+  /**
+   * Returns `true` if subscription has been explicitly cancelled, `false`
+   * otherwise.
+   */
+  get isCancelled(): boolean {
+    return this._isCancelled
+  }
+
+  /**
+   * The name of the collection that the subscription is based on.
+   */
+  get collectionName() {
+    return this.collection.name
+  }
+
+  /**
+   * Cancels a subscription and releases all associated resources.
+   */
+  cancel() {
+    if (!this.isCancelled) {
+      this._isCancelled = true
+      this.manager.remove(this)
+    }
+  }
+
+  // ----------------------------------------------------------- Internal ------
+
+  /** @internal */
+  constructor(collection: Collection, query: string, queryArgsCBOR: Uint8Array | null, orderBys: FFI.OrderBy[], limit: number, offset: number) {
+    this.query = query
+    this.queryArgsCBOR = queryArgsCBOR
+    this.collection = collection
+    this.contextInfo = {
+      id: generateEphemeralToken(),
+      collectionName: collection.name,
+      query,
+      queryArgsCBOR,
+      orderBys,
+      limit,
+      offset,
+    }
+    this.manager = collection.store.ditto.subscriptionManager
+    this.manager.add(this)
+  }
+
+  /**
+   * The collection this subscription belongs to.
+   * @internal Because not exposed in any of the other SDKs (yet?).
+   */
+  readonly collection: Collection
+
+  /**
+   * The corresponding named arguments for {@link query}, if any.
+   * @internal Because not exposed in any of the other SDKs (yet?).
+   */
+  readonly queryArgsCBOR: Uint8Array | null
+
+  /** @internal */
+  readonly contextInfo: SubscriptionContextInfo
+
+  private readonly manager: SubscriptionManager
+
+  private _isCancelled = false
+}

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

@@ -0,0 +1,90 @@
+//
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
+//
+
+import { DittoError } from './error'
+
+import type { DQLQueryArguments } from './essentials'
+import type { Ditto } from './ditto'
+import type { Sync } from './sync'
+
+/**
+ * A sync subscription configures Ditto to receive updates from remote peers
+ * about documents matching the subscription's query.
+ *
+ * The sync subscription will remain active until it is
+ * {@link SyncSubscription.cancel | cancelled}, or the Ditto instance managing
+ * the subscription has been {@link Ditto.close | closed}.
+ *
+ * Create a sync subscription by calling
+ * {@link Sync.registerSubscription | `ditto.sync.registerSubscription()`}.
+ */
+export class SyncSubscription {
+  /**
+   * Documents matching this query will be included in the sync subscription.
+   */
+  readonly queryString: string
+
+  /**
+   * The query arguments of the sync subscription (as passed when
+   * adding it to the store).
+   */
+  readonly queryArguments?: Readonly<DQLQueryArguments>
+
+  /**
+   * The {@link Ditto} instance this sync subscription belongs to.
+   */
+  readonly ditto: Ditto
+
+  /**
+   * `true` when the sync subscription has been cancelled or the {@link Ditto}
+   * instance managing this subscription has been closed.
+   */
+  get isCancelled() {
+    return this._isCancelled
+  }
+
+  /**
+   * Cancels the sync subscription and unregisters it. No-op
+   * if the sync subscription has already been cancelled or the {@link Ditto}
+   * instance managing this subscription has been closed.
+   */
+  cancel() {
+    if (this._isCancelled) return
+    this._isCancelled = true
+    this.ditto.sync.unregisterSubscription(this)
+  }
+
+  // --------------------------- Internal --------------------------------------
+
+  /** @internal */
+  constructor(ditto: Ditto, query: string, queryArguments: DQLQueryArguments | null, queryArgumentsCBOR: Uint8Array | null) {
+    if ((queryArguments == null) !== (queryArgumentsCBOR == null)) {
+      throw new DittoError('internal', 'Internal inconsistency, query arguments and query arguments CBOR must be both null or both non-null', { queryArguments, queryArgumentsCBOR })
+    }
+
+    this.ditto = ditto
+    this.queryString = query
+    this.queryArguments = queryArguments ? Object.freeze({ ...queryArguments }) : undefined
+    this.queryArgumentsCBOR = queryArgumentsCBOR
+  }
+
+  /**
+   * The CBOR-encoded query arguments, or `null` if no query arguments were
+   * passed in.
+   *
+   * @internal
+   */
+  readonly queryArgumentsCBOR: Uint8Array | null
+
+  // --------------------------- Private --------------------------------------
+
+  /**
+   * `true` when the ssync ubscription has been cancelled.
+   *
+   * We mark the sync subscription as cancelled here as an optimization to avoid
+   * a scan of all subscriptions in the store whenever the `isCancelled`
+   * property is checked.
+   */
+  private _isCancelled = false
+}