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

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

@@ -0,0 +1,52 @@
+//
+// 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 occured. 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 occured. Please get in touch with Ditto customer service to report this incident.',
+
+  //
+  // 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.',
+
+  //
+  // 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.',
+} as const

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

@@ -0,0 +1,208 @@
+//
+// 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 = {
+  // 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'],
+
+  // Store errors
+  StoreDocumentNotFound: ['store/document-not-found'],
+  StoreDatabase: ['store/backend'],
+  Crdt: ['store/crdt'],
+
+  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.
+ */
+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(`<${code}> ${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,
+    }
+    return new DittoError(code, message, errorContext)
+  }
+}
+
+/**
+ * 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,53 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import { DocumentID } from './document-id'
+
+/**
+ * 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.
+ */
+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.
+ */
+export type QueryArguments = {
+  [key: string]: any
+}
+
+/**
+ * Values to be incorporated into a query, keyed by the placeholder used within
+ * that query.
+ */
+export type DQLQueryArguments = {
+  [key: string]: DQLQueryArgumentValue | undefined
+}
+
+/**
+ * Individual value in a {@link DQLQueryArguments} object.
+ */
+export type DQLQueryArgumentValue = string | number | boolean | Uint8Array | null | DocumentID | DQLQueryArgumentValue[] | { [key: string]: DQLQueryArgumentValue }

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

@@ -0,0 +1,122 @@
+//
+// 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.
+ *
+ * @internal
+ */
+// prettier-ignore
+export type FFIResultErrorCode = 
+  'StoreDocumentNotFound' | 
+  'StoreDatabase' | 
+  'StoreQuery' | 
+  'Crdt' | 
+  'JsFloatingStoreOperation' | 
+  'DqlQueryCompilation' | 
+  'DqlInvalidQueryArgs' | 
+  'DqlUnsupported'
+
+/**
+ * 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)
+}