/** @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 */ type ObserverManagerConstructorOptions = { keepAlive?: KeepAlive; register?: (callback: (...args: any[]) => void) => void; unregister?: () => void; process?: (...args: any[]) => any[]; }; /** @internal */ declare class ObserverManager { /** @internal */ readonly id: string; /** @internal */ readonly keepAlive: KeepAlive | null; /** @internal */ constructor(id: string, options?: ObserverManagerConstructorOptions); /** @internal */ addObserver(callback: any): ObserverToken; /** @internal */ removeObserver(token: ObserverToken): void; hasObserver(token: ObserverToken): boolean; /** @internal */ notify(...args: any[]): void; /** @internal */ close(): void; /** * Can be injected and replaced via constructor options. * * @abstract */ protected register(callback: (...args: any[]) => void): void; /** * Can be injected and replaced via constructor options. * * @abstract */ protected unregister(): void; /** * Can be injected and replaced via constructor options. * * @abstract */ protected process(...args: any[]): any[]; private isClosed; private isRegistered; private callbacksByToken; private constructorOptions; private hasObservers; private registerIfNeeded; private unregisterIfNeeded; } /** @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' | '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' | '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 FFIAuthenticationStatus = 'dittoffi_authentication_status_t'; /** @internal */ type FFIQueryResultItem = 'dittoffi_query_result_item_t'; /** @internal */ type FFIQueryResult = 'dittoffi_query_result_t'; /** @internal */ type FFIDiffer = 'dittoffi_differ_t'; /** @internal */ type FFIWriteTransaction = 'CWriteTransaction_t'; /** @internal */ type FFIDitto = 'CDitto_t'; /** @internal */ type OrderBy = { query: string; direction: 'Ascending' | 'Descending'; }; /** @internal */ type PathAccessorType = 'String' | 'Number' | 'Int' | 'UInt' | 'Float' | 'Double' | 'Bool' | 'Null' | 'Object' | 'Array' | 'Any' | 'Counter' | 'Register' | 'Attachment' | 'Rga' | 'RWMap'; /** @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; /** @internal */ type UntypedAttachmentToken = { id: string; len: number | BigInt; metadata: AttachmentMetadata; }; /** @internal */ type TypedAttachmentToken = { [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()}. */ 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 | TypedAttachmentToken); /** @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; } /** * 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; /** * Manages attachment fetchers to make sure we free all resources when the * fetcher is garbage collected and to allow us to wait for freeing of * ressources to be finished before the ditto instance is closed. * * @internal */ declare class AttachmentFetcherManager { readonly ditto: Ditto; /** @internal */ constructor(ditto: Ditto); /** * Start an attachment fetcher. * * @internal */ startAttachmentFetcher(token: AttachmentToken, eventHandler?: (attachmentFetchEvent: AttachmentFetchEvent) => void): AttachmentFetcher; /** * Stop an attachment fetcher and wait for it to be stopped. * * @internal */ stopAttachmentFetcher(attachmentFetcher: AttachmentFetcher): Promise; /** * Closing the manager will cancel all attachment fetchers. * * @internal */ close(): void; private contextInfoByID; private finalizationRegistry; /** * Stop the attachment fetcher without unregistering it from the finalization * registry. */ private stopWithContextInfo; } /** * 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. * * If this attachment fetcher has been initiated through {@link * Collection.fetchAttachment | `Collection.fetchAttachment()`}, the promise * resolves to `null` if the attachment could not be found instead of being * rejected. */ 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; /** * Defined when the fetcher was started from `Collection.fetchAttachment()`. * Otherwise, the fetcher was started from `Store.fetchAttachment()`. * * @internal */ readonly manager?: AttachmentFetcherManager; /** @internal */ readonly token: AttachmentToken; /** @internal */ then(onfulfilled?: ((value: any) => TResult1 | PromiseLike) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike) | null | undefined): PromiseLike; /** @internal */ constructor(ditto: Ditto, token: AttachmentToken, manager?: AttachmentFetcherManager, 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; } /** Represents a unique identifier for a {@link Document}. */ type DocumentIDValue = any; /** Represents a unique identifier for a {@link Document}. */ declare class DocumentID { /** * Returns the value of the receiver, lazily decoded from its CBOR * representation if needed. */ get value(): any; /** * Returns `false` if validation has been skipped at construction time, * otherwise returns `true`. This is mostly for internal use only, you * shouldn't need this in client code. */ readonly isValidated: boolean; /** * Creates a new `DocumentID`. * * A document ID can be created from any of the following: * * - `string` * - `number` (integer) * - `boolean` * - `null` * - raw data in the form of a JS [Typed Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays) * - `Array` (containing any of the items in this list) * - Map (a raw JS `object`, where the keys must be strings and the values * can be made up of any of the items in this list) * * Note that you cannot use floats or other custom types to create a document * ID. * * Document IDs are also limited in size, based on their serialized * representation, to 256 bytes. You will receive an error if you try to * create a document ID that exceeds the size limit. * * @param value The value that represents the document identifier. * @param skipCBOREncoding If `true, skips CBOR encoding and assumes * the passed in `value` is already CBOR encoded. You shouldn't need to ever * pass this parameter, it's only used internally for certain edge cases. * @param skipValidation If `true, skips validation of the passed in value or * CBOR. You shouldn't need to ever pass this parameter, it's only used * internally for certain edge cases. */ constructor(value: any, skipCBOREncoding?: boolean, skipValidation?: boolean); /** * Returns `true` if passed in `documentID` is equal to the receiver, * otherwise returns `false`. */ equals(documentID: DocumentID): boolean; /** * Returns a string representation of the receiver. * * If you need a string representation to be used directly in a query, * please use `toQueryCompatibleString()` instead. */ toString(): string; /** * Returns the base64-encoded CBOR representation of this document ID. * * @deprecated */ toBase64String(): string; /** * Returns a query compatible string representation of the receiver. * * The returned string can be used directly in queries that you use with other * Ditto functions. For example you could create a query that was like this: * * ``` TypeScript * collection.find(`_id == ${documentID.toQueryCompatibleString()}`) * ``` * * @deprecated use document IDs in queries by embedding them in the query * arguments parameter. */ toQueryCompatibleString(): string; /** @internal */ toCBOR(): Uint8Array; } /** @internal */ declare function validateDocumentIDValue(id: DocumentIDValue): DocumentIDValue; /** @internal */ declare function validateDocumentIDCBOR(idCBOR: Uint8Array): Uint8Array; /** @internal */ type SubscriptionContextInfo = { id: string; collectionName: string; query: string; queryArgsCBOR: Uint8Array | null; orderBys: OrderBy[]; limit: number; offset: number; }; /** * Tracks `Subscription` instances in order to remove them when Ditto is * closed. * * @internal */ declare class SubscriptionManager { /** @internal */ constructor(ditto: Ditto); /** * Begin tracking a subscription instance and start it. * * @internal */ add(subscription: Subscription): void; /** * Stop tracking a subscription instance and cancel it. * * @internal */ remove(subscription: Subscription): void; /** * Stop tracking all subscriptions and cancel them. * * @internal */ close(): void; private ditto; private subscriptions; private finalizationRegistry; /** * Remove tracked subscription without unregistering from finalization * registry. * * @internal */ private removeWithContextInfo; } /** * Used to subscribe to receive updates from remote peers about matching * documents. * * While {@link Subscription} objects remain in scope they ensure that * documents in the collection specified and that match the query provided will * try to be kept up-to-date with the latest changes from remote peers. * * This class is used by Ditto's query builder APIs. * @see {@link SyncSubscription} for the DQL equivalent. * * Not available in React Native environments. */ declare class Subscription { /** * The query that the subscription is based on. */ readonly query: string; /** * Returns `true` if subscription has been explicitly cancelled, `false` * otherwise. */ get isCancelled(): boolean; /** * The name of the collection that the subscription is based on. */ get collectionName(): string; /** * Cancels a subscription and releases all associated resources. */ cancel(): void; /** @internal */ constructor(collection: Collection, query: string, queryArgsCBOR: Uint8Array | null, orderBys: OrderBy[], limit: number, offset: number); /** * The collection this subscription belongs to. * @internal Because not exposed in any of the other SDKs (yet?). */ readonly collection: Collection; /** * The corresponding named arguments for {@link query}, if any. * @internal Because not exposed in any of the other SDKs (yet?). */ readonly queryArgsCBOR: Uint8Array | null; /** @internal */ readonly contextInfo: SubscriptionContextInfo; private readonly manager; private _isCancelled; } /** @internal */ declare class LiveQueryManager { readonly ditto: Ditto; readonly keepAlive: KeepAlive; /** @internal */ constructor(ditto: Ditto, keepAlive: KeepAlive); /** @internal */ startLiveQuery(liveQuery: LiveQuery): void; /** @internal */ stopLiveQuery(liveQuery: LiveQuery): void; /** @internal */ close(): void; private liveQueriesByID; private finalizationRegistry; private stopLiveQueryWithID; private finalize; } /** * The type that is returned when calling * {@link PendingCursorOperation.observeLocal | observeLocal()} on a * {@link PendingCursorOperation} object. It handles the logic for calling the * event handler that is provided to `observeLocal()` calls. * * Ditto will prevent the process from exiting as long as there are active live * queries (not relevant when running in the browser). * * `LiveQuery` objects must be kept in scope for as long as you wish to have * your event handler be called when there is an update to a document matching * the query you provide. When you no longer want to receive updates about * documents matching a query then you must call {@link stop | stop()}. * * Not available in React Native environments. */ declare class LiveQuery { /** The query that the live query is based on. */ readonly query: string; /** The arguments belonging to {@link query}. */ readonly queryArgs: QueryArguments | null; /** The name of the collection that the live query is based on. */ get collectionName(): string; /** Returns true if the receiver has been stopped. */ get isStopped(): boolean; /** * Stop the live query from delivering updates. * * @throws {Error} when called in a React Native environment. */ stop(): void; /** @internal */ orderBys: OrderBy[]; /** @internal */ queryArgsCBOR: Uint8Array | null; /** @internal */ readonly limit: number; /** @internal */ readonly offset: number; /** @internal */ readonly collection: Collection; /** @internal */ readonly handler: QueryObservationHandler; /** * This field is only populated while a live query is active and set to null * when the live query is stopped. * * @internal */ liveQueryManager: LiveQueryManager | null; get liveQueryID(): number; /** @internal */ constructor(query: string, queryArgs: QueryArguments | null, queryArgsCBOR: Uint8Array | null, orderBys: OrderBy[], limit: number, offset: number, collection: Collection, handler: QueryObservationHandler); private _liveQueryID; } /** * Represents a CRDT counter that can be upserted as part of a document or * assigned to a property during an update of a document. * * Not available in React Native environments. */ declare class Counter { /** The value of the counter. */ get value(): number; /** * Creates a new counter that can be used as part of a document's content. */ constructor(); /** @internal */ static '@ditto.create'(mutDoc: any, path: any, value: any): any; protected mutDoc: any; protected path: any; protected _value: number; } /** * Represents a mutable CRDT counter that can be incremented by a specific * amount while updating a document. * * This class can't be instantiated directly, it's returned automatically for * any counter property within an update block via {@link MutableDocumentPath.counter}. */ declare class MutableCounter extends Counter { /** * Increments the counter by `amount`, which can be any valid number. * * Only valid within the `update` closure of * {@link PendingCursorOperation.update | PendingCursorOperation.update()} and * {@link PendingIDSpecificOperation.update | PendingIDSpecificOperation.update()}, * otherwise an exception is thrown. * * @throws {Error} when called in a React Native environment. */ increment(amount: number): void; /** @internal */ protected constructor(); } /** * Represents a CRDT register that can be upserted as part of a document or * assigned to a property during an update of a document. * * Not available in React Native environments. */ declare class Register { /** Returns the value of the register. */ get value(): any; /** * Creates a new Register that can be used as part of a document's content. */ constructor(value: any); /** @internal */ static '@ditto.create'(mutableDocument: any, path: any, value: any): any; /** @internal */ protected '@ditto.mutableDocument': any; /** @internal */ protected '@ditto.path': any; /** @internal */ protected '@ditto.value': any; } /** * Represents a mutable CRDT register that can be set to a specific value when * updating a document. * * This class can't be instantiated directly, it's returned automatically for * any register property of a document within an update block via * {@link MutableDocumentPath.register}. * * Not available in React Native environments. */ declare class MutableRegister extends Register { /** * Returns the value of the register. * * Not available in React Native environments. */ get value(): any; /** * Convenience setter, equivalent to {@link set | set()}. * * Not available in React Native environments. */ set value(value: any); /** * Sets the register to the provided value. * * Only valid within the `update` closure of * {@link PendingCursorOperation.update | PendingCursorOperation.update()} and * {@link PendingIDSpecificOperation.update | PendingIDSpecificOperation.update()}, * otherwise an exception is thrown. * * Not available in React Native environments. */ set(value: any): void; /** @internal */ constructor(value: any); } /** * Represents a portion of the document at a specific key-path. * * Provides an interface to specify a path to a key in a document that you can * then call a function on to get the value at the specified key as a specific * type. You don't create a `DocumentPath` directly but obtain one via the * {@link Document.path | path} property or the {@link Document.at | at()} * method of {@link Document}. * * Not available in React Native environments. */ declare class DocumentPath { /** The document this path belongs to. */ readonly document: Document; /** The full document path so far. */ readonly path: string; /** * Returns a new document path instance with the passed in key-path or * index appended. * * A key-path can be a single property name or multiple property names * separated by a dot. Indexes can also be specified as part of the key * path using the square bracket syntax. The empty string returns a document * path representing the same portion of the document as the receiver. If a * key-path starts with a property name and is prefixed by a dot, the dot is * ignored. * * Examples: * * - `documentPath.at('mileage')` * - `documentPath.at('driver.name')` * - `documentPath.at('passengers[2]')` * - `documentPath.at('passengers[2].belongings[1].kind')` * - `documentPath.at('.mileage')` * * @throws {Error} when called in a React Native environment. */ at(keyPathOrIndex: string | number): DocumentPath; /** * Traverses the document with the key-path represented by the receiver and * returns the corresponding object or value. * * @throws {Error} when called in a React Native environment. */ get value(): any | undefined; /** * Returns the value at the previously specified key in the document as a * {@link Counter} if possible, otherwise returns `null`. * * @throws {Error} when called in a React Native environment. */ get counter(): Counter | null; /** * Returns the value at the previously specified key in the document as a * {@link Register} if possible, otherwise returns `null`. * * @throws {Error} when called in a React Native environment. */ get register(): Register | null; /** * Returns the value at the previously specified key in the document as an * {@link AttachmentToken} if possible, otherwise returns `null`. * * @throws {Error} when called in a React Native environment. */ get attachmentToken(): AttachmentToken | null; /** @internal */ constructor(document: Document, path: string, validate: boolean); /** @internal */ underlyingValueForPathType(pathType: PathAccessorType): any | undefined; } /** * Mutable version of {@link DocumentPath} allowing you to mutate a document at * a specific key-path. You don't create a `MutableDocumentPath` directly but * obtain one via the {@link MutableDocument.path | path} property or the * {@link MutableDocument.at | at()} method of {@link MutableDocument}. * * Not available in React Native environments. */ declare class MutableDocumentPath { /** The (mutable) document this path belongs to. */ readonly mutableDocument: MutableDocument; /** The full document path so far. */ readonly path: string; /** * Returns a new mutable document path instance with the passed in key-path or * index appended. * * A key-path can be a single property name or multiple property names * separated by a dot. Indexes can also be specified as part of the key * path using square brackets syntax. The empty string returns a document path * representing the same portion of the document as the receiver. If a key * path starts with a property name and is prefixed by a dot, the dot is * ignored. * * Examples: * * - `mutableDocumentPath.at('mileage')` * - `mutableDocumentPath.at('driver.name')` * - `mutableDocumentPath.at('passengers[2]')` * - `mutableDocumentPath.at('passengers[2].belongings[1].kind')` * - `mutableDocumentPath.at('.mileage')` * * @throws {Error} when called in a React Native environment. */ at(keyPathOrIndex: string | number): MutableDocumentPath; /** * Traverses the document with the key-path represented by the receiver and * returns the corresponding object or value. * * @throws {Error} when called in a React Native environment. */ get value(): any | undefined; /** * Returns the value at the previously specified key in the document as a * {@link MutableCounter} if possible, otherwise returns `null`. * * @throws {Error} when called in a React Native environment. */ get counter(): MutableCounter | null; /** * Returns the value at the previously specified key in the document as a * {@link MutableRegister} if possible, otherwise returns `null`. * * @throws {Error} when called in a React Native environment. */ get register(): MutableRegister | null; /** * Returns the value at the previously specified key in the document as a * {@link AttachmentToken} if possible, otherwise returns `null`. * * @throws {Error} when called in a React Native environment. */ get attachmentToken(): AttachmentToken | null; /** * Sets a value at the document's key-path defined by the receiver. * * @param isDefault Represents whether or not the value should be set as a * default value. Set this to `true` if you want to set a default value that * you expect to be overwritten by other devices in the network. The default * value is `false`. * * @throws {Error} when called in a React Native environment. */ set(value: any, isDefault?: boolean): void; /** * Removes a value at the document's key-path defined by the receiver. * * @throws {Error} when called in a React Native environment. */ remove(): void; /** @internal */ constructor(mutableDocument: MutableDocument, path: string, validate: boolean); /** @internal */ underlyingValueForPathType(pathType: PathAccessorType): any | null; /** @internal */ '@ditto.increment'(amount: number): void; /** @internal */ '@ditto.set'(value: any, isDefault?: boolean): void; /** @internal */ '@ditto.remove'(): void; /** @private */ private updateInMemory; /** @private */ private recordUpdateResult; } /** * The types of an {@link UpdateResult}. */ type UpdateResultType = 'set' | 'incremented' | 'removed'; /** * Provides information about a successful update operation on a document. * * The update result can be one of the following types: * - `set` * - `removed` * - `incremented` * * Not available in React Native environments. */ declare class UpdateResult { /** The update result's type. */ readonly type: UpdateResultType; /** The ID of the document that was updated. */ readonly docID: DocumentID; /** The path to the key in the document that was updated. */ readonly path: string; /** * The associated value for `set` operations. The value will be the new value * at the key path. * * All other types of update results do not have this property set. */ readonly value?: any; /** The associated amount, only set if {@link type} is `incremented`. */ readonly amount?: number; /** @internal */ static set(docID: DocumentID, path: string, value?: any): UpdateResult; /** @internal */ static incremented(docID: DocumentID, path: string, amount: number): UpdateResult; /** @internal */ static removed(docID: DocumentID, path: string): UpdateResult; /** @internal */ private constructor(); } declare const CUSTOM_INSPECT_SYMBOL$1: unique symbol; /** * A document value is a JavaScript object containing values for keys that can * be serialized via CBOR. * * This value must not contain any non-finite numbers (`NaN`, `Infinity`, * `-Infinity`). */ type DocumentValue = Record; /** * A document belonging to a {@link Collection} with an inner value. * * Not available in React Native environments. */ declare class Document { /** * Returns a hash that represents the passed in document(s). * * @throws {Error} when called in a React Native environment. */ static hash(documentOrMany: Document | Document[]): BigInt; /** * Returns a pattern of words that together create a mnemonic, which * represents the passed in document(s). * * @throws {Error} when called in a React Native environment. */ static hashMnemonic(documentOrMany: Document | Document[]): string; /** * Returns the document ID. * * @throws {Error} when called in a React Native environment. */ get id(): DocumentID; /** * Returns the document path at the root of the document. * * @throws {Error} when called in a React Native environment. */ get path(): DocumentPath; /** * Convenience property, same as calling `path.value`. The value is cached on * first access and returned on subsequent calls without calling `path.value` * again. * * @throws {Error} when called in a React Native environment. */ get value(): DocumentValue; /** * Convenience method, same as calling `path.at()`. * * @throws {Error} when called in a React Native environment. */ at(keyPathOrIndex: string | number): DocumentPath; /** @internal */ constructor(); /** @internal */ static idCBOR(document: Document): Uint8Array; /** @internal */ static canonicalizedIDCBOR(idCBOR: Uint8Array): Uint8Array; /** @internal */ static isIDCBORCanonical(idCBOR: Uint8Array): boolean; /** @internal */ toString(): string; /** * Defines a custom inspect function for Node.js that will be used when the * object is inspected with console.log() or util.inspect(). * * @internal */ [CUSTOM_INSPECT_SYMBOL$1](_depth: number, _inspectOptions: any, inspect: any): string; } /** * A representation of a {@link Document} that can be mutated via * {@link MutableDocumentPath}. You don't create or interact with a * `MutableDocument` directly but rather through the `update()` methods of * {@link PendingCursorOperation.update | PendingCursorOperation} and * {@link PendingIDSpecificOperation.update | PendingIDSpecificOperation}. * * Not available in React Native environments. */ declare class MutableDocument { /** * Returns the ID of the document. * * @throws {Error} when called in a React Native environment. */ get id(): DocumentID; /** * Returns the document path at the root of the document. * * @throws {Error} when called in a React Native environment. */ get path(): MutableDocumentPath; /** * Convenience property, same as `path.value`. * * @throws {Error} when called in a React Native environment. */ get value(): DocumentValue; /** * Convenience method, same as calling `path.at()`. * * @throws {Error} when called in a React Native environment. */ at(keyPathOrIndex: string | number): MutableDocumentPath; /** @internal */ constructor(); /** @internal */ readonly '@ditto.updateResults': UpdateResult[]; /** @internal */ static idCBOR(mutableDocument: MutableDocument): Uint8Array; /** @internal */ static canonicalizedIDCBOR: typeof Document.canonicalizedIDCBOR; /** @internal */ static isIDCBORCanonical: typeof Document.isIDCBORCanonical; /** @internal */ toString(): string; /** * Defines a custom inspect function for Node.js that will be used when * the object is inspected with console.log() or util.inspect(). * * @internal */ [CUSTOM_INSPECT_SYMBOL$1](_depth: number, _inspectOptions: any, inspect: any): string; } /** * Maps a {@link DocumentID} to an array of * {@link UpdateResult | update results}. This is the data structure you get * when {@link PendingCursorOperation.update | updating} a set of documents * with detailed info about the performed updates. * * Not available in React Native environments. */ declare class UpdateResultsMap { /** * Returns an array of {@link UpdateResult | update results} associated with * the `documentID` or undefined if not found. */ get(documentIDOrValue: DocumentID | DocumentIDValue): UpdateResult[] | undefined; /** * Returns all contained keys, i.e. {@link DocumentID | document IDs} * contained in this map. */ keys(): DocumentID[]; /** @internal */ constructor(documentIDs: DocumentID[], updateResultsByDocumentIDString: object); private documentIDs; private updateResultsByDocumentIDString; } /** * These objects are returned when using `find`-like functionality on * {@link Collection}. * * They allow chaining of further query-related functions to do things like add * a limit to the number of documents you want returned or specify how you want * the documents to be sorted and ordered. * * You can call {@link exec | exec()} on the cursor to get an array of * {@link Document | documents} or you can use methods for updating, removing * or evicting any matching documents. * * Live queries and subscriptions are only available outside of transactions. * * Not available in React Native environments. */ declare class WriteTransactionPendingCursorOperation extends BasePendingCursorOperation { sort(propertyPath: string, direction?: SortDirection): WriteTransactionPendingCursorOperation; offset(offset: number): WriteTransactionPendingCursorOperation; limit(limit: number): WriteTransactionPendingCursorOperation; remove(): Promise; evict(): Promise; update(closure: (documents: MutableDocument[]) => void): Promise; /** @internal */ constructor(query: string, queryArgs: QueryArguments | null, collection: WriteTransactionCollection); } declare class WriteTransactionPendingIDSpecificOperation extends BasePendingIDSpecificOperation { remove(): Promise; evict(): Promise; update(closure: (document: MutableDocument) => void): Promise; updateV2(closure: (document?: MutableDocument) => void): Promise; exec(): Promise; /** @internal */ constructor(documentID: DocumentID, collection: WriteTransactionCollection); } /** * Represents a collection of a Ditto store that is used in the context of a * write transaction. * * Supports most of a regular {@link Collection | collection}'s functionality * but cannot be subscribed or live queried and can not be used to create * attachments. * * Create a `WriteTransactionCollection` by starting a {@link WriteTransaction} * and using its `scoped` method. * * Not available in React Native environments. */ declare class WriteTransactionCollection implements CollectionInterface { /** The name of the collection. */ readonly name: string; /** * The store this collection belongs to. * @internal */ readonly store: Store; /** * The write transaction within which this collection instance is used. * @internal */ readonly writeTransaction: WriteTransaction; /** * Search for documents in this collection using the provided query string. * * The returned cursor operation can be used to chain operations on the * resulting document set. * * @param query The query to run against the collection. * @param queryArgs These arguments replace placeholders in the provided * query. * @throws {Error} when called in a React Native environment. */ find(query: string, queryArgs?: QueryArguments | undefined): WriteTransactionPendingCursorOperation; /** * Convenience method, equivalent to calling {@link find | find()} and passing * the query `"true"`. * * @throws {Error} when called in a React Native environment. */ findAll(): WriteTransactionPendingCursorOperation; /** * Generates a {@link WriteTransactionPendingIDSpecificOperation} with the * provided document ID. * * The returned object can be used to find and return the document. It can also be used to update, remove or evict the document. * * @param id The ID of the document to find. * @throws {Error} when called in a React Native environment. */ findByID(id: any): WriteTransactionPendingIDSpecificOperation; upsert(value: DocumentValue, options?: UpsertOptions): Promise; /** * See comment in {@link CollectionInterface.findByIDCBOR()} * * @internal */ findByIDCBOR(idCBOR: Uint8Array): WriteTransactionPendingIDSpecificOperation; /** * This constructor is marked internal because write transaction collections * should be created from a {@link WriteTransaction} instance. * * @internal */ constructor(name: string, store: Store, writeTransaction: WriteTransaction); } /** * Provides information about the result of an operation on a document that was * part of a write transaction. * * The write transaction result can be one of the following types: * * - `inserted` * - `removed` * - `evicted` * - `updated` * * Please note that an `upsert` operation always results in the result type * `inserted`, regardless of whether it resulted in an update or insert. * * Not available in React Native environments. */ interface WriteTransactionResult { type: 'inserted' | 'removed' | 'evicted' | 'updated'; docID: DocumentID; collectionName: string; } /** * Perform writes in a transaction. * * Create a write transaction using {@link Store.write | ditto.store.write}. */ declare class WriteTransaction { readonly results: WriteTransactionResult[]; /** * Creates a transaction-specific * {@link WriteTransactionCollection | collection} object that will ensure * that operations called on it are all in the context of the collection name * provided to this function. You can create many * {@link WriteTransactionCollection | collection} objects per * {@link WriteTransaction} object. * * @throws {Error} when called in a React Native environment. * */ scoped(toCollectionNamed: string): WriteTransactionCollection; /** @internal */ readonly writeTransactionPointer: Pointer; /** @internal */ readonly ditto: Ditto; /** @internal */ constructor(ditto: Ditto, cTransaction: Pointer); /** * Initialise a write transaction given a Ditto instance. * * This is not implemented as a constructor in order to be able to use FFI * async functions. Users start transactions through {@link Store.write}. * * @param ditto an instance of Ditto * @internal */ static init(ditto: Ditto): Promise; /** @internal */ commit(): Promise; /** @internal */ rollback(): Promise; /** * Adds an entry to the list of results that is returned at the end of a * transaction. * * @internal */ addResult(type: WriteTransactionResult['type'], docID: DocumentID, collectionName: string): void; } /** * These objects are returned when using * {@link Collection.findByID | findByID()} functionality on * {@link Collection | collections}. * * You can either call {@link exec | exec()} on the object to get an immediate * return value, or chain calls to update, evict or remove the document. * * Live queries and subscriptions are only available outside of a transaction. * * Not available in React Native environments. */ declare abstract class BasePendingIDSpecificOperation implements PromiseLike { /** * Removes the document with the matching ID. * * @throws {Error} when called in a React Native environment. * @returns `true` promise if the document was found and removed. `false` * promise if the document wasn't found and therefore wasn't removed. */ abstract remove(): Promise; /** * Evicts the document with the matching ID. * * @throws {Error} when called in a React Native environment. * @returns `true` promise if the document was found and evicted. `false` * promise if the document wasn't found and therefore wasn't evicted. */ abstract evict(): Promise; /** * Updates the document with the matching ID. * * Document values must not be set to any non-finite numbers (`NaN`, * `Infinity`, `-Infinity`). * * @param closure A closure that gets called with the document matching the * ID. If found, the document is a {@link MutableDocument}, so you can call * update-related functions on it. The closure is not called if the document * is not found. * * @throws `Error` if the document is not found. * * @return An array promise of {@link UpdateResult | update results} that * describe the updates that were performed on the document. * * @deprecated This method throws and does not call the closure if the * document is not found. Use {@link updateV2 | updateV2() } instead. */ abstract update(closure: (document: MutableDocument) => void): Promise; /** * Updates the document with the matching ID. * * Document values must not be set to any non-finite numbers (`NaN`, * `Infinity`, `-Infinity`). * * @param closure A closure that gets called with the document matching the * ID. If found, the document is a {@link MutableDocument}, so you can call * update-related functions on it. If the document is not found then the value * provided to the closure will be `undefined`. * * @throws {Error} when called in a React Native environment. * @return An array promise of {@link UpdateResult | update results} that * describe the updates that were performed on the document. */ abstract updateV2(closure: (document?: MutableDocument) => void): Promise; /** The ID of the document this operation operates on. */ readonly documentID: DocumentID; /** The collection the receiver is operating on. */ readonly collection: CollectionInterface; /** * Executes the find operation to return the document with the matching ID. * * @throws {Error} when called in a React Native environment. * @returns The {@link Document} promise with the ID provided in the * {@link Collection.findByID | findByID()} call or `undefined` if the document was * not found. */ exec(): Promise; /** @internal */ constructor(documentID: DocumentID, collection: CollectionInterface); /** @internal */ then(onfulfilled?: ((value: any) => TResult1 | PromiseLike) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike) | null | undefined): PromiseLike; /** @internal */ get query(): string; protected documentIDCBOR: Uint8Array; /** * Commit changes made by the given closure to the current document. * * @param closure * @param throwOnAsyncClosure if true, throw an error when passed an async * closure, otherwise log a warning * @param throwOnDocumentNotFound if true, throw an error if the document is * not found, otherwise call the closure with `undefined` and return an * empty array * @param publicAPIName the name of the public API that was called, used in * error messages and warnings * @param transaction the transaction to use, if not provided a new one will * be created and committed * @internal */ protected updateWithClosure(closure: (document?: MutableDocument) => void, throwOnAsyncClosure: boolean, throwOnDocumentNotFound: boolean, publicAPIName: string, transaction?: WriteTransaction): Promise; } type UpsertOptions = { /** * Specifies the desired strategy for inserting a document. The default * strategy is `merge`. See {@link WriteStrategy} for more information. */ writeStrategy?: WriteStrategy; }; interface CollectionInterface { /** The name of the collection. */ readonly name: string; /** * The store this collection belongs to. * @internal */ readonly store: Store; /** * Search for documents in this collection using the provided query string. * * @param query The query to run against the collection. * @param queryArgs These arguments replace placeholders in the provided * query. * @throws {Error} when called in a React Native environment. */ find(query: string, queryArgs?: QueryArguments): BasePendingCursorOperation; /** * Convenience method, equivalent to calling {@link find | find()} and passing * the query `"true"`. * * @throws {Error} when called in a React Native environment. */ findAll(): BasePendingCursorOperation; /** * Find documents given a specific ID. * * Use the returned cursor instance to chain operations on the search result. * * @param id The document's identifier * @throws {Error} when called in a React Native environment. */ findByID(id: DocumentID | DocumentIDValue): BasePendingIDSpecificOperation; /** * TEMPORARY: helper to deal with non-canonical IDs. * * @internal */ findByIDCBOR(idCBOR: Uint8Array): BasePendingIDSpecificOperation; /** * Inserts a new document into the collection and returns its ID. * * If the document already exists, the contents of both are merged by default. * You can change this by providing a different `writeStrategy` via `options`. * * @param value The content of the document to be inserted or updated. Must * not contain any non-finite numbers (NaN, Infinity, -Infinity). * @param options Change defaults for the behavior of the operation, such as * the write strategy. * @throws {Error} when called in a React Native environment. */ upsert(value: DocumentValue, options: UpsertOptions): Promise; } /** * Not available in React Native environments. */ declare abstract class BasePendingCursorOperation implements PromiseLike { /** * Removes all documents that match the query generated by the preceding * function chaining. * * @throws {Error} when called in a React Native environment. * @returns An array promise containing the IDs of the documents that were * removed. */ abstract remove(): Promise; /** * Evicts all documents that match the query generated by the preceding * function chaining. * * @throws {Error} when called in a React Native environment. * @return An array promise containing the IDs of the documents that were * evicted. */ abstract evict(): Promise; /** * Updates documents that match the query generated by the preceding function * chaining. * * Document values must not be set to any non-finite numbers (`NaN`, * `Infinity`, `-Infinity`). * * @param closure A closure that gets called with all of the documents * matching the query. The documents are instances of {@link MutableDocument} * so you can call update-related functions on them. * * @throws {Error} when called in a React Native environment. * @returns An {@link UpdateResultsMap} promise mapping document IDs to lists * of {@link UpdateResult | update results} that describe the updates that * were performed for each document. */ abstract update(closure: (documents: MutableDocument[]) => void): Promise; /** The query the receiver is operating with. */ readonly query: string; /** The named arguments for the {@link query}. */ readonly queryArgs: QueryArguments | null; /** The collection the receiver is operating on. */ readonly collection: CollectionInterface; /** * Sorts the documents that match the query provided in the preceding * `find`-like function call. * * Documents that are missing the field to sort by will appear at * the beginning of the results when sorting in ascending order. * * @param query Name or path of the field to sort by. * * @param direction Specify whether you want the sorting order to be * `ascending` or `descending`. Defaults to `ascending`. * * @throws {Error} when called in a React Native environment. * @return A cursor that you can chain further function calls and then either * get the matching documents immediately or get updates about them over time. */ sort(query: string, direction?: SortDirection): BasePendingCursorOperation; /** * Offsets the resulting set of matching documents. * * This is useful if you aren't interested in the first N matching documents * for one reason or another. For example, you might already have queried the * collection and obtained the first 20 matching documents and so you might * want to run the same query as you did previously but ignore the first 20 * matching documents, and that is when you would use `offset`. * * @param offset The number of matching documents that you want the eventual * resulting set of matching documents to be offset by (and thus not include). * * @throws {Error} when called in a React Native environment. * @return A cursor that you can chain further function calls and then either * get the matching documents immediately or get updates about them over time. */ offset(offset: number): BasePendingCursorOperation; /** * Limits the number of documents that get returned when querying a collection * for matching documents. * * @param limit The maximum number of documents that will be returned. * * @throws {Error} when called in a React Native environment. * @return A cursor that you can chain further function calls and then either * get the matching documents immediately or get updates about them over time. */ limit(limit: number): BasePendingCursorOperation; /** * Executes the query generated by the preceding function chaining and return * the list of matching documents. * * @throws {Error} when called in a React Native environment. * @returns An array promise containing {@link Document | documents} matching * the query generated by the preceding function chaining. */ exec(): Promise; /** * Updates documents that match the query generated by the preceding function * chaining. * * @param closure A closure that gets called with all of the documents * matching the query. The documents are instances of * {@link MutableDocument} so you can call update-related functions on them. * @param publicAPIName the name of the public API function that was called * to perform the operation. Used in error messages and warnings. * @param writeTransactionPointer a transaction to perform the operation in. * If not provided, a new transaction will be created. * * @returns An {@link UpdateResultsMap} promise mapping document IDs to lists * of {@link UpdateResult | update results} that describe the updates that * were performed for each document. * * @internal */ updateWithClosure(closure: (documents: MutableDocument[]) => void, publicAPIName: string, writeTransactionPointer?: Pointer): Promise; /** @internal */ constructor(query: string, queryArgs: QueryArguments | null, collection: CollectionInterface); /** @internal */ then(onfulfilled?: ((value: any) => TResult1 | PromiseLike) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike) | null | undefined): PromiseLike; /** @internal */ protected queryArgsCBOR: Uint8Array | null; /** @internal */ protected currentLimit: number; /** @internal */ protected currentOffset: number; /** @internal */ protected orderBys: OrderBy[]; } /** * An object that describes how a document's position in a live query's list of * matching documents has changed since the previous live query event. */ interface LiveQueryMove { /** * The index of the document in the list of matching documents from the * previous live query event. */ readonly from: number; /** * The index of the document in the list of matching documents from the new * live query event. */ readonly to: number; } /** @internal */ interface LiveQueryEventUpdateParams { oldDocuments: Document[]; insertions: number[]; deletions: number[]; updates: number[]; moves: LiveQueryMove[]; } /** * First event fired immediately after registering a live query without any * mutations. All subsequent events are of type {@link LiveQueryEventUpdate}. * * Not available in React Native environments. */ declare class LiveQueryEventInitial { /** * Whether or not this is the initial event being delivered. Always `true` * for `LiveQueryEventInitial`. */ readonly isInitial = true; /** * Returns a hash that represents the set of matching documents. * * @deprecated use {@link Document.hash | Document.hash()} instead. */ hash(documents: Document[]): BigInt; /** * Returns a pattern of words that together create a mnemonic, which * represents the set of matching documents. * * @deprecated use {@link Document.hashMnemonic | Document.hashMnemonic()} instead. */ hashMnemonic(documents: Document[]): string; } /** * Represents an update event describing all changes that occured for documents * covered by a (live) query. * * Not available in React Native environments. */ declare class LiveQueryEventUpdate { /** * Whether or not this is the initial event being delivered. Always `false` * for `LiveQueryEventUpdate`. */ readonly isInitial = false; /** * The documents that previously matched the query, before the latest event. */ readonly oldDocuments: Document[]; /** * The indexes in the array of matching documents that accompany this event, * which relate to a document that was not in the previous most recent list of * matching documents. */ readonly insertions: number[]; /** * The indexes into the array {@link oldDocuments}, which relate to a document * that was in the previous most recent list of matching documents but is no * longer a matching document. */ readonly deletions: number[]; /** * The indexes in the array of matching documents that accompany this event, * which relate to a document that has been updated since the previous live * query event. */ readonly updates: number[]; /** * Objects that describe how documents' positions in the list of matching * documents have changed since the previous live query event. */ readonly moves: LiveQueryMove[]; /** * Returns a hash that represents the set of matching documents. * * @throws {Error} when called in a React Native environment. * @deprecated use {@link Document.hash | Document.hash()} instead. */ hash(documents: Document[]): BigInt; /** * Returns a pattern of words that together create a mnemonic, which * represents the set of matching documents. * * @throws {Error} when called in a React Native environment. * @deprecated use {@link Document.hashMnemonic | Document.hashMnemonic()} instead. */ hashMnemonic(documents: Document[]): string; /** @internal */ constructor(params: LiveQueryEventUpdateParams); } /** * Represents events delivered by a {@link LiveQuery}, which can be initial * (fired immediately upon registration) or an update (all subsequent events). */ type LiveQueryEvent = LiveQueryEventInitial | LiveQueryEventUpdate; /** * Provides information about a live query event relating to a single document * live query. */ declare class SingleDocumentLiveQueryEvent { /** * Whether or not this is the initial event being delivered. */ readonly isInitial: boolean; /** The old representation of the document with the relveant document ID. */ readonly oldDocument?: Document; /** * Returns a hash that represents the set of matching documents. * * @deprecated use {@link Document.hash | Document.hash()} instead. */ hash(document: Document | null): BigInt; /** * Returns a pattern of words that together create a mnemonic, which * represents the set of matching documents. * * @deprecated use {@link Document.hashMnemonic | Document.hashMnemonic()} instead. */ hashMnemonic(document: Document | null): string; /** @internal */ constructor(isInitial: boolean, oldDocument?: Document); } /** * The closure that is called whenever the documents covered by a live query * change. */ type QueryObservationHandler = (documents: Document[], event: LiveQueryEvent, signalNext?: () => any) => void | Promise; /** * These objects are returned when using `find`-like functionality on * {@link Collection}. * * They allow chaining of further query-related functions to do things like add * a limit to the number of documents you want returned or specify how you want * the documents to be sorted and ordered. * * You can either call {@link exec | exec()} on the object to get an array of * {@link Document | documents} as an immediate return value, or you can * establish either a live query or a subscription, which both work over time. * * A live query, established by calling * {@link PendingCursorOperation.observeLocal | observeLocal()}, will notify you * every time there's an update to a document that matches the query you * provided in the preceding `find`-like call. * * A subscription, established by calling * {@link PendingCursorOperation.subscribe | subscribe()}, will act as a signal * to other peers that the device connects to that you would like to receive * updates from them about documents that match the query you provided in the * preceding `find`-like call. * * Update and remove functionality is also exposed through this object. * * Not available in React Native environments. */ declare class PendingCursorOperation extends BasePendingCursorOperation { sort(propertyPath: string, direction?: SortDirection): PendingCursorOperation; offset(offset: number): PendingCursorOperation; limit(limit: number): PendingCursorOperation; remove(): Promise; evict(): Promise; update(closure: (documents: MutableDocument[]) => void): Promise; /** * Enables you to subscribe to changes that occur in a collection remotely. * * Having a subscription acts as a signal to other peers that you are * interested in receiving updates when local or remote changes are made to * documents that match the query generated by the chain of operations that * precedes the call to {@link subscribe | subscribe()}. * * The returned {@link Subscription} object must be kept in scope for as long * as you want to keep receiving updates. * * @throws {Error} when called in a React Native environment. * * @returns A {@link Subscription} object that must be kept in scope for as * long as you want to keep receiving updates for documents that match the * query specified in the preceding chain. */ subscribe(): Subscription; /** * Enables you to listen for changes that occur in a collection locally. * * The `handler` block will be called when local changes are * made to documents that match the query generated by the chain of operations * that precedes the call to {@link PendingCursorOperation.observeLocal | observeLocal()}. * The returned {@link LiveQuery} object must be kept in scope for as long as * you want the provided `handler` to be called when an update occurs. * * This won't subscribe to receive changes made remotely by others and so it * will only fire updates when a local change is made. If you want to receive * remotely performed updates as well, you'll have to create a subscription * via {@link PendingCursorOperation.subscribe | subscribe()} with the * relevant query. The returned {@link LiveQuery} object must be kept in scope * for as long as you want the provided `eventHandler` to be called when an * update occurs. * * @param handler A closure that will be called every time there is a * transaction committed to the store that involves modifications to documents * matching the query in the collection this method was called on. * * @throws {Error} when called in a React Native environment. * * @return A {@link LiveQuery} object that must be kept in scope for as long * as you want to keep receiving updates. */ observeLocal(handler: QueryObservationHandler): LiveQuery; /** * Enables you to listen for changes that occur in a collection locally and * to signal when you are ready for the live query to deliver the next event. * * The `handler` block will be called when local changes are * made to documents that match the query generated by the chain of operations * that precedes the call to {@link PendingCursorOperation.observeLocalWithNextSignal | observeLocalWithNextSignal()}. * The returned {@link LiveQuery} object must be kept in scope for as long as * you want the provided `handler` to be called when an update occurs. * * This won't subscribe to receive changes made remotely by others and so it * will only fire updates when a local change is made. If you want to receive * remotely performed updates as well, you'll have to create a subscription * via {@link PendingCursorOperation.subscribe | subscribe()} with the * relevant query. The returned {@link LiveQuery} object must be kept in scope * for as long as you want the provided `eventHandler` to be called when an * update occurs. * * @param handler A closure that will be called every time there is a * transaction committed to the store that involves modifications to * documents matching the query in the collection that this method was called * on. * * @throws {Error} when called in a React Native environment. * * @return A {@link LiveQuery} object that must be kept in scope for as long * as you want to keep receiving updates. */ observeLocalWithNextSignal(handler: QueryObservationHandler): LiveQuery; /** @internal */ constructor(query: string, queryArgs: QueryArguments | null, collection: Collection); /** @internal */ _observe(handler: QueryObservationHandler, waitForNextSignal: boolean): LiveQuery; } /** * The closure that is called whenever a single documunent covered by a * live query changes. */ type SingleObservationHandler = (document: Document | null, event: SingleDocumentLiveQueryEvent, signalNext?: () => void) => void | Promise; /** * These objects are returned when using {@link Collection.findByID | findByID()} * functionality on {@link Collection | collections}. * * You can either call {@link exec | exec()} on the object to get an immediate * return value, or you can establish either a live query or a subscription, * which both work over time. * * A live query, established by calling * {@link PendingIDSpecificOperation.observeLocal | observeLocal()}, will notify * you every time there's an update to the document with the ID you provided in * the preceding {@link Collection.findByID | findByID()} call. * * A subscription, established by calling {@link PendingIDSpecificOperation.subscribe | subscribe()}, will * act as a signal to other peers that you would like to receive updates from * them about the document with the ID you provided in the preceding * {@link Collection.findByID | findByID()} call. * * Update and remove functionality is also exposed through this object. */ declare class PendingIDSpecificOperation extends BasePendingIDSpecificOperation { remove(): Promise; evict(): Promise; update(closure: (document: MutableDocument) => void): Promise; updateV2(closure: (document?: MutableDocument) => void): Promise; /** * Enables you to subscribe to changes that occur in relation to a document * remotely. * * Having a subscription acts as a signal to other peers that you are * interested in receiving updates when local or remote changes are made to * the relevant document. * * The returned {@link Subscription} object must be kept in scope for as long * as you want to keep receiving updates. * * @returns A {@link Subscription} object that must be kept in scope for as * long as you want to keep receiving updates for the document. */ subscribe(): Subscription; /** * Enables you to listen for changes that occur in relation to a document * locally. * * This won't subscribe to receive changes made remotely by others and so it * will only fire updates when a local change is made. If you want to receive * remotely performed updates as well, you'll have to create a subscription * via {@link PendingIDSpecificOperation.subscribe | subscribe()} for the same * document ID. * * The returned {@link LiveQuery} object must be kept in scope for as long * as you want the provided `handler` to be called when an update * occurs. * * @param handler A block that will be called every time there is a * transaction committed to the store that involves a modification to the * document with the relevant ID in the collection that * {@link PendingIDSpecificOperation.observeLocal | observeLocal()} was called on. * * @returns A {@link LiveQuery} object that must be kept in scope for as long * as you want to keep receiving updates. */ observeLocal(handler: SingleObservationHandler): LiveQuery; /** * Enables you to listen for changes that occur in relation to a document * locally and to signal when you are ready for the live query to deliver * the next event. * * This won't subscribe to receive changes made remotely by others and so it * will only fire updates when a local change is made. If you want to receive * remotely performed updates as well, you'll have to create a subscription * via {@link PendingIDSpecificOperation.subscribe | subscribe()} for the same * document ID. * * The returned {@link LiveQuery} object must be kept in scope for as long * as you want the provided `handler` to be called when an update * occurs. * * @param handler A block that will be called every time there is a * transaction committed to the store that involves a modification to the * document with the relevant ID in the collection that * {@link PendingIDSpecificOperation.observeLocal | observeLocal()} was called on. * * @returns A {@link LiveQuery} object that must be kept in scope for as long * as you want to keep receiving updates. */ observeLocalWithNextSignal(handler: SingleObservationHandler): LiveQuery; /** @internal */ constructor(documentID: DocumentID, collection: Collection); /** @internal */ _observe(handler: SingleObservationHandler, waitForNextSignal: boolean): LiveQuery; } /** * Represents a collection of a Ditto store. * * This is the entrypoint for inserting documents into a collection, as well as * querying a collection. You can get a collection by calling * {@link Store.collection | collection()} on a {@link Store} of a {@link Ditto} * object. * * Not available in React Native environments. */ declare class Collection implements CollectionInterface { /** The name of the collection. */ readonly name: string; /** The store this collection belongs to. */ readonly store: Store; /** * Generates a {@link PendingCursorOperation} using the provided query. * * The returned object can be used to find and return the documents or you can * chain a call to `observeLocal()` or `subscribe()` if you want to get * updates about the list of matching documents over time. It can also be used * to update, remove or evict the matching documents. * * You can incorporate dynamic data into the query string with placeholders in * the form of `$args.my_arg_name`, along with providing an accompanying * dictionary in the form of `{ "my_arg_name": "some value" }`. The * placeholders will be appropriately replaced by the corresponding argument * contained in `queryArgs`. This includes handling things like wrapping * strings in quotation marks and arrays in square brackets, for example. * * Find more information about the query string format in the documentation's * section on {@link https://docs.ditto.live/javascript/common/concepts/querying Querying} * * @throws {Error} when called in a React Native environment. * @param query The query to run against the collection. * @param queryArgs The arguments to use to replace placeholders in the * provided query. */ find(query: string, queryArgs?: QueryArguments): PendingCursorOperation; findAll(): PendingCursorOperation; /** * Generates a {@link PendingIDSpecificOperation} with the provided document * ID. * * The returned object can be used to find and return the document or you can * chain a call to * {@link PendingIDSpecificOperation.observeLocal | observeLocal()}, or * {@link PendingIDSpecificOperation.subscribe | subscribe()} if you want to * get updates about the document over time. It can also be used to update, * remove or evict the document. * * @param id The ID of the document to find. * @throws {Error} when called in a React Native environment. */ findByID(id: DocumentID | DocumentIDValue): PendingIDSpecificOperation; upsert(value: DocumentValue, options?: UpsertOptions): Promise; /** * Creates a new {@link Attachment} object, which can then be inserted into a * document. Node only, throws when running in the web browser. * * 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. * * You can provide metadata about the attachment, which will be replicated to * other peers alongside the file attachment. * * Below is a snippet to show how you can use the * {@link newAttachment | newAttachment()} functionality to insert an * attachment into a document. * * ``` JavaScript * const attachment = await collection.newAttachment('/path/to/my/file.pdf') * await collection.upsert({ _id: '123', attachment, other: 'some-string' }) * } * ``` * * @param pathOrData The path to the file that you want to create an * attachment with or the raw data. * @param metadata Metadata relating to the attachment. * * @throws {Error} when called in a React Native environment. * * @deprecated Use {@link Store.newAttachment | ditto.store.newAttachment() } * instead. */ newAttachment(pathOrData: string | Uint8Array, metadata?: { [key: string]: string; }): 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. * * @param token The {@link AttachmentToken} relevant to the attachment that * you wish to download and observe. Throws if token is invalid. * @param eventHandler An optional callback that will be called when there is * an update to the status of the attachment fetch attempt. * * @throws {Error} when called in a React Native environment. * * @return An `AttachmentFetcher` object, which must be kept alive for the * fetch request to proceed and for you to be notified about the attachment's * fetch status changes. * * @deprecated Use * {@link Store.fetchAttachment | ditto.store.fetchAttachment() } instead. */ fetchAttachment(token: AttachmentToken, eventHandler?: (event: AttachmentFetchEvent) => void): AttachmentFetcher; /** @internal */ constructor(name: string, store: Store); /** @internal */ findByIDCBOR(idCBOR: Uint8Array): PendingIDSpecificOperation; } 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. * * Note: This property is very similar to {@link Document.value}. */ 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. * * **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 IDs */ mutatedDocumentIDs(): DocumentID[]; /** @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()`}. * * @template T The type of items in query results. This is a convenience type * that is neither inferred from the store observer's * {@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). */ readonly queryString: string; /** * The query arguments of the store observer (as passed when registering it). */ readonly queryArguments?: Readonly; /** * 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; /** * The ID of this observer's live query. * * @internal */ readonly liveQueryID: number; /** @internal */ constructor(ditto: Ditto, query: string, queryArguments: S | null, observationHandler: StoreObservationHandlerWithSignalNext); /** * `true` when the store observer has been cancelled. * * We mark the store observer as cancelled here as an optimization to avoid a * scan of all store observers in the store whenever the `isCancelled` * property is checked. */ private _isCancelled; /** * Signals to Ditto Core that the observer is ready for the next event. */ private signalNext; } /** @internal */ interface CollectionsEventParams { isInitial: boolean; collections: Collection[]; oldCollections: Collection[]; insertions: number[]; deletions: number[]; updates: number[]; moves: LiveQueryMove[]; } /** * Provides information about the changes that have occurred in relation to an * event delivered when observing the collections in a {@link Store}. * * It contains information about the collections that are known about as well as * the collections that were previously known about in the previous event, along * with information about what collections have been inserted, deleted, updated, * or moved since the last event. * * Not available in React Native environments. */ declare class CollectionsEvent { /** * Indicates whether or not this is the first event to be delivered when * observing collections in the store. */ readonly isInitial: boolean; /** * A list of all of the known collections. */ readonly collections: Collection[]; /** * A list of all of the known collections at the time the previous event was * delivered. */ readonly oldCollections: Collection[]; /** * A list of the indexes in the list of currently known about collections at * which new collections have been inserted. */ readonly insertions: number[]; /** * A list of the indexes in the list of previously known about collections at * which collections have been removed. */ readonly deletions: number[]; /** * A list of the indexes in the list of currently known about collections at * which pre-existing collections have been updated. */ readonly updates: number[]; /** * A list of the tuples that provides the indexes, in relation to the list of * previously known about collections, that already known about collections * have moved from and the indexes, in relation to the list of currently known * about collections, that the collections have moved to. */ readonly moves: LiveQueryMove[]; /** @internal */ static initial(collections: Collection[]): CollectionsEvent; /** @internal */ constructor(params: CollectionsEventParams); } /** * The closure that is called whenever the collections covered by a live query * change. */ type CollectionsObservationHandler = (event: CollectionsEvent, signalNext?: () => void) => void | Promise; /** * These objects are returned when calling * {@link Store.collections | collections()} on {@link Store}. * * They allow chaining of further collections-related functions. You can either * call {@link exec | exec()} on the object to get an array of * {@link Collection}s as an immediate return value, or you can establish either * a live query or a subscription, which both work over time. * * A live query, established by calling * {@link PendingCollectionsOperation.observeLocal | observeLocal()}, will * notify you every time there's a change in the collections that the device * knows about. * * A subscription, established by calling {@link subscribe | subscribe()}, will * act as a signal to other peers that the device connects to that you would * like to receive updates from them about the collections that they know about. * * Not available in React Native environments. */ declare class PendingCollectionsOperation implements PromiseLike { /** * Sort the collections based on a property of the collection. * * @param propertyPath The property path specifies the logic to be used when * sorting the matching collections. * * @param direction Specify whether you want the sorting order to be * `Ascending` or `Descending`. * * @throws {Error} when called in a React Native environment. * * @return A {@link PendingCollectionsOperation} that you can chain further * function calls to. */ sort(propertyPath: string, direction?: SortDirection): PendingCollectionsOperation; /** * Offset the resulting set of collections. * * This is useful if you aren't interested in the first N collections for one * reason or another. For example, you might already have obtained the first * 20 collections and so you might want to get the next 20 collections, and * that is when you would use {@link offset | offset()}. * * @param offset The number of collections that you want the eventual * resulting set of collections to be offset by (and thus not include). * * @throws {Error} when called in a React Native environment. * * @return A {@link PendingCollectionsOperation} that you can chain further * function calls to. */ offset(offset: number): PendingCollectionsOperation; /** * Limit the number of collections that get returned. * * @param limit The maximum number of collections that will be returned. * * @throws {Error} when called in a React Native environment. * * @return A {@link PendingCollectionsOperation} that you can chain further * function calls to. */ limit(limit: number): PendingCollectionsOperation; /** * Subscribes the device to updates about collections that other devices know * about. * * The returned {@link Subscription} object must be kept in scope for as long * as you want to keep receiving updates. * * @throws {Error} when called in a React Native environment. * * @return A {@link Subscription} object that must be kept in scope for as * long as you want to keep receiving updates from other devices about the * collections that they know about. */ subscribe(): Subscription; /** * Enables you to listen for changes that occur in relation to the collections * that are known about locally. * * The returned {@link LiveQuery} object must be kept in scope for as long as * you want the provided `handler` to be called when an update occurs. * * This won't subscribe to receive updates from other devices and so it will * only fire when a local change to the known about collections occurs. If * you want to receive remote updates as well, then create a subscription via * {@link PendingCollectionsOperation.subscribe | subscribe()}. * * @param handler A closure that will be called every time there is an update * about the list of known about collections. * * @throws {Error} when called in a React Native environment. * * @return A {@link LiveQuery} object that must be kept in scope for as long * as you want to keep receiving updates. */ observeLocal(handler: CollectionsObservationHandler): LiveQuery; /** * Enables you to listen for changes that occur in relation to the collections * that are known about locally. * * The returned {@link LiveQuery} object must be kept in scope for as long as * you want the provided `handler` to be called when an update occurs. * * This won't subscribe to receive updates from other devices and so it will * only fire when a local change to the known about collections occurs. If * you want to receive remote updates as well, then create a subscription via * {@link PendingCollectionsOperation.subscribe | subscribe()}. * * @param handler A closure that will be called every time there is an update * about the list of known about collections. * * @throws {Error} when called in a React Native environment. * * @return A {@link LiveQuery} object that must be kept in scope for as long * as you want to keep receiving updates. */ observeLocalWithNextSignal(handler: CollectionsObservationHandler): LiveQuery; /** * Return the list of collections requested based on the preceding function * chaining. * * @throws {Error} when called in a React Native environment. * * @return A list of {@link Collection}s based on the preceding function * chaining. */ exec(): Promise; /** @internal */ readonly store: Store; /** @internal */ constructor(store: Store); /** @internal */ then(onfulfilled?: ((value: any) => TResult1 | PromiseLike) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike) | null | undefined): PromiseLike; /** @internal */ _observe(handler: CollectionsObservationHandler, waitForNextSignal: boolean): LiveQuery; private readonly pendingCursorOperation; } /** * 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; /** * 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://docs.ditto.live/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. */ readonly 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. * @template U The type of the query arguments. * @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?: U): 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. * @template U The type of the query arguments * @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?: U): StoreObserver; /** * Returns the collection for the given name. If the collection doesn't * exist yet, it will be created automatically as soon as the first * entry is inserted. * A collection name is valid if: * * its length is less than 100 * * it is not empty * * it does not contain the char '\0' * * it does not begin with "$TS_" * * @throws {Error} when called in a React Native environment. */ collection(name: string): Collection; /** * Returns an object that lets you fetch or observe the collections in the * store. * * @return A {@link PendingCollectionsOperation} object that you can use to * fetch or observe the collections in the store * * @throws {Error} when called in a React Native environment. */ collections(): PendingCollectionsOperation; /** * Returns the names of all available collections in the store of the * related {@link Ditto} instance. * * @throws {Error} when called in a React Native environment. */ collectionNames(): Promise; execute(query: string, queryArguments?: U): Promise>; /** * Initiate a write transaction in a callback. * * Allows you to group multiple operations together that affect multiple documents, potentially across multiple collections. * * @param callback is given access to a {@link WriteTransaction | write transaction object} that can be used to perform operations on the store. * @throws {Error} when called in a React Native environment. * @returns a list of `WriteTransactionResult`s. There is a result for each operation performed as part of the write transaction. */ write(callback: (transaction: WriteTransaction) => Promise): 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} `sdk/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. This * may either be an {@link AttachmentToken} instance received from a * {@link Document} or a plain object as is returned in a * {@link QueryResultItem} (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 (my_attachment ATTACHMENT) * WHERE my_attachment.id = :id`, * { id: "123" } * ) * const attachmentToken = result.items[0].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 {@link AttachmentToken} instance or plain object * representation 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: AttachmentToken | { id: string; len: number | BigInt; metadata: AttachmentMetadata; }, eventHandler?: (event: AttachmentFetchEvent) => void): AttachmentFetcher; /** @internal */ constructor(ditto: Ditto); /** * Unregister a store observer. No-op if the change observer has already * been removed. * * This must only be called by the store observer itself. * * @param changeObserver the store observer to unregister * @returns true if the store observer was found and removed, false otherwise * @throws {@link DittoError} `internal`: if the store observer does not belong to * this store * @throws {@link DittoError} `internal`: if the store observer has not been * cancelled yet * @throws {@link DittoError} `internal`: for any other error that occurs while * trying to unregister the store observer * @internal */ unregisterObserver(storeObserver: StoreObserver): boolean; /** * 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://docs.ditto.live/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 `peerKeyString` on {@link Peer} for more information on peer * keys. */ get peerKeyString(): 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'; /** * An opaque address uniquely identifying another peer on the Ditto mesh * network. * * IMPORTANT: You should not rely on the individual components of the address, * those can change at any time. Please use * {@link addressToString | addressToString()} to compare individual addresses * with each other. */ type Address = { siteId: number | BigInt; pubkey: Uint8Array; }; /** * Returns a string representation of the given address. Use this function * to compare multiple addresses or whenever you need the address to be a key * in a hash object. */ declare function addressToString(address: Address): string; /** 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; /** * Peer key of the peer at one end of the connection. * * This peer key is lexicographically smaller than `peer2`. * * @deprecated Use {@link peerKeyString1} instead. */ peer1: Uint8Array; /** * Peer key of the peer at the other end of the connection. * * This peer key is lexicographically larger than `peer1`. * * @deprecated Use {@link peerKeyString2} instead. */ peer2: Uint8Array; /** * The peer key of the peer at one end of the connection, as a string. * * The assignment to `peerKeyString1` and `peerKeyString2` is deterministic * and stable for any two peers. */ peerKeyString1: string; /** * The peer key of the peer at the other end of the connection, as a string. * * The assignment to `peerKeyString1` and `peerKeyString2` is deterministic * and stable for any two peers. */ peerKeyString2: string; approximateDistanceInMeters?: number; }; /** Represents a peer in a Ditto mesh network. */ type Peer = { /** * Address to contact this peer via Ditto Bus, unique with a Ditto mesh * network. */ address: Address; /** * 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 be empty when a peer is not updated to the latest * version of the SDK. * * @deprecated Use {@link peerKeyString} instead. */ peerKey: Uint8Array; /** * 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 be empty when a peer is not updated to the latest * version of the SDK. */ peerKeyString: 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. */ isConnectedToDittoCloud: boolean; /** The operating system the peer is running on, `undefined` if (yet) unknown. */ os?: string; /** 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; 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()`}. * * @template T The type of query arguments passed to the sync subscription. */ declare class SyncSubscription { /** * Documents matching this query will be included in the sync subscription. */ readonly queryString: string; /** * The query arguments of the sync subscription (as passed when * adding it to the store). */ readonly queryArguments?: Readonly; /** * The {@link Ditto} instance this sync subscription belongs to. */ readonly ditto: Ditto; /** * `true` when the sync subscription has been cancelled or the {@link Ditto} * instance managing this subscription has been closed. */ get isCancelled(): boolean; /** * 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, query: string, queryArguments: T | null, queryArgumentsCBOR: Uint8Array | null); /** * The CBOR-encoded query arguments, or `null` if no query arguments were * passed in. * * @internal */ readonly queryArgumentsCBOR: Uint8Array | null; /** * `true` when the sync subscription has been cancelled. * * We mark the sync subscription as cancelled here as an optimization to avoid * a scan of all subscriptions in the store whenever the `isCancelled` * property is checked. */ private _isCancelled; } /** * 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. */ readonly subscriptions: Readonly>>; /** * 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. * @template T The type of the query arguments. * @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?: T): SyncSubscription; /** @internal */ constructor(ditto: Ditto); /** * Removes the passed in `syncSubscription`, configuring Ditto to not receive * updates for documents matching the corresponding query anymore. No-op if * the passed in `syncSubscription` has already been removed. * * This must only be called by the sync subscription itself. * * @param syncSubscription the sync subscription to remove * @returns `true` if the passed in sync subscription could be found and has * been removed, otherwise returns `false`. * @throws {@link DittoError} `internal`: if the replication subscription does not * belong to this store * @throws {@link DittoError} `internal`: if the replication subscription has not * been cancelled yet * @internal */ unregisterSubscription(syncSubscription: SyncSubscription): boolean; /** @internal */ close(): void; } /** * Specifies which peers to replicate the small peer info to when enabled. * * Possible values are: * * - `LocalPeerOnly`: no replication (default) * - `BigPeerOnly`: replicate to the Big Peer */ type SmallPeerInfoSyncScope = 'LocalPeerOnly' | 'BigPeerOnly'; /** * 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). This is controlled by * {@link getSyncScope | getSyncScope()} and * {@link setSyncScope | setSyncScope()}. */ 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); /** * Determines which "kind" of peers the small peer info will be replicated to. * * Defaults to `LocalPeerOnly`, which means no replication. Set this to * `BigPeerOnly` to replicate collected info to the Big Peer. * * @throws when set to a value other than `BigPeerOnly` or `LocalPeerOnly`. */ get syncScope(): SmallPeerInfoSyncScope; set syncScope(syncScope: SmallPeerInfoSyncScope); /** * Determines which "kind" of peers the small peer info will be * replicated to. * * Defaults to `LocalPeerOnly`, which means no replication. Set this to * `BigPeerOnly` to replicate collected info to the Big Peer. * * @deprecated use {@link SmallPeerInfo.syncScope} instead. */ getSyncScope(): Promise; /** * Set the sync scope. * * See {@link getSyncScope} for more information. * * @param syncScope the new sync scope. * @throws when set to a value other than `BigPeerOnly` or `LocalPeerOnly`. * @deprecated use {@link SmallPeerInfo.syncScope} instead. */ setSyncScope(syncScope: SmallPeerInfoSyncScope): Promise; 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; staticContentPath?: string; websocketSync: boolean; tlsKeyPath?: string; tlsCertificatePath?: string; } /** * Part of {@link TransportConfig} type, configuration for all P2P transports. */ interface TransportConfigPeerToPeer { bluetoothLE: { isEnabled: boolean; }; awdl: { 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 peer-to-peer transports are enabled. 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. * * 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 all peer-to-peer transports. Throws if receiver is frozen. */ setAllPeerToPeerEnabled(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; } 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 'internal/unknown-error': "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 'sdk/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 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 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."; }; /** * Additional data, which provides context to the error and may help with * debugging. * * **Warning:** The contents of this object may change in future versions of * the SDK. */ type ErrorContext = Record; /** * `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; /** * Additional data, which provides context to the error and may help with * debugging. * * **Warning:** The contents of this object may change in future versions of * the SDK. */ readonly context: Readonly; /** * @internal * @param code string error code, see {@link ERROR_CODES} * @param message optional error message that replace's the message for the given error code * @param context optional object containing data that can help debug this error * @throws {@link DittoError} `internal`: when supplied with an invalid error code */ constructor(code: ErrorCode, message?: string | null, context?: ErrorContext); /** * Create a {@link DittoError} from a {@link DittoFFIError}. * * The error message will be set to the optional `messageOverride` parameter * if supplied, otherwise it will be taken from the `message` property of the * given {@link DittoFFIError}. In any case, the details of the underlying FFI * error are made available in the error context of the returned {@link DittoError}. * * @internal * @param code string error code from {@link ERROR_CODES} * @param messageOverride optional string that will be used as the error * message even if a thread-local error message has been retrieved from the * FFI * @param context optional object containing data that can help debug this error * @returns {@link DittoError} */ static fromFFIError(ffiError: DittoFFIError, code: ErrorCode, messageOverride?: string, context?: ErrorContext): DittoError; } /** * Wraps the given function to catch any {@link DittoFFIError} and rethrow it as * a {@link DittoError}, mapping status codes of the {@link DittoFFIError} to * error codes of the {@link DittoError} using the given `statusCodeMapping`. * * Use either this function or {@link mapFFIErrorsAsync} to wrap all calls into * the FFI that can fail. * * If the given status code mapping contains error messages, they will replace * any error message that is returned by the FFI. * * @internal * @param closure function that can throw a {@link DittoFFIError} * @param statusCodeMapping optional mapping of status codes of the * {@link DittoFFIError} to error codes of the {@link DittoError} * @param context optional object containing data that can help debug this error * @throws {@link DittoError} when the wrapped function throws a {@link DittoFFIError} */ declare function mapFFIErrors(closure: () => T, statusCodeMapping?: Partial, context?: ErrorContext): 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}. * @param context optional object containing data that can help debug this error * @throws {@link DittoError} when the wrapped function throws a {@link DittoFFIError} */ declare function mapFFIErrorsAsync(closure: () => Promise, statusCodeMapping?: Partial, context?: ErrorContext): 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 = { [statusCode in FFIResultErrorCode | number | 'default']: [ErrorCode, string?]; }; /** * 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; }; declare const AuthenticationStatus: { fromFFI(ffiAuthenticationStatus: FFIAuthenticationStatus): AuthenticationStatus; }; /** * 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 `DittoError` object with * details about the error. */ error: DittoError | null; }; /** * Provides feedback to the developer about Ditto authentication status. */ interface AuthenticationHandler { /** * There is no Ditto authentication token or it has expired. Sync will not * work until there is a successful login using one of the login methods on * {@link Authenticator}. */ authenticationRequired: (authenticator: Authenticator) => void; /** * Warns that the Ditto authentication token is getting old. * * Ditto will attempt to refresh tokens periodically, starting from halfway * through the token's validity period. This reduces the risk of * authentication expiring while the user is offline. * * The refresh will happen automatically if Ditto has a suitable refresh * token. If new credentials are required, such as a third-party token or a * username/password, then Ditto does not cache that information and you must * submit it again using one of the `login` methods on {@link Authenticator}. */ authenticationExpiringSoon: (authenticator: Authenticator, secondsRemaining: number) => void; /** * Notifies the authentication handler that the authentication status did * change. Use the `authenticator`s property `status` to query for the current * authentication status. * * This method is **optional**. */ authenticationStatusDidChange?: (authenticator: Authenticator) => void; } /** * Log in to a remote authentication service, using an * `OnlineWithAuthentication` or an `Online` identity. */ 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 identity of type * {@link IdentityOnlineWithAuthentication | 'onlineWithAuthentication'}. */ readonly loginSupported: boolean; /** 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 `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. * @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 in to Ditto with a third-party token. Throws if authentication is not * available, which can be checked with {@link loginSupported}. * * @param token the authentication token required to log in. * @param provider the name of the authentication provider. * @deprecated Use {@link login} instead, which provides access to client info * provided by the authentication service. */ loginWithToken(token: string, provider: string): Promise; /** * Log in to Ditto with a username and password. Throws if authentication is * not available, which can be checked with {@link loginSupported}. * * @param username the username component of the credentials used for log in. * @param password the password component of the credentials used for log in. * @param provider the name of the authentication provider. */ loginWithUsernameAndPassword(username: string, password: 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); /** @internal */ '@ditto.authenticationExpiring'(number: any): void; /** @internal */ close(): void; /** @internal */ protected keepAlive: KeepAlive; /** @internal */ protected observerManager: ObserverManager; /** @internal */ protected _status: AuthenticationStatus; } /** @internal */ declare class OnlineAuthenticator extends Authenticator { readonly loginSupported: boolean; login(token: string, provider: string): Promise; loginWithToken(token: string, provider: string): Promise; loginWithUsernameAndPassword(username: string, password: string, provider: string): Promise; logout(cleanupFn?: (ditto: Ditto) => void): Promise; readonly authenticationHandler: AuthenticationHandler; private ditto; constructor(keepAlive: KeepAlive, ditto: Ditto, authenticationHandler: AuthenticationHandler); '@ditto.authenticationExpiring'(secondsRemaining: number): void; private authenticationStatusUpdated; private updateAndNotify; } /** @internal */ declare class NotAvailableAuthenticator extends Authenticator { login(token: string, provider: string): Promise; loginWithToken(token: string, provider: string): Promise; loginWithUsernameAndPassword(username: string, password: string, provider: string): Promise; logout(cleanupFn?: (ditto: Ditto) => void): Promise; '@ditto.authenticationExpiring'(secondsRemaining: number): never; } /** * 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 document: Bridge; /** @internal */ static readonly mutableDocument: 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 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; } /** * An identity to be used while in development when you want to control the app * name and the site ID of the peer. */ interface IdentityOfflinePlayground { type: 'offlinePlayground'; /** * The app ID for the Ditto instance. */ appID: string; /** * The `siteID` needs to be an unsigned 64 bit integer >= 0, i.e. either a * regular non-fractional `number` or a `BigInt` in the range between 0 and * 2^64 - 1 (inclusive). If `siteID` is `0`, Ditto will generate an * appropriate site ID and persist it when needed. Default is `0`. */ siteID?: number | BigInt; } /** * An identity with intermediate level of security where all users and devices * are trusted and a single shared secret (key) between all peers satisfies the * security requirements. * * **NOTE**: This identity type is only supported for Node environments, using * this to create a Ditto instance in the web browser will throw an exception. */ interface IdentitySharedKey { type: 'sharedKey'; /** * The app ID for the Ditto instance. */ appID: string; /** * The `siteID` needs to be an unsigned 64 bit integer >= 0, i.e. either a * regular non-fractional `number` or a `BigInt` in the range between 0 and * 2^64 - 1 (inclusive). If `siteID` is `0`, Ditto will generate an * appropriate site ID and persist it when needed. Default is `0`. */ siteID?: number | BigInt; /** * A base64 encoded DER representation of a private key, which is shared * between devices for a single app. */ sharedKey: string; } /** * A manually-provided certificate identity. This accepts a * base64-encoded bundle. * * A manual identity's `appID` is encoded in its certificate. */ interface IdentityManual { type: 'manual'; certificate: string; } /** * Test a Ditto Cloud app with weak shared token authentication ("Playground * mode"). This mode is not secure and must only be used for development. */ interface IdentityOnlinePlayground { type: 'onlinePlayground'; /** * An ID identifying this app registration on the Ditto portal, which can be * found at https://portal.ditto.live. */ appID: string; /** * A shared token used to set up the OnlinePlayground session. This token is * provided by the Ditto Portal when setting up the application. */ token: string; /** If true, auto-configure sync with Ditto Cloud. Default is `true`. */ enableDittoCloudSync?: boolean; /** * If specified, use a custom authentication service instead of Ditto Cloud. */ customAuthURL?: string; /** * A custom Ditto Cloud URL. * @internal */ customDittoCloudURL?: string; } /** * Run Ditto in secure production mode, logging on to Ditto Cloud or an * on-premises authentication server. User permissions are centrally managed. * Sync will not work until a successful login has occurred. * * The only required configuration is the application's UUID, which can be found * on the Ditto portal where the app is registered. * * By default cloud sync is enabled. This means the SDK will sync to a Big Peer * in Ditto's cloud when an internet connection is available. This is controlled * by the `enableCloudSync` parameter. If `true` (default), a suitable wss:// * URL will be added to the `TransportConfig`. To prevent cloud sync, or to * specify your own URL later, pass `false`. * * Authentication requests are handled by Ditto's cloud by default, configured * in the portal at https://portal.ditto.live. * * To use a different or on-premises authentication service, pass a custom HTTPS * base URL as the `customAuthUrl` parameter. */ interface IdentityOnlineWithAuthentication { type: 'onlineWithAuthentication'; /** * An ID identifying this app registration on the Ditto portal, which can be * found at https://portal.ditto.live. */ appID: string; /** * If true, auto-configure sync with Ditto Cloud. Default is `true`. */ enableDittoCloudSync?: boolean; /** * A handler for when Ditto requires (re)authentication. */ authHandler: AuthenticationHandler; /** * If specified, use a custom authentication service instead of Ditto Cloud. */ customAuthURL?: string; /** * A custom Ditto Cloud URL. * @internal */ customDittoCloudURL?: string; } /** * The various identity configurations that you can use when initializing a * `Ditto` instance. */ type Identity = IdentityOfflinePlayground | IdentitySharedKey | IdentityManual | IdentityOnlinePlayground | IdentityOnlineWithAuthentication; /** The list of identity types that require activation through an offlineLicenseToken */ declare const IdentityTypesRequiringOfflineLicenseToken: string[]; /** 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'; /** * Types of connections that can be established between two peers. * @deprecated replaced by {@link ConnectionType}. */ type PresenceConnectionType = 'WiFi' | 'WebSocket' | 'AWDL' | 'BLE'; /** * A peer object with information about an observed peer. * @deprecated replaced by {@link Peer}. */ type RemotePeer = { networkID: string; deviceName: string; rssi?: number; approximateDistanceInMeters?: number; connections: PresenceConnectionType[]; }; /** * 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; /** * 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 startSync | startSync()} 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 startSync | startSync()} is called. */ get deviceName(): string; set deviceName(value: string); /** Returns a string identifying the version of the Ditto SDK. */ get sdkVersion(): string; /** * The (validated) identity this Ditto instance was initialized with. */ readonly identity: Identity; /** * The path this Ditto instance was initialized with, if no path was given at * construction time, the default value is returned (see constructor). * * @deprecated `Ditto.path` is deprecated. Please update your code to use the * new 'Ditto.persistenceDirectory' property instead. */ get path(): string; /** * Path to the local directory used for persistent data storage. * * Defaults to 'ditto'. In environments without file system access, such as * browsers, this is used as a namespace for the internal data store. * * 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 {@link Ditto.close | closed}. Please refer to * the documentation of {@link Logger} for more information. */ readonly persistenceDirectory: 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; /** * The site ID that the instance of `Ditto` is using as part of its identity. */ readonly siteID: number | BigInt; /** * Provides access to the SDK's small peer info functionality. */ readonly smallPeerInfo: SmallPeerInfo; /** * 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; /** * Returns `true` if sync is active, otherwise returns `false`. Use * {@link startSync | startSync()} to activate and * {@link stopSync | stopSync()} to deactivate sync. */ get isSyncActive(): boolean; /** * Application ID associated with the {@link Identity | identity} used by this * Ditto instance. * */ readonly appID: string; /** * Initializes a new `Ditto` instance. * * **NOTE**: The `sharedKey` identity is only supported for Node environments, * using this to create a Ditto instance in the web browser will throw an * exception. * * @param identity - Identity for the new Ditto instance, defaults to * `offlinePlayground` with `appID` being the empty string `''`. * * @param persistenceDirectory optional string containing a directory path * that Ditto will use for persistence. Defaults to `"ditto"`. On Windows, * the path will be automatically normalized. * * @see {@link Ditto.identity} * @see {@link Ditto.persistenceDirectory} * @throws {Error} when the current environment is not supported by this SDK. * @throws {Error} for other failures during initialization of Ditto and * validation of the provided identity. */ constructor(identity?: Identity, persistenceDirectory?: string); /** * 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; /** * Validates and creates the given directory and returns its path. * * Any string containing non-whitespace characters is considered valid. * Defaults to `ditto` if no path or an invalid path is given. In web * environments, the given path is returned as-is if it is valid. * * @param path optional string containing a writable directory path * @returns validated path * @internal */ static initPersistenceDirectory(path?: string): string; /** * 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 identities of type `development`, `manual`, * `offlinePlayground`, and `sharedKey`. * * @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 startSync | startSync()} is called. * * @see {@link 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; /** * 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 updateTransportConfig | updateTransportConfig()} * or replaced with {@link setTransportConfig | setTransportConfig()}. * * Performance of initial sync when bootstrapping new peers can be improved by * calling {@link disableSyncWithV3 | disableSyncWithV3()} before * {@link startSync | startSync()}. Only call that method when all peers in * the mesh are known to be running Ditto v4 or higher. * * Ditto will prevent the process from exiting until sync is stopped (not * relevant when running in the browser). * * **NOTE**: the BluetoothLE transport on Linux is experimental, this * method panics if no BluetoothLE hardware is available. Therefore, contrary * to the above, the BluetoothLE transport is temporarily disabled by default * on Linux. * * @see {@link isSyncActive} * @see {@link stopSync | stopSync()} */ startSync(): 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 isSyncActive} * @see {@link startSync | startSync()} */ stopSync(): void; /** * Registers an observer for info about Ditto peers in range of this device. * * Ditto will prevent the process from exiting as long as there are active * peers observers (not relevant when running in the browser). * * @param callback called immediately with the current state of peers * in range and whenever that state changes. Then it will be invoked * repeatedly when Ditto devices come and go, or the active connections to * them change. * * @deprecated please use {@link Presence.observe | presence.observe()} instead. */ observePeers(callback: (peersData: RemotePeer[]) => void): Observer; /** * 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; /** * Removes all sync metadata for remote peers that aren't currently connected. * * This method shouldn't usually be called. Manually running garbage * collection often will result in slower sync times. Ditto automatically runs * a garbage a collection process in the background at optimal times. * * Manually running garbage collection is typically only useful during testing * if large amounts of data are being generated. Alternatively, if an entire * data set is to be evicted and it's clear that maintaining this metadata * isn't necessary, then garbage collection could be run after evicting the * old data. * * This method does not have any effect when running Ditto in a browser. */ runGarbageCollection(): Promise; /** * Disable sync with peers running version 3 or lower of the Ditto SDK. * * Required for the execution of mutating DQL statements. * * This setting spreads to other peers on connection. Those peers will in turn * spread it further until all peers in the mesh take on the same setting. * This is irreversible and will persist across restarts of the Ditto * instance. * * Calling this method before starting sync is recommended whenever possible. * This improves performance of initial sync when this peer has never before * connected to a Ditto mesh for which sync with v3 peers is disabled. * * @throws {Error} when called in a React Native environment where sync with v3 * is always disabled. */ disableSyncWithV3(): Promise; /** * 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 */ liveQueryManager: LiveQueryManager; /** @internal */ subscriptionManager: SubscriptionManager; /** @internal */ attachmentFetcherManager: AttachmentFetcherManager; /** * 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 presenceManager; private transportConditionsManager; private _isClosed; private _deviceName; /** Set of pending operations that need to complete before the Ditto instance can be closed in a safe manner. */ private pendingOperations; private validateIdentity; } /** * 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: AttachmentToken; /** 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; /** * Returns the attachment's data. * * @deprecated Use `data()` instead. */ getData(): Promise; /** * Copies the attachment to the specified file path. Node-only, * throws in the browser. * * @param path The path that the attachment should be copied to. */ copyToPath(path: string): Promise; /** @internal */ constructor(ditto: Ditto, token: AttachmentToken); } /** * 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; /** * Describes the direction when sorting a query. */ type SortDirection = 'ascending' | 'descending'; /** * Defines the various strategies available when inserting a document into a * collection. * * - `merge`: the existing document will be merged with the document being * inserted, if there is a pre-existing document. * * - `insertIfAbsent`: insert the document only if there is not already a * document with the same ID in the store. If there is already a document in * the store with the same ID then this will be a no-op. * * - `insertDefaultIfAbsent`: insert the document, with its contents treated as * default data, only if there is not already a document with the same ID in * the store. If there is already a document in the store with the same ID * then this will be a no-op. Use this strategy if you want to insert default * data for a given document ID, which you want to treat as common initial * data amongst all peers and that you expect to be mutated or overwritten in * due course. */ type WriteStrategy = 'merge' | 'insertIfAbsent' | 'insertDefaultIfAbsent'; /** * Represents a dictionary of values to be incorporated into a query keyed by * the placeholder used within that query. See method * {@link Collection.find | find()} of {@link Collection} for more info. * * This value must not contain any non-finite numbers (`NaN`, `Infinity`, * `-Infinity`). */ type QueryArguments = { [key: string]: any; }; /** * Values to be incorporated into a query, keyed by the placeholder used within * that query. * * This value must not contain any non-finite numbers (`NaN`, `Infinity`, * `-Infinity`). */ type DQLQueryArguments = { [key: string]: DQLQueryArgumentValue | undefined; }; /** * Individual value in a {@link DQLQueryArguments} object. */ type DQLQueryArgumentValue = string | number | boolean | Uint8Array | null | Attachment | DocumentID | 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; /** * On Node, registers a file path where logs will be written to, whenever * Ditto wants to issue a log (on _top_ of emitting the log to the console). * In the browser, this method has no effect. * * @param path can be `null`, in which case the current logging file, if any, * is unregistered, otherwise, the file path must be within an already * existing directory. */ static setLogFile(path: string | null): void; /** * Convenience method, takes the path part of the URL and calls * {@link setLogFile | setLogFile()} with it. */ static setLogFileURL(url: URL | undefined): void; /** * 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); /** * Represents whether or not emojis should be used as the log level * indicator in the logs. */ static get emojiLogLevelHeadingsEnabled(): boolean; /** * Represents whether or not emojis should be used as the log level * indicator in the logs. */ static set emojiLogLevelHeadingsEnabled(emojiLogLevelHeadingsEnabled: 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). * * Ditto limits the amount of logs it retains on disk to 15 MB and a maximum * age of three 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} `sdk/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; }; /** @internal */ declare class CBOR { /** @internal */ static encode(data: any): Uint8Array; /** @internal */ static decode(data: Uint8Array, reviver?: (key: any, value: any) => any): any; } export { type Address, Attachment, type AttachmentFetchEvent, type AttachmentFetchEventCompleted, type AttachmentFetchEventDeleted, type AttachmentFetchEventProgress, type AttachmentFetchEventType, AttachmentFetcher, type AttachmentMetadata, AttachmentToken, type AuthenticationHandler, AuthenticationStatus, Authenticator, BasePendingCursorOperation, BasePendingIDSpecificOperation, CBOR, Collection, type CollectionInterface, CollectionsEvent, type CollectionsEventParams, type CollectionsObservationHandler, type ConditionSource, type Connection, ConnectionRequest, type ConnectionRequestAuthorization, type ConnectionRequestHandler, type ConnectionType, Counter, type CustomLogCallback, type DQLQueryArgumentValue, type DQLQueryArguments, Diff, Differ, Ditto, DittoError, Document, DocumentID, type DocumentIDValue, DocumentPath, type DocumentValue, ERROR_CODES, type ErrorCode, type ErrorContext, type Identity, type IdentityManual, type IdentityOfflinePlayground, type IdentityOnlinePlayground, type IdentityOnlineWithAuthentication, type IdentitySharedKey, IdentityTypesRequiringOfflineLicenseToken, type InitOptions, KeepAlive, LiveQuery, type LiveQueryEvent, LiveQueryEventInitial, LiveQueryEventUpdate, type LiveQueryEventUpdateParams, type LiveQueryMove, type LogLevel, Logger, type LoginResult, MutableCounter, MutableDocument, MutableDocumentPath, MutableRegister, NotAvailableAuthenticator, Observer, type ObserverOptions, OnlineAuthenticator, type Peer, PendingCollectionsOperation, PendingCursorOperation, PendingIDSpecificOperation, Presence, type PresenceConnectionType, type PresenceGraph, type QueryArguments, type QueryExecuting, type QueryObservationHandler, QueryResult, QueryResultItem, Register, type RemotePeer, SingleDocumentLiveQueryEvent, type SingleObservationHandler, SmallPeerInfo, type SmallPeerInfoSyncScope, type SortDirection, Store, type StoreObservationHandler, type StoreObservationHandlerWithSignalNext, StoreObserver, Subscription, Sync, SyncSubscription, Transaction, type TransactionCompletionAction, TransactionInfo, type TransactionOptions, type TransportCondition, TransportConfig, type TransportConfigConnect, type TransportConfigGlobal, type TransportConfigLan, type TransportConfigListen, type TransportConfigListenHTTP, type TransportConfigListenTCP, type TransportConfigPeerToPeer, type TypedAttachmentToken, type UntypedAttachmentToken, UpdateResult, type UpdateResultType, UpdateResultsMap, type UpsertOptions, type WebAssemblyModule, type WriteStrategy, WriteTransaction, WriteTransactionCollection, WriteTransactionPendingCursorOperation, WriteTransactionPendingIDSpecificOperation, type WriteTransactionResult, addressToString, checkAPIs, disableDeadlockTimeoutWhenDebugging, getBridgeLoad, init, mapFFIErrors, mapFFIErrorsAsync, transportConfigFromDeserializable, transportConfigToSerializable, validateAttachmentMetadata, validateDocumentIDCBOR, validateDocumentIDValue }; //# sourceMappingURL=ditto.d.ts.map