@dittolive/ditto 4.7.4-rc.2 → 4.7.4

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

@@ -0,0 +1,32 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+// NOTE: this is the last file to be rolled up. Typically, you'll use this to
+// tie up certain associations that would otherwise lead to import cycles. The
+// bridges are a good example of this: the type constructors for the bridged
+// types need to be registered with it, but can't do it at creation time of the
+// bridges, because anything that would require a certain bridge would
+// immediately require the bridged type, oftentimes leading to an import cycle.
+
+import { Attachment } from './attachment'
+import { Document, MutableDocument } from './document'
+
+import { StaticTCPClient } from './static-tcp-client'
+import { WebsocketClient } from './websocket-client'
+
+import { Ditto } from './ditto'
+import { Bridge } from './bridge'
+import { ConnectionRequest } from './connection-request'
+import { QueryResult } from './query-result'
+import { QueryResultItem } from './query-result-item'
+
+Bridge.attachment.registerType(Attachment)
+Bridge.connectionRequest.registerType(ConnectionRequest)
+Bridge.document.registerType(Document)
+Bridge.queryResultItem.registerType(QueryResultItem)
+Bridge.queryResult.registerType(QueryResult)
+Bridge.mutableDocument.registerType(MutableDocument)
+Bridge.staticTCPClient.registerType(StaticTCPClient)
+Bridge.websocketClient.registerType(WebsocketClient)
+Bridge.ditto.registerType(Ditto)

package/react-native/src/sources/error-codes.ts

@@ -0,0 +1,114 @@
+//
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
+//
+
+export type ErrorCode = keyof typeof ERROR_CODES
+
+/**
+ * Error code and default error message for all Ditto error messages.
+ *
+ * Keys of this object define _error codes_ with each value containing the
+ * accompanying error description that is set as the default error message for
+ * errors instantiated with this code.
+ *
+ * Error codes may start with an error domain and a slash to group categories of
+ * errors together.
+ */
+export const ERROR_CODES = {
+  /** Internal error for unexpected system states */
+  internal: 'An unexpected internal error occurred. Please get in touch with Ditto customer service to report this incident.',
+
+  /** Internal error with an unknown error cause */
+  'internal/unknown-error': 'An unexpected internal error occurred. Please get in touch with Ditto customer service to report this incident.',
+
+  //
+  // Errors originating in the SDK
+  //
+
+  /** Error when using a feature not supported by the current environment */
+  'sdk/unsupported': 'The feature is not supported by the current environment.',
+
+  //
+  // Query errors
+  //
+
+  /** Error for invalid DQL query arguments. */
+  'query/arguments-invalid': 'The query arguments were invalid.',
+
+  /** Errors that occur during execution of a query */
+  'query/execution': 'The query could not be executed.',
+
+  /** Error for an invalid DQL query. */
+  'query/invalid': 'The query was invalid.',
+
+  /** Error for a query that uses DQL features not supported in this version or not supported by the currently used API. */
+  'query/unsupported': 'The query contains unsupported features.',
+
+  /** Error for a failed query updating system parameters */
+  'query/parameter': 'The query to update system parameters failed.',
+
+  //
+  // Store errors
+  //
+
+  /** Error in the storage backend. */
+  'store/backend': 'An error occurred with the storage backend.',
+
+  /** Error for an invalid CRDT. */
+  'store/crdt': 'An error occurred processing a CRDT.',
+
+  /** Error for a document not found. */
+  'store/document-not-found': 'The document with the provided ID could not be found.',
+
+  /** Permission has been denied for a file operation when working with attachments. */
+  'store/attachment-file-permission-denied': 'Permission has been denied for a file operation when working with attachments.',
+
+  /** The source file for an attachment does not exist. */
+  'store/attachment-file-not-found': 'The source file for the attachment does not exist.',
+
+  /** Attachment could not be found. */
+  'store/attachment-not-found': 'The attachment could not be found.',
+
+  /** Attachment token is invalid. */
+  'store/attachment-token-invalid': 'The attachment token is invalid.',
+
+  /** An unclassified error while creating an attachment. */
+  'store/failed-to-create-attachment': 'The attachment could not be created.',
+
+  /** An unclassified error while fetching an attachment. */
+  'store/failed-to-fetch-attachment': 'The attachment could not be fetched.',
+
+  //
+  // Activation errors
+  //
+
+  /** An error representing an invalid license token. */
+  'activation/license-token-verification-failed': 'Please provide a valid license token.',
+
+  /** An error representing an expired license token.  */
+  'activation/license-token-expired': 'The license token expired. Please renew it.',
+
+  /** An error representing a token is in an unsupported future format. */
+  'activation/license-token-unsupported-future-version': 'The provided license token is in an unsupported future format.',
+
+  /** The operation failed because it requires an activated Ditto instance. */
+  'activation/not-activated': 'The operation failed because the Ditto instance has not yet been activated.',
+
+  /** A validation error where the maximum depth limit was exceeded. */
+  'validation/depth-limit-exceeded': 'The maximum depth limit has been exceeded.',
+
+  /** A validation error where the value is not valid CBOR. */
+  'validation/invalid-cbor': 'The value provided is not valid CBOR.',
+
+  /** A validation error where the value is not valid JSON. */
+  'validation/invalid-json': 'The value provided is not valid JSON.',
+
+  /** A validation error where a value is required to be a JavaScript object */
+  'validation/not-an-object': 'The value provided is not of type object.',
+
+  /** The value provided can not be serialized as JSON. */
+  'validation/not-json-compatible': 'Value is not serializable as JSON.',
+
+  /** A validation error where a size limit was exceeded. */
+  'validation/size-limit-exceeded': 'The size limit has been exceeded.',
+} as const

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

