@dittolive/ditto 4.7.4 → 4.7.5-rc.2

package/react-native/src/sources/live-query-event.ts

@@ -1,208 +0,0 @@
-//
-// Copyright © 2021 DittoLive Incorporated. All rights reserved.
-//
-
-import * as FFI from './ffi'
-import { Bridge } from './bridge'
-import { Logger } from './logger'
-
-import type { Document } from './document'
-
-// -----------------------------------------------------------------------------
-
-/**
- * An object that describes how a document's position in a live query's list of
- * matching documents has changed since the previous live query event.
- */
-export interface LiveQueryMove {
-  /**
-   * The index of the document in the list of matching documents from the
-   * previous live query event.
-   */
-  readonly from: number
-
-  /**
-   * The index of the document in the list of matching documents from the new
-   * live query event.
-   */
-  readonly to: number
-}
-
-// -----------------------------------------------------------------------------
-
-/** @internal */
-export interface LiveQueryEventUpdateParams {
-  oldDocuments: Document[]
-  insertions: number[]
-  deletions: number[]
-  updates: number[]
-  moves: LiveQueryMove[]
-}
-
-// -----------------------------------------------------------------------------
-
-/**
- * First event fired immediately after registering a live query without any
- * mutations. All subsequent events are of type {@link LiveQueryEventUpdate}.
- */
-export class LiveQueryEventInitial {
-  /**
-   * Whether or not this is the initial event being delivered. Always `true`
-   * for `LiveQueryEventInitial`.
-   */
-  readonly isInitial = true
-
-  /**
-   * Returns a hash that represents the set of matching documents.
-   *
-   * @deprecated use {@link Document.hash | Document.hash()} instead.
-   */
-  hash(documents: Document[]): BigInt {
-    Logger.warning('LiveQueryEventInitial.hash() is deprecated, use Document.hash() instead')
-    const documentHandles = Bridge.document.handlesFor(documents)
-    return FFI.documentsHash(documentHandles.deref())
-  }
-
-  /**
-   * Returns a pattern of words that together create a mnemonic, which
-   * represents the set of matching documents.
-   *
-   * @deprecated use {@link Document.hashMnemonic | Document.hashMnemonic()} instead.
-   */
-  hashMnemonic(documents: Document[]): string {
-    Logger.warning('LiveQueryEventInitial.hashMnemonic() is deprecated, use Document.hashMnemonic() instead')
-    const documentHandles = Bridge.document.handlesFor(documents)
-    return FFI.documentsHashMnemonic(documentHandles.deref())
-  }
-}
-
-// -----------------------------------------------------------------------------
-
-/**
- * Represents an update event describing all changes that occured for documents
- * covered by a (live) query.
- */
-export class LiveQueryEventUpdate {
-  /**
-   * Whether or not this is the initial event being delivered. Always `false`
-   * for `LiveQueryEventUpdate`.
-   */
-  readonly isInitial = false
-
-  /**
-   * The documents that previously matched the query, before the latest event.
-   */
-  readonly oldDocuments: Document[]
-
-  /**
-   * The indexes in the array of matching documents that accompany this event,
-   * which relate to a document that was not in the previous most recent list of
-   * matching documents.
-   */
-  readonly insertions: number[]
-
-  /**
-   * The indexes into the array {@link oldDocuments}, which relate to a document
-   * that was in the previous most recent list of matching documents but is no
-   * longer a matching document.
-   */
-  readonly deletions: number[]
-
-  /**
-   * The indexes in the array of matching documents that accompany this event,
-   * which relate to a document that has been updated since the previous live
-   * query event.
-   */
-  readonly updates: number[]
-
-  /**
-   * Objects that describe how documents' positions in the list of matching
-   * documents have changed since the previous live query event.
-   */
-  readonly moves: LiveQueryMove[]
-
-  /**
-   * Returns a hash that represents the set of matching documents.
-   *
-   * @deprecated use {@link Document.hash | Document.hash()} instead.
-   */
-  hash(documents: Document[]): BigInt {
-    Logger.warning('LiveQueryEventUpdate.hash() is deprecated, use Document.hash() instead')
-    const documentHandles = Bridge.document.handlesFor(documents)
-    return FFI.documentsHash(documentHandles.deref())
-  }
-
-  /**
-   * Returns a pattern of words that together create a mnemonic, which
-   * represents the set of matching documents.
-   *
-   * @deprecated use {@link Document.hashMnemonic | Document.hashMnemonic()} instead.
-   */
-  hashMnemonic(documents: Document[]): string {
-    Logger.warning('LiveQueryEventUpdate.hashMnemonic() is deprecated, use Document.hashMnemonic() instead')
-    const documentHandles = Bridge.document.handlesFor(documents)
-    return FFI.documentsHashMnemonic(documentHandles.deref())
-  }
-
-  /** @internal */
-  constructor(params: LiveQueryEventUpdateParams) {
-    this.oldDocuments = params.oldDocuments
-    this.insertions = params.insertions
-    this.deletions = params.deletions
-    this.updates = params.updates
-    this.moves = params.moves
-  }
-}
-
-// -----------------------------------------------------------------------------
-
-/**
- * Represents events delivered by a {@link LiveQuery}, which can be initial
- * (fired immediately upon registration) or an update (all subsequent events).
- */
-export type LiveQueryEvent = LiveQueryEventInitial | LiveQueryEventUpdate
-
-// -----------------------------------------------------------------------------
-
-/**
- * Provides information about a live query event relating to a single document
- * live query.
- */
-export class SingleDocumentLiveQueryEvent {
-  /**
-   * Whether or not this is the initial event being delivered.
-   */
-  readonly isInitial: boolean
-
-  /** The old representation of the document with the relveant document ID. */
-  readonly oldDocument?: Document
-
-  /**
-   * Returns a hash that represents the set of matching documents.
-   *
-   * @deprecated use {@link Document.hash | Document.hash()} instead.
-   */
-  hash(document: Document | null): BigInt {
-    Logger.warning('SingleDocumentLiveQueryEvent.hash() is deprecated, use Document.hash() instead')
-    const documentHandles = Bridge.document.handlesFor(document == null ? [] : [document])
-    return FFI.documentsHash(documentHandles.deref())
-  }
-
-  /**
-   * Returns a pattern of words that together create a mnemonic, which
-   * represents the set of matching documents.
-   *
-   * @deprecated use {@link Document.hashMnemonic | Document.hashMnemonic()} instead.
-   */
-  hashMnemonic(document: Document | null): string {
-    Logger.warning('SingleDocumentLiveQueryEvent.hashMnemonic() is deprecated, use Document.hashMnemonic() instead')
-    const documentHandles = Bridge.document.handlesFor(document == null ? [] : [document])
-    return FFI.documentsHashMnemonic(documentHandles.deref())
-  }
-
-  /** @internal */
-  constructor(isInitial: boolean, oldDocument?: Document) {
-    this.isInitial = isInitial
-    this.oldDocument = oldDocument
-  }
-}

