/** @internal */ declare class KeepAlive { /** @internal */ get isActive(): boolean; /** @internal */ constructor(); /** @internal */ retain(id: string): void; /** @internal */ release(id: string): void; /** @internal */ currentIDs(): string[]; /** @internal */ countForID(id: string): number | null; private static finalizationRegistry; private intervalID; private countsByID; } /** @internal */ type ObserverToken = string; /** @internal */ interface ObserverManaging { hasObserver(token: ObserverToken): boolean; removeObserver(token: ObserverToken): void; } /** @internal */ type ObserverOptions = { stopsWhenFinalized?: boolean; }; /** * Generic observer handle returned by various observation APIs. The observation * remains active until the {@link stop | stop()} method is called explicitly or * the observer instance is garbage collected. Therefore, to keep the observation * alive, you have to keep a reference to the corresponding observer. */ declare class Observer { /** @internal */ readonly observerManager: ObserverManaging; /** @internal */ get token(): ObserverToken | undefined; /** @internal */ readonly options?: ObserverOptions; /** @internal */ constructor(observerManager: ObserverManaging, token: any, options?: ObserverOptions); /** * Returns `true` if the observer has been explicitly stopped via the `stop()` * method. Otherwise returns `false`. */ get isStopped(): boolean; /** * Stops the observation. Calling this method multiple times has no effect. */ stop(): void; private static finalizationRegistry; private _token?; private static finalize; } /** * Error codes for FFI result. * * This should include all variants of `FfiError` in `ffi/src/result/error.rs`. * * @internal */ type FFIResultErrorCode = 'ActivationLicenseTokenExpired' | 'ActivationLicenseTokenInvalid' | 'ActivationLicenseUnsupportedFutureVersion' | 'ActivationNotActivated' | 'ActivationUnnecessary' | 'AuthenticationExpirationHandlerMissing' | 'Base64Invalid' | 'CborInvalid' | 'CborUnsupported' | 'Crdt' | 'DifferIdentityKeyPathInvalid' | 'DqlEvaluationError' | 'DqlInvalidQueryArgs' | 'DqlQueryCompilation' | 'DqlUnsupported' | 'IoAlreadyExists' | 'IoNotFound' | 'IoOperationFailed' | 'IoPermissionDenied' | 'JsFloatingStoreOperation' | 'LockedDittoWorkingDirectory' | 'EncryptionExtraneousPassphraseGiven' | 'ParameterQuery' | 'StoreDatabase' | 'StoreDocumentId' | 'StoreDocumentNotFound' | 'StoreTransactionReadOnly' | 'StoreQuery' | 'Transport' | 'Unknown' | 'Unsupported' | 'ValidationDepthLimitExceeded' | 'ValidationInvalidCbor' | 'ValidationInvalidDittoConfig' | 'ValidationInvalidJson' | 'ValidationNotAMap' | 'ValidationInvalidTransportConfig' | '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 */ declare 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); } /** @internal */ type Pointer = { type: Type; addr: string; }; /** @internal */ declare const DittoCRDTTypeKey = "_ditto_internal_type_jkb12973t4b"; /** @internal */ type FFIQueryResultItem = 'dittoffi_query_result_item_t'; /** @internal */ type FFIQueryResult = 'dittoffi_query_result_t'; /** @internal */ type FFIDiffer = 'dittoffi_differ_t'; /** @internal */ type FFIDitto = 'CDitto_t'; /** @internal */ declare enum DittoCRDTType { counter = 0, register = 1, attachment = 2, rga = 3, rwMap = 4 } /** Various options to pass the web assembly module to Ditto. */ type WebAssemblyModule = RequestInfo | URL | Response | BufferSource | WebAssembly.Module | string | null; interface DittoConfigConnectServer$1 { type: 'server'; url: string; } interface DittoConfigConnectSmallPeersOnly$1 { type: 'small_peers_only'; private_key?: string; } interface DittoConfig$1 { database_id: string; connect: DittoConfigConnectServer$1 | DittoConfigConnectSmallPeersOnly$1; persistence_directory: string | null; experimental: {}; } /** @internal */ type UntypedAttachmentToken = { id: string; len: number | bigint; metadata: AttachmentMetadata; }; /** @internal */ type TypedAttachmentTokenV1 = { [DittoCRDTTypeKey]?: DittoCRDTType.attachment; _id: Uint8Array; _len: number | bigint; _meta: AttachmentMetadata; }; /** * Serves as a token for a specific attachment that you can pass to a call to * {@link Store.fetchAttachment | ditto.store.fetchAttachment()}. * * @internal */ declare class AttachmentToken { /** The attachment's ID. */ readonly id: string; /** The attachment's size given as number of bytes. */ readonly len: number | bigint; /** The attachment's metadata. */ readonly metadata: AttachmentMetadata; /** @internal */ constructor(jsObj: UntypedAttachmentToken | TypedAttachmentTokenV1); /** @internal */ readonly idBytes: Uint8Array; /** * Validate an input value that has a field `[FFI.DittoCRDTTypeKey]` and * return its contents. * * @throws {Error} If the input is invalid. * @returns {object} binary id, len and metadata of the attachment token */ private static validateTypedInput; /** * Validate an untyped input value and return its contents. * * Converts _unpadded_ base64-encoded ID in input to _padded_ base64-encoded * ID before returning it as `Uint8Array`. * * @throws {@link DittoError} `store/attachment-token-invalid` If the input id * is not a valid base64 string. * @returns {object} binary id, len and metadata of the attachment token */ private static validateUntypedInput; } 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. */ declare const ERROR_CODES: { /** Internal error for unexpected system states */ readonly 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 */ readonly unknown: "An unexpected internal error occurred. Please get in touch with Ditto customer service to report this incident."; /** Error when using a feature not supported by the current environment */ readonly unsupported: "The feature is not supported by the current environment."; /** Error when authentication failed */ readonly 'authentication/failed-to-authenticate': "Ditto failed to authenticate."; /** Error when the required expiration handler is not set before starting sync. */ readonly 'authentication/expiration-handler-missing': "The expiration handler must be set before starting sync."; /** Error when a file or directory already exists */ readonly 'io/already-exists': "A file or directory already exists."; /** Error when a file or directory could not be found */ readonly 'io/not-found': "A file or directory could not be found."; /** Error when permission is denied for a file operation */ readonly 'io/permission-denied': "The operation failed due to insufficient permissions."; /** Error when an IO operation failed for an unspecified reason. See error message for details. */ readonly 'io/operation-failed': "The operation failed."; /** Error for invalid DQL query arguments. */ readonly 'query/arguments-invalid': "The query arguments were invalid."; /** Errors that occur during evaluation of a query */ readonly 'query/evaluation': "The query could not be evaluated."; /** Errors that occur during execution of a query */ readonly 'query/execution': "The query could not be executed."; /** Error for an invalid DQL query. */ readonly '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. */ readonly 'query/unsupported': "The query contains unsupported features."; /** Error for a failed query updating system parameters */ readonly 'query/parameter': "The query to update system parameters failed."; /** Error in the storage backend. */ readonly 'store/backend': "An error occurred with the storage backend."; /** Error for an invalid CRDT. */ readonly 'store/crdt': "An error occurred processing a CRDT."; /** Error for a document not found. */ readonly 'store/document-not-found': "The document with the provided ID could not be found."; /** Error for writing to a read-only transaction. */ readonly 'store/transaction-read-only': "A mutating DQL query was attempted using a read-only transaction."; /** Error for an invalid document ID. */ readonly 'store/document-id': "The document ID is invalid."; /** Error when the chosen persistence directory is already in use by another Ditto instance. */ readonly 'store/persistence-directory-locked': "The chosen persistence directory is already in use by another Ditto instance."; /** Permission has been denied for a file operation when working with attachments. */ readonly '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. */ readonly 'store/attachment-file-not-found': "The source file for the attachment does not exist."; /** Attachment could not be found. */ readonly 'store/attachment-not-found': "The attachment could not be found."; /** Attachment token is invalid. */ readonly 'store/attachment-token-invalid': "The attachment token is invalid."; /** An unclassified error while creating an attachment. */ readonly 'store/failed-to-create-attachment': "The attachment could not be created."; /** An unclassified error while fetching an attachment. */ readonly 'store/failed-to-fetch-attachment': "The attachment could not be fetched."; /** An error representing an invalid license token. */ readonly 'activation/license-token-verification-failed': "Please provide a valid license token."; /** An error representing an expired license token. */ readonly 'activation/license-token-expired': "The license token expired. Please renew it."; /** An error representing a token is in an unsupported future format. */ readonly '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. */ readonly 'activation/not-activated': "The operation failed because the Ditto instance has not yet been activated."; /** Activation is unnecessary for this Ditto instance, because of its identity. */ readonly 'activation/unnecessary': "Activation is unnecessary for this Ditto instance, because of its identity."; /** A validation error where the maximum depth limit was exceeded. */ readonly 'validation/depth-limit-exceeded': "The maximum depth limit has been exceeded."; /** A validation error where the value is not valid CBOR. */ readonly 'validation/invalid-cbor': "The value provided is not valid CBOR."; /** A validation error where the value is not valid JSON. */ readonly 'validation/invalid-json': "The value provided is not valid JSON."; /** A validation error where the TransportConfig is invalid for the active platform. */ readonly 'validation/invalid-transport-config': "The TransportConfig is invalid for the active platform."; /** A validation error where the {@link DittoConfig} is invalid. */ readonly 'validation/invalid-ditto-config': "The DittoConfig provided is invalid."; /** A validation error where a value is required to be a JavaScript object */ readonly 'validation/not-an-object': "The value provided is not of type object."; /** The value provided can not be serialized as JSON. */ readonly 'validation/not-json-compatible': "Value is not serializable as JSON."; /** A validation error where a size limit was exceeded. */ readonly 'validation/size-limit-exceeded': "The size limit has been exceeded."; /** * Error when a passphrase was provided but the store is not encrypted. * * This error is not in use for the JavaScript SDK, which currently does not * support encrypted stores. */ readonly 'encryption/extraneous-passphrase-given': "Unexpected passphrase provided for the currently unencrypted store."; /** */ readonly 'differ/identity-key-path-invalid': "A provided identity key path is invalid."; }; /** * `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 * } * ``` */ declare 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; /** Some environments provide a stack trace that is attached to any error. */ readonly stack?: string; /** * @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 * @throws {@link DittoError} `internal`: when supplied with an invalid error code */ constructor(code: ErrorCode, message?: string | null); /** * 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}. * * @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 * @returns {@link DittoError} */ static fromFFIError(ffiError: DittoFFIError, code: ErrorCode, messageOverride?: string): DittoError; } /** * 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} * @throws {@link DittoError} when the wrapped function throws a {@link DittoFFIError} */ declare function mapFFIErrors(closure: () => T, statusCodeMapping?: Partial): T; /** * 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}. * @throws {@link DittoError} when the wrapped function throws a {@link DittoFFIError} */ declare function mapFFIErrorsAsync(closure: () => Promise, statusCodeMapping?: Partial): Promise; /** * 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 = Record; /** * Provides info about the authentication status. */ type AuthenticationStatus = { /** * Returns `true` if authenticated, otherwise returns `false`. */ isAuthenticated: boolean; /** * If authenticated, returns the `userID` if one was provided by the * authentication service. Otherwise returns `null`. */ userID: string | null; }; /** * Represents the result of a login attempt. */ type LoginResult = { /** * JSON-formatted client info returned by the authentication webhook, if any. * This field is populated for both successful and failed login attempts and * is only `null` when no client info was provided by the webhook. * * See Ditto's online documentation for more information on how to provide * client info using an authentication webhook. */ clientInfo: string | null; /** * If the login attempt was successful, this property will be `null`. If the * login attempt failed, this property will contain a {@link DittoError} object with * details about the error. */ error: DittoError | null; }; /** * A function type that handles authentication expiration events for Ditto. * * This handler is called when the authentication for a Ditto instance has or is * about to expire, or if authentication has not yet occurred. It provides the * relevant {@link Ditto} instance and the time interval (in seconds) until * expiration. You can use this to login or to perform other necessary actions * before authentication expires. * * **Important:** When using the _server_ connection mode (i.e. * {@link DittoConfigConnectServer}), you **must** set an expiration handler via * {@link Authenticator.setExpirationHandler | ditto.auth.setExpirationHandler() }. * Otherwise, {@link Sync.start | ditto.sync.start()} will throw * {@link DittoError} with code `authentication/expiration-handler-missing`. * * @param ditto The {@link Ditto} instance whose authentication is expiring. * @param timeUntilExpiration The time interval, in seconds, until * authentication expires. */ type AuthenticationExpirationHandler = (ditto: Ditto, timeUntilExpiration: number) => Promise | any; /** * Provides access to authentication information and methods for logging on to * Ditto Cloud. Relevant when using a `server` connection mode. */ declare class Authenticator { /** * Returns `true` if authentication is available and the login methods can be * used, otherwise returns `false`. Currently, authentication is only * available if Ditto was initialized with an "server" connection mode * (i.e. {@link DittoConfigConnectServer}). */ readonly loginSupported: boolean; /** * The built-in development authentication provider to be used together with * development authentication tokens. * * @see {@link Authenticator.login | Authenticator.login()} for more information * about the `provider` parameter. */ static get DEVELOPMENT_PROVIDER(): string; /** * The handler that will be called when authentication for this Ditto instance * is about to expire. * * **Important:** If the Ditto instance is configured with a * {@link DittoConfigConnectServer} this property **must** be set and the * handler **must** properly authenticate when called. * * @see {@link setExpirationHandler} */ get expirationHandler(): AuthenticationExpirationHandler | null; /** * Sets the handler that will be called when authentication for this Ditto * instance is about to expire. * * Assign a handler function to be notified before authentication expires, * allowing you to login or perform other necessary actions. * * @see {@link expirationHandler} */ setExpirationHandler(handler: AuthenticationExpirationHandler | null): Promise; /** Returns the current authentication status. */ get status(): AuthenticationStatus; /** * Log in to Ditto with a third-party token. * * Returns a promise that resolves to a `LoginResult` object. When the login * attempt is successful, the `error` property of the response will be `null`, * otherwise it will contain a {@link DittoError} object with details about * the error. * * If the authentication service provides additional client info, it will be * returned in the `clientInfo` property of the response, whether the login * attempt was successful or not. * * @param token The authentication token required to log in. * @param provider The name of the authentication provider. Use * {@link Authenticator.DEVELOPMENT_PROVIDER} with development tokens. * @throws {@link DittoError} `authentication/failed-to-authenticate` if the * Ditto instance is closed. * @returns A promise that resolves to a `LoginResult` object. */ login(token: string, provider: string): Promise; /** * Log out of Ditto. * * This will stop sync, shut down all replication sessions, and remove any * cached authentication credentials. Note that this does not remove any data * from the store. If you wish to delete data from the store then use the * optional `cleanupFn` parameter to perform any required cleanup. * * @param cleanupFn An optional function that will be called with the relevant * [Ditto] instance as the sole argument that allows you to perform any * required cleanup of the store as part of the logout process. */ logout(cleanupFn?: (ditto: Ditto) => void): Promise; observeStatus(callback: (authenticationStatus: AuthenticationStatus) => void): Observer; /** @internal */ constructor(keepAlive: KeepAlive, ditto: Ditto); /** @internal */ close(): void; /** @internal */ private readonly ditto; /** @internal */ private keepAlive; /** @internal */ private observerManager; /** @internal */ private _status; /** @internal */ private _expirationHandler; private authenticationStatusUpdated; private updateAndNotify; private makeFFFIAuthenticationExpirationHandler; } /** * Specifies how this instance discovers and connects to peers, including * network settings and authentication options. This is a substructure of * {@link DittoConfig}. */ type DittoConfigConnect = DittoConfigConnectServer | DittoConfigConnectSmallPeersOnly; /** * Connects this Ditto instance to a Big Peer at the specified URL. This is a * substructure of {@link DittoConfig}. * * **Important**: For sync to work with server connections, Ditto requires (a) a * {@link AuthenticationExpirationHandler} to be set via * {@link Authenticator.setExpirationHandler | ditto.auth.setExpirationHandler()}, and * (b) that handler to properly authenticate when requested. * {@link Sync.start | startSync()} will throw if the expiration handler is * not set. */ interface DittoConfigConnectServer { mode: 'server'; url: string; } /** * Restricts connectivity to small peers only, optionally using a shared secret * (in the form of a private key) for authentication. * * If a {@link DittoConfigConnectSmallPeersOnly.privateKey | privateKey} is * provided, it will be used as a shared secret for authenticating peer-to-peer * connections. The default value is `null`, which means no encryption is used * in transit. */ interface DittoConfigConnectSmallPeersOnly { mode: 'smallPeersOnly'; privateKey?: string | null; } /** * A configuration object for initializing a {@link Ditto} instance. * * Encapsulates all the parameters required to configure a Ditto instance, * including identity, connectivity, and persistence. */ declare class DittoConfig { /** * The default database ID, used when no database ID is provided. * * @see {@link DittoConfig.databaseID | database_id} for more information about the * `databaseID` parameter. */ static get DEFAULT_DATABASE_ID(): string; /** * Returns a default {@link DittoConfig} instance with standard settings. * * This is useful as a starting point or for quickly creating a basic * configuration, but for production use you should customize the * configuration as needed. */ static get default(): DittoConfig; /** * The unique identifier for the Ditto instance. * * This must be a valid UUID string. You can find the ID in the Ditto portal, * or provide your own if you only need to sync with a small set of peers. * * Note: "Database ID" was referred to as "App ID" in older versions of the * SDK. * * @see {@link DittoConfig.DEFAULT_DATABASE_ID | DEFAULT_DATABASE_ID} for the * default database ID used when no ID is provided. */ databaseID: string; /** * The connectivity configuration for this Ditto instance. * * Specifies how this instance discovers and connects to peers, including * network settings and authentication options. */ connect: DittoConfigConnect; /** * The persistence directory used by Ditto to persist data. * * This property can have three types of values: * - **Absolute path**: A string with an absolute file path (e.g., * `/Users/joe/some/path/to/my-project.ddb`) * - **Relative path**: A string with a relative file path (e.g., * `some/path/to/my-project.ddb`) * - **undefined**: Uses the default persistence directory * * When a relative path is set, it will be resolved relative to * {@link Ditto.DEFAULT_ROOT_DIRECTORY}. When this is `undefined`, Ditto will * use a default directory name of `ditto-{id}` within * {@link Ditto.DEFAULT_ROOT_DIRECTORY}, where `{id}` is the lowercase version * of the {@link DittoConfig.databaseID | id} set in this `DittoConfig`. * * To access the final resolved absolute path after creating a Ditto instance, * use {@link Ditto.absolutePersistenceDirectory}. This property will always * return the effective absolute file path being used, regardless of whether * you provided an absolute path, relative path, or `undefined`. * * Note: It is not recommended to directly read from or write to this directory, as * its structure and contents are managed by Ditto and may change in future * versions. * * Note: When {@link Logger} is enabled, logs may be written to this directory even * after a Ditto instance has been deallocated. Please refer to the * documentation of {@link Logger} for more information. * * @see {@link Ditto.absolutePersistenceDirectory} */ persistenceDirectory?: string; /** * Initializes a new {@link DittoConfig} instance with the new API. */ constructor(id: string, connect: DittoConfigConnect, persistenceDirectory?: string); /** * Returns true if the receiver has been frozen using * {@link DittoConfig.freeze | freeze()}. */ get isFrozen(): boolean; /** * Deep freezes the receiver such that it can't be modified anymore. * * Use {@link DittoConfig.copy | copy()} to create a copy of the receiver that * is not frozen. * * @see {@link DittoConfig.isFrozen} */ freeze(): Readonly; /** * Returns a deep copy of the receiver. * * The copy is not frozen, so it's properties can be modified. * * Warning: This does not create copies of * {@link AuthenticationExpirationHandler | authentication expiration handlers} * referenced by the config. Changes inside the handlers will be reflected in * the copy. */ copy(): DittoConfig; private _isFrozen; /** @internal */ get requiresOfflineLicenseToken(): boolean; /** * @param legacyPersistenceDirectory - SDKS-3187: optional v4 default path for * migration fallback. Passed by Ditto.open()/openSync() when the user hasn't * set an explicit persistenceDirectory. * @internal */ toCBOR(legacyPersistenceDirectory?: string): Uint8Array; /** * Validates the config structure. * * Only covers type and presence validation as anything beyond that is handled * by core. */ private validate; } /** * Converts a FFI {@link DittoConfig} into a {@link DittoConfig} instance. * * @internal */ declare function fromFFICBORData(data: DittoConfig$1): DittoConfig; /** * The types of attachment fetch events that can be delivered to an attachment * fetcher's `callback`. */ type AttachmentFetchEventType = 'Completed' | 'Progress' | 'Deleted'; /** * An attachment fetch event used when the attachment's download has completed. */ type AttachmentFetchEventCompleted = { type: 'Completed'; attachment: Attachment; }; /** * An attachment fetch event used when the attachment's download progressed but * is not yet complete. */ type AttachmentFetchEventProgress = { type: 'Progress'; totalBytes: number | bigint; downloadedBytes: number | bigint; }; /** * An attachment fetch event used when the attachment is deleted. */ type AttachmentFetchEventDeleted = { type: 'Deleted'; }; /** * A representation of the events that can occur in relation to an attachment * fetch. * * There are three different attachment fetch events: `Completed`, `Progress`, * or `Deleted`. * * There will be at most one `Completed` or `Deleted` event per attachment * fetch. There can be many `Progress` events delivered for each attachment * fetch. * * Updates relating to an attachment fetch are delivered by registering an * {@link AttachmentFetcher} through a call to * {@link Store["fetchAttachment"] | ditto.store.fetchAttachment()}. */ type AttachmentFetchEvent = AttachmentFetchEventCompleted | AttachmentFetchEventProgress | AttachmentFetchEventDeleted; /** * These objects are returned by calls to * {@link Store.fetchAttachment | ditto.store.fetchAttachment()} * and allow you to stop an in-flight attachment fetch. */ declare class AttachmentFetcher implements PromiseLike { /** * Returns a promise for the attachment that you can `await`. * * The promise is rejected if an error occurs during the fetch. Note that the * `AttachmentFetcher` itself implements `PromiseLike`, so you can `await` it * directly. */ readonly attachment: Promise; /** * Stops fetching the associated attachment and cleans up any associated * resources. * * Note that you are not required to call `stop()` once your attachment fetch * operation has finished. The method primarily exists to allow you to cancel * an attachment fetch request while it is ongoing if you no longer wish for * the attachment to be made available locally to the device. */ stop(): void; /** @internal */ readonly cancelTokenPromise: Promise | null; /** @internal */ readonly ditto: Ditto; /** @internal */ readonly id: string; /** @internal */ readonly tokenIDBytes: Uint8Array; /** @internal */ readonly token: UntypedAttachmentToken; /** @internal */ then(onfulfilled?: ((value: any) => TResult1 | PromiseLike) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike) | null | undefined): PromiseLike; /** @internal */ constructor(ditto: Ditto, token: UntypedAttachmentToken, eventHandler?: (attachmentFetchEvent: AttachmentFetchEvent) => void); /** * `true` if the fetcher has completed or was stopped. * * @internal */ get isStopped(): boolean; /** * This function is defined while a fetch is in progress and is used to reject * the promise `this.attachment` when the fetch is canceled. * * @internal */ private rejectPendingFetch; } declare const CUSTOM_INSPECT_SYMBOL: unique symbol; /** * Represents a single match of a DQL query, similar to a “row” in SQL terms. * It’s a reference type serving as a “cursor”, allowing for efficient access of * the underlying data in various formats. * * The {@link QueryResultItem.value | value } property is lazily materialized * and kept in memory until it goes out of scope. To reduce the memory * footprint, structure your code such that items can be processed as a stream, * i.e. one by one (or in batches) and * {@link QueryResultItem.dematerialize | dematerialize() } them right after * use. * * @template T The type of the item's {@link QueryResultItem.value | value }. */ declare class QueryResultItem { /** * Returns the content as a materialized object. * * The item's value is * {@link QueryResultItem.materialize | materialized() } on first access * and subsequently on each access after performing * {@link QueryResultItem.dematerialize | dematerialize() }. Once * materialized, the value is kept in memory until explicitly * {@link QueryResultItem.dematerialize | dematerialize() }-ed or the item * goes out of scope. */ get value(): T; /** * Returns `true` if value is currently held materialized in memory, otherwise * returns `false`. * * See {@link QueryResultItem.materialize | materialize()} and * {@link QueryResultItem.dematerialize | dematerialize()}. */ get isMaterialized(): boolean; /** * Loads the CBOR representation of the item's content, decodes it as an * object so it can be accessed via {@link QueryResultItem.value | value }. * Keeps the object in memory until * {@link QueryResultItem.dematerialize | dematerialize() } is called. No-op * if {@link QueryResultItem.value | value } is already materialized. */ materialize(): void; /** * Releases the materialized value from memory. No-op if item is not * materialized. */ dematerialize(): void; /** * Returns the content of the item as CBOR data. * * Important: The returned CBOR data is not cached, make sure to call this * method once and keep it for as long as needed. */ cborData(): Uint8Array; /** * Returns the content of the item as a JSON string. * * Important: The returned JSON string is not cached, make sure to call this * method once and keep it for as long as needed. */ jsonString(): string; /** * Defines a custom inspect representation for Node.js that will be used when * the object is inspected with console.log() or util.inspect(). * * @internal */ [CUSTOM_INSPECT_SYMBOL](_depth: number, _inspectOptions: any, inspect: any): string; private materializedValue; /** @internal */ constructor(); /** @internal */ static fromJSON(jsonData: string): QueryResultItem; /** @internal */ deref(): Pointer; } /** * Represents results returned when executing a DQL query containing a * {@link QueryResultItem} for each match. * * More info, such as metrics, will be provided in the near future. * * @template T The type of items in the query result. */ declare class QueryResult { /** * Individual items matching a DQL query. */ readonly items: QueryResultItem[]; /** * IDs of documents that were mutated _locally_ by a _mutating_ DQL query * passed to {@link Store.execute | `execute()`}. Empty array if no documents * have been mutated. * * **Note: Query results received from a {@link StoreObserver} never contain * mutated document IDs because a store observer is always registered using a * non-mutating `SELECT` query. /** * IDs of documents that were mutated _locally_ by a _mutating_ DQL query * passed to {@link Store.execute | `execute()`}. Empty array if no documents * have been mutated. * * **Note: Query results received from a {@link StoreObserver} never contain * mutated document IDs because a store observer is always registered using a * non-mutating `SELECT` query. * * **Important:** The returned document IDs are not cached, make sure to call * this method once and keep the return value for as long as needed. * * @returns an array of document ID values as JSON-compatible values */ mutatedDocumentIDsV2(): any[]; /** * The commit ID associated with this query result, if any. * * This ID uniquely identifies the commit in which this change was accepted * into the _local_ store. The commit ID is available for all query results * involving insertions, updates, or deletions. This ID can be used to track * whether a local change has been synced to other peers. * * For write transactions, the commit ID is only available after the * transaction has been successfully committed. Queries executed within an * uncommitted transaction will not have a commit ID. */ get commitID(): bigint | null; /** @internal */ constructor(queryResultPointer: Pointer); } /** * A store observation handler is called whenever an active store observer * receives new results. * * @template T The type of items in the query result. */ 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. * * @template T The type of items in the query result. */ type StoreObservationHandlerWithSignalNext = (queryResult: QueryResult, signalNext: () => any) => 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()`}. * * {@link StoreObserver.queryString | query} nor validated against it. * @template S The type of query arguments. */ declare 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). */ get queryString(): string; /** * The query arguments of the store observer (as passed when registering it). */ get queryArguments(): Readonly | undefined; /** * The query arguments of the store observer, serialized as CBOR, (as passed * when adding it to the store). * * Note that any {@link Attachment} values passed in as query arguments when * creating this store observer will be represented by a serialized version of * that attachment. */ get queryArgumentsCBORData(): Uint8Array | undefined; /** * The query arguments of the store observer, serialized as JSON, (as passed * when adding it to the store). * * Note that any {@link Attachment} values passed in as query arguments when * creating this store observer will be represented by a serialized version of * that attachment. */ get queryArgumentsJSONString(): string | undefined; /** * Convenience property, returns `true` once the store observer has been * cancelled. */ get isCancelled(): boolean; /** * Cancels the store observer and unregisters it. No-op if the store observer * has already been cancelled. */ cancel(): void; /** @internal */ constructor(ditto: Ditto); private deref; } /** * Defines the interface for executing DQL queries. Implemented by * {@link Store | Store} and {@link Transaction | Transaction}. */ interface QueryExecuting { /** * Executes a DQL query and returns matching items as a query result. * * **Note:** only returns results from the local store without waiting for any * {@link SyncSubscription | sync subscriptions} to have caught up with the * latest changes. Only use this method if your program must proceed with * immediate results. Use a {@link StoreObserver | store observer} to receive * updates to query results as soon as they have been synced to this peer. * * @param query A string containing a valid query expressed in DQL. * @param args 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`. * @template T The type of items returned by the query. This is a convenience * type that is neither inferred from the `query` parameter nor validated * against it. * @template U The type of the query arguments * @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 `args` * argument is invalid (e.g. contains unsupported types). * @throws {@link DittoError} `transaction-read-only`: if a mutating DQL query * was attempted using a read-only transaction. (only for * the `transaction.execute()` API). * @throws {@link DittoError} may throw other errors. */ execute(query: string, args?: U): Promise>; } /** Encapsulates information about a transaction. * * @see {@link Store.transaction | ditto.store.transaction()} */ declare class TransactionInfo { /** A globally unique ID of the transaction. */ id: string; /** * The user hint passed when creating the transaction, useful * for debugging and testing. */ hint?: string | undefined; /** * Indicates whether mutating DQL statements can be executed in the * transaction. Defaults to `false`. */ isReadOnly: boolean; constructor(id: string, isReadOnly: boolean, hint?: string); } /** * Represents an action that completes a transaction, by either committing it or * rolling it back. */ type TransactionCompletionAction = 'commit' | 'rollback'; /** * Represents a transaction in the Ditto store. * * A `Transaction` groups multiple operations into a single atomic unit, * ensuring that all operations within the transaction are either fully applied * or not applied at all, thereby maintaining data integrity. * * For more information on creating and using transactions, refer to the * {@link Store.transaction | ditto.store.transaction()} method. For a comprehensive guide on * transactions, please visit the * [Ditto documentation](https://ditto.com/link/sdk-latest-crud-transactions). */ declare class Transaction implements QueryExecuting { /** The store this transaction belongs to. */ readonly store: Store; constructor(store: Store); /** Provides information about the current transaction. */ get info(): TransactionInfo; execute(query: string, queryArguments?: U): Promise>; /** @internal */ complete(action: TransactionCompletionAction): Promise; } /** * Interface representing options for a transaction. */ type TransactionOptions = { /** * Indicates whether the transaction is read-only. Defaults to `false`. */ isReadOnly?: boolean; /** * A hint for the transaction, useful for debugging and testing. * Defaults to `null`. */ hint?: string; }; /** * 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. */ declare class Store implements QueryExecuting { /** 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. * * @throws when this Ditto instance has been closed. */ get observers(): Readonly>; /** * All currently active attachment fetchers. * * **Note:** Manage attachment fetchers using * {@link fetchAttachment | fetchAttachment()} to start a new attachment fetch * and {@link AttachmentFetcher.stop | AttachmentFetcher.stop()} to cancel * an existing attachment fetch. */ readonly attachmentFetchers: Readonly>; /** @internal */ get transactions(): TransactionInfo[]; /** * 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`. * @template T The type of items returned by the query. This is a convenience * type that is neither inferred from the `query` parameter nor validated * against it. * @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; /** * 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`. * @template T The type of items returned by the query. This is a convenience * type that is neither inferred from the `query` parameter nor validated * against it. * @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; execute(query: string, queryArguments?: U): Promise>; /** * Creates a new {@link Attachment} object, which can then be inserted into a * document. * * The file residing at the provided path will be copied into * Ditto's store. * The {@link Attachment} object that is returned is what you can then use to * insert an attachment into a document. * * **Note**: Relative paths for file sources are resolved from the current working * directory. * * You can provide metadata about the attachment, which will be replicated to * other peers alongside the file attachment. * * @example Inserting an attachment into a document * ```JavaScript * // Copy the file into Ditto's store and create an attachment object. * const attachment = await ditto.store.newAttachment( * '/path/to/my/file.pdf', * { my_field: 'optional metadata' } * ) * * // Prepare the document value including the attachment. * const doc = { * _id: '123', * my_attachment: attachment, * other: 'some-string' * } * * // Insert the document into the collection, marking `my_attachment` as an * // attachment field. * await ditto.store.execute( * `INSERT INTO my_collection (my_attachment ATTACHMENT) * VALUES (:doc)`, * { doc } * ) * ``` * * @param pathOrData The path to the file that you want to create an * attachment with or the raw data. * * @param metadata Optional metadata that will be stored alongside the * attachment. * * @returns A promise for an {@link Attachment} object that can be used to * insert the attachment into a document. * * @throws {@link DittoError} `store/attachment-file-permission-denied` when * the file at the given path could not be read because of insufficient * permissions. * * @throws {@link DittoError} `store/attachment-file-not-found` when the file * at the given path could not be found. * * @throws {@link DittoError} `store/failed-to-create-attachment` when the * attachment could not be created for other reasons. * * @throws {@link DittoError} `unsupported` when trying to create an * attachment from a file path in a web browser. */ newAttachment(pathOrData: string | Uint8Array, metadata?: AttachmentMetadata): Promise; /** * Trigger an attachment to be downloaded locally to the device and observe * its progress as it does so. * * When you encounter a document that contains an attachment, the attachment * will not automatically be downloaded along with the document. You trigger * an attachment to be downloaded locally to a device by calling this method. * It will report events relating to the attachment fetch attempt as it tries * to download it. The `eventHandler` block may be called multiple times with * progress events. It will then be called with either a `Completed` event or * a `Deleted` event. If downloading the attachment succeeds then the * `Completed` event that the `eventHandler` will be called with will hold a * reference to the downloaded attachment. * * The attachment to be fetched is identified by the `token` parameter. The * token is found in {@link QueryResultItem} objects returned from queries for * documents that have attachments (see example below). * * @example Fetch an attachment from a document in the store * * ```js * // Fetch the attachment token from a document in the store * const result = await ditto.store.execute(` * SELECT * FROM COLLECTION cars WHERE my_attachment.id = :id`, * { id: "123" } * ) * const attachmentToken = result.items[0].value.my_attachment * * // Trigger the attachment to be downloaded * const attachment = await ditto.store.fetchAttachment(attachmentToken) * * // Extract the attachment data * const attachmentData = await attachment.data() * ``` * * @param token The attachment token of the attachment to be downloaded. * * @param eventHandler An optional callback that will be called when there is * an update to the status of the attachment fetch attempt. * * @returns An {@link AttachmentFetcher} object, which is `PromiseLike` so * that you can `await` it to wait for the attachment to be downloaded. It * also provides a {@link AttachmentFetcher.stop | stop()} method to cancel * the fetch attempt. * * @throws {@link DittoError} `store/attachment-not-found` when the attachment * could not be found. * * @throws {@link DittoError} `store/attachment-token-invalid` when the given * attachment token is invalid. * * @throws {@link DittoError} `store/failed-to-fetch-attachment` when fetching * the attachment fails for other reasons. */ fetchAttachment(token: { id: string; len: number | bigint; metadata: AttachmentMetadata; }, eventHandler?: (event: AttachmentFetchEvent) => void): AttachmentFetcher; /** @internal */ constructor(ditto: Ditto); /** * Remove an attachment fetcher that is owned by this store. No-op if the * attachment fetcher has already been removed. * * This must only be called by the attachment fetcher itself. * * @param attachmentFetcher the attachment fetcher to finalize * @returns true if the attachment fetcher was found and removed, false * otherwise * @internal */ removeAttachmentFetcher(attachmentFetcher: AttachmentFetcher): boolean; /** * Executes multiple DQL queries within a single atomic transaction. * * This ensures that either all statements are executed successfully, or none * are executed at all, providing strong consistency guarantees. Certain mesh * configurations may impose limitations on these guarantees. For more * details, refer to the [Ditto * documentation](https://ditto.com/link/sdk-latest-crud-transactions). * * Transactions are initiated as read-write by default, and only one * read-write transaction can be executed at any given time. Any other * read-write transaction started concurrently will wait until the current * transaction has been committed or rolled back. Therefore, it is crucial to * ensure a transaction finishes as early as possible to prevent blocking * other read-write transactions. * * A transaction can also be configured to be read-only using the `isReadOnly` * parameter. Multiple read-only transactions can be executed concurrently. * However, executing a mutating DQL statement in a read-only transaction will * throw an error. * * If errors occur in an `execute()` call within a transaction block and the * error is caught and handled within the block, the transaction will continue * to run and not be rolled back. When an error is thrown at any point inside * the transaction block or while committing the transaction, the transaction * is implicitly rolled back, and the error is propagated to the caller. * * When a Ditto instance goes out of scope, it will drive all pending * transactions to completion before being shut down. * * **Warning:** Calling `ditto.store.execute()` or creating a nested * transaction within a transaction may lead to a deadlock. * * The transaction closure provided here can either return a * {@link TransactionCompletionAction} or an arbitrary value, either of which * will then also be returned by the call to this method itself. If one of the * {@link TransactionCompletionAction} values `'commit'` or `'rollback'` is * returned from the closure, that action is applied. If any other value, * including `null`, is returned, the transaction is committed unless an error * is thrown from the closure. * * Example usage (explicit completion): * * ```ts * await store.transaction(async (transaction) => { * // ... * return 'commit' * }) * ``` * * Example usage (returning a custom type): * * ```ts * interface UserData { * id: string * name: string * } * * const user: UserData = await store.transaction(async (transaction) => { * // ... * return { id: 'u1', name: 'Alice' } * }) * ``` * * @template T The type of the value returned from the `scope` function. * Defaults to `TransactionCompletionAction`. * @param {Function} scope A function that provides access to a transaction * object to execute DQL queries. * @param {TransactionOptions} [options] Optional settings for the * transaction. * @returns {Promise} A promise that resolves to the value returned by the * scope function. If that value is a {@link TransactionCompletionAction}, the * transaction is completed with the same action. * @throws {DittoError} Throws `DittoError` of `store/transaction-read-only` * if a mutating query is executed in a read-only transaction. * @throws {DittoError} May throw other `DittoError`s. * @throws Will rethrow any error thrown within the `scope` function. * @see {@link Transaction} * @see {@link TransactionOptions} */ transaction(scope: (transaction: Transaction) => Promise, options?: TransactionOptions): Promise; /** @internal */ beginTransaction(options?: TransactionOptions): Promise; /** @internal */ close(): void; } /** * Indicates whether a connection request should be authorized. * * `allow` if the request should be authorized, `deny` otherwise. */ type ConnectionRequestAuthorization = 'allow' | 'deny'; /** * A handler for connection requests from other peers. * * Set a `ConnectionRequestHandler` on * {@link Presence.connectionRequestHandler | `ditto.presence.connectionRequestHandler`} * to allow or deny connection requests from other peers. * * @param connectionRequest - Contains information about the remote peer that * can be used to make an authorization decision. * * @returns `allow` if the request should be authorized, `deny` otherwise. * * @see * {@link Presence.connectionRequestHandler | `ditto.presence.connectionRequestHandler`} * for details on the connection request API. */ type ConnectionRequestHandler = (connectionRequest: ConnectionRequest) => Promise; /** * Contains information about a remote peer that has requested a connection. * * Connection requests and their authorization are scoped to a specific Ditto * peer and connection type. */ declare class ConnectionRequest { /** * The unique peer key of the remote peer. * * @see field `peerKey` on {@link Peer} for more information on peer keys. */ get peerKey(): string; /** * Metadata associated with the remote peer. * * This is an empty object if the remote peer has not set any metadata. * * Set peer metadata for the local peer using {@link Presence.peerMetadata} or * {@link Presence.peerMetadataJSONString}. * * This is a convenience property that wraps * {@link peerMetadataJSONString | `peerMetadataJSONString()`}. */ get peerMetadata(): Record; /** * JSON-encoded metadata associated with the remote peer. * * This is a JSON string representing an empty dictionary if the remote peer * has not set any metadata. * * Set peer metadata for the local peer using {@link Presence.peerMetadata} or * {@link Presence.peerMetadataJSONString}. * * Uses UTF-8 encoding. */ get peerMetadataJSONString(): string; /** * Metadata for the remote peer that is provided by the identity service. * * Use an authentication webhook to set this value. See Ditto's online * documentation for more information on how to configure an authentication * webhook. * * Convenience property that wraps {@link identityServiceMetadataJSONString}. */ get identityServiceMetadata(): Record; /** * JSON-encoded metadata for the remote peer that is provided by the * identity service. * * Use an authentication webhook to set this value. See Ditto's online * documentation for more information on how to configure an authentication * webhook. * * Uses UTF-8 encoding. */ get identityServiceMetadataJSONString(): string; /** * The network transport of this connection request. * * Expect to receive separate connection requests for each network * transport that connects the local and remote peer. */ get connectionType(): ConnectionType; /** @internal */ toString(): string; private deref; } /** Types of connections that can be established between two peers. */ type ConnectionType = 'P2PWiFi' | 'WebSocket' | 'AccessPoint' | 'Bluetooth'; /** Represents a connection between two peers in a Ditto mesh network. */ type Connection = { /** Unique identifier for the connection. * * This ID is deterministic for any two peers and a given connection type. * * **Example ID** * * "1<->2:Bluetooth" */ id: string; /** Type of transport enabling this connection. */ connectionType: ConnectionType; /** * The peer key of the peer at one end of the connection. * * The assignment to `peer1` and `peer2` is deterministic * and stable for any two peers. */ peer1: string; /** * The peer key of the peer at the other end of the connection. * * The assignment to `peer1` and `peer2` is deterministic * and stable for any two peers. */ peer2: string; }; /** * The operating system a peer is running on, if known. */ type PeerOS = 'Generic' | 'iOS' | 'tvOS' | 'Android' | 'Linux' | 'Windows' | 'macOS'; /** Represents a peer in a Ditto mesh network. */ type Peer = { /** * The peer key is a unique identifier for a given peer, equal to or * derived from the cryptographic public key used to authenticate it. * * NOTE: This will be empty when a peer is not updated to the latest * version of the SDK. */ peerKey: string; /** * Metadata associated with the peer, empty dictionary by default. * * Use `ditto.presence.setPeerMetadata()` or * `ditto.presence.setPeerMetadataJSONData()` to set this value. * * Peer metadata is dynamic and may change over the lifecycle of the * {@link Presence.graph | presence graph}. Specifically, it may be empty when * a peer initially appears in the graph and will be updated once the peer has * synced its metadata with the local peer. * * @see {@link Presence.peerMetadata | `ditto.presence.peerMetadata`} for * details on usage of metadata. */ peerMetadata: Record; /** * Metadata associated with the peer by the identity service. * * Use an authentication webhook to set this value. See Ditto's online * documentation for more information on how to configure an authentication * webhook. */ identityServiceMetadata: Record; /** * The human-readable device name of the peer. This defaults to the hostname * but can be manually set by the application developer of the other peer. * It is not necessarily unique. */ deviceName: string; /** * Currently active connections of the peer. */ connections: Connection[]; /** * Indicates whether the peer is connected to Ditto Cloud. * * This field was called `isConnectedToDittoCloud` in SDK versions prior to * 5.0.0. */ isConnectedToDittoServer: boolean; /** * Indicates whether the peer is compatible with the local peer. * May be `undefined` if compatibility is not yet determined. */ isCompatible?: boolean; /** The operating system the peer is running on, `undefined` if (yet) unknown. */ os?: PeerOS; /** The Ditto SDK version the peer is running with, `undefined` if (yet) unknown. */ dittoSdkVersion?: string; }; /** * Represents the Ditto mesh network of peers and their connections between each * other. The `localPeer` is the entry point, all others are remote peers known * by the local peer (either directly or via other remote peers). */ type PresenceGraph = { /** * Returns the local peer (usually the peer that is represented by the * currently running Ditto instance). The `localPeer` is the entry point, all * others are remote peers known by the local peer (either directly or via * other remote peers). */ localPeer: Peer; /** * Returns all remote peers known by the `localPeer`, either directly or via * other remote peers. */ remotePeers: Peer[]; /** * Returns the underlying CBOR data if the presence graph has been initialized * with CBOR. All of Ditto API returning a presence graph has this property * set. */ underlyingCBOR?: Uint8Array; }; /** * The entrypoint for all actions that relate presence of other peers known by * the current peer, either directly or through other peers. * * You don't create one directly but can access it from a particular `Ditto` * instance via its `presence` property. */ declare class Presence { /** The Ditto instance this object belongs to. */ readonly ditto: Ditto; /** * Set this handler to control which peers in a Ditto mesh can connect to the * current peer. * * Each peer in a Ditto mesh will attempt to connect to other peers that it * can reach. By default, the mesh will try and establish connections that * optimize for the best overall connectivity between peers. However, you can * set this handler to assert some control over which peers you connect to. * * If set, this handler is called for every incoming connection request from a * remote peer and is passed the other peer's `peerKey`, `peerMetadata`, and * `identityServiceMetadata`. The handler can then accept or reject the * request by returning an according {@link ConnectionRequestAuthorization} * value. When the connection request is rejected, the remote peer may retry * the connection request after a short delay. * * Connection request handlers must reliably respond to requests within a * short time. If a handler takes too long to respond or throws an exception, * the connection request will be denied. The response timeout is currently 10 * seconds but may be subject to change in future releases. * * @see {@link peerMetadata | peerMetadata()} */ get connectionRequestHandler(): ConnectionRequestHandler | null; /** * @throws TypeError: if the given handler is not a function. */ set connectionRequestHandler(handler: ConnectionRequestHandler | null); /** * Returns the current presence graph capturing all known peers and * connections between them. */ get graph(): PresenceGraph; /** * Metadata associated with the current peer. Other peers in the same mesh can * access this user-provided object of metadata via the presence {@link graph} * and when evaluating connection requests using * {@link connectionRequestHandler | connectionRequestHandler()}. * * Uses UTF-8 encoding. * * @see {@link peerMetadata | peerMetadata()} for a convenience property that * provides access to parsed metadata. */ get peerMetadataJSONString(): string; /** * Set arbitrary metadata to be associated with the current peer. * * The metadata must not exceed 4 KB in size when JSON-encoded. * * @param {string} jsonString JSON-encoded metadata. * * @throws {@link DittoError} `validation/invalid-json`: if `jsonString` does * not contain valid JSON. * * @throws {@link DittoError} `validation/not-an-object`: if `jsonString` does * not contain an object. * * @throws {@link DittoError} `validation/size-limit-exceeded`: if the size * limit for `jsonString` has been exceeded. * * @see {@link peerMetadataJSONString | peerMetadataJSONString()} for details * on usage of metadata. */ setPeerMetadataJSONString(jsonString: string): Promise; /** * This is a convenience property that wraps * {@link peerMetadataJSONString | peerMetadataJSONString()}. * * @see {@link peerMetadataJSONString | peerMetadataJSONString()} for details. */ get peerMetadata(): Record; /** * This is a convenience method that wraps * {@link setPeerMetadataJSONString | setPeerMetadataJSONString()}. * * @throws {@link DittoError} `validation/not-an-object`: if `peerMetadata` is * not an object. * * @throws {@link DittoError} `validation/not-json-compatible`: if * `peerMetadata` is not JSON serializable. * * @throws {@link DittoError} `validation/size-limit-exceeded`: if the size * limit for `peerMetadata` has been exceeded. * * @see {@link setPeerMetadataJSONString | setPeerMetadataJSONString()} for * details. */ setPeerMetadata(peerMetadata: Record): Promise; /** * Request information about Ditto peers in range of this device. * * This method returns an observer which should be held as long as updates are * required. A newly registered observer will have a peers update delivered to * it immediately. From then on it will be invoked repeatedly when Ditto * devices come and go, or the active connections to them change. */ observe(didChangeHandler: (presenceGraph: PresenceGraph) => void): Observer; /** @internal */ constructor(ditto: Ditto); /** @internal */ close(): void; /** * Cleans up and transforms the raw presence graph from FFI. * * - Removes deprecated byte array properties (peerKey, address, etc.) * - Adds new string properties (peerKey from peerKeyString, peer1/peer2 from peerKeyString1/2) * - Migrates renamed properties (isConnectedToDittoCloud → isConnectedToDittoServer) */ private static cleanPresenceGraph; /** * Cleans up a single peer and its connections. */ private static cleanPeer; /** * Renames the field name. c.f. SDKS-1007 */ private static migratePeerToIsConnectedToDittoServer; private observerManager; private _connectionRequestHandler; } /** * 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()`}. */ declare class SyncSubscription { /** * Documents matching this query will be included in the sync subscription. */ get queryString(): string; /** * The query arguments of the sync subscription (as passed when adding it to * the store). * * Note that this value is not guaranteed to be strictly equal to the value * used when registering the sync subscription. In particular, any * {@link Attachment} values in query arguments will be represented by that * attachment's attachment token here. * * Also see {@link queryArgumentsCBORData} and * {@link queryArgumentsJSONString} for the raw serialized representations of * the query arguments. */ get queryArguments(): Readonly | undefined; /** * The query arguments of the sync subscription, serialized as CBOR, (as * passed when adding it to the store). * * Note that any {@link Attachment} values passed in as query arguments when * creating this sync subscription will be represented by a serialized version * of that attachment. */ get queryArgumentsCBORData(): Uint8Array | undefined; /** * The query arguments of the sync subscription, serialized as JSON, (as * passed when adding it to the store). * * Note that any {@link Attachment} values passed in as query arguments when * creating this sync subscription will be represented by a serialized version * of that attachment. */ get queryArgumentsJSONString(): string | undefined; /** * `true` when the sync subscription has been cancelled or the {@link Ditto} * instance managing this subscription has been closed. */ get isCancelled(): boolean; /** * The {@link Ditto} instance this sync subscription belongs to. */ readonly ditto: Ditto; /** * 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(): void; /** @internal */ constructor(ditto: Ditto); private deref; } /** * Provides access to sync related functionality of Ditto. * * Access this object via {@link Ditto.sync | Ditto.sync} on any Ditto instance. */ declare class Sync { /** * The {@link Ditto} instance managed by this sync object. */ readonly ditto: Ditto; /** * All currently active {@link SyncSubscription | sync subscriptions}. * * **Note:** Manage sync subscriptions using * {@link registerSubscription | registerSubscription()} to register a new * sync subscription and * {@link SyncSubscription.cancel | SyncSubscription.cancel()} to remove an * existing sync subscription. */ get subscriptions(): Readonly>; /** * Returns `true` if sync is active, otherwise returns `false`. Use * {@link Sync.start | ditto.sync.start()} to activate and * {@link Sync.stop | ditto.sync.stop()} to deactivate sync. */ get isActive(): boolean; /** * Starts the network transports. Ditto will connect to other devices. * * By default Ditto will enable all peer-to-peer transport types. On **Node**, * this means BluetoothLE, WiFi/LAN, and AWDL. On the **Web**, only connecting * via Websockets is supported. The default network configuration can be * modified with {@link Ditto.updateTransportConfig | updateTransportConfig()} * or replaced with {@link Ditto.setTransportConfig | setTransportConfig()}. * * * Ditto will prevent the process from exiting until sync is stopped (not * relevant when running in the browser). * * @see {@link Sync.isActive | ditto.sync.isActive} * @see {@link Sync.stop | ditto.sync.stop()} */ start(): void; /** * Stops all network transports. * * You may continue to use the Ditto store locally but no data will sync to or * from other devices. * * @see {@link Sync.isActive | ditto.sync.isActive} * @see {@link Sync.start | ditto.sync.start()} */ stop(): void; /** * Installs and returns a sync subscription for a query, configuring Ditto to * receive updates from other peers for documents matching that query. The * passed in query must be a `SELECT` query, otherwise an error is thrown. * * @param query a string containing a valid query expressed in DQL. * @param queryArguments an object containing the arguments for the query. * Example: `{mileage: 123}` for a query with `:mileage` placeholder. * @returns An active `SyncSubscription` for the passed in query and * arguments. It will remain active until it is * {@link SyncSubscription.cancel | cancelled} or the {@link Ditto} instance * managing the sync subscription has been closed. * @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. */ registerSubscription(query: string, queryArguments?: DQLQueryArguments): SyncSubscription; /** @internal */ constructor(ditto: Ditto); /** @internal */ close(): void; } /** * The entrypoint for small peer user info collection. Small peer info consists * of information gathered into a system collection on a regular interval and * optionally synced to the Big Peer for device dashboard and debugging * purposes. * * An instance of this class is available on each `Ditto` instance via its * {@link Ditto.smallPeerInfo | `smallPeerInfo`} property. Instantiating this * class directly is not supported. */ declare class SmallPeerInfo { /** * Indicates whether small peer info collection is currently enabled, defaults * to `true`. * * **Note**: whether the background ingestion process is enabled or not is a * separate decision to whether this information is allowed to sync to other * peers (including the big peer). That is controlled by _sync scopes_, see * Ditto's online documentation for details on how to configure them. */ get isEnabled(): boolean; /** * Set whether small peer info collection is enabled. * * @throws when set to a non-boolean value. */ set isEnabled(newValue: boolean); /** * The metadata associated with the small peer info. * * Small peer info metadata is a free-form, user-provided JSON object that * is inserted into the small peer info system document at each collection * interval. */ get metadata(): Record; /** * Set the metadata associated with the small peer info. * * The metadata must be a JSON-serializable object that conforms to the * following constraints: * * - Must be a JSON object (not an array, string, number, etc.) * - The size when encoded as JSON must be less than 128 KB * - May only be nested up to 64 levels deep * * @example Valid metadata * ditto.smallPeerInfo.metadata = { * "foo": "bar", * "nested": { * "inner": "value" * } * } * * @throws when set to a value that violates any of the constraints listed * above. */ set metadata(metadata: Record); /** * The metadata associated with the small peer info, as a JSON string. */ get metadataJSONString(): string; /** * Set the metadata associated with the small peer info, as a JSON string. * * @see {@link SmallPeerInfo.metadata | `metadata`} for more information on * valid values. * @throws when set to a value that violates any of the constraints listed in * {@link SmallPeerInfo.metadata | `metadata`}. */ set metadataJSONString(metadata: string); private ditto; /** @internal */ constructor(ditto: Ditto); } /** * Restore a `TransportConfig` from its serializable representation. * * @internal */ declare function transportConfigFromDeserializable(serialized: any): TransportConfig; /** * Convert a `TransportConfig` to a serializable representation. * * This mainly involves converting the `TransportConfig`'s properties to have the expected key names * and casing. * * @internal */ declare function transportConfigToSerializable(config: TransportConfig): any; /** * Part of {@link TransportConfig} type, configuration for listening for TCP * connections. */ interface TransportConfigListenTCP { isEnabled: boolean; interfaceIP: string; port: number; } /** * Part of {@link TransportConfig} type, configuration for listening for HTTP, * including Websocket, connections. */ interface TransportConfigListenHTTP { isEnabled: boolean; interfaceIP: string; port: number; websocketSync: boolean; tlsKeyPath?: string; tlsCertificatePath?: string; } /** * Part of {@link TransportConfig} type, configuration for all P2P transports. */ interface TransportConfigPeerToPeer { bluetoothLE: { isEnabled: boolean; }; awdl: { isEnabled: boolean; }; wifiAware: { isEnabled: boolean; }; lan: TransportConfigLan; } /** * Part of {@link TransportConfig} type, configuration for discovering and syncing with peers on LAN. */ interface TransportConfigLan { isEnabled: boolean; isMdnsEnabled: boolean; isMulticastEnabled: boolean; } /** * Part of {@link TransportConfig} type, configuration for connecting to TCP * and Websocket servers. */ interface TransportConfigConnect { tcpServers: string[]; websocketURLs: string[]; /** * The retry interval in milliseconds between failed connection attempts. For cross-compatibility, this must be less than 2^32 - 1. */ retryInterval: number; } /** * Part of {@link TransportConfig} type, configuration for listening for * incoming TCP and HTTP connections. */ interface TransportConfigListen { tcp: TransportConfigListenTCP; http: TransportConfigListenHTTP; } /** * Part of {@link TransportConfig} type, settings not associated with any specific type of transport. */ interface TransportConfigGlobal { /** * The sync group for this device. * * When peer-to-peer transports are enabled, all devices with the same App ID will * normally form an interconnected mesh network. In some situations it may be * desirable to have distinct groups of devices within the same app, so that * connections will only be formed within each group. The `syncGroup` parameter * changes that group membership. A device can only ever be in one sync group, which * by default is group 0. Up to 2^32 distinct group numbers can be used in an app. * * This is an optimization, not a security control. If a connection is created * manually, such as by specifying a `connect` transport, then devices from * different sync groups will still sync as normal. If two groups of devices are * intended to have access to different data sets, this must be enforced using * Ditto's permissions system. */ syncGroup: number; /** * The routing hint for this device. * * A routing hint is a performance tuning option which can improve the performance of * applications that use large collections. Ditto will make a best effort to co-locate data for * the same routing key. In most circumstances, this should substantially improve responsiveness * of the Ditto Cloud. * * The value of the routing hint is application specific - you are free to chose any value. * Devices which you expect to operate on much the same data should be configured to * use the same value. * * A routing hint does not partition data. The value of the routing hint will not affect the data * returned for a query. The routing hint only improves the efficiency of the Cloud's * ability to satisfy the query. */ routingHint: number; } /** * A configuration object specifying which network transports Ditto should * use to sync data. * * A Ditto object comes with a default transport configuration where all * available transports are enabled (for example, regarding peer-to-peer transports, * Bluetooth LE and LAN on every platform, plus AWDL on Apple platforms or * Wi‑Fi Aware on Android). You can customize this by copying that or * initializing a new `TransportConfig`, adjusting its properties, and supplying * it to `setTransportConfig()` on `Ditto`. * * When you initialize a new `TransportConfig` instance, all transports are * disabled. You must enable each one explicitly. * * Platform‑supported transports can also be toggled in a single call with * {@link setAvailablePeerToPeerEnabled | setAvailablePeerToPeerEnabled()}. * * Peer-to-peer transports will automatically discover peers in the vicinity * and create connections without any configuration. These are configured via * the `peerToPeer` property. To turn each one on, set its `isEnabled` property * to `true`. * * To connect to a peer at a known location, such as a Ditto Big Peer, add its * address inside the connect configuration. These are either "host:port" * strings for raw TCP sync, or a "wss://…" URL for websockets. * * The listen configurations are for specific less common data sync scenarios. * Please read the documentation on the Ditto website for examples. Incorrect * use of listen can result in insecure configurations. * * **IMPORTANT**: when running in the browser, only the `connect.websocketURLs` * part is considered, the rest of the configuration is ignored. */ declare class TransportConfig { /** Configuration for peer-to-peer connections. */ readonly peerToPeer: TransportConfigPeerToPeer; /** Configuration for connecting to servers. */ readonly connect: TransportConfigConnect; /** Configuration for listening for incoming connections. */ readonly listen: TransportConfigListen; /** Settings not associated with any specific type of transport. */ readonly global: TransportConfigGlobal; /** * Create a new transport config initialized with the default settings. */ constructor(); /** * Enables or disables _every_ peer-to-peer transport protocols defined in * {@link peerToPeer} regardless of whether the current platform * can actually drive those transport implementations. * * Throws if receiver is frozen. */ setAllPeerToPeerEnabled(enabled: boolean): void; /** * Enables or disables the peer-to-peer transport protocols defined in * {@link TransportConfigPeerToPeer} that are supported on the current platform. * * You can check the list of available transports for each platform at * https://ditto.com/link/sdk-latest-compatibility */ setAvailablePeerToPeerEnabled(enabled: boolean): void; /** * Returns `true` if the transport configuration is frozen, otherwise * returns `false`. */ get isFrozen(): boolean; /** * (Deep) freezes the receiver such that it can't be modified anymore. */ freeze(): TransportConfig; /** * Returns a (deep) copy of the receiver. */ copy(): TransportConfig; /** * Returns `true` if passed in TCP configurations are equal, otherwise * returns `false`. */ static areListenTCPsEqual(left: TransportConfigListenTCP, right: TransportConfigListenTCP): boolean; /** * Returns `true` if passed in HTTP configurations are equal, otherwise * returns `false`. */ static areListenHTTPsEqual(left: TransportConfigListenHTTP, right: TransportConfigListenHTTP): boolean; private _isFrozen; } /** * Represents a diff between two arrays. * * Create a diff between arrays of {@link QueryResultItem} using a {@link Differ}. */ declare class Diff { /** The set of indexes in the _new_ array at which new items have been inserted. */ readonly insertions: number[]; /** The set of indexes in the _old_ array at which old items have been deleted. */ readonly deletions: number[]; /** The set of indexes in the _new_ array at which items have been updated. */ readonly updates: number[]; /** * A set of tuples each representing a move of an item `from` a particular * index in the _old_ array `to` a particular index in the _new_ array. */ readonly moves: { from: number; to: number; }[]; constructor(cborData: Uint8Array); } /** * Calculates diffs between arrays of {@link QueryResultItem}. * * Use a {@link Differ} with a {@link StoreObserver} to get the diff between * subsequent query results delivered by the store observer. */ declare class Differ { /** Create a new differ. */ constructor(); /** * Calculate the diff of the provided items against the last set of items that * were passed to this differ. * * The returned {@link Diff} identifies changes from the old array of items * to the new array of items using indices into both arrays. * * Initially, the differ has no items, so the first call to this method will * always return a diff showing all items as insertions. * * The identity of items is determined by their `_id` field. */ diff(items: QueryResultItem[]): Diff; /** @internal */ deref(): Pointer; } /** * A JavaScript class that identifies a bridge's type and may be used to create * new instances. */ type BridgeType = new (...args: any[]) => T; /** * A handle serves as a safe wrapper around a pointer to a native object. * * A bridge keeps track of all handles that have been created on its * {@link Bridge.handlesByAddress | `handlesByAddress`} property, which allows * enumerating all objects that are currently managed by the bridge. * * @internal */ declare class Handle { readonly bridge: Bridge; readonly pointer: Pointer; private objectWeakRef; readonly isClosed: boolean; readonly isFinalized: boolean; readonly isUnregistered: boolean; /** * Warning: Do not call this constructor directly. Use * {@link Bridge.handleFor | `Bridge..handleFor()`} instead. * * @internal */ constructor(bridge: Bridge, object: T, pointer: Pointer); /** The type of this handle's bridge */ get type(): BridgeType; /** * Returns the pointer associated with this handle. * * @throws {Error} if the object has already been closed, garbage collected, * or unregistered from the bridge. */ deref(): Pointer; /** * Returns the pointer associated with this handle or `null` if the object * has been closed, garbage collected, or unregistered. */ derefOrNull(): Pointer | null; /** * Returns the object associated with this handle. * * @throws {Error} if the object has been closed, unregistered, or garbage collected, * closed or unregistered. */ object(): T; /** * Returns the object associated with this handle or `null` if the object * has been closed, unregistered, or garbage collected. */ objectOrNull(): T | null; /** @internal */ toString(): string; /** @internal */ bridgeWillClose(): void; /** @internal */ bridgeDidClose(): void; /** @internal */ bridgeWillFinalize(): void; /** @internal */ bridgeDidFinalize(): void; /** @internal */ bridgeWillUnregister(): void; /** @internal */ bridgeDidUnregister(): void; } /** * Use this for passing arrays of pointers to the FFI. */ declare class Handles { readonly handles: Handle[]; /** * @throws {Error} if any of the objects are not registered in the bridge. * @throws {Error} if any of the objects have already been garbage collected. */ constructor(bridge: Bridge, objects: T[]); deref(): Pointer[]; } /** * A bridge manages memory allocated by the FFI that is used in the JS SDK. * * The main purpose of a bridge is keeping track of JavaScript objects that * require access to memory allocated by the FFI. When such objects are * garbage collected in JavaScript, the bridge instructs the FFI to free the * corresponding memory. Every managed memory pointer corresponds to exactly * one JS Object. * * There is a static `Bridge` instance for every class of objects that can be * managed: * * - {@link Attachment}: `Bridge.attachment` * - {@link Ditto}: `Bridge.ditto` * - {@link Document}: `Bridge.document` * - {@link MutableDocument}: `Bridge.mutableDocument` * * Use `Bridge..handleFor()` to obtain a handle, which is a wrapper around * the raw pointer, and `Bridge..bridge()` to get or create the matching * object for a memory address. * * @internal */ declare class Bridge { readonly release: (pointer: Pointer) => void | Promise; /** * Creates a new bridge for objects of `type`. Requires a `release` function * that is called whenever a registered object is garbage collected, passing * the associated `pointer` to it. The release function is then responsible * to free or drop the corresponding native object. * * **IMPORTANT**: The `type` of all bridges needs to be set in `epilogue.ts` * after initiating the bridge instance. This helps avoid import cycles * (otherwise anything importing the bridge instance, would also have to * import the type, which usually leads to import cycles). * * @private */ constructor(release: (pointer: Pointer) => void | Promise); /** * The type of a bridge is the JavaScript `Class` of objects it represents. * * @internal */ get type(): BridgeType; /** * All bridges' types have to be registered in `epilogue.ts` before using * them. * * @internal */ registerType(value: BridgeType): void; /** * Returns the handle for a bridged object. * * Use `handle.deref()` to get the pointer for the object at the time of use. * * @throws {Error} if the object is not registered. * * @internal */ handleFor(object: T): Handle; /** * Returns a `Handles` instance for an array of objects. * * @internal */ handlesFor(objects: T[]): Handles; /** * Convenience method, returns the object for the FFI `pointer` if registered, * otherwise returns `undefined`. If the object associated with the `pointer` * has been unregistered before, returns `undefined`, too. * * @internal */ objectFor(pointer: Pointer): T | undefined; /** * Returns the object for the FFI `pointer` if registered. Otherwise, calls * the passed in `create` function to create a new object, which it then * returns after registering. If no `create` function is given, uses the * type of the bridge as a constructor and creates a new instance of it * without passing any parameters. * * @param pointer reference to the FFi instance for the object * @param objectOrCreate can either be the JS object, or a function that returns the instance when called. If undefined, an object is created based on the Bridge type. * @throws {Error} if `objectOrCreate` is a function that returns an object that is not an instance of the bridge's type. * @internal */ bridge(pointer: Pointer, objectOrCreate?: T | (() => T)): T; /** * Registers an instance in this bridge's {@link FinalizationRegistry}. * * This causes the FFI to drop the memory linked to the object as soon as it * is garbage collected in JavaScript. * * If you want to control the order with which a number of objects' memory is * dropped, use {@link Bridge.unregister | Bridge.unregister()} * * @private */ register(object: T, pointer: Pointer): void; /** * Removes an instance from this bridge's {@link FinalizationRegistry}. * * This lets you control the order with which memory is dropped in the FFI. * After calling this function, manually call the FFI function to drop the * memory then finally delete the JavaScript instance. * * @internal */ unregister(object: T): void; /** @internal */ unregisterAll(): void; /** * Closes the object by calling `release()` and `null`-ing its pointer, such * that its handle can't be `deref()`-ed afterwards. * * @internal */ close(object: T): Promise; /** @internal */ get count(): number; /** * Keeps track of all bridges for debugging and test purposes. With this, we * can iterate over all bridges and make sure everything is deallocated after * a test, or a suite of tests, has run. * * @internal */ static readonly all: Array>>; /** @internal */ static readonly attachment: Bridge; /** @internal */ static readonly connectionRequest: Bridge; /** @internal */ static readonly queryResult: Bridge, "dittoffi_query_result_t">; /** @internal */ static readonly queryResultItem: Bridge, "dittoffi_query_result_item_t">; /** @internal */ static readonly transaction: Bridge; /** @internal */ static readonly differ: Bridge; /** @internal */ static readonly storeObserver: Bridge; /** @internal */ static readonly syncSubscription: Bridge; /** @internal */ static readonly ditto: Bridge; private internalType; /** * All bridged objects' {@link Handle} entries for lookup by pointer address. */ private handlesByAddress; /** * Look up a handle given its object. * * As `WeakMap` does not allow for enumeration, use `this.handlesByAddress` to * iterate over all handles. */ private handlesByObject; private finalizationRegistry; private finalize; } /** Types of connections that can be established between two peers. */ type TransportCondition = 'Unknown' | 'OK' | 'GenericFailure' | 'AppInBackground' | 'MDNSFailure' | 'TCPListenFailure' | 'NoBLECentralPermission' | 'NoBLEPeripheralPermission' | 'CannotEstablishConnection' | 'BLEDisabled' | 'NoBLEHardware' | 'WiFiDisabled' | 'TemporarilyUnavailable'; /** The source for a transport condition. */ type ConditionSource = 'BLE' | 'TCP' | 'AWDL' | 'MDNS' | 'WiFiAware'; /** * Ditto is the entry point for accessing Ditto-related functionality. */ declare class Ditto { /** * A string containing the semantic version of the Ditto SDK. Example: 4.4.3 */ static get VERSION(): string; /** * The default root directory used for Ditto data persistence. * * This property returns the platform-dependent directory where Ditto stores * its data when a relative persistence directory path (or `null`) is * provided. * * **Node.js** * * - On macOS, this is the `~/Library/Application Support/ditto` directory. * - On Windows, this is the `~/AppData/Roaming/ditto` directory. * - On Linux, this is the `~/.local/share/ditto` directory. * * Note that sandboxed environments, such as Electron apps running under * Apple's App Sandbox, can require setting a * {@link DittoConfig.persistenceDirectory | custom persistence directory} as * these default directories may not be accessible. * * **React Native** * * - On iOS and macOS, this is the Application Support directory. * - On Android, this is the app's internal files directory. * * **Browsers** * * In browsers, this returns an empty string as there is no file system * access. * * @returns A string representing the default root directory. * @throws {DittoError} `unsupported` if the current environment is not * supported by Ditto. * @see {@link DittoConfig.persistenceDirectory} for more information on * configuring the persistence directory. */ static get DEFAULT_ROOT_DIRECTORY(): string; /** * Asynchronously creates and returns a new `Ditto` instance using the * provided configuration. * * This is the recommended way to initialize Ditto in async environments. * * @param config - The configuration to initialize the new Ditto instance * with. Defaults to {@link DittoConfig.default}. * * @returns The newly created `Ditto` instance. * * @throws {@link DittoError} with code `persistenceDirectoryLocked` if the * chosen persistence directory is already in use by another Ditto instance. * * @throws {@link DittoError} with code `invalidDittoConfig` if the passed in * `DittoConfig`'s contents do not meet the required validation criteria. * For detailed information on the validation requirements, consult the * documentation of the individual properties of `DittoConfig`. * * @throws May throw other {@link DittoError}s for other initialization * failures. * * @see {@link openSync | Ditto.openSync()} for a blocking, non-async * alternative. */ static open(config?: DittoConfig): Promise; /** * Synchronously creates and returns a new `Ditto` instance using the provided * configuration. * * This is a blocking convenience method for initializing Ditto, intended for * use in non-async environments. * * @param config - The configuration to initialize the new Ditto instance * with. Defaults to {@link DittoConfig.default}. * * @returns The newly created `Ditto` instance. * * @throws {@link DittoError} with code `persistenceDirectoryLocked` if the * chosen persistence directory is already in use by another Ditto instance. * * @throws {@link DittoError} with code `invalidDittoConfig` if the passed in * `DittoConfig`'s contents do not meet the required validation criteria. * For detailed information on the validation requirements, consult the * documentation of the individual properties of `DittoConfig`. * * @throws May throw other {@link DittoError}s for other initialization * failures. * * @see {@link open | Ditto.open()} for an async alternative. */ static openSync(config?: DittoConfig): Ditto; /** * Configure a custom identifier for this peer. * * When using {@link Presence.observe | presence.observe()}, each remote peer * is represented by a short UTF-8 "device name". By default this will be a * truncated version of the device's hostname. * * Changes to this property after {@link Sync.start | ditto.sync.start()} was * called will only take effect after the next restart of sync. The value does * not need to be unique among peers. Device names longer than 24 bytes will * be truncated once {@link Sync.start | ditto.sync.start()} is called. */ get deviceName(): string; set deviceName(value: string); /** * The persistence directory used by Ditto to persist data, represented by an * absolute path. * * It is not recommended to directly read or write to this directory as its * structure and contents are managed by Ditto and may change in future * versions. * * When {@link Logger} is enabled, logs may be written to this directory even * after a Ditto instance was deallocated. Please refer to the documentation * of {@link Logger} for more information. * * In browsers, this string acts as a namespace for the in-memory data store * and does not correspond to a file system directory. */ get absolutePersistenceDirectory(): string; /** * Provides access to the SDK's store functionality. */ readonly store: Store; /** * Provides access to the SDK's sync functionality. */ readonly sync: Sync; /** * Provides access to the SDK's presence functionality. */ readonly presence: Presence; /** * Provides access to authentication methods for logging on to Ditto Cloud. */ readonly auth: Authenticator; /** * Provides access to the SDK's small peer info functionality. */ readonly smallPeerInfo: SmallPeerInfo; /** * The configuration used to initialize this `Ditto` instance. * * The returned value is frozen, use * {@link DittoConfig.copy | `ditto.config.copy()`} to obtain a modifiable * copy. * * @throws {DittoError} when accessed after this Ditto instance has been * {@link Ditto.close | closed}. */ get config(): Readonly; /** * Returns `true` if an offline license token has been set, otherwise returns `false`. * * @see {@link setOfflineOnlyLicenseToken | setOfflineOnlyLicenseToken()} */ get isActivated(): boolean; /** * `true` once {@link Ditto.close | Ditto.close()} has been called, otherwise * `false`. */ get isClosed(): boolean; /** * Initializes a new `Ditto` instance. * * Called from {@link Ditto.open} and {@link Ditto.openSync} factory methods. * * @internal */ constructor(dittoPointer: Pointer, config: Readonly, accessToken: Symbol); /** * Don't terminate the process when callbacks are pending for a long time. * * Some methods in the Ditto library accept asynchronous functions as callback * parameters. If these asynchronous functions do not resolve within a certain * period of time after having been invoked by Ditto, deadlock detection gets * triggered, resulting in the termination of the process. * * When Ditto is executed in a Node.js environment with an interactive * debugger attached, this deadlock detection might get activated upon * encountering a breakpoint. Calling `Ditto.disableDeadlockDetection()` * disables this behavior, thus allowing the use of an interactive debugger * without triggering the deadlock detection. * * This feature is only available in Node.js environments. */ static disableDeadlockDetection(): void; /** * Returns `true` if deadlock detection is enabled. * * See * {@link Ditto.disableDeadlockDetection | Ditto.disableDeadlockDetection()} * for more information. * * When called outside of a Node.js environment, this method always returns * `false` as deadlock detection is only available in Node.js. * * @returns `true` if deadlock detection is enabled */ static hasDeadlockDetection(): boolean; /** * Check if the current environment supports running Ditto. * * Required APIs include: * * - `BigInt` * - `FinalizationRegistry` * - `WeakRef` * * Internet Explorer is not supported. * * @returns `true` if the environment is supported */ static isEnvironmentSupported(): boolean; /** * Activate a `Ditto` instance by setting an offline only license token. You * cannot initiate sync with `Ditto` before you have activated it. The offline * license token is only valid for the `smallPeersOnly` * {@link DittoConfigConnectSmallPeersOnly | mode}. * * @param licenseToken the license token to activate the `Ditto` instance * with. You can find yours on the [Ditto portal](https://portal.ditto.live). */ setOfflineOnlyLicenseToken(licenseToken: string): void; /** * Returns the current transport configuration, frozen. If you want to modify * the transport config, make a {@link TransportConfig.copy | copy} first. Or * use the {@link updateTransportConfig | updateTransportConfig()} * convenience method. By default peer-to-peer transports (Bluetooth, WiFi, * and AWDL) are enabled if available in the current environment * (Web, Node, OS, etc.). * * @see {@link setTransportConfig | setTransportConfig()} * @see {@link updateTransportConfig | updateTransportConfig()} */ get transportConfig(): TransportConfig; /** * Assigns a new transports configuration. By default peer-to-peer transports * (Bluetooth, WiFi, and AWDL) are enabled. You may use this method to alter * the configuration at any time, however sync will not begin until * {@link Sync.start | ditto.sync.start()} is called. * * @see {@link Ditto.transportConfig} * @see {@link updateTransportConfig | updateTransportConfig()} */ setTransportConfig(transportConfig: TransportConfig): void; /** * Convenience method for updating the transport config. Creates a copy of the * current transport config, passes that copy to the `update` closure, * allowing it to mutate as needed, and sets that updated copy afterwards. */ updateTransportConfig(update: (transportConfig: TransportConfig) => void): Ditto; /** * Register observer for changes of underlying transport conditions. * * Ditto will prevent the process from exiting as long as there are active * transport conditions observers (not relevant when running in the browser). * * @param callback called when underlying transport conditions change with * the changed `condition` and its `source`. */ observeTransportConditions(callback: (condition: TransportCondition, source: ConditionSource) => void): Observer; /** * Shut down Ditto and release all resources. * * Must be called before recreating a Ditto instance that uses the same * persistence directory. */ close(): Promise; /** @internal */ keepAlive: KeepAlive; /** @internal */ _deviceName: string; /** * The number of operations pending before the Ditto instance can be closed. * * For testing purposes only. * @internal */ get numPendingOperations(): number; /** * Makes sure that the closure is executed only if the Ditto instance hasn't * been closed yet. * * The closure is given a {@link Handle | handle} to the Ditto instance that * is valid while the closure is executing. * * @param closure the synchronous closure to execute. * @returns the result of the closure. * @throws if the Ditto instance was closed before calling this method. * @internal */ deferClose(closure: (dittoHandle: Handle) => T): T; /** * Makes sure that the closure is executed to completion before the Ditto * instance is closed. * * Any calls to {@link close | `Ditto.close()`} will wait until the closure * has completed before closing the Ditto instance. * * The closure is given a {@link Handle | handle} to the Ditto instance that * is valid while the closure is executing. * * @param closure the asynchronous closure to execute. * @returns the result of the closure. * @throws if the Ditto instance was closed before calling this method. * @internal */ deferCloseAsync(closure: (dittoHandle: Handle) => Promise): Promise; private deferCloseAllowed; private transportConditionsManager; private _isClosed; /** Set of pending operations that need to complete before the Ditto instance can be closed in a safe manner. */ private pendingOperations; } /** * Returns true if the current JS environment supports all required APIs. * * @param _globalObject optional global object to test this function without * having to mock `global`. * @returns `true` iff all required APIs exist on `global`. * @internal */ declare const checkAPIs: (_globalObject?: typeof globalThis) => boolean; /** * Disable deadlock timeout when Node.js is running with `--inspect` parameter. * * This heuristic is not failsafe as debugging mode can also be enabled by * sending a `SIGUSR1` signal to the process. * * @internal */ declare const disableDeadlockTimeoutWhenDebugging: () => void; /** * A key-value map of user-defined metadata for an attachment. */ type AttachmentMetadata = { [key: string]: string; }; /** * Represents an attachment and can be used to insert the associated attachment * into a document at a specific key-path. You can't instantiate an attachment * directly, please use the * {@link Store.newAttachment | ditto.store.newAttachment()} method instead. */ declare class Attachment { /** @internal */ readonly ditto: Ditto; /** @internal */ readonly token: UntypedAttachmentToken; /** The attachment's ID. */ get id(): string; /** The attachment's size given as number of bytes. */ get len(): number | bigint; /** The attachment's metadata. */ get metadata(): { [key: string]: string; }; /** * Returns the attachment's data. */ data(): Promise; /** * Copies the attachment to the specified file path. * * **React Native:** * - **Relative paths** (e.g., `"data/file.txt"`) are automatically prefixed with * `ditto.absolutePersistenceDirectory`, resulting in `${persistenceDir}/data/file.txt` * - **Absolute paths** (e.g., `"/Users/me/file.txt"`) are used as-is without modification * * **Node.js:** * - Relative paths are resolved relative to the current working directory * * This method throws an error when running in the browser. * * @param path The path where the attachment should be copied. */ copyToPath(path: string): Promise; /** @internal */ constructor(ditto: Ditto, token: UntypedAttachmentToken); } /** * Validates the given attachment metadata. Metadata must be a flat object with * string values. * * This should really happen in core to make sure we use the same validation * logic across SDKs but we decided to postpone that for the next iteration on * attachments. * * @throws {@link DittoError} 'store/failed-to-create-attachment' * @internal */ declare function validateAttachmentMetadata(metadata: AttachmentMetadata): void; /** * 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`). */ type DQLQueryArguments = { [key: string]: DQLQueryArgumentValue | undefined; }; /** * Individual value in a {@link DQLQueryArguments} object. */ type DQLQueryArgumentValue = string | number | boolean | Uint8Array | null | Attachment | bigint | DQLQueryArgumentValue[] | { [key: string]: DQLQueryArgumentValue; }; /** * Available options for {@link init | init()}. */ type InitOptions = { /** * You can explicitly pass the WebAssembly module or its location via the * `webAssemblyModule` option. By default, Ditto tries to load the WebAssembly * module from the same path where this JavaScript is served. */ webAssemblyModule?: WebAssemblyModule; }; /** * Initializes the whole Ditto module. Needs to be called and complete before * any of the Ditto API is used. * * @param options - Dictionary with global {@link InitOptions | initialization options}. */ declare function init(options?: InitOptions): Promise; /** The log levels supported by Ditto. */ type LogLevel = 'Error' | 'Warning' | 'Info' | 'Debug' | 'Verbose'; /** * Closure that {@link Logger.setCustomLogCallback} can be set as a custom * log callback on {@link Logger}. */ 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. * * Currently, Ditto uses the persistence directory of the Ditto instance that * was most recently created to store a limited amount of logs. Ditto may * continue writing logs to a persistence directory even after the associated * Ditto instance is {@link Ditto.close | closed}. If this is a concern, * consider either disabling logging by setting {@link Logger.enabled} to * `false`, or instantiating a new Ditto instance. After either of these * actions, it is safe to remove the persistence directory. Please refer to * {@link Logger.exportToFile | `exportToFile()`} for further details on locally * collected logs. */ declare 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; /** * Whether the logger is currently enabled. * * Logs exported through {@link exportToFile | exportToFile()} are not * affected by this setting and will also include logs emitted while * {@link enabled} is `false`. */ static get enabled(): boolean; /** Enables or disables logging. */ static set enabled(enabled: boolean); /** * 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. * * Logs exported through {@link exportToFile | exportToFile()} are not * affected by this setting and include all logs at `Debug` level and above. */ static get minimumLogLevel(): LogLevel; /** * 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); /** * Returns the current custom log callback, `undefined` by default. See * {@link setCustomLogCallback | setCustomLogCallback()} for a detailed * description. */ static get customLogCallback(): CustomLogCallback | undefined; /** * 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 {TypeError} if `callback` is not a function or `undefined`. * @throws {Error} when called in a React Native environment. */ static setCustomLogCallback(callback?: CustomLogCallback): Promise; /** * Exports collected logs to a compressed and JSON-encoded file on the local * file system. * * Ditto's logger locally collects a limited amount of logs at `Debug` level * and above, periodically discarding older logs. This internal logger is * always enabled and works independently of the {@link Logger.enabled} * setting and the configured {@link Logger.minimumLogLevel}. Its logs can be * requested and downloaded from any peer that is active in a Ditto app using * the portal's device dashboard. This method provides an alternative way of * accessing those logs by exporting them to the local file system. * * The logs will be written as a gzip compressed file at the path specified by * the `path` parameter. When uncompressed, the file contains one JSON value * per line with the oldest entry on the first line (JSON lines format). * * By default, Ditto limits the amount of logs it retains on disk to 15 MB and * a maximum age of 15 days. Older logs are periodically discarded once one of * these limits is reached. * * This method currently only exports logs from the most recently created * Ditto instance, even when multiple instances are running in the same * process. * * Not supported in browser environments. * * @param path The path of the file to write the logs to. The file must not * already exist, and the containing directory must exist. It is recommended * for the `path` to have the `.jsonl.gz` file extension but Ditto won't * enforce it, nor correct it. * * @returns The number of bytes written to the file. * * @throws `TypeError` if `path` is not a string. * * @throws {@link DittoError} `io/*` when the file cannot be written to disk. * Prevent this by ensuring that no file exists at the provided `path`, all * parent directories exists, sufficient permissions are granted, and that the * disk is not full. * * @throws {@link DittoError} `unsupported` when called in a browser * environment. */ static exportToFile(path: string): Promise; /** * 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): void; /** * Convenience method, same as calling {@link log | log()} with * {@link LogLevel} `Error`. */ static error(message: string): void; /** * Convenience method, same as calling {@link log | log()} with * {@link LogLevel} `Warning`. */ static warning(message: string): void; /** * Convenience method, same as calling {@link log | log()} with * {@link LogLevel} `Info`. */ static info(message: string): void; /** * Convenience method, same as calling {@link log | log()} with * {@link LogLevel} `Debug`. */ static debug(message: string): void; /** * Convenience method, same as calling {@link log | log()} with * {@link LogLevel} `Verbose`. */ static verbose(message: string): void; private static _logFile?; private static _customLogCallback?; private constructor(); } /** * Get a count of bridged objects binned by bridge type. * * Use this in testing to ensure that all objects are properly garbage collected at the end of tests. * * @returns an object with a key per bridge type, set to the count of registered * objects. */ declare function getBridgeLoad(): { [bridgeName: string]: number; }; /** * Get the default transport config from core as deserialized TransportConfig. * * @internal */ declare function getDefaultTransportConfigFromCore(): TransportConfig; /** @internal */ declare class CBOR { /** @internal */ static encode(data: any): Uint8Array; /** @internal */ static encodeWithReplacer(data: any, replacer: (key: any, value: any) => any): Uint8Array; /** @internal */ static decode(data: Uint8Array, reviver?: (key: any, value: any) => any): any; } export { Attachment, AttachmentFetcher, AttachmentToken, Authenticator, CBOR, ConnectionRequest, Diff, Differ, Ditto, DittoConfig, DittoError, ERROR_CODES, KeepAlive, Logger, Observer, Presence, QueryResult, QueryResultItem, SmallPeerInfo, Store, StoreObserver, Sync, SyncSubscription, Transaction, TransactionInfo, TransportConfig, checkAPIs, disableDeadlockTimeoutWhenDebugging, fromFFICBORData, getBridgeLoad, getDefaultTransportConfigFromCore, init, mapFFIErrors, mapFFIErrorsAsync, transportConfigFromDeserializable, transportConfigToSerializable, validateAttachmentMetadata }; export type { AttachmentFetchEvent, AttachmentFetchEventCompleted, AttachmentFetchEventDeleted, AttachmentFetchEventProgress, AttachmentFetchEventType, AttachmentMetadata, AuthenticationExpirationHandler, AuthenticationStatus, ConditionSource, Connection, ConnectionRequestAuthorization, ConnectionRequestHandler, ConnectionType, CustomLogCallback, DQLQueryArgumentValue, DQLQueryArguments, DittoConfigConnect, DittoConfigConnectServer, DittoConfigConnectSmallPeersOnly, ErrorCode, InitOptions, LogLevel, LoginResult, ObserverOptions, Peer, PeerOS, PresenceGraph, QueryExecuting, StoreObservationHandler, StoreObservationHandlerWithSignalNext, TransactionCompletionAction, TransactionOptions, TransportCondition, TransportConfigConnect, TransportConfigGlobal, TransportConfigLan, TransportConfigListen, TransportConfigListenHTTP, TransportConfigListenTCP, TransportConfigPeerToPeer, TypedAttachmentTokenV1, UntypedAttachmentToken, WebAssemblyModule }; //# sourceMappingURL=ditto.d.ts.map