@@ -0,0 +1,256 @@
+//
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
+//
+
+import { ErrorCode, ERROR_CODES } from './error-codes'
+import { DittoFFIError } from './ffi-error'
+
+/**
+ * Additional data, which provides context to the error and may help with
+ * debugging.
+ *
+ * **Warning:** The contents of this object may change in future versions of
+ * the SDK.
+ */
+export type ErrorContext = Record<string, any>
+
+/** @see {@link FFIErrorMapping} */
+const DEFAULT_STATUS_CODE_MAPPING: FFIErrorMapping = {
+  //
+  // Activation errors
+  //
+  ActivationLicenseTokenExpired: ['activation/license-token-expired'],
+  ActivationLicenseTokenInvalid: ['activation/license-token-verification-failed'],
+  ActivationLicenseUnsupportedFutureVersion: ['activation/license-token-unsupported-future-version'],
+  ActivationNotActivated: ['activation/not-activated'],
+
+  //
+  // SDK-specific errors
+  //
+  JsFloatingStoreOperation: ['internal', 'Internal inconsistency, an outstanding store operation was not awaited.'],
+
+  //
+  // DQL errors
+  //
+  DqlQueryCompilation: ['query/invalid'],
+  DqlInvalidQueryArgs: ['query/arguments-invalid'],
+  DqlUnsupported: ['query/unsupported'],
+  StoreQuery: ['query/execution'],
+  ParameterQuery: ['query/parameter'],
+
+  //
+  // Store errors
+  //
+  StoreDocumentNotFound: ['store/document-not-found'],
+  StoreDatabase: ['store/backend'],
+  Crdt: ['store/crdt'],
+
+  //
+  // Validation errors
+  //
+  // This gets mapped to `internal` by default but depending on the context,
+  // it should be mapped to a more specific error code.
+  Base64Invalid: ['internal', 'Invalid base64 encoding.'],
+  ValidationDepthLimitExceeded: ['validation/depth-limit-exceeded'],
+  ValidationInvalidCbor: ['validation/invalid-cbor'],
+  ValidationInvalidJson: ['validation/invalid-json'],
+  ValidationNotAMap: ['validation/not-an-object'],
+  ValidationSizeLimitExceeded: ['validation/size-limit-exceeded'],
+
+  default: ['internal/unknown-error'],
+}
+
+/**
+ * `DittoError` is a subclass of the default Javascript `Error`. You can
+ * identify specific errors programatically using the
+ * {@link DittoError.code | code} property.
+ *
+ * Please reference {@link ERROR_CODES} for a comprehensive list of
+ * possible error codes in this SDK version.
+ *
+ * @example
+ * Handling a specific error code:
+ * ```typescript
+ * import { Attachment, DittoError } from '@dittolive/ditto'
+ *
+ * let attachment: Attachment
+ * try {
+ *   attachment = await ditto.store.newAttachment(filePath)
+ * } catch (error) {
+ *   if (error instanceof DittoError && error.code === 'store/attachment-file-not-found') {
+ *     // Handle a non-existing file
+ *   }
+ *   throw error // Rethrow any other error
+ * }
+ * ```
+ */
+export class DittoError extends Error {
+  /**
+   * Use the error code to identify a specific error programatically.
+   *
+   * @see {@link ERROR_CODES} for a comprehensive list of possible
+   * error codes in this SDK version.
+   */
+  readonly code: ErrorCode = 'internal'
+
+  /** Some environments provide a stack trace that is attached to any error. */
+  readonly stack?: string
+
+  /**
+   * Additional data, which provides context to the error and may help with
+   * debugging.
+   *
+   * **Warning:** The contents of this object may change in future versions of
+   * the SDK.
+   */
+  readonly context: Readonly<ErrorContext>
+
+  // --------------------------------------- Internal ------------------------
+
+  /**
+   * @internal
+   * @param code string error code, see {@link ERROR_CODES}
+   * @param message optional error message that replace's the message for the given error code
+   * @param context optional object containing data that can help debug this error
+   * @throws {@link DittoError} `internal`: when supplied with an invalid error code
+   */
+  constructor(code: ErrorCode, message?: string | null, context: ErrorContext = {}) {
+    if (ERROR_CODES[code] == null) {
+      throw new DittoError('internal', `Invalid error code: ${code}`)
+    }
+    super(message || ERROR_CODES[code])
+
+    this.code = code
+    this.context = Object.freeze({ ...context })
+  }
+
+  /**
+   * Create a {@link DittoError} from a {@link DittoFFIError}.
+   *
+   * The error message will be set to the optional `messageOverride` parameter
+   * if supplied, otherwise it will be taken from the `message` property of the
+   * given {@link DittoFFIError}. In any case, the details of the underlying FFI
+   * error are made available in the error context of the returned {@link DittoError}.
+   *
+   * @internal
+   * @param code string error code from {@link ERROR_CODES}
+   * @param messageOverride optional string that will be used as the error
+   * message even if a thread-local error message has been retrieved from the
+   * FFI
+   * @param context optional object containing data that can help debug this error
+   * @returns {@link DittoError}
+   */
+  static fromFFIError(ffiError: DittoFFIError, code: ErrorCode, messageOverride?: string, context?: ErrorContext): DittoError {
+    const message = messageOverride || ffiError.message
+    const errorContext = {
+      coreError: ffiError.code,
+      coreErrorMessage: ffiError.message,
+      ...context,
+    }
+    const err = new DittoError(code, message, errorContext)
+    if (ffiError.stack != null) {
+      // @ts-ignore
+      err.stack = ffiError.stack
+    }
+    return err
+  }
+}
+
+/**
+ * Wraps the given function to catch any {@link DittoFFIError} and rethrow it as
+ * a {@link DittoError}, mapping status codes of the {@link DittoFFIError} to
+ * error codes of the {@link DittoError} using the given `statusCodeMapping`.
+ *
+ * Use either this function or {@link mapFFIErrorsAsync} to wrap all calls into
+ * the FFI that can fail.
+ *
+ * If the given status code mapping contains error messages, they will replace
+ * any error message that is returned by the FFI.
+ *
+ * @internal
+ * @param closure function that can throw a {@link DittoFFIError}
+ * @param statusCodeMapping optional mapping of status codes of the
+ * {@link DittoFFIError} to error codes of the {@link DittoError}
+ * @param context optional object containing data that can help debug this error
+ * @throws {@link DittoError} when the wrapped function throws a {@link DittoFFIError}
+ */
+export function mapFFIErrors<T>(closure: () => T, statusCodeMapping?: FFIErrorMapping, context?: ErrorContext): T {
+  try {
+    return closure()
+  } catch (error) {
+    if (error instanceof DittoFFIError) {
+      throw translateFFIError(error, statusCodeMapping, context)
+    }
+    throw error
+  }
+}
+
+/**
+ * Wraps the given async function to catch any {@link DittoFFIError} and rethrow
+ * it as a {@link DittoError}, mapping status codes of the {@link DittoFFIError}
+ * to error codes of the {@link DittoError} using the given `statusCodeMapping`.
+ *
+ * Use either this function or {@link mapFFIErrors} to wrap any calls into the
+ * FFI that can fail.
+ *
+ * If the given status code mapping contains error messages, they will replace
+ * any error message that is returned by the FFI.
+ *
+ * @internal
+ * @param closure async function that can throw a {@link DittoFFIError}
+ * @param statusCodeMapping optional mapping of status codes of the
+ * {@link DittoFFIError} to error codes of the {@link DittoError}.
+ * @param context optional object containing data that can help debug this error
+ * @throws {@link DittoError} when the wrapped function throws a {@link DittoFFIError}
+ */
+export async function mapFFIErrorsAsync<T>(closure: () => Promise<T>, statusCodeMapping?: FFIErrorMapping, context?: ErrorContext): Promise<T> {
+  try {
+    return await closure()
+  } catch (error) {
+    if (error instanceof DittoFFIError) {
+      throw translateFFIError(error, statusCodeMapping, context)
+    }
+    throw error
+  }
+}
+
+/**
+ * Defines which status code of an FFI response should be mapped to which error
+ * code of a {@link DittoError}.
+ *
+ * The second element of the tuple is an optional string that will be used as
+ * the error message of the {@link DittoError} instead of the FFI error message
+ * if defined.
+ *
+ * If a key `default` is present, it will be used as the error code if no
+ * mapping for a given status code is found.
+ *
+ * @example
+ * ```typescript
+ * const statusCodeMapping: FFIErrorMapping = {
+ *  '1': ['activation/failed', 'It just didn\'t work out'],
+ *  'default': ['sdk/environment-incompatible']
+ * }
+ * ```
+ *
+ * @internal
+ */
+type FFIErrorMapping = {
+  // statusCode needs to be `string` because it may be a negative number, which
+  // can't be used as an object key.
+  [statusCode: string]: [ErrorCode, string?]
+}
+
+const translateFFIError = (ffiError: DittoFFIError, customStatusCodeMapping?: FFIErrorMapping, context?: ErrorContext): DittoError => {
+  // Convert the status code to a string because it may be a negative number,
+  // which can't be used as an index into an object.
+  const statusCode = ffiError.code.toString()
+
+  let code: ErrorCode, message: string | undefined
+  if (customStatusCodeMapping != null && customStatusCodeMapping[statusCode] != null) {
+    ;[code, message] = customStatusCodeMapping[statusCode]
+  } else {
+    ;[code, message] = DEFAULT_STATUS_CODE_MAPPING[statusCode] ?? DEFAULT_STATUS_CODE_MAPPING.default
+  }
+  return DittoError.fromFFIError(ffiError, code, message, context)
+}

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