package/react-native/src/sources/live-query-manager.ts

@@ -1,110 +0,0 @@
-//
-// Copyright © 2023 DittoLive Incorporated. All rights reserved.
-//
-
-import * as FFI from './ffi'
-import { Bridge } from './bridge'
-import { KeepAlive } from './keep-alive'
-import { LiveQuery } from './live-query'
-import { step } from './internal'
-
-import type { Ditto } from './ditto'
-
-/** @internal */
-export class LiveQueryManager {
-  readonly ditto: Ditto
-  readonly keepAlive: KeepAlive
-
-  /** @internal */
-  constructor(ditto: Ditto, keepAlive: KeepAlive) {
-    this.ditto = ditto
-    this.keepAlive = keepAlive
-    this.liveQueriesByID = {}
-  }
-
-  /** @internal */
-  startLiveQuery(liveQuery: LiveQuery) {
-    const ditto = this.ditto
-    const dittoHandle = Bridge.ditto.handleFor(ditto)
-
-    // REFACTOR: the starting closure runs detached from here which is a smell.
-    // Can we make this whole starting mechanism non-async? The culprit is
-    // the workaround for a zalgo with `ditto_live_query_start()` FFI function:
-    // It immediately triggers the live query handler making it run "in-line"
-    // when creating a live query, while subsequent invocations are async
-    // (by definition). This is a classic zalgo case. Fix by making
-    // `ditto_live_query_start()` trigger the first live query callback `async`,
-    // just like the subsequent ones.
-
-    void this.ditto.deferCloseAsync(async () => {
-      const liveQueryID = liveQuery.liveQueryID
-      if (!liveQueryID) {
-        throw new Error("Internal inconsistency, tried to add a live query that doesn't have a live query ID (probably stopped).")
-      }
-
-      const existingLiveQuery = this.liveQueriesByID[liveQueryID]
-      if (existingLiveQuery) {
-        throw new Error('Internal inconsistency, tried to add a live query with an ID that has already been added.')
-      }
-
-      const weakLiveQuery = new WeakRef(liveQuery)
-      this.liveQueriesByID[liveQueryID] = weakLiveQuery
-      this.finalizationRegistry.register(liveQuery, liveQueryID, this.finalize)
-      liveQuery.liveQueryManager = this
-
-      ditto.keepAlive.retain(`LiveQuery.${liveQueryID}`)
-
-      return new Promise<void>((resolve, reject) => {
-        // not awaited on purpose; let the invocation of the initial observation
-        // happen in a "fire-and-forget" / detached / escaping fashion, to be
-        // consistent with the subsequent invocations.
-        void step(async () => {
-          await FFI.liveQueryStart(dittoHandle.deref(), liveQueryID)
-          resolve()
-        })
-      })
-    })
-  }
-
-  /** @internal */
-  stopLiveQuery(liveQuery: LiveQuery) {
-    this.finalizationRegistry.unregister(liveQuery)
-    const liveQueryID = liveQuery.liveQueryID
-    if (!liveQueryID) {
-      throw new Error("Internal inconsistency, tried to remove a live query that doesn't have a live query ID (probably stopped).")
-    }
-
-    liveQuery.liveQueryManager = null
-    this.stopLiveQueryWithID(liveQueryID)
-  }
-
-  /** @internal */
-  close() {
-    for (const liveQueryID in this.liveQueriesByID) {
-      const weakLiveQuery = this.liveQueriesByID[liveQueryID]
-      const liveQuery = weakLiveQuery.deref()
-      if (liveQuery) {
-        this.stopLiveQuery(liveQuery)
-      }
-    }
-  }
-
-  // ------------------------------------------------------------ Private ------
-
-  private liveQueriesByID: { [key: number]: WeakRef<LiveQuery> }
-  private finalizationRegistry = new FinalizationRegistry(this.finalize)
-
-  private stopLiveQueryWithID(liveQueryID: number) {
-    const ditto = this.ditto
-    const dittoHandle = Bridge.ditto.handleFor(ditto)
-    ditto.deferClose(() => {
-      FFI.liveQueryStop(dittoHandle.deref(), liveQueryID)
-      this.keepAlive.release(`LiveQuery.${liveQueryID}`)
-      delete this.liveQueriesByID[liveQueryID]
-    })
-  }
-
-  private finalize(liveQueryID: number) {
-    this.stopLiveQueryWithID(liveQueryID)
-  }
-}

package/react-native/src/sources/live-query.ts

@@ -1,167 +0,0 @@
-//
-// Copyright © 2021 DittoLive Incorporated. All rights reserved.
-//
-
-import * as FFI from './ffi'
-
-import { Bridge } from './bridge'
-
-import { LiveQueryEventInitial } from './live-query-event'
-import { LiveQueryEventUpdate } from './live-query-event'
-
-import type { Collection } from './collection'
-import type { QueryArguments } from './essentials'
-import type { LiveQueryEvent } from './live-query-event'
-import type { LiveQueryManager } from './live-query-manager'
-import type { QueryObservationHandler } from './pending-cursor-operation'
-
-/**
- * The type that is returned when calling
- * {@link PendingCursorOperation.observeLocal | observeLocal()} on a
- * {@link PendingCursorOperation} object. It handles the logic for calling the
- * event handler that is provided to `observeLocal()` calls.
- *
- * Ditto will prevent the process from exiting as long as there are active live
- * queries (not relevant when running in the browser).
- *
- * `LiveQuery` objects must be kept in scope for as long as you wish to have
- * your event handler be called when there is an update to a document matching
- * the query you provide. When you no longer want to receive updates about
- * documents matching a query then you must call {@link stop | stop()}.
- */
-export class LiveQuery {
-  /** The query that the live query is based on. */
-  readonly query: string
-
-  /** The arguments belonging to {@link query}. */
-  readonly queryArgs: QueryArguments | null
-
-  /** The name of the collection that the live query is based on. */
-  get collectionName(): string {
-    return this.collection.name
-  }
-
-  /** Returns true if the receiver has been stopped. */
-  get isStopped(): boolean {
-    return !this.liveQueryManager
-  }
-
-  /**
-   * Stop the live query from delivering updates.
-   */
-  stop() {
-    if (!this.isStopped) {
-      ;(this.liveQueryManager as LiveQueryManager).stopLiveQuery(this)
-    }
-  }
-
-  // ----------------------------------------------------------- Internal ------
-
-  /** @internal */
-  orderBys: FFI.OrderBy[]
-
-  /** @internal */
-  queryArgsCBOR: Uint8Array | null
-
-  /** @internal */
-  readonly limit: number
-
-  /** @internal */
-  readonly offset: number
-
-  /** @internal */
-  readonly collection: Collection
-
-  /** @internal */
-  readonly handler: QueryObservationHandler
-
-  /**
-   * This field is only populated while a live query is active and set to null
-   * when the live query is stopped.
-   *
-   * @internal
-   */
-  liveQueryManager: LiveQueryManager | null
-
-  get liveQueryID(): number {
-    return this._liveQueryID
-  }
-
-  /** @internal */
-  constructor(query: string, queryArgs: QueryArguments | null, queryArgsCBOR: Uint8Array | null, orderBys: FFI.OrderBy[], limit: number, offset: number, collection: Collection, handler: QueryObservationHandler) {
-    // Query should be validated at this point.
-    this.query = query
-    this.queryArgs = queryArgs ? Object.freeze({ ...queryArgs }) : null
-    this.queryArgsCBOR = queryArgsCBOR
-    this.orderBys = orderBys
-    this.limit = limit
-    this.offset = offset
-    this.collection = collection
-    this.handler = handler
-    this.liveQueryManager = null
-
-    const collectionName = collection.name
-    const weakDitto = new WeakRef(collection.store.ditto)
-
-    let liveQueryID: number | undefined = undefined
-    const signalNext = async () => {
-      const ditto = weakDitto.deref()
-      if (!ditto) return
-
-      const dittoHandle = Bridge.ditto.handleFor(ditto)
-      const dittoPointer = dittoHandle.derefOrNull()
-      if (!dittoPointer) return
-
-      return ditto.deferCloseAsync(async () => {
-        await FFI.liveQuerySignalAvailableNext(dittoPointer, liveQueryID as number)
-      })
-    }
-
-    const ditto = collection.store.ditto
-    const dittoHandle = Bridge.ditto.handleFor(ditto)
-    ditto.deferClose(() => {
-      liveQueryID = FFI.liveQueryRegister(dittoHandle.deref(), collectionName, query, queryArgsCBOR, this.orderBys, limit, offset, (cCBParams) => {
-        const documents = cCBParams.documents.map((ptr) => Bridge.document.bridge(ptr))
-
-        let event: LiveQueryEvent
-        if (cCBParams.is_initial) {
-          event = new LiveQueryEventInitial()
-        } else {
-          event = new LiveQueryEventUpdate({
-            oldDocuments: cCBParams.old_documents.map((ptr) => Bridge.document.bridge(ptr)),
-            insertions: cCBParams.insertions,
-            deletions: cCBParams.deletions,
-            updates: cCBParams.updates,
-            moves: cCBParams.moves.map((move) => ({ from: move[0], to: move[1] })),
-          })
-        }
-
-        // We discard the return promise because error-handling is not supported.
-        void handler(documents, event, signalNext)
-      })
-    })
-
-    if (!liveQueryID) {
-      throw new Error("Internal inconsistency, couldn't create a valid live query ID.")
-    }
-
-    this._liveQueryID = liveQueryID as number
-  }
-
-  /** @internal */
-  async signalNext() {
-    // IDEA: make this public?
-    const ditto = this.collection.store.ditto
-    const dittoHandle = Bridge.ditto.handleFor(ditto)
-    const dittoPointer = dittoHandle.derefOrNull()
-    if (!dittoPointer) return
-
-    return ditto.deferCloseAsync(async () => {
-      await FFI.liveQuerySignalAvailableNext(dittoHandle.deref(), this.liveQueryID)
-    })
-  }
-
-  // ------------------------------------------------------------ Private ------
-
-  private _liveQueryID: number
-}

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