@@ -0,0 +1,81 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import { DocumentID } from './document-id'
+
+import type { Attachment } from './attachment'
+
+/**
+ * Describes the direction when sorting a query.
+ */
+export type SortDirection = 'ascending' | 'descending'
+
+/**
+ * Defines the various strategies available when inserting a document into a
+ * collection.
+ *
+ * - `merge`: the existing document will be merged with the document being
+ *    inserted, if there is a pre-existing document.
+ *
+ * - `insertIfAbsent`: insert the document only if there is not already a
+ *    document with the same ID in the store. If there is already a document in
+ *    the store with the same ID then this will be a no-op.
+ *
+ * - `insertDefaultIfAbsent`: insert the document, with its contents treated as
+ *    default data, only if there is not already a document with the same ID in
+ *    the store. If there is already a document in the store with the same ID
+ *    then this will be a no-op. Use this strategy if you want to insert default
+ *    data for a given document ID, which you want to treat as common initial
+ *    data amongst all peers and that you expect to be mutated or overwritten in
+ *    due course.
+ */
+// We support an additional write strategy, `updateDifferentValues`, but don't
+// expose it in the public API of the JS SDK. This strategy was added to the
+// Cocoa, Android, and .NET SDKs but is not necessarily something we want users to use.
+// If we need to expose this strategy for JS in the future, it is already
+// implemented and can be added to the union type and documentation to make it
+// publicly available. c.f. #8638
+export type WriteStrategy = 'merge' | 'insertIfAbsent' | 'insertDefaultIfAbsent'
+
+/**
+ * Represents a dictionary of values to be incorporated into a query keyed by
+ * the placeholder used within that query. See method
+ * {@link Collection.find | find()} of {@link Collection} for more info.
+ *
+ * This value must not contain any non-finite numbers (`NaN`, `Infinity`,
+ * `-Infinity`).
+ */
+// When CBOR-encoding a `QueryArguments` object, consider using
+// `desugarJSObject()` to convert data to a JSON-compatible representation.
+//
+// NOTE: We decided not to upgrade this type to a more specific type alias
+// because this type is only used in the query builder API which is in
+// maintenance only mode.
+export type QueryArguments = {
+  [key: string]: any
+}
+
+/**
+ * Values to be incorporated into a query, keyed by the placeholder used within
+ * that query.
+ *
+ * This value must not contain any non-finite numbers (`NaN`, `Infinity`,
+ * `-Infinity`).
+ */
+// When CBOR-encoding a `DQLQueryArguments` object, consider using
+// `desugarJSObject()` to convert data to a JSON-compatible representation.
+//
+// Internally, this supports all types supported by `ditto_types::Value`.
+// https://github.com/getditto/ditto/blob/releases/stable/sdk-4.4/utils/types/src/value.rs#L267
+//
+// NOTE: This type contains `DocumentID` as the only exception to this rule,
+// that should be removed once we remove the query builder API.
+export type DQLQueryArguments = {
+  [key: string]: DQLQueryArgumentValue | undefined
+}
+
+/**
+ * Individual value in a {@link DQLQueryArguments} object.
+ */
+export type DQLQueryArgumentValue = string | number | boolean | Uint8Array | null | Attachment | DocumentID | DQLQueryArgumentValue[] | { [key: string]: DQLQueryArgumentValue }