@@ -1,196 +0,0 @@
-//
-// Copyright © 2021 DittoLive Incorporated. All rights reserved.
-//
-
-import * as Environment from './@environment'
-import * as FFI from './ffi'
-
-/** The log levels supported by Ditto. */
-export type LogLevel = 'Error' | 'Warning' | 'Info' | 'Debug' | 'Verbose'
-
-/**
- * Closure that {@link Logger.setCustomLogCallback} can be set as a custom
- * log callback on {@link Logger}.
- */
-export type CustomLogCallback = (logLevel: LogLevel, message: string) => void
-
-/**
- * Class with static methods to customize the logging behavior from Ditto and
- * log messages with the Ditto logging infrastructure.
- */
-export class Logger {
-  /**
-   * Registers a file path where logs will be written to, whenever Ditto wants
-   * to issue a log (on _top_ of emitting the log to the console).
-   */
-  static get logFile(): string | undefined {
-    return this._logFile
-  }
-
-  /**
-   * On Node, registers a file path where logs will be written to, whenever
-   * Ditto wants to issue a log (on _top_ of emitting the log to the console).
-   * In the browser, this method has no effect.
-   *
-   * @param path can be `null`, in which case the current logging file, if any,
-   * is unregistered, otherwise, the file path must be within an already
-   * existing directory.
-   */
-  static setLogFile(path: string | null) {
-    if (path) {
-      FFI.loggerSetLogFile(path)
-      this._logFile = path
-    } else {
-      FFI.loggerSetLogFile(undefined)
-      delete this._logFile
-    }
-  }
-
-  /**
-   * Convenience method, takes the path part of the URL and calls
-   * {@link setLogFile | setLogFile()} with it.
-   */
-  static setLogFileURL(url: URL | undefined) {
-    this.setLogFile(url?.pathname ?? null)
-  }
-
-  /** Whether the logger is currently enabled. */
-  static get enabled(): boolean {
-    return FFI.loggerEnabledGet()
-  }
-
-  /** Enables or disables logging. */
-  static set enabled(enabled: boolean) {
-    FFI.loggerEnabled(enabled)
-  }
-
-  /**
-   * Represents whether or not emojis should be used as the log level
-   * indicator in the logs.
-   */
-  static get emojiLogLevelHeadingsEnabled(): boolean {
-    return FFI.loggerEmojiHeadingsEnabledGet()
-  }
-
-  /**
-   * Represents whether or not emojis should be used as the log level
-   * indicator in the logs.
-   */
-  static set emojiLogLevelHeadingsEnabled(emojiLogLevelHeadingsEnabled: boolean) {
-    FFI.loggerEmojiHeadingsEnabled(emojiLogLevelHeadingsEnabled)
-  }
-
-  /**
-   * The minimum log level at which logs will be logged.
-   *
-   * For example if this is set to `Warning`, then only logs that are logged
-   * with the `Warning` or `Error` log levels will be shown.
-   */
-  static get minimumLogLevel(): LogLevel {
-    return FFI.loggerMinimumLogLevelGet()
-  }
-
-  /**
-   * The minimum log level at which logs will be logged.
-   *
-   * For example if this is set to `Warning`, then only logs that are logged
-   * with the `Warning` or `Error` log levels will be shown.
-   */
-  static set minimumLogLevel(minimumLogLevel: LogLevel) {
-    FFI.loggerMinimumLogLevel(minimumLogLevel)
-  }
-
-  /**
-   * Returns the current custom log callback, `undefined` by default. See
-   * {@link setCustomLogCallback | setCustomLogCallback()} for a detailed
-   * description.
-   */
-  static get customLogCallback(): CustomLogCallback | undefined {
-    return this._customLogCallback
-  }
-
-  /**
-   * Registers a custom callback that will be called to report each log entry.
-   *
-   * @param callback function called for each log entry. `undefined` will
-   * unregister any previous callback and stop reporting log entries through
-   * callbacks.
-   *
-   * @throws {Error} if called in a React Native environment.
-   */
-  static async setCustomLogCallback(callback: CustomLogCallback | undefined): Promise<void> {
-    if (Environment.isReactNativeBuild) {
-      throw new Error('Logger custom callback is currently not implemented for React Native.')
-    }
-
-    if (callback) {
-      await FFI.loggerSetCustomLogCb(callback)
-      this._customLogCallback = callback
-    } else {
-      await FFI.loggerSetCustomLogCb(null)
-      delete this._customLogCallback
-    }
-  }
-
-  /**
-   * Logs the message for the given `level`.
-   *
-   * @see {@link error | error()}
-   * @see {@link warning | warning()}
-   * @see {@link info | info()}
-   * @see {@link debug | debug()}
-   * @see {@link verbose | verbose()}
-   */
-  static log(level: LogLevel, message: string) {
-    FFI.log(level, message)
-  }
-
-  /**
-   * Convenience method, same as calling {@link log | log()} with
-   * {@link LogLevel} `Error`.
-   */
-  static error(message: string) {
-    this.log('Error', message)
-  }
-
-  /**
-   * Convenience method, same as calling {@link log | log()} with
-   * {@link LogLevel} `Warning`.
-   */
-  static warning(message: string) {
-    this.log('Warning', message)
-  }
-
-  /**
-   * Convenience method, same as calling {@link log | log()} with
-   * {@link LogLevel} `Info`.
-   */
-  static info(message: string) {
-    this.log('Info', message)
-  }
-
-  /**
-   * Convenience method, same as calling {@link log | log()} with
-   * {@link LogLevel} `Debug`.
-   */
-  static debug(message: string) {
-    this.log('Debug', message)
-  }
-
-  /**
-   * Convenience method, same as calling {@link log | log()} with
-   * {@link LogLevel} `Verbose`.
-   */
-  static verbose(message: string) {
-    this.log('Verbose', message)
-  }
-
-  // ------------------------------------------------------------ Private ------
-
-  private static _logFile?: string
-  private static _customLogCallback?: CustomLogCallback
-
-  private constructor() {
-    throw new Error("Logger can't be instantiated, use its static properties & methods directly instead.")
-  }
-}