package/react-native/src/sources/ffi-error.ts

@@ -0,0 +1,134 @@
+//
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
+//
+// This internal module contains the Ditto FFI error type and helper functions
+// for working with it. Except for the feature flag helper, this module should
+// not depend on any other parts of the Ditto Javascript SDK.
+
+import * as dittoCore from './@ditto.core'
+
+import type { Pointer, FFIError } from './ffi'
+
+/** Matches a `<...>` prefix in an FFI result error message, e.g. `<dql> ...`. **/
+const PREFIX_REGEX = new RegExp(/^<.*?>\s*/)
+
+/**
+ * Error codes for FFI result.
+ *
+ * This should include all variants of `FfiError` in `ffi/src/result/error.rs`.
+ *
+ * @internal
+ */
+// prettier-ignore
+export type FFIResultErrorCode =
+  'ActivationLicenseTokenExpired' |
+  'ActivationLicenseTokenInvalid' |
+  'ActivationLicenseUnsupportedFutureVersion' |
+  'ActivationNotActivated' |
+  'Base64Invalid' |
+  'Crdt' |
+  'DqlInvalidQueryArgs' |
+  'DqlQueryCompilation' |
+  'DqlUnsupported' |
+  'JsFloatingStoreOperation' |
+  'StoreDatabase' |
+  'StoreDocumentNotFound' |
+  'StoreQuery' |
+  'ValidationDepthLimitExceeded' | 
+  'ValidationInvalidCbor' |
+  'ValidationInvalidJson' |
+  'ValidationNotAMap' | 
+  'ValidationSizeLimitExceeded'
+
+/**
+ * Represents an exception that occurred during a call into the Ditto FFI.
+ *
+ * Use the {@link throwOnErrorStatus | throwOnErrorStatus()} helper to
+ * automatically throw this error when an FFI call returns with a non-zero
+ * return value.
+ *
+ * @internal
+ */
+export class DittoFFIError extends Error {
+  /**
+   * The code identifying this error.
+   *
+   * May be a numerical status code returned by an FFI call or an
+   * {@link FFIResultErrorCode} for errors returned on FFI result objects.
+   *
+   * @see {@link throwOnErrorStatus | throwOnErrorStatus()}
+   */
+  readonly code: number | FFIResultErrorCode
+
+  /**
+   * Only call this constructor after having called `FFI.ensureInitialized()`
+   * and `FFI.trace()`.
+   *
+   * @param code numerical status code returned by an FFI call or an
+   * {@link FFIResultErrorCode} for errors returned on FFI result objects
+   * @param messageOverride overrides the thread-local error message set in
+   * Ditto core
+   * @param messageFallback fallback message to use if the thread-local error
+   * message is empty
+   */
+  constructor(code: number | FFIResultErrorCode, messageOverride?: string, messageFallback?: string) {
+    // Call `ffiErrorMessage()` even when an override is provided to ensure that
+    // the thread-local error message is cleared.
+    const threadLocalErrorMessage = ffiErrorMessage()
+    super(messageOverride || threadLocalErrorMessage || messageFallback)
+    this.code = code
+  }
+}
+
+/**
+ * Throws a {@link DittoFFIError} if the given `ffiError` is not `null`.
+ *
+ * Removes the thread-local error message from Ditto core. If an error description
+ * is available on the given `ffiError`, it is used as the error message of the
+ * thrown {@link DittoFFIError}. A prefix in the error message is removed, e.g.
+ * `<dql> ...`.
+ *
+ * If no error description is available, the given `ffiFunctionName` is used to
+ * produce a fallback error message.
+ *
+ * @internal
+ */
+export function throwOnErrorResult(ffiError: Pointer<FFIError> | null, ffiFunctionName: string): void {
+  if (ffiError !== null) {
+    let errorCode: FFIResultErrorCode
+    let errorMsg: string | null
+    try {
+      errorCode = dittoCore.dittoffi_error_code(ffiError)
+      errorMsg = dittoCore.boxCStringIntoString(dittoCore.dittoffi_error_description(ffiError))
+      dittoCore.dittoffi_error_free(ffiError)
+    } catch (err: any) {
+      throw new DittoFFIError(-1, `Failed to retrieve Ditto core error message: ${err.message}`)
+    }
+
+    if (errorMsg == null) {
+      errorMsg = `${ffiFunctionName}() failed with error code: ${errorCode}`
+    } else {
+      // Remove prefix from error message, e.g. `<dql> ...`.
+      errorMsg = errorMsg.replace(PREFIX_REGEX, '')
+    }
+
+    throw new DittoFFIError(errorCode, errorMsg)
+  }
+}
+
+/**
+ * Retrieves last thread-local error message and removes it.
+ *
+ * Subsequent call to this function (if no new error message has been set) will
+ * always return `null`.
+ *
+ * This function is not calling `FFI.ensureInitialized()` to avoid a circular
+ * dependency. This is okay as long as this function is only called from a
+ * context where `FFI.ensureInitialized()` has already been called.
+ *
+ * @internal
+ */
+function ffiErrorMessage(): string | null {
+  const errorMessageCString = dittoCore.ditto_error_message()
+  return dittoCore.boxCStringIntoString(errorMessageCString)
+}