@dittolive/ditto 4.11.2-rc.1 → 4.12.0-experimental-untangle.0

package/node/ditto.cjs.js

@@ -106,6 +106,8 @@ class Observer {
 }
 Observer.finalizationRegistry = new FinalizationRegistry(Observer.finalize);
 
+const isReactNativeBuild = false;
+
 //
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
 //
@@ -118,14 +120,21 @@ const privateToken$1 = Symbol('privateConstructorToken');
  * assigned to a property during an update of a document.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class Counter {
-    /** The value of the counter. */
+    /**
+     * The value of the counter.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
+     */
     get value() {
         return this._value;
     }
     /**
      * Creates a new counter that can be used as part of a document's content.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     constructor() {
         this._value = 0.0;
@@ -147,6 +156,8 @@ class Counter {
  *
  * This class can't be instantiated directly, it's returned automatically for
  * any counter property within an update block via {@link MutableDocumentPath.counter}.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class MutableCounter extends Counter {
     /**
@@ -156,8 +167,8 @@ class MutableCounter extends Counter {
      * {@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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     increment(amount) {
         const mutDoc = this.mutDoc;
@@ -191,14 +202,23 @@ const privateToken = '@ditto.ff82dae89821c5ab822a8b539056bce4';
  * assigned to a property during an update of a document.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class Register {
-    /** Returns the value of the register. */
+    /**
+     * Returns the value of the register.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
+     */
     get value() {
         return this['@ditto.value'];
     }
     /**
      * Creates a new Register that can be used as part of a document's content.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     constructor(value) {
         this['@ditto.value'] = value;
@@ -224,12 +244,17 @@ class Register {
  * {@link MutableDocumentPath.register}.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class MutableRegister extends Register {
     /**
      * Returns the value of the register.
      *
      * Not available in React Native environments.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get value() {
         return super.value;
@@ -238,6 +263,9 @@ class MutableRegister extends Register {
      * Convenience setter, equivalent to {@link set | set()}.
      *
      * Not available in React Native environments.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     set value(value) {
         this.set(value);
@@ -251,6 +279,9 @@ class MutableRegister extends Register {
      * otherwise an exception is thrown.
      *
      * Not available in React Native environments.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     set(value) {
         const mutableDocument = this['@ditto.mutableDocument'];
@@ -382,6 +413,8 @@ function ditto_validate_document_id(...args) { return ditto.ditto_validate_docum
 function ditto_write_transaction(...args) { return ditto.ditto_write_transaction(...args) }
 function ditto_write_transaction_commit(...args) { return ditto.ditto_write_transaction_commit(...args) }
 function ditto_write_transaction_rollback(...args) { return ditto.ditto_write_transaction_rollback(...args) }
+function dittoffi_DEFAULT_DATABASE_ID(...args) { return ditto.dittoffi_DEFAULT_DATABASE_ID(...args) }
+function dittoffi_DITTO_DEVELOPMENT_PROVIDER(...args) { return ditto.dittoffi_DITTO_DEVELOPMENT_PROVIDER(...args) }
 function dittoffi_authentication_status_free(...args) { return ditto.dittoffi_authentication_status_free(...args) }
 function dittoffi_authentication_status_is_authenticated(...args) { return ditto.dittoffi_authentication_status_is_authenticated(...args) }
 function dittoffi_authentication_status_user_id(...args) { return ditto.dittoffi_authentication_status_user_id(...args) }
@@ -396,8 +429,11 @@ function dittoffi_crypto_generate_secure_random_token(...args) { return ditto.di
 function dittoffi_differ_diff(...args) { return ditto.dittoffi_differ_diff(...args) }
 function dittoffi_differ_free(...args) { return ditto.dittoffi_differ_free(...args) }
 function dittoffi_differ_new(...args) { return ditto.dittoffi_differ_new(...args) }
+function dittoffi_ditto_absolute_persistence_directory(...args) { return ditto.dittoffi_ditto_absolute_persistence_directory(...args) }
+function dittoffi_ditto_config_default(...args) { return ditto.dittoffi_ditto_config_default(...args) }
 function dittoffi_ditto_is_activated(...args) { return ditto.dittoffi_ditto_is_activated(...args) }
 function dittoffi_ditto_is_sync_active(...args) { return ditto.dittoffi_ditto_is_sync_active(...args) }
+function dittoffi_ditto_open_throws(...args) { return ditto.dittoffi_ditto_open_throws(...args) }
 function dittoffi_ditto_set_authentication_status_handler(...args) { return ditto.dittoffi_ditto_set_authentication_status_handler(...args) }
 function dittoffi_ditto_set_cloud_sync_enabled(...args) { return ditto.dittoffi_ditto_set_cloud_sync_enabled(...args) }
 function dittoffi_ditto_stop_sync(...args) { return ditto.dittoffi_ditto_stop_sync(...args) }
@@ -413,7 +449,9 @@ function dittoffi_logger_try_export_to_file_async(...args) { return ditto.dittof
 function dittoffi_presence_peer_metadata_json(...args) { return ditto.dittoffi_presence_peer_metadata_json(...args) }
 function dittoffi_presence_set_connection_request_handler(...args) { return ditto.dittoffi_presence_set_connection_request_handler(...args) }
 function dittoffi_presence_try_set_peer_metadata_json(...args) { return ditto.dittoffi_presence_try_set_peer_metadata_json(...args) }
+function dittoffi_query_result_commit_id(...args) { return ditto.dittoffi_query_result_commit_id(...args) }
 function dittoffi_query_result_free(...args) { return ditto.dittoffi_query_result_free(...args) }
+function dittoffi_query_result_has_commit_id(...args) { return ditto.dittoffi_query_result_has_commit_id(...args) }
 function dittoffi_query_result_item_at(...args) { return ditto.dittoffi_query_result_item_at(...args) }
 function dittoffi_query_result_item_cbor(...args) { return ditto.dittoffi_query_result_item_cbor(...args) }
 function dittoffi_query_result_item_count(...args) { return ditto.dittoffi_query_result_item_count(...args) }
@@ -553,6 +591,19 @@ var DittoCRDTType;
     DittoCRDTType[DittoCRDTType["rga"] = 3] = "rga";
     DittoCRDTType[DittoCRDTType["rwMap"] = 4] = "rwMap";
 })(DittoCRDTType || (DittoCRDTType = {}));
+// ------------------------------------------------------------- Constants --
+/** @internal */
+function DITTO_DEVELOPMENT_PROVIDER() {
+    ensureInitialized();
+    const providerCString = dittoffi_DITTO_DEVELOPMENT_PROVIDER();
+    return refCStringToString(providerCString);
+}
+/** @internal */
+function DEFAULT_DATABASE_ID() {
+    ensureInitialized();
+    const idCString = dittoffi_DEFAULT_DATABASE_ID();
+    return refCStringToString(idCString);
+}
 // ------------------------------------------------------------- Differ --------
 function differNew() {
     ensureInitialized();
@@ -881,6 +932,23 @@ function queryResultMutatedDocumentIDs(queryResultPointer) {
     }
     return rv;
 }
+/**
+ * @internal
+ */
+function queryResultHasCommitID(queryResultPointer) {
+    ensureInitialized();
+    return dittoffi_query_result_has_commit_id(queryResultPointer);
+}
+/**
+ * @internal
+ */
+function queryResultCommitID(queryResultPointer) {
+    ensureInitialized();
+    const commitId = dittoffi_query_result_commit_id(queryResultPointer);
+    // the FFI function returns a number or BigInt, we convert it to BigInt
+    // to simplify the API
+    return BigInt(commitId);
+}
 /**
  * The result CBOR contains a map/object with fields and values. No CRDTs are
  * present there as they are not needed. By default only values from registers
@@ -1083,7 +1151,7 @@ function loggerSetLogFile(path) {
     }
 }
 /** @internal */
-async function loggerTryExportToFileAsync(path) {
+async function loggerTryExportToFile(path) {
     ensureInitialized();
     const pathBytes = bytesFromString(path);
     const result = await new Promise((resolve, reject) => {
@@ -1299,7 +1367,34 @@ function transactionFree(transaction) {
     ensureInitialized();
     dittoffi_transaction_free(transaction);
 }
-// ---------------------------------------------------------------- Ditto ------
+// --------------------------------------------------------- Ditto Config ------
+/** @internal */
+function dittoConfigDefault() {
+    ensureInitialized();
+    const cborBytes = dittoffi_ditto_config_default();
+    return boxCBytesIntoBuffer(cborBytes);
+}
+/** @internal */
+function dittoAbsolutePersistenceDirectory(dittoPointer) {
+    ensureInitialized();
+    const cString = dittoffi_ditto_absolute_persistence_directory(dittoPointer);
+    return boxCStringIntoString(cString);
+}
+/** @internal */
+function dittoOpenThrows(configCBOR, transportConfigMode, defaultRootDirectory) {
+    ensureInitialized();
+    const defaultRootDirectoryPointer = bytesFromString(defaultRootDirectory);
+    // // Debug: Log CBOR bytes in hex format. The output can be pasted to https://cbor.me
+    // // to visualize the CBOR structure.
+    // const hexBytes = Array.from(configCBOR)
+    //   .map((byte) => byte.toString(16).padStart(2, '0').toUpperCase())
+    //   .join(' ');
+    // console.log(`DEBUG: CBOR bytes (${configCBOR.length} bytes):`);
+    // console.log(hexBytes);
+    const result = dittoffi_ditto_open_throws(configCBOR, transportConfigMode, defaultRootDirectoryPointer);
+    throwOnErrorResult(result.error, 'dittoffi_ditto_open_throws');
+    return result.success;
+}
 /** @internal */
 function dittoTryNewBlocking(path, identityConfig, historyTracking, transportConfigMode) {
     ensureInitialized();
@@ -1449,7 +1544,7 @@ function dittoIsSyncActive(ditto) {
     return dittoffi_ditto_is_sync_active(ditto);
 }
 /** @internal */
-function dittoStartSync(ditto) {
+function dittoTryStartSync(ditto) {
     ensureInitialized();
     const result = dittoffi_ditto_try_start_sync(ditto);
     throwOnErrorResult(result.error, 'dittoffi_ditto_try_start_sync');
@@ -1729,8 +1824,8 @@ function withTransportsError(ffiFunction, ...args) {
 }
 // ---------------------------------------------------------------- Other ------
 /** @internal */
-let isInitialized = false;
-isInitialized = true;
+let isInitialized$1 = false;
+isInitialized$1 = true;
 /** @internal */
 function initSDKVersion(platform, language, semVer) {
     ensureInitialized();
@@ -1750,6 +1845,19 @@ function tryVerifyLicense(ditto, license) {
     const result = dittoffi_try_verify_license(ditto, licenseBuffer);
     throwOnErrorResult(result.error, 'dittoffi_try_verify_license');
 }
+/**
+ * Returns the platform-dependent default device name.
+ *
+ * @internal
+ */
+// FIXME: Move this to Ditto core.
+function defaultDeviceName() {
+    // FIXME: Check if device name stays the same on sdk and core levels (AR-5950).
+    {
+        const os = require('os');
+        return os.hostname();
+    }
+}
 // -------------------------------------------------------------- Private ------
 // HACK: this is a left-over error code still in use which will be removed
 // in the near future. Until then, we hard-code it here, just like the
@@ -1821,7 +1929,7 @@ function errorMessage() {
 }
 /** @internal */
 function ensureInitialized() {
-    if (!isInitialized) {
+    if (!isInitialized$1) {
         throw new Error('Ditto needs to be initialized before using any of its API, please make sure to call `await init()` first.');
     }
 }
@@ -1856,6 +1964,8 @@ const ERROR_CODES = {
     //
     /** Error when authentication failed */
     'authentication/failed-to-authenticate': 'Ditto failed to authenticate.',
+    /** Error when the required expiration handler is not set before starting sync. */
+    'authentication/expiration-handler-missing': 'The expiration handler must be set before starting sync.',
     //
     // IO errors
     //
@@ -1930,6 +2040,8 @@ const ERROR_CODES = {
     'validation/invalid-json': 'The value provided is not valid JSON.',
     /** A validation error where the TransportConfig is invalid for the active platform. */
     'validation/invalid-transport-config': 'The TransportConfig is invalid for the active platform.',
+    /** A validation error where the {@link DittoConfig} is invalid. */
+    'validation/invalid-ditto-config': 'The DittoConfig provided is invalid.',
     /** A validation error where a value is required to be a JavaScript object */
     'validation/not-an-object': 'The value provided is not of type object.',
     /** The value provided can not be serialized as JSON. */
@@ -1971,6 +2083,12 @@ const DEFAULT_STATUS_CODE_MAPPING = {
     ActivationNotActivated: ['activation/not-activated'],
     ActivationUnnecessary: ['activation/unnecessary'],
     //
+    // Authenticaion errors
+    //
+    AuthenticationExpirationHandlerMissing: [
+        'authentication/expiration-handler-missing',
+    ],
+    //
     // Input/output errors
     //
     IoAlreadyExists: ['io/already-exists'],
@@ -2018,6 +2136,7 @@ const DEFAULT_STATUS_CODE_MAPPING = {
     CborUnsupported: ['internal', 'Unsupported CBOR encoding.'],
     ValidationDepthLimitExceeded: ['validation/depth-limit-exceeded'],
     ValidationInvalidCbor: ['validation/invalid-cbor'],
+    ValidationInvalidDittoConfig: ['validation/invalid-ditto-config'],
     ValidationInvalidJson: ['validation/invalid-json'],
     ValidationInvalidTransportConfig: ['validation/invalid-transport-config'],
     ValidationNotAMap: ['validation/not-an-object'],
@@ -2274,11 +2393,13 @@ class AttachmentToken {
 
 // NOTE: this is patched up with the actual build version by Jake task
 // build:package and has to be a valid semantic version as defined here: https://semver.org.
-const fullBuildVersionString = '4.11.2-rc.1';
+const fullBuildVersionString = '4.12.0-experimental-untangle.0';
 
 //
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
 //
+let isInitialized = false;
+let initPromise = null;
 // Replacing {custom-sdk-name} with any string that doesn't contain '{' in the
 // final build output switches the SDK_NAME to the custom name.
 const SDK_NAME = '{custom-sdk-name}'.includes('{')
@@ -2290,7 +2411,17 @@ const SDK_NAME = '{custom-sdk-name}'.includes('{')
  *
  * @param options - Dictionary with global {@link InitOptions | initialization options}.
  */
-async function init(options = {}) {
+function init(options = {}) {
+    // If we have already completed initialization just return the resolved Promise
+    if (isInitialized)
+        return initPromise;
+    // If initialization is in flight return the already created promise
+    if (initPromise)
+        return initPromise;
+    initPromise = (async () => {
+        isInitialized = true;
+    })();
+    return initPromise;
 }
 {
     switch (process.platform) {
@@ -2345,6 +2476,7 @@ class Logger {
      * @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.
+     * @deprecated this mehod is deprecated and will be removed in a future version.
      */
     static setLogFile(path) {
         if (path) {
@@ -2359,6 +2491,8 @@ class Logger {
     /**
      * Convenience method, takes the path part of the URL and calls
      * {@link setLogFile | setLogFile()} with it.
+     *
+     * @deprecated this method is deprecated and will be removed in a future version.
      */
     static setLogFileURL(url) {
         var _a;
@@ -2381,6 +2515,8 @@ class Logger {
     /**
      * Represents whether or not emojis should be used as the log level
      * indicator in the logs.
+     *
+     * @deprecated This property is deprecated and will be removed in a future version.
      */
     static get emojiLogLevelHeadingsEnabled() {
         return loggerEmojiHeadingsEnabledGet();
@@ -2501,7 +2637,7 @@ class Logger {
             // c.f. httpes://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#maximum-path-length-limitation
             normalizedPath = `\\\\?\\${path}`;
         }
-        return mapFFIErrorsAsync(() => loggerTryExportToFileAsync(normalizedPath));
+        return mapFFIErrorsAsync(() => loggerTryExportToFile(normalizedPath));
     }
     /**
      * Logs the message for the given `level`.
@@ -3568,11 +3704,16 @@ class CBOR {
 //
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
 //
-/** Represents a unique identifier for a {@link Document}. */
+/**
+ * Represents a unique identifier for a {@link Document}.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
+ */
 class DocumentID {
     /**
      * Returns the value of the receiver, lazily decoded from its CBOR
      * representation if needed.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get value() {
         let value = this['@ditto.value'];
@@ -3623,6 +3764,8 @@ class DocumentID {
     /**
      * Returns `true` if passed in `documentID` is equal to the receiver,
      * otherwise returns `false`.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     equals(documentID) {
         const left = this['@ditto.cbor'];
@@ -3645,6 +3788,8 @@ class DocumentID {
      *
      * If you need a string representation to be used directly in a query,
      * please use `toQueryCompatibleString()` instead.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     toString() {
         return documentIDQueryCompatible(this['@ditto.cbor'], 'WithoutQuotes');
@@ -4376,6 +4521,9 @@ function checkForUnsupportedValues(jsObj) {
  *   - `incremented`
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class UpdateResult {
     // ----------------------------------------------------------- Internal ------
@@ -4680,16 +4828,19 @@ class KeyPath {
  * method of {@link Document}.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class DocumentPath {
     /**
-     * Returns a new document path instance with the passed in key-path or
-     * index appended.
+     * 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
+     * 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.
      *
@@ -4702,6 +4853,8 @@ class DocumentPath {
      *    - `documentPath.at('.mileage')`
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     at(keyPathOrIndex) {
         if (typeof keyPathOrIndex === 'string') {
@@ -4727,6 +4880,8 @@ class DocumentPath {
      * returns the corresponding object or value.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get value() {
         return this.underlyingValueForPathType('Any');
@@ -4736,6 +4891,8 @@ class DocumentPath {
      * {@link Counter} if possible, otherwise returns `null`.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get counter() {
         const underlyingValue = this.underlyingValueForPathType('Counter');
@@ -4748,6 +4905,8 @@ class DocumentPath {
      * {@link Register} if possible, otherwise returns `null`.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get register() {
         const underlyingValue = this.underlyingValueForPathType('Register');
@@ -4760,6 +4919,8 @@ class DocumentPath {
      * {@link AttachmentToken} if possible, otherwise returns `null`.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get attachmentToken() {
         const underlyingValue = this.underlyingValueForPathType('Attachment');
@@ -4791,6 +4952,9 @@ class DocumentPath {
  * {@link MutableDocument.at | at()} method of {@link MutableDocument}.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class MutableDocumentPath {
     /**
@@ -4798,8 +4962,8 @@ class MutableDocumentPath {
      * 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
+     * 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.
@@ -4813,6 +4977,8 @@ class MutableDocumentPath {
      *    - `mutableDocumentPath.at('.mileage')`
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     at(keyPathOrIndex) {
         if (typeof keyPathOrIndex === 'string') {
@@ -4838,6 +5004,8 @@ class MutableDocumentPath {
      * returns the corresponding object or value.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get value() {
         return this.underlyingValueForPathType('Any');
@@ -4847,6 +5015,8 @@ class MutableDocumentPath {
      * {@link MutableCounter} if possible, otherwise returns `null`.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get counter() {
         const underlyingValue = this.underlyingValueForPathType('Counter');
@@ -4859,6 +5029,8 @@ class MutableDocumentPath {
      * {@link MutableRegister} if possible, otherwise returns `null`.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get register() {
         const underlyingValue = this.underlyingValueForPathType('Register');
@@ -4871,6 +5043,8 @@ class MutableDocumentPath {
      * {@link AttachmentToken} if possible, otherwise returns `null`.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get attachmentToken() {
         const underlyingValue = this.underlyingValueForPathType('Attachment');
@@ -4887,6 +5061,8 @@ class MutableDocumentPath {
      * value is `false`.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     set(value, isDefault) {
         return this['@ditto.set'](value, isDefault);
@@ -4895,6 +5071,8 @@ class MutableDocumentPath {
      * Removes a value at the document's key-path defined by the receiver.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     remove() {
         return this['@ditto.remove']();
@@ -4967,8 +5145,8 @@ class MutableDocumentPath {
     }
     /** @private */
     recordUpdateResult(updateResult) {
-        // OPTIMIZE: not sure how much of a performance hit this
-        // clone-modify-freeze dance implies. Investigate and fix.
+        // OPTIMIZE: not sure how much of a performance hit this clone-modify-freeze
+        // dance implies. Investigate and fix.
         const updateResults = this.mutableDocument['@ditto.updateResults'].slice();
         updateResults.push(updateResult);
         Object.freeze(updateResults);
@@ -4987,12 +5165,18 @@ const CUSTOM_INSPECT_SYMBOL$1 = Symbol.for('nodejs.util.inspect.custom');
  * A document belonging to a {@link Collection} with an inner value.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class Document {
     /**
      * Returns a hash that represents the passed in document(s).
      *
      * @throws {Error} when called in a React Native environment.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     static hash(documentOrMany) {
         const documents = documentsFrom(documentOrMany);
@@ -5004,6 +5188,9 @@ class Document {
      * represents the passed in document(s).
      *
      * @throws {Error} when called in a React Native environment.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     static hashMnemonic(documentOrMany) {
         const documents = documentsFrom(documentOrMany);
@@ -5014,6 +5201,8 @@ class Document {
      * Returns the document ID.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get id() {
         let id = this['@ditto.id'];
@@ -5029,6 +5218,8 @@ class Document {
      * Returns the document path at the root of the document.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get path() {
         return new DocumentPath(this, '', false);
@@ -5039,6 +5230,8 @@ class Document {
      * again.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get value() {
         let value = this['@ditto.value'];
@@ -5052,6 +5245,8 @@ class Document {
      * Convenience method, same as calling `path.at()`.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     at(keyPathOrIndex) {
         return this.path.at(keyPathOrIndex);
@@ -5089,12 +5284,12 @@ class Document {
 }
 // -----------------------------------------------------------------------------
 // REFACTOR: adapt the mutable document proxying to the way it is done for
-// Document, i.e. only use the proxy to dispatch and delegate to actual
-// methods on the corresponding classes. The way it is right now is that
-// most of the code of this code is duplicated within the MutableDocument,
-// the MutableDocumentPath classes and the proxy implementation. Also make
-// sure to proxy the mutable document right within its constructor. Same
-// for mutable and immutable document path.
+// Document, i.e. only use the proxy to dispatch and delegate to actual methods
+// on the corresponding classes. The way it is right now is that most of the
+// code of this code is duplicated within the MutableDocument, the
+// MutableDocumentPath classes and the proxy implementation. Also make sure to
+// proxy the mutable document right within its constructor. Same for mutable and
+// immutable document path.
 /**
  * A representation of a {@link Document} that can be mutated via
  * {@link MutableDocumentPath}. You don't create or interact with a
@@ -5103,12 +5298,17 @@ class Document {
  * {@link PendingIDSpecificOperation.update | PendingIDSpecificOperation}.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class MutableDocument {
     /**
      * Returns the ID of the document.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get id() {
         let id = this['@ditto.id'];
@@ -5124,6 +5324,8 @@ class MutableDocument {
      * Returns the document path at the root of the document.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get path() {
         return new MutableDocumentPath(this, '', false);
@@ -5132,6 +5334,8 @@ class MutableDocument {
      * Convenience property, same as `path.value`.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get value() {
         return this.path.value;
@@ -5140,6 +5344,8 @@ class MutableDocument {
      * Convenience method, same as calling `path.at()`.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     at(keyPathOrIndex) {
         return this.path.at(keyPathOrIndex);
@@ -5160,8 +5366,8 @@ class MutableDocument {
         return `${this.constructor.name}(${this.id})`;
     }
     /**
-     * Defines a custom inspect function for Node.js that will be used when
-     * the object is inspected with console.log() or util.inspect().
+     * 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, _inspectOptions, inspect) {
@@ -5190,15 +5396,22 @@ function documentsFrom(documentOrMany) {
 /**
  * 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.
+ * when {@link PendingCursorOperation.update | updating} a set of documents with
+ * detailed info about the performed updates.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class UpdateResultsMap {
     /**
      * Returns an array of {@link UpdateResult | update results} associated with
      * the `documentID` or undefined if not found.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
+  
      */
     get(documentIDOrValue) {
         const documentID = documentIDOrValue instanceof DocumentID
@@ -5210,6 +5423,10 @@ class UpdateResultsMap {
     /**
      * Returns all contained keys, i.e. {@link DocumentID | document IDs}
      * contained in this map.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
+  
      */
     keys() {
         return this.documentIDs.slice();
@@ -5246,14 +5463,17 @@ class UpdateResultsMap {
 //
 /**
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information
+ * see: https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class BasePendingCursorOperation {
     /**
      * 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.
+     * 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.
      *
@@ -5263,6 +5483,8 @@ class BasePendingCursorOperation {
      * @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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     sort(query, direction = 'ascending') {
         this.orderBys.push({
@@ -5286,6 +5508,8 @@ class BasePendingCursorOperation {
      * @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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     offset(offset) {
         // REFACTOR: factor out parameter validation.
@@ -5313,6 +5537,8 @@ class BasePendingCursorOperation {
      * @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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     limit(limit) {
         // REFACTOR: factor out parameter validation.
@@ -5339,6 +5565,7 @@ class BasePendingCursorOperation {
      * @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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     async exec() {
         const ditto = this.collection.store.ditto;
@@ -5453,6 +5680,8 @@ class BasePendingCursorOperation {
  * Live queries and subscriptions are only available outside of a transaction.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class BasePendingIDSpecificOperation {
     /**
@@ -5462,6 +5691,9 @@ class BasePendingIDSpecificOperation {
      * @returns The {@link Document} promise with the ID provided in the
      * {@link Collection.findByID | findByID()} call or `undefined` if the document was
      * not found.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     async exec() {
         const ditto = this.collection.store.ditto;
@@ -5793,23 +6025,67 @@ class ObserverManager {
 //
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
 //
-const AuthenticationStatus = {
-    fromFFI(ffiAuthenticationStatus) {
-        const isAuthenticated = authenticationStatusIsAuthenticated(ffiAuthenticationStatus);
-        const userID = authenticationStatusUserID(ffiAuthenticationStatus);
-        authenticationStatusFree(ffiAuthenticationStatus);
-        return {
-            isAuthenticated,
-            userID,
-        };
-    },
-};
+function authenticationStatusFromFFI(ffiAuthenticationStatus) {
+    const isAuthenticated = authenticationStatusIsAuthenticated(ffiAuthenticationStatus);
+    const userID = authenticationStatusUserID(ffiAuthenticationStatus);
+    authenticationStatusFree(ffiAuthenticationStatus);
+    return {
+        isAuthenticated,
+        userID,
+    };
+}
 // -----------------------------------------------------------------------------
 /**
  * Log in to a remote authentication service, using an
  * `OnlineWithAuthentication` or an `Online` identity.
  */
 class Authenticator {
+    /**
+     * The built-in development authentication provider to be used together with
+     * development authentication tokens.
+     *
+     * This API is in **preview** as part of the new configuration APIs that replace
+     * the legacy {@link Identity}-based initialization.
+     *
+     * @see {@link Authenticator.login | Authenticator.login()} for more information
+     * about the `provider` parameter.
+     */
+    static get DEVELOPMENT_PROVIDER() {
+        return DITTO_DEVELOPMENT_PROVIDER();
+    }
+    /**
+     * The handler that will be called when authentication for this Ditto instance
+     * is about to expire.
+     *
+     * This API is in **preview** and provides a replacement for the phased out
+     * {@link AuthenticationHandler} interface.
+     *
+     * **Important:** If the Ditto instance is configured with a
+     * {@link DittoConfigConnectServer} this property **must** be set and the
+     * handler **must** properly authenticate when called.
+     *
+     * @see {@link setExpirationHandler}
+     */
+    get expirationHandler() {
+        throw new Error(`Authenticator.expirationHandler is only available when using a ` +
+            `DittoConfig with a ConfigConnectServer.`);
+    }
+    /**
+     * Sets the handler that will be called when authentication for this Ditto
+     * instance is about to expire.
+     *
+     * This API is in **preview** and provides a replacement for the phased out
+     * {@link AuthenticationHandler} interface.
+     *
+     * Assign a handler function to be notified before authentication expires,
+     * allowing you to login or perform other necessary actions.
+     *
+     * @see {@link expirationHandler}
+     */
+    async setExpirationHandler(handler) {
+        throw new Error(`Authenticator.expirationHandler is only available when using a ` +
+            `DittoConfig with a ConfigConnectServer.`);
+    }
     /**
      Returns the current authentication status.
      */
@@ -5821,15 +6097,16 @@ class Authenticator {
      *
      * 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.
+     * otherwise it will contain a {@link DittoError} object with details about
+     * the error.
      *
      * If the authentication service provides additional client info, it will be
      * returned in the `clientInfo` property of the response, whether the login
      * attempt was successful or not.
      *
      * @param token The authentication token required to log in.
-     * @param provider The name of the authentication provider.
+     * @param provider The name of the authentication provider. Use
+     *   {@link Authenticator.DEVELOPMENT_PROVIDER} with development tokens.
      * @throws {@link DittoError} `authentication/failed-to-authenticate` if the
      * Ditto instance is closed.
      * @returns A promise that resolves to a `LoginResult` object.
@@ -5856,6 +6133,8 @@ class Authenticator {
      * @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.
+     * @deprecated this method is deprecated and will be removed in a future
+     * version.
      */
     loginWithUsernameAndPassword(username, password, provider) {
         throw new Error(`Authenticator.loginWithUsernameAndPassword() is abstract and must be implemented by subclasses.`);
@@ -5958,13 +6237,28 @@ class OnlineAuthenticator extends Authenticator {
                     Logger.info('Authenticator is null, ignoring authentication status change');
                     return;
                 }
-                const authenticationStatus = AuthenticationStatus.fromFFI(ffiAuthenticationStatus);
+                const authenticationStatus = authenticationStatusFromFFI(ffiAuthenticationStatus);
                 authenticator.authenticationStatusUpdated(authenticationStatus);
             });
         });
         this.updateAndNotify(false);
     }
     '@ditto.authenticationExpiring'(secondsRemaining) {
+        const ditto = this.ditto.deref();
+        const isLegacyIdentity = ditto !== null && ditto.configOrParameters.isParameters;
+        // Handle new-style expiration handler first
+        if (!isLegacyIdentity) {
+            void ditto.deferCloseAsync(async () => {
+                try {
+                    await this.expirationHandler(ditto, secondsRemaining);
+                }
+                catch (error) {
+                    Logger.error(`Authentication expiration handler failed: ${error.message}`);
+                }
+            });
+            return;
+        }
+        // Fallback to legacy authentication handler
         const authenticationHandler = this.authenticationHandler;
         if (secondsRemaining > 0)
             authenticationHandler.authenticationExpiringSoon(this, secondsRemaining);
@@ -6009,6 +6303,171 @@ class OnlineAuthenticator extends Authenticator {
     }
 }
 // -----------------------------------------------------------------------------
+/**
+ * OnlineAuthenticatorV2 exclusively supports the new DittoConfig-based API,
+ *
+ * @internal
+ */
+class OnlineAuthenticatorV2 extends Authenticator {
+    get expirationHandler() {
+        const ditto = this.ditto.deref();
+        if (!ditto || ditto.isClosed) {
+            Logger.error('Ditto instance is closed, cannot get authentication expiration handler.');
+            return null;
+        }
+        return this._expirationHandler;
+    }
+    async setExpirationHandler(handler) {
+        const ditto = this.ditto.deref();
+        if (!ditto || ditto.isClosed) {
+            Logger.error('Ditto instance is closed, cannot set authentication expiration handler.');
+        }
+        this._expirationHandler = handler;
+        // Register the expiration handler with the FFI layer.
+        return ditto.deferCloseAsync(async (dittoHandle) => {
+            try {
+                const providerPointer = dittoAuthClientMakeLoginProvider(this.makeFFFIAuthenticationExpirationHandler());
+                await dittoAuthSetLoginProvider(dittoHandle.deref(), providerPointer);
+            }
+            catch (error) {
+                Logger.error(`Failed to set authentication expiration handler: ${error.message}`);
+            }
+        });
+    }
+    constructor(keepAlive, ditto) {
+        super(keepAlive);
+        // -----------------------------------------------------------------------------
+        /** @internal */
+        this._expirationHandler = null;
+        if (ditto.configOrParameters.isParameters) {
+            throw new Error('OnlineAuthenticatorV2 can only be used with the new DittoConfig-based API.');
+        }
+        this.loginSupported = ditto.config.connect.type === 'server';
+        this.ditto = new WeakRef(ditto);
+        // Set up authentication status handler like OnlineAuthenticator does
+        const weakThis = new WeakRef(this);
+        ditto.deferClose((dittoHandle) => {
+            dittoSetAuthenticationStatusHandler(dittoHandle.deref(), function (ffiAuthenticationStatus) {
+                const authenticator = weakThis.deref();
+                if (authenticator == null) {
+                    Logger.info('Authenticator is null, ignoring authentication status change');
+                    return;
+                }
+                const authenticationStatus = authenticationStatusFromFFI(ffiAuthenticationStatus);
+                authenticator.authenticationStatusUpdated(authenticationStatus);
+            });
+        });
+        // Initialize status by querying current state
+        this.updateAndNotify(false);
+    }
+    async login(token, provider) {
+        const ditto = this.ditto.deref();
+        if (!ditto || ditto.isClosed) {
+            throw new DittoError('authentication/failed-to-authenticate', 'Ditto instance is closed');
+        }
+        return ditto.deferCloseAsync(async (dittoHandle) => {
+            const { clientInfo, error: ffiError } = await dittoAuthClientLoginWithTokenAndFeedback(dittoHandle.deref(), token, provider);
+            const error = ffiError != null
+                ? DittoError.fromFFIError(ffiError, 'authentication/failed-to-authenticate')
+                : null;
+            return { clientInfo, error };
+        });
+    }
+    async loginWithToken(token, provider) {
+        const ditto = this.ditto.deref();
+        if (!ditto || ditto.isClosed)
+            return;
+        return ditto.deferCloseAsync(async (dittoHandle) => {
+            await dittoAuthClientLoginWithToken(dittoHandle.deref(), token, provider);
+        });
+    }
+    async loginWithUsernameAndPassword(username, password, provider) {
+        const ditto = this.ditto.deref();
+        if (!ditto || ditto.isClosed)
+            return;
+        return ditto.deferCloseAsync(async (dittoHandle) => {
+            await dittoAuthClientLoginWithUsernameAndPassword(dittoHandle.deref(), username, password, provider);
+        });
+    }
+    async logout(cleanupFn) {
+        const ditto = this.ditto.deref();
+        if (!ditto || ditto.isClosed)
+            return;
+        return ditto.deferCloseAsync(async (dittoHandle) => {
+            await dittoAuthClientLogout(dittoHandle.deref());
+            ditto.stopSync();
+            cleanupFn === null || cleanupFn === void 0 ? void 0 : cleanupFn(ditto);
+        });
+    }
+    authenticationStatusUpdated(authenticationStatus) {
+        const previousStatus = this.status;
+        this._status = authenticationStatus;
+        const sameStatus = !!previousStatus.isAuthenticated ===
+            !!authenticationStatus.isAuthenticated &&
+            previousStatus.userID === authenticationStatus.userID;
+        if (!sameStatus)
+            this.observerManager.notify(authenticationStatus);
+    }
+    updateAndNotify(shouldNotify) {
+        const ditto = this.ditto.deref();
+        if (!ditto) {
+            Logger.debug('Unable to update auth status and notify, related Ditto object does not exist anymore.');
+            return;
+        }
+        const dittoHandle = Bridge.ditto.handleFor(ditto);
+        const dittoPointer = dittoHandle.derefOrNull();
+        if (!dittoPointer) {
+            Logger.debug('Unable to update auth status and notify, related Ditto object does not exist anymore.');
+            return;
+        }
+        const isAuthenticated = dittoAuthClientIsWebValid(dittoPointer);
+        const userID = dittoAuthClientUserID(dittoPointer);
+        const status = { isAuthenticated, userID };
+        if (shouldNotify) {
+            // We don't need to set the `_status` property here because it's done in
+            // `authenticationStatusUpdated`.
+            this.authenticationStatusUpdated(status);
+        }
+        else {
+            this._status = status;
+        }
+    }
+    makeFFFIAuthenticationExpirationHandler() {
+        const weakAuthenticator = new WeakRef(this);
+        return (secondsUntilExpiration) => {
+            const authenticator = weakAuthenticator.deref();
+            if (!authenticator) {
+                // If owning authenticator has gone out of scope, we sure don't need to
+                // notify anyone about the expiration.
+                return;
+            }
+            const ditto = authenticator.ditto.deref();
+            if (!ditto) {
+                // Same if Ditto went out of scope.
+                return;
+            }
+            if (authenticator.expirationHandler != null) {
+                // This is being called from FFI so no point in awaiting the
+                // deferCloseAsync promise.
+                void ditto.deferCloseAsync(async () => {
+                    try {
+                        await authenticator.expirationHandler(ditto, secondsUntilExpiration);
+                    }
+                    catch (error) {
+                        Logger.error('The authentication handler set via `ditto.auth.setExpirationHandler()` ' +
+                            `failed: ${error.message}`);
+                    }
+                });
+            }
+            else {
+                Logger.error('Authentication required but no expiration handler is set. ' +
+                    'Please set an expiration handler using ' +
+                    '`ditto.auth.setExpirationHandler()`.');
+            }
+        };
+    }
+}
+// -----------------------------------------------------------------------------
 /** @internal */
 class NotAvailableAuthenticator extends Authenticator {
     async login(token, provider) {
@@ -6037,27 +6496,260 @@ const IdentityTypesRequiringOfflineLicenseToken = [
     'sharedKey',
     'offlinePlayground',
 ];
+/**
+ * Registers the given identity with Ditto FFI and returns a pointer to the
+ * identity configuration.
+ *
+ * @internal
+ * @deprecated
+ */
+function makeIdentityConfig(identity) {
+    var _a, _b, _c;
+    if (identity.type === 'offlinePlayground') {
+        return dittoIdentityConfigMakeOfflinePlayground(identity.appID, (_a = identity.siteID) !== null && _a !== void 0 ? _a : 0);
+    }
+    if (identity.type === 'manual') {
+        return dittoIdentityConfigMakeManual(identity.certificate);
+    }
+    if (identity.type === 'sharedKey') {
+        return dittoIdentityConfigMakeSharedKey(identity.appID, identity.sharedKey, identity.siteID);
+    }
+    if (identity.type === 'onlinePlayground') {
+        const authURL = (_b = identity.customAuthURL) !== null && _b !== void 0 ? _b : defaultAuthURL(identity.appID);
+        return dittoIdentityConfigMakeOnlinePlayground(identity.appID, identity.token, authURL);
+    }
+    if (identity.type === 'onlineWithAuthentication') {
+        const authURL = (_c = identity.customAuthURL) !== null && _c !== void 0 ? _c : defaultAuthURL(identity.appID);
+        return dittoIdentityConfigMakeOnlineWithAuthentication(identity.appID, authURL);
+    }
+}
 
 //
-// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+// Copyright © 2025 DittoLive Incorporated. All rights reserved.
 //
 /**
- * Restore a `TransportConfig` from its serializable representation.
+ * The default identity that is used when no identity is specified while
+ * creating a Ditto instance.
  *
  * @internal
+ * @deprecated This is used for backward compatibility with the legacy
+ * {@link DittoConfig} constructor.
  */
-function transportConfigFromDeserializable(serialized) {
-    const peerToPeerJSON = serialized['peer_to_peer'];
-    const bluetoothLEJSON = peerToPeerJSON['bluetooth_le'];
-    const bluetoothLEEnabled = bluetoothLEJSON['enabled'];
-    const awdlJSON = peerToPeerJSON['awdl'];
-    const awdlEnabled = awdlJSON['enabled'];
-    const lanJSON = peerToPeerJSON['lan'];
-    const lanEnabled = lanJSON['enabled'];
-    const lanMdnsEnabled = lanJSON['mdns_enabled'];
-    const lanMulticastEnabled = lanJSON['multicast_enabled'];
-    const connectJSON = serialized['connect'];
-    const connectTcpServers = connectJSON['tcp_servers'];
+const DEFAULT_IDENTITY = {
+    type: 'offlinePlayground',
+    appID: '',
+};
+/**
+ * A configuration object for initializing a {@link Ditto} instance.
+ *
+ * Encapsulates all the parameters required to configure a Ditto instance,
+ * including identity, connectivity, and persistence.
+ *
+ * This API is in **preview** and will become the standard way to initialize
+ * Ditto instances in v5, replacing the legacy {@link Identity}-based
+ * initialization.
+ */
+class DittoConfig {
+    /**
+     * The default database ID, used when no database ID is provided.
+     *
+     * @see {@link DittoConfig.databaseID | database_id} for more information about the
+     * `databaseID` parameter.
+     */
+    static get DEFAULT_DATABASE_ID() {
+        return DEFAULT_DATABASE_ID();
+    }
+    /**
+     * Returns a default {@link DittoConfig} instance with standard settings.
+     *
+     * This is useful as a starting point or for quickly creating a basic
+     * configuration, but for production use you should customize the
+     * configuration as needed.
+     */
+    static get default() {
+        const configCBOR = dittoConfigDefault();
+        const ffiConfig = CBOR.decode(configCBOR);
+        return fromFFICBORData(ffiConfig);
+    }
+    /**
+     * Initializes a new {@link DittoConfig} instance with the new API.
+     */
+    constructor(id, connect, persistenceDirectory) {
+        this._isFrozen = false;
+        // The logger is initialized here to ensure that users have a chance to set
+        // a minimum log level before the logger starts emitting logs.
+        loggerInit();
+        // New API: DittoConfig(id, connect, persistenceDirectory?)
+        if (typeof id !== 'string')
+            throw new TypeError('Expected id to be a string, but got: ' + typeof id);
+        if (typeof connect !== 'object') {
+            throw new TypeError(`Expected connect to be an object, but got: ` + typeof connect);
+        }
+        if (persistenceDirectory != null &&
+            typeof persistenceDirectory !== 'string') {
+            throw new TypeError(`Expected persistenceDirectory to be undefined or a string, but got: ` +
+                typeof persistenceDirectory);
+        }
+        this.databaseID = id;
+        this.connect = connect;
+        this.persistenceDirectory = persistenceDirectory;
+        this.validate();
+    }
+    /**
+     * Returns true if the receiver has been frozen using
+     * {@link DittoConfig.freeze | freeze()}.
+     */
+    get isFrozen() {
+        return this._isFrozen;
+    }
+    /**
+     * Deep freezes the receiver such that it can't be modified anymore.
+     *
+     * Use {@link DittoConfig.copy | copy()} to create a copy of the receiver that
+     * is not frozen.
+     *
+     * Warning: this does not freeze legacy
+     * {@link AuthenticationHandler | authentication handlers} referenced by the
+     * identity. Changes inside the authentication handlers will be reflected in the
+     * frozen {@link DittoConfig}.
+     *
+     * @see {@link DittoConfig.isFrozen}
+     */
+    freeze() {
+        if (this.isFrozen)
+            return this;
+        this._isFrozen = true;
+        Object.freeze(this.connect);
+        Object.freeze(this);
+        return this;
+    }
+    /**
+     * Returns a deep copy of the receiver.
+     *
+     * The copy is not frozen, so it's properties can be modified.
+     *
+     * Warning: This does not create copies of
+     * {@link AuthenticationHandler | authentication handlers} referenced by the
+     * identity. Changes inside the authentication handlers will be reflected in the
+     * copy.
+     */
+    copy() {
+        // New config structure
+        const copy = new DittoConfig(this.databaseID, { ...this.connect }, this.persistenceDirectory);
+        return copy;
+    }
+    /** @internal */
+    toCBOR() {
+        try {
+            const ffiConfig = toFFICBORData(this);
+            // Logger.info(
+            //   `Converting DittoConfig to CBOR: ${JSON.stringify(ffiConfig, null, 2)}`,
+            // );
+            return CBOR.encode(ffiConfig);
+        }
+        catch (error) {
+            throw new DittoError('validation/invalid-ditto-config', `Failed to convert DittoConfig to CBOR: ${error.message}`);
+        }
+    }
+    /**
+     * Validates the config structure.
+     *
+     * Only covers type and presence validation as anything beyond that is handled
+     * by core.
+     */
+    validate() {
+        if (!this.databaseID) {
+            throw new DittoError('validation/invalid-ditto-config', '`id` must be provided for DittoConfig.');
+        }
+        if (typeof this.databaseID !== 'string') {
+            throw new DittoError('validation/invalid-ditto-config', `\`id\` must be of type string, but is of type '${typeof this.databaseID}': ${this.databaseID}`);
+        }
+        if (!this.connect) {
+            throw new DittoError('validation/invalid-ditto-config', '`connect` must be provided for DittoConfig.');
+        }
+        if (typeof this.connect !== 'object') {
+            throw new DittoError('validation/invalid-ditto-config', `\`connect\` must be an object, but is of type '${typeof this.connect}'.`);
+        }
+    }
+}
+/**
+ * Converts a {@link DittoConfig} into a plain JS object that conforms to the
+ * expected shape used in FFI.
+ *
+ * @internal
+ */
+function toFFICBORData(config) {
+    var _a;
+    let connectFFI;
+    if (config.connect.type === 'server') {
+        connectFFI = {
+            type: 'server',
+            url: config.connect.url,
+        };
+    }
+    else if (config.connect.type === 'smallPeersOnly') {
+        connectFFI = {
+            type: 'small_peers_only',
+        };
+        if (config.connect.privateKey)
+            connectFFI.private_key = config.connect.privateKey;
+    }
+    else {
+        throw new DittoError('validation/invalid-ditto-config', `Unsupported connect type: ${config.connect.type}`);
+    }
+    const ffiConfig = {
+        database_id: config.databaseID,
+        connect: connectFFI,
+        persistence_directory: (_a = config.persistenceDirectory) !== null && _a !== void 0 ? _a : null, // MUST not be undefined
+        experimental: {}, // Currently no experimental features in JS SDK
+    };
+    return ffiConfig;
+}
+/**
+ * Converts a FFI {@link DittoConfig} into a {@link DittoConfig} instance.
+ *
+ * @internal
+ */
+function fromFFICBORData(data) {
+    let connect;
+    if (data.connect.type === 'server') {
+        connect = {
+            type: 'server',
+            url: data.connect.url,
+        };
+    }
+    else {
+        connect = {
+            type: 'smallPeersOnly',
+        };
+        if (data.connect.private_key)
+            connect.privateKey = data.connect.private_key;
+    }
+    return new DittoConfig(data.database_id, connect, data.persistence_directory);
+}
+
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+/**
+ * Restore a `TransportConfig` from its serializable representation.
+ *
+ * @internal
+ */
+function transportConfigFromDeserializable(serialized) {
+    const peerToPeerJSON = serialized['peer_to_peer'];
+    const bluetoothLEJSON = peerToPeerJSON['bluetooth_le'];
+    const bluetoothLEEnabled = bluetoothLEJSON['enabled'];
+    const awdlJSON = peerToPeerJSON['awdl'];
+    const awdlEnabled = awdlJSON['enabled'];
+    const lanJSON = peerToPeerJSON['lan'];
+    const lanEnabled = lanJSON['enabled'];
+    const lanMdnsEnabled = lanJSON['mdns_enabled'];
+    const lanMulticastEnabled = lanJSON['multicast_enabled'];
+    const wifiAwareJSON = peerToPeerJSON['wifi_aware'];
+    const wifiAwareEnabled = wifiAwareJSON['enabled'];
+    const connectJSON = serialized['connect'];
+    const connectTcpServers = connectJSON['tcp_servers'];
     const connectWebsocketURLs = connectJSON['websocket_urls'];
     const connectRetryInterval = connectJSON['retry_interval'];
     const listenJSON = serialized['listen'];
@@ -6082,6 +6774,7 @@ function transportConfigFromDeserializable(serialized) {
     config.peerToPeer.lan.isEnabled = lanEnabled;
     config.peerToPeer.lan.isMdnsEnabled = lanMdnsEnabled;
     config.peerToPeer.lan.isMulticastEnabled = lanMulticastEnabled;
+    config.peerToPeer.wifiAware.isEnabled = wifiAwareEnabled;
     config.connect.tcpServers = connectTcpServers;
     config.connect.websocketURLs = connectWebsocketURLs;
     config.connect.retryInterval = connectRetryInterval;
@@ -6120,6 +6813,9 @@ function transportConfigToSerializable(config) {
             awdl: {
                 enabled: peerToPeer.awdl.isEnabled,
             },
+            wifi_aware: {
+                enabled: peerToPeer.wifiAware.isEnabled,
+            },
             lan: {
                 enabled: peerToPeer.lan.isEnabled,
                 mdns_enabled: peerToPeer.lan.isMdnsEnabled,
@@ -6168,13 +6864,18 @@ const NO_PREFERRED_ROUTE_HINT = 0;
  * 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`.
+ * available transports are enabled (for example, regarding peer-to-peer transports,
+ * Bluetooth LE and LAN on every platform, plus AWDL on Apple platforms or
+ * Wi‑Fi Aware on Android). You can customize this by copying that or
+ * initializing a new `TransportConfig`, adjusting its properties, and supplying
+ * it to `setTransportConfig()` on `Ditto`.
  *
  * When you initialize a new `TransportConfig` instance, all  transports are
  * disabled. You must enable each one explicitly.
  *
+ * Platform‑supported transports can also be toggled in a single call with
+ * {@link setAvailablePeerToPeerEnabled | setAvailablePeerToPeerEnabled()}.
+ *
  * Peer-to-peer transports will automatically discover peers in the vicinity
  * and create connections without any configuration. These are configured via
  * the `peerToPeer` property. To turn each one on, set its `isEnabled` property
@@ -6201,6 +6902,7 @@ class TransportConfig {
             bluetoothLE: { isEnabled: false },
             awdl: { isEnabled: false },
             lan: { isEnabled: false, isMdnsEnabled: true, isMulticastEnabled: true },
+            wifiAware: { isEnabled: false },
         };
         this.connect = {
             tcpServers: [],
@@ -6226,12 +6928,36 @@ class TransportConfig {
         };
     }
     /**
-     * Enables all peer-to-peer transports. Throws if receiver is frozen.
+     * Enables or disables _every_ peer-to-peer transport protocols defined in
+     * {@link peerToPeer} regardless of whether the current platform
+     * can actually drive those transport implementations.
+     *
+     * Throws if receiver is frozen.
+     *
+     * @deprecated Use {@link setAvailablePeerToPeerEnabled | setAvailablePeerToPeerEnabled()}. instead.
      */
     setAllPeerToPeerEnabled(enabled) {
         this.peerToPeer.bluetoothLE.isEnabled = enabled;
         this.peerToPeer.lan.isEnabled = enabled;
         this.peerToPeer.awdl.isEnabled = enabled;
+        this.peerToPeer.wifiAware.isEnabled = enabled;
+    }
+    /**
+     * Enables or disables the peer-to-peer transport protocols defined in
+     * {@link TransportConfigPeerToPeer} that are supported on the current platform.
+     *
+     * You can check the list of available transports for each platform at
+     * https://ditto.com/link/sdk-latest-compatibility
+     */
+    setAvailablePeerToPeerEnabled(enabled) {
+        const isNodeMacOS = process.platform === 'darwin';
+        const isReactNative = isReactNativeBuild;
+        const isReactNativeiOS = isReactNative;
+        this.peerToPeer.bluetoothLE.isEnabled = enabled;
+        this.peerToPeer.lan.isEnabled = enabled;
+        this.peerToPeer.wifiAware.isEnabled = false;
+        this.peerToPeer.awdl.isEnabled =
+            isNodeMacOS || isReactNativeiOS ? enabled : false;
     }
     /**
      * Returns `true` if the transport configuration is frozen, otherwise
@@ -6250,6 +6976,7 @@ class TransportConfig {
         Object.freeze(this.peerToPeer.bluetoothLE);
         Object.freeze(this.peerToPeer.awdl);
         Object.freeze(this.peerToPeer.lan);
+        Object.freeze(this.peerToPeer.wifiAware);
         Object.freeze(this.peerToPeer);
         Object.freeze(this.connect.tcpServers);
         Object.freeze(this.connect.websocketURLs);
@@ -6258,6 +6985,7 @@ class TransportConfig {
         Object.freeze(this.listen.http);
         Object.freeze(this.listen);
         Object.freeze(this.global);
+        Object.freeze(this);
         return this;
     }
     /**
@@ -6272,6 +7000,7 @@ class TransportConfig {
         copy.peerToPeer.lan.isMdnsEnabled = this.peerToPeer.lan.isMdnsEnabled;
         copy.peerToPeer.lan.isMulticastEnabled =
             this.peerToPeer.lan.isMulticastEnabled;
+        copy.peerToPeer.wifiAware.isEnabled = this.peerToPeer.wifiAware.isEnabled;
         copy.connect.tcpServers = this.connect.tcpServers.slice();
         copy.connect.websocketURLs = this.connect.websocketURLs.slice();
         copy.connect.retryInterval = this.connect.retryInterval;
@@ -6517,31 +7246,43 @@ class AttachmentFetcher {
  * 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.
+ * 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.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class Subscription {
     /**
      * Returns `true` if subscription has been explicitly cancelled, `false`
      * otherwise.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get isCancelled() {
         return this._isCancelled;
     }
     /**
      * The name of the collection that the subscription is based on.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get collectionName() {
         return this.collection.name;
     }
     /**
      * Cancels a subscription and releases all associated resources.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     cancel() {
         if (!this.isCancelled) {
@@ -6568,6 +7309,9 @@ class Subscription {
         };
         this.manager = collection.store.ditto.subscriptionManager;
         this.manager.add(this);
+        Logger.warning(`Subscription is deprecated, use ditto.sync.registerSubscription() instead. ` +
+            `For more information see: ` +
+            `https://ditto.com/link/dql-legacy-to-dql-adoption`);
     }
 }
 
@@ -6580,22 +7324,29 @@ class Subscription {
  * mutations. All subsequent events are of type {@link LiveQueryEventUpdate}.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class LiveQueryEventInitial {
     constructor() {
         /**
-         * Whether or not this is the initial event being delivered. Always `true`
-         * for `LiveQueryEventInitial`.
+         * Whether or not this is the initial event being delivered. Always `true` for
+         * `LiveQueryEventInitial`.
+         *
+         * @deprecated Use DQL (Ditto Query Language) instead. For more information
+         * see: https://ditto.com/link/dql-legacy-to-dql-adoption
          */
         this.isInitial = true;
     }
     /**
      * Returns a hash that represents the set of matching documents.
      *
-     * @deprecated use {@link Document.hash | Document.hash()} instead.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     hash(documents) {
-        Logger.warning('LiveQueryEventInitial.hash() is deprecated, use Document.hash() instead');
+        Logger.warning('Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption');
         const documentHandles = Bridge.document.handlesFor(documents);
         return documentsHash(documentHandles.deref());
     }
@@ -6603,10 +7354,11 @@ class LiveQueryEventInitial {
      * 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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     hashMnemonic(documents) {
-        Logger.warning('LiveQueryEventInitial.hashMnemonic() is deprecated, use Document.hashMnemonic() instead');
+        Logger.warning('Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption');
         const documentHandles = Bridge.document.handlesFor(documents);
         return documentsHashMnemonic(documentHandles.deref());
     }
@@ -6617,13 +7369,17 @@ class LiveQueryEventInitial {
  * covered by a (live) query.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class LiveQueryEventUpdate {
     /**
      * 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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     hash(documents) {
         Logger.warning('LiveQueryEventUpdate.hash() is deprecated, use Document.hash() instead');
@@ -6635,7 +7391,8 @@ class LiveQueryEventUpdate {
      * represents the set of matching documents.
      *
      * @throws {Error} when called in a React Native environment.
-     * @deprecated use {@link Document.hashMnemonic | Document.hashMnemonic()} instead.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     hashMnemonic(documents) {
         Logger.warning('LiveQueryEventUpdate.hashMnemonic() is deprecated, use Document.hashMnemonic() instead');
@@ -6647,6 +7404,9 @@ class LiveQueryEventUpdate {
         /**
          * Whether or not this is the initial event being delivered. Always `false`
          * for `LiveQueryEventUpdate`.
+         *
+         * @deprecated Use DQL (Ditto Query Language) instead. For more information
+         * see: https://ditto.com/link/dql-legacy-to-dql-adoption
          */
         this.isInitial = false;
         this.oldDocuments = params.oldDocuments;
@@ -6660,6 +7420,9 @@ class LiveQueryEventUpdate {
 /**
  * Provides information about a live query event relating to a single document
  * live query.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class SingleDocumentLiveQueryEvent {
     /**
@@ -6676,7 +7439,8 @@ class SingleDocumentLiveQueryEvent {
      * 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.
+     * @deprecated use {@link Document.hashMnemonic | Document.hashMnemonic()}
+     * instead.
      */
     hashMnemonic(document) {
         Logger.warning('SingleDocumentLiveQueryEvent.hashMnemonic() is deprecated, use Document.hashMnemonic() instead');
@@ -6708,13 +7472,24 @@ class SingleDocumentLiveQueryEvent {
  * documents matching a query then you must call {@link stop | stop()}.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class LiveQuery {
-    /** The name of the collection that the live query is based on. */
+    /**
+     * The name of the collection that the live query is based on.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
+     */
     get collectionName() {
         return this.collection.name;
     }
-    /** Returns true if the receiver has been stopped. */
+    /**
+     * Returns true if the receiver has been stopped.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
+     */
     get isStopped() {
         return !this.liveQueryManager;
     }
@@ -6722,11 +7497,17 @@ class LiveQuery {
      * Stop the live query from delivering updates.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     stop() {
         if (!this.isStopped)
             this.liveQueryManager.stopLiveQuery(this);
     }
+    /**
+     * The ID of this live query.
+     * @internal
+     */
     get liveQueryID() {
         return this._liveQueryID;
     }
@@ -6744,6 +7525,9 @@ class LiveQuery {
         this.liveQueryManager = null;
         const collectionName = collection.name;
         const weakDitto = new WeakRef(collection.store.ditto);
+        Logger.warning(`LiveQuery is deprecated, use ditto.store.registerObserver() instead. ` +
+            `For more information see: ` +
+            `https://ditto.com/link/dql-legacy-to-dql-adoption`);
         let liveQueryID = undefined;
         const signalNext = async () => {
             const ditto = weakDitto.deref();
@@ -6817,6 +7601,9 @@ class LiveQuery {
  * Update and remove functionality is also exposed through this object.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class PendingCursorOperation extends BasePendingCursorOperation {
     sort(propertyPath, direction = 'ascending') {
@@ -6882,6 +7669,8 @@ class PendingCursorOperation extends BasePendingCursorOperation {
      * @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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     subscribe() {
         const subscription = new Subscription(this.collection, this.query, this.queryArgsCBOR, this.orderBys, this.currentLimit, this.currentOffset);
@@ -6891,11 +7680,11 @@ class PendingCursorOperation extends BasePendingCursorOperation {
     /**
      * 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.
+     * 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
@@ -6913,17 +7702,20 @@ class PendingCursorOperation extends BasePendingCursorOperation {
      *
      * @return A {@link LiveQuery} object that must be kept in scope for as long
      * as you want to keep receiving updates.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     observeLocal(handler) {
         return this._observe(handler, false);
     }
     /**
-     * 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.
+     * 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 `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.
      *
@@ -6936,14 +7728,15 @@ class PendingCursorOperation extends BasePendingCursorOperation {
      * 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.
+     * 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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     observeLocalWithNextSignal(handler) {
         return this._observe(handler, true);
@@ -6952,6 +7745,8 @@ class PendingCursorOperation extends BasePendingCursorOperation {
     /** @internal */
     constructor(query, queryArgs, collection) {
         super(query, queryArgs, collection);
+        Logger.warning(`Cursor operations are deprecated, use DQL (Ditto Query Language) instead. ` +
+            `See https://ditto.com/link/dql-legacy-to-dql-adoption`);
     }
     /** @internal */
     _observe(handler, waitForNextSignal) {
@@ -6995,6 +7790,8 @@ class PendingCursorOperation extends BasePendingCursorOperation {
  * {@link Collection.findByID | findByID()} call.
  *
  * Update and remove functionality is also exposed through this object.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class PendingIDSpecificOperation extends BasePendingIDSpecificOperation {
     async remove() {
@@ -7038,6 +7835,9 @@ class PendingIDSpecificOperation extends BasePendingIDSpecificOperation {
      *
      * @returns A {@link Subscription} object that must be kept in scope for as
      * long as you want to keep receiving updates for the document.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
+  
      */
     subscribe() {
         const subscription = new Subscription(this.collection, this.query, null, [], -1, 0);
@@ -7054,25 +7854,28 @@ class PendingIDSpecificOperation extends BasePendingIDSpecificOperation {
      * 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.
+     * 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.
+     * {@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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
+  
      */
     observeLocal(handler) {
         return this._observe(handler, false);
     }
     /**
      * 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.
+     * 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
@@ -7080,17 +7883,20 @@ class PendingIDSpecificOperation extends BasePendingIDSpecificOperation {
      * 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.
+     * 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.
+     * {@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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
+  
      */
     observeLocalWithNextSignal(handler) {
         return this._observe(handler, true);
@@ -7098,6 +7904,8 @@ class PendingIDSpecificOperation extends BasePendingIDSpecificOperation {
     /** @internal */
     constructor(documentID, collection) {
         super(documentID, collection);
+        Logger.warning(`Cursor operations are deprecated, use DQL (Ditto Query Language) instead. ` +
+            `See https://ditto.com/link/dql-legacy-to-dql-adoption`);
     }
     /** @internal */
     _observe(handler, waitForNextSignal) {
@@ -7162,6 +7970,8 @@ class PendingIDSpecificOperation extends BasePendingIDSpecificOperation {
  * object.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class Collection {
     /**
@@ -7180,16 +7990,21 @@ class Collection {
      * 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}
+     * section on {@link https://ditto.com/link/js-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.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     find(query, queryArgs) {
         return new PendingCursorOperation(query, queryArgs !== null && queryArgs !== void 0 ? queryArgs : null, this);
     }
+    /**
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
+     */
     findAll() {
         return this.find('true');
     }
@@ -7206,12 +8021,20 @@ class Collection {
      *
      * @param id The ID of the document to find.
      * @throws {Error} when called in a React Native environment.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     findByID(id) {
         const documentID = id instanceof DocumentID ? id : new DocumentID(id);
         return new PendingIDSpecificOperation(documentID, this);
     }
+    /**
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information see: https://ditto.com/link/dql-legacy-to-dql-adoption
+     */
     async upsert(value, options = {}) {
+        Logger.warning(`Collection.upsert() is deprecated, use ditto.store.execute() instead. ` +
+            `For more information see: ` +
+            `https://ditto.com/link/dql-legacy-to-dql-adoption`);
         return this.store.ditto.deferCloseAsync(async (dittoHandle) => {
             var _a;
             const writeStrategy = (_a = options.writeStrategy) !== null && _a !== void 0 ? _a : 'merge';
@@ -7351,12 +8174,51 @@ class QueryResult {
      * this method once and keep the return value for as long as needed.
      *
      * @returns an array of document IDs
+     * @deprecated Use mutatedDocumentIDsV2() instead. This method will be removed
+     * in a future version.
      */
     mutatedDocumentIDs() {
         const queryResultHandle = Bridge.queryResult.handleFor(this);
         const affectedCBORIDs = queryResultMutatedDocumentIDs(queryResultHandle.deref());
         return affectedCBORIDs.map((id) => new DocumentID(id, true));
     }
+    /**
+     * IDs of documents that were mutated _locally_ by a _mutating_ DQL query
+     * passed to {@link Store.execute | `execute()`}. Empty array if no documents
+     * have been mutated.
+     *
+     * **Note: Query results received from a {@link StoreObserver} never contain
+     * mutated document IDs because a store observer is always registered using a
+     * non-mutating `SELECT` query.
+     *
+     * **Important:** The returned document IDs are not cached, make sure to call
+     * this method once and keep the return value for as long as needed.
+     *
+     * @returns an array of document ID values as JSON-compatible values
+     */
+    mutatedDocumentIDsV2() {
+        const queryResultHandle = Bridge.queryResult.handleFor(this);
+        const affectedCBORIDs = queryResultMutatedDocumentIDs(queryResultHandle.deref());
+        return affectedCBORIDs.map((cborID) => CBOR.decode(cborID));
+    }
+    /**
+     * The commit ID associated with this query result, if any.
+     *
+     * This ID uniquely identifies the commit in which this change was accepted
+     * into the _local_ store. The commit ID is available for all query results
+     * involving insertions, updates, or deletions. This ID can be used to track
+     * whether a local change has been synced to other peers.
+     *
+     * For write transactions, the commit ID is only available after the
+     * transaction has been successfully committed. Queries executed within an
+     * uncommitted transaction will not have a commit ID.
+     */
+    get commitID() {
+        const queryResultHandle = Bridge.queryResult.handleFor(this);
+        if (queryResultHasCommitID(queryResultHandle.deref()))
+            return queryResultCommitID(queryResultHandle.deref());
+        return null;
+    }
     // ----------------------------------------------------- Internal ------------
     /** @internal */
     constructor(queryResultPointer) {
@@ -7486,6 +8348,9 @@ class StoreObserver {
  * or moved since the last event.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more details and
+ * guidance, visit: https://ditto.com/link/dql.
  */
 class CollectionsEvent {
     /** @internal */
@@ -7535,6 +8400,9 @@ class CollectionsEvent {
  * like to receive updates from them about the collections that they know about.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class PendingCollectionsOperation {
     /**
@@ -7550,6 +8418,8 @@ class PendingCollectionsOperation {
      *
      * @return A {@link PendingCollectionsOperation} that you can chain further
      * function calls to.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     sort(propertyPath, direction = 'ascending') {
         // The return value is ignored here because we don't want to await the
@@ -7572,6 +8442,8 @@ class PendingCollectionsOperation {
      *
      * @return A {@link PendingCollectionsOperation} that you can chain further
      * function calls to.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     offset(offset) {
         // The return value is ignored here because we don't want to await the
@@ -7588,6 +8460,8 @@ class PendingCollectionsOperation {
      *
      * @return A {@link PendingCollectionsOperation} that you can chain further
      * function calls to.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     limit(limit) {
         // The return value is ignored here because we don't want to await the
@@ -7607,6 +8481,8 @@ class PendingCollectionsOperation {
      * @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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     subscribe() {
         return this.pendingCursorOperation.subscribe();
@@ -7619,8 +8495,8 @@ class PendingCollectionsOperation {
      * 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
+     * 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
@@ -7630,6 +8506,8 @@ class PendingCollectionsOperation {
      *
      * @return A {@link LiveQuery} object that must be kept in scope for as long
      * as you want to keep receiving updates.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     observeLocal(handler) {
         return this._observe(handler, false);
@@ -7642,8 +8520,8 @@ class PendingCollectionsOperation {
      * 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
+     * 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
@@ -7653,6 +8531,8 @@ class PendingCollectionsOperation {
      *
      * @return A {@link LiveQuery} object that must be kept in scope for as long
      * as you want to keep receiving updates.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     observeLocalWithNextSignal(handler) {
         return this._observe(handler, true);
@@ -7665,6 +8545,8 @@ class PendingCollectionsOperation {
      *
      * @return A list of {@link Collection}s based on the preceding function
      * chaining.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     async exec() {
         const documents = await this.pendingCursorOperation.exec();
@@ -7743,6 +8625,9 @@ function collectionsFromDocuments(documents, store) {
  * Live queries and subscriptions are only available outside of transactions.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class WriteTransactionPendingCursorOperation extends BasePendingCursorOperation {
     sort(propertyPath, direction = 'ascending') {
@@ -7805,6 +8690,10 @@ class WriteTransactionPendingCursorOperation extends BasePendingCursorOperation
 //
 // Copyright © 2023 DittoLive Incorporated. All rights reserved.
 //
+/**
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
+ */
 class WriteTransactionPendingIDSpecificOperation extends BasePendingIDSpecificOperation {
     async remove() {
         const ditto = this.collection.store.ditto;
@@ -7876,6 +8765,9 @@ class WriteTransactionPendingIDSpecificOperation extends BasePendingIDSpecificOp
  * and using its `scoped` method.
  *
  * Not available in React Native environments.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class WriteTransactionCollection {
     /**
@@ -7888,6 +8780,8 @@ class WriteTransactionCollection {
      * @param queryArgs These arguments replace placeholders in the provided
      * query.
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     find(query, queryArgs) {
         return new WriteTransactionPendingCursorOperation(query, queryArgs !== null && queryArgs !== void 0 ? queryArgs : null, this);
@@ -7897,6 +8791,8 @@ class WriteTransactionCollection {
      * the query `"true"`.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     findAll() {
         return this.find('true');
@@ -7905,10 +8801,13 @@ class WriteTransactionCollection {
      * 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.
+     * 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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     findByID(id) {
         const documentID = id instanceof DocumentID ? id : new DocumentID(id);
@@ -7956,6 +8855,9 @@ class WriteTransactionCollection {
  * Perform writes in a transaction.
  *
  * Create a write transaction using {@link Store.write | ditto.store.write}.
+ *
+ * @deprecated Use DQL (Ditto Query Language) instead. For more information see:
+ * https://ditto.com/link/dql-legacy-to-dql-adoption
  */
 class WriteTransaction {
     /**
@@ -7967,6 +8869,8 @@ class WriteTransaction {
      * {@link WriteTransaction} object.
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      * */
     scoped(toCollectionNamed) {
         if (typeof toCollectionNamed !== 'string')
@@ -8042,7 +8946,7 @@ class TransactionInfo {
  * 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).
+ * [Ditto documentation](https://ditto.com/link/sdk-latest-crud-transactions).
  */
 class Transaction {
     constructor(store) {
@@ -8221,16 +9125,18 @@ class Store {
         return 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:
+     * 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.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     collection(name) {
         return new Collection(name, this);
@@ -8243,15 +9149,19 @@ class Store {
      * fetch or observe the collections in the store
      *
      * @throws {Error} when called in a React Native environment.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     collections() {
         return new PendingCollectionsOperation(this);
     }
     /**
-     * Returns the names of all available collections in the store of the
-     * related {@link Ditto} instance.
+     * 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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     collectionNames() {
         return this.ditto.deferClose((dittoHandle) => {
@@ -8280,13 +9190,22 @@ class Store {
     /**
      * Initiate a write transaction in a callback.
      *
-     * Allows you to group multiple operations together that affect multiple documents, potentially across multiple collections.
+     * 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.
+     * @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.
+     * @returns a list of `WriteTransactionResult`s. There is a result for each
+     * operation performed as part of the write transaction.
+     *
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     async write(callback) {
+        Logger.warning(`ditto.store.write() is deprecated, use ditto.store.transaction() instead. ` +
+            `See https://ditto.com/link/dql-legacy-to-dql-adoption`);
         // Run caller's callback, rolling back if needed.
         return this.ditto.deferCloseAsync(async () => {
             const transaction = await WriteTransaction.init(this.ditto);
@@ -8577,7 +9496,7 @@ class Store {
      * 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).
+     * documentation](https://ditto.com/link/sdk-latest-crud-transactions).
      *
      * Transactions are initiated as read-write by default, and only one
      * read-write transaction can be executed at any given time. Any other
@@ -8710,9 +9629,12 @@ class Store {
 //
 // -----------------------------------------------------------------------------
 /**
- * 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.
+ * 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.
+ *
+ * @deprecated Use `peerKeyString` to identify a peer. It is accessible via
+ * {@link Peer}, {@link Connection}, and {@link ConnectionRequest}.
  */
 function addressToString(address) {
     return `${address.siteId}-${address.pubkey}`;
@@ -9165,6 +10087,9 @@ class TransportConditionsManager extends ObserverManager {
             case 'Mdns':
                 apiConditionSource = 'MDNS';
                 break;
+            case 'WiFiAware':
+                apiConditionSource = 'WiFiAware';
+                break;
         }
         /* eslint-enable */
         /* eslint-disable */
@@ -9283,6 +10208,54 @@ class SyncSubscription {
  * Access this object via {@link Ditto.sync | Ditto.sync} on any Ditto instance.
  */
 class Sync {
+    /**
+     * Returns `true` if sync is active, otherwise returns `false`. Use
+     * {@link Sync.start | ditto.sync.start()} to activate and
+     * {@link Sync.stop | ditto.sync.stop()} to deactivate sync.
+     */
+    get isActive() {
+        return this.ditto.isSyncActive;
+    }
+    /**
+     * Starts the network transports. Ditto will connect to other devices.
+     *
+     * By default Ditto will enable all peer-to-peer transport types. On **Node**,
+     * this means BluetoothLE, WiFi/LAN, and AWDL. On the **Web**, only connecting
+     * via  Websockets is supported. The default network configuration can be
+     * modified with {@link Ditto.updateTransportConfig | updateTransportConfig()}
+     * or replaced with {@link Ditto.setTransportConfig | setTransportConfig()}.
+     *
+     * Performance of initial sync when bootstrapping new peers can be improved by
+     * calling {@link Ditto.disableSyncWithV3 | disableSyncWithV3()} before
+     * {@link start | start()}. 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 Sync.isActive | ditto.sync.isActive}
+     * @see {@link Sync.stop | ditto.sync.stop()}
+     */
+    start() {
+        this.ditto.startSync();
+    }
+    /**
+     * Stops all network transports.
+     *
+     * You may continue to use the Ditto store locally but no data will sync to or
+     * from other devices.
+     *
+     * @see {@link Sync.isActive | ditto.sync.isActive}
+     * @see {@link Sync.start | ditto.sync.start()}
+     */
+    stop() {
+        this.ditto.stopSync();
+    }
     /**
      * Installs and returns a sync subscription for a query, configuring Ditto to
      * receive updates from other peers for documents matching that query. The
@@ -9667,6 +10640,8 @@ class SmallPeerInfo {
      * `BigPeerOnly` to replicate collected info to the Big Peer.
      *
      * @throws when set to a value other than `BigPeerOnly` or `LocalPeerOnly`.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     get syncScope() {
         return this.ditto.deferClose((dittoHandle) => {
@@ -9679,13 +10654,13 @@ class SmallPeerInfo {
         });
     }
     /**
-     * Determines which "kind" of peers the small peer info will be
-     * replicated to.
+     * 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.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     async getSyncScope() {
         return this.ditto.deferClose((dittoHandle) => {
@@ -9699,7 +10674,8 @@ class SmallPeerInfo {
      *
      * @param syncScope the new sync scope.
      * @throws when set to a value other than `BigPeerOnly` or `LocalPeerOnly`.
-     * @deprecated use {@link SmallPeerInfo.syncScope} instead.
+     * @deprecated Use DQL (Ditto Query Language) instead. For more information
+     * see: https://ditto.com/link/dql-legacy-to-dql-adoption
      */
     async setSyncScope(syncScope) {
         return this.ditto.deferClose((dittoHandle) => {
@@ -9712,13 +10688,251 @@ class SmallPeerInfo {
     }
 }
 
+//
+// Copyright © 2025 DittoLive Incorporated. All rights reserved.
+//
+const AUTH_HANDLER_NOOP = {
+    authenticationRequired(_authenticator) { },
+    authenticationExpiringSoon(_authenticator, _secondsRemaining) { },
+    authenticationStatusDidChange(_authenticator) { },
+};
+/**
+ * The name of the directory, relative to the current working directory, that
+ * will be used for persistence if no other directory is specified.
+ *
+ * @internal
+ * @deprecated The new Ditto configuration APIs define the default in core
+ */
+const DEFAULT_PERSISTENCE_DIRECTORY = 'ditto';
+/**
+ * @internal
+ */
+class ConfigOrParameters {
+    get isConfig() {
+        return this._config !== undefined;
+    }
+    get isParameters() {
+        return this._parameters !== undefined;
+    }
+    get kind() {
+        if (this.isConfig && !this.isParameters) {
+            return 'config';
+        }
+        else if (this.isParameters && !this.isConfig) {
+            return 'parameters';
+        }
+        else {
+            throw new DittoError('internal', 'ConfigOrParameters is neither a config nor parameters');
+        }
+    }
+    get config() {
+        switch (this.kind) {
+            case 'config':
+                return this._config;
+            case 'parameters':
+                const identity = this._parameters.identity;
+                switch (identity.type) {
+                    case 'onlineWithAuthentication':
+                    case 'onlinePlayground':
+                        return new DittoConfig(identity.appID, {
+                            type: 'server',
+                            url: this.urlFrom(identity.customAuthURL, identity.appID),
+                        }, this._parameters.persistenceDirectory);
+                    case 'sharedKey':
+                        return new DittoConfig(identity.appID, {
+                            type: 'smallPeersOnly',
+                            privateKey: identity.sharedKey,
+                        }, this._parameters.persistenceDirectory);
+                    case 'offlinePlayground':
+                        return new DittoConfig(identity.appID, {
+                            type: 'smallPeersOnly',
+                        }, this._parameters.persistenceDirectory);
+                    case 'manual':
+                        Logger.warning("Can't create a `DittoConfig` from a `manual` " +
+                            ' identity, manual identities are being phased out and ' +
+                            'not supported with the `DittoConfig`-based APIs anymore. ' +
+                            "Mapping onto `{ type: 'smallPeersOnly' }`.");
+                        return new DittoConfig(DittoConfig.DEFAULT_DATABASE_ID, {
+                            type: 'smallPeersOnly',
+                        }, this._parameters.persistenceDirectory);
+                }
+        }
+    }
+    get identity() {
+        switch (this.kind) {
+            case 'parameters':
+                return this._parameters.identity;
+            case 'config':
+                const { databaseID: id, connect } = this._config;
+                switch (connect.type) {
+                    case 'server':
+                        return {
+                            type: 'onlineWithAuthentication',
+                            appID: id,
+                            authHandler: AUTH_HANDLER_NOOP,
+                            enableDittoCloudSync: false,
+                            customAuthURL: connect.url,
+                        };
+                    case 'smallPeersOnly':
+                        if (connect.privateKey) {
+                            return {
+                                type: 'sharedKey',
+                                appID: id,
+                                sharedKey: connect.privateKey,
+                            };
+                        }
+                        else {
+                            return {
+                                type: 'offlinePlayground',
+                                appID: id,
+                            };
+                        }
+                }
+        }
+    }
+    get persistenceDirectory() {
+        switch (this.kind) {
+            case 'parameters':
+                return this._parameters.persistenceDirectory;
+            case 'config':
+                return this._config.persistenceDirectory;
+        }
+    }
+    constructor(identityOrConfig, persistenceDirectory) {
+        // Not supported by the JS SDK
+        this.passphrase = null;
+        this.historyTrackingEnabled = false;
+        if (identityOrConfig instanceof DittoConfig) {
+            this._config = identityOrConfig;
+            this._parameters = undefined;
+        }
+        else {
+            const persistenceDirectoryValidated = this.validatePersistenceDirectory(persistenceDirectory);
+            this.validateIdentity(identityOrConfig);
+            this._parameters = {
+                identity: identityOrConfig,
+                persistenceDirectory: persistenceDirectoryValidated,
+            };
+            this._config = undefined;
+        }
+    }
+    /**
+     * Returns a copy having sensitive data replaced with a placeholder
+     */
+    redactingSensitiveData() {
+        switch (this.kind) {
+            case 'config':
+                const configCopy = this._config.copy();
+                if (configCopy.connect.type === 'smallPeersOnly' &&
+                    configCopy.connect.privateKey != null)
+                    configCopy.connect.privateKey = '[REDACTED]';
+                return new ConfigOrParameters(configCopy);
+            case 'parameters':
+                const identityCopy = { ...this._parameters.identity };
+                if (identityCopy.type === 'sharedKey')
+                    identityCopy.sharedKey = '[REDACTED]';
+                return new ConfigOrParameters(identityCopy, this._parameters.persistenceDirectory);
+        }
+    }
+    validateIdentity(identity) {
+        var _a, _b;
+        if (!identity || typeof identity !== 'object') {
+            throw new TypeError('Expected `identity` to be an object, but got: ' + typeof identity);
+        }
+        const validIdentity = { ...identity };
+        // @ts-expect-error we validate the existence of the value below.
+        const appID = identity.appID;
+        if (![
+            'offlinePlayground',
+            'sharedKey',
+            'manual',
+            'onlinePlayground',
+            'onlineWithAuthentication',
+        ].includes(identity.type))
+            throw new Error(`Unknown identity type: ${identity.type}`);
+        if ((identity.type === 'offlinePlayground' ||
+            identity.type === 'sharedKey' ||
+            identity.type === 'onlinePlayground' ||
+            identity.type === 'onlineWithAuthentication') &&
+            typeof appID === 'undefined')
+            throw new Error(`Property .appID must be given for identity, but isn't.`);
+        if (typeof appID !== 'undefined' && typeof appID !== 'string') {
+            throw new Error(`Property .appID must be be of type string, but is of type '${typeof appID}': ${appID}`);
+        }
+        if ((identity.type === 'offlinePlayground' ||
+            identity.type === 'sharedKey') &&
+            typeof identity.siteID !== 'undefined') {
+            const siteID = identity.siteID;
+            const isSiteIDNumberOrBigInt = typeof siteID === 'number' || typeof siteID === 'bigint';
+            if (!isSiteIDNumberOrBigInt)
+                throw new Error('siteID must be a number or BigInt');
+            if (siteID < 0)
+                throw new Error('siteID must be >= 0');
+            if (siteID > BigInt('0xffffffffffffffff'))
+                throw new Error('siteID must be < 2^64');
+        }
+        if (identity.type === 'offlinePlayground') {
+            if (typeof identity.siteID !== 'undefined') {
+                Logger.warning(`Property .siteID is deprecated and should no longer be specified in an offline playground identity.`);
+            }
+        }
+        if (identity.type === 'sharedKey') {
+            if (typeof identity.siteID !== 'undefined') {
+                Logger.warning(`Property .siteID is deprecated and should no longer be specified in a shared key identity.`);
+            }
+            // No validations of the remainder of the properties yet.
+        }
+        if (identity.type === 'manual') ;
+        if (identity.type === 'onlinePlayground') {
+            const token = identity.token;
+            if (typeof token === 'undefined') {
+                throw new Error(`Property .token must be given for identity but isn't. You can find the corresponding token on the Ditto Portal.`);
+            }
+            if (typeof token !== 'undefined' && typeof token !== 'string') {
+                throw new Error(`Property .token of identity must be be of type string, but is of type '${typeof token}': ${token}`);
+            }
+        }
+        if (identity.type === 'onlineWithAuthentication') {
+            const authHandlerType = typeof identity.authHandler;
+            if (authHandlerType !== 'object') {
+                throw new TypeError(`Property .authHandler on identity of type onlineWithAuthentication must be an object, but is of type '${authHandlerType}'.`);
+            }
+            const expiringSoonType = typeof ((_a = identity.authHandler) === null || _a === void 0 ? void 0 : _a.authenticationExpiringSoon);
+            const authenticationRequiredType = typeof ((_b = identity.authHandler) === null || _b === void 0 ? void 0 : _b.authenticationRequired);
+            if (expiringSoonType !== 'function') {
+                throw new TypeError(`Property .authHandler.authenticationExpiringSoon on identity of type onlineWithAuthentication must be a function, but is of type '${expiringSoonType}'.`);
+            }
+            if (authenticationRequiredType !== 'function') {
+                throw new TypeError(`Property .authHandler.authenticationRequired on identity of type onlineWithAuthentication must be a function, but is of type '${authenticationRequiredType}'.`);
+            }
+        }
+        return validIdentity;
+    }
+    /**
+     * Returns the default persistence directory if the given path is null and
+     * throws an error if the given path is empty or contains only whitespace.
+     *
+     * @deprecated this is only used by the legacy `DittoConfig` constructor.
+     */
+    validatePersistenceDirectory(persistenceDirectory) {
+        if (persistenceDirectory == null)
+            return DEFAULT_PERSISTENCE_DIRECTORY;
+        if (persistenceDirectory.trim().length === 0) {
+            throw new Error(`Invalid persistenceDirectory: '${persistenceDirectory}'`);
+        }
+        return persistenceDirectory;
+    }
+    urlFrom(customAuthURL, appID) {
+        if (customAuthURL != null)
+            return customAuthURL;
+        return `https://${appID}.cloud.ditto.live`;
+    }
+}
+
 //
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
 //
 // -----------------------------------------------------------------------------
-// The name of the directory, relative to cwd, that will be used for persistence
-// if no other directory is specified.
-const DEFAULT_PERSISTENCE_DIRECTORY = 'ditto';
 /**
  * Ditto is the entry point for accessing Ditto-related functionality.
  */
@@ -9730,6 +10944,163 @@ class Ditto {
         // Requires having called FFI.initSDKVersion() first.
         return dittoGetSDKSemver();
     }
+    /**
+     * The default root directory used for Ditto data persistence.
+     *
+     * This property returns the platform-dependent directory where Ditto stores
+     * its data when a relative persistence directory path (or `null`) is
+     * provided.
+     *
+     * **Node.js**
+     *
+     * - On macOS, this is the `~/Library/Application Support/ditto` directory.
+     * - On Windows, this is the `~/AppData/Roaming/ditto` directory.
+     * - On Linux, this is the `~/.local/share/ditto` directory.
+     *
+     * Note that sandboxed environments, such as Electron apps running under
+     * Apple's App Sandbox, can require setting a
+     * {@link DittoConfig.persistenceDirectory | custom persistence directory} as
+     * these default directories may not be accessible.
+     *
+     * **React Native**
+     *
+     * - On iOS and macOS, this is the Application Support directory.
+     * - On Android, this is the app's internal files directory.
+     *
+     * **Browsers**
+     *
+     * In browsers, this returns an empty string as there is no file system
+     * access.
+     *
+     * @returns A string representing the default root directory.
+     * @throws {DittoError} `sdk/unsupported` if the current environment is not
+     * supported by Ditto.
+     * @see {@link DittoConfig.persistenceDirectory} for more information on
+     * configuring the persistence directory.
+     */
+    static get DEFAULT_ROOT_DIRECTORY() {
+        {
+            const { homedir } = require('os');
+            const path = require('path');
+            if (process.platform === 'darwin') {
+                return path.join(homedir(), 'Library', 'Application Support', 'ditto');
+            }
+            else if (process.platform === 'win32') {
+                return path.join(homedir(), 'AppData', 'Roaming', 'ditto');
+            }
+            else {
+                // Linux
+                return path.join(homedir(), '.local', 'share', 'ditto');
+            }
+        }
+    }
+    /**
+     * Asynchronously creates and returns a new `Ditto` instance using the
+     * provided configuration.
+     *
+     * This is the recommended way to initialize Ditto in async environments.
+     *
+     * This API is in **preview** and will become the standard way to initialize
+     * Ditto instances in v5, replacing the legacy
+     * {@link Ditto.constructor | Ditto constructor}.
+     *
+     * In Ditto 4.x, this method is only partially `async` and blocks for a
+     * significant portion of the initialization process. It will become fully
+     * `async` in Ditto 5.x.
+     *
+     * @param config - The configuration to initialize the new Ditto instance
+     *   with. Defaults to {@link DittoConfig.default}.
+     *
+     * @returns The newly created `Ditto` instance.
+     *
+     * @throws {@link DittoError} with code `persistenceDirectoryLocked` if the
+     *   chosen persistence directory is already in use by another Ditto instance.
+     *
+     * @throws {@link DittoError} with code `invalidDittoConfig` if the passed in
+     *   `DittoConfig`'s contents do not meet the required validation criteria.
+     *   For detailed information on the validation requirements, consult the
+     *   documentation of the individual properties of `DittoConfig`.
+     *
+     * @throws May throw other {@link DittoError}s for other initialization
+     * failures.
+     *
+     * @see {@link openSync | Ditto.openSync()} for a blocking, non-async
+     * alternative.
+     */
+    static async open(config = DittoConfig.default) {
+        if (!(config instanceof DittoConfig)) {
+            throw new TypeError(`Ditto.open() expects a DittoConfig, but got ${typeof config}`);
+        }
+        if (typeof config.connect !== 'object') {
+            throw new TypeError(`Ditto.open() expects a DittoConfig with a \`connect\` property, but got ${typeof config.connect}`);
+        }
+        if (!Ditto.isEnvironmentSupported()) {
+            throw new Error('Ditto does not support this JavaScript environment. Please consult ' +
+                'the Ditto JavaScript documentation for a list of supported ' +
+                'environments and browsers. You can use ' +
+                '`Ditto.isEnvironmentSupported()` to run this check anytime.');
+        }
+        // FIXME: Failures in error reporting in the async open method
+        //
+        // const dittoPointer = await mapFFIErrorsAsync(async () =>
+        //   FFI.dittoOpenAsyncThrows(
+        //     config.toCBOR(),
+        //     'PlatformDependent',
+        //     Ditto.DEFAULT_ROOT_DIRECTORY,
+        //   ),
+        // );
+        const dittoPointer = mapFFIErrors(() => dittoOpenThrows(config.toCBOR(), 'PlatformDependent', Ditto.DEFAULT_ROOT_DIRECTORY));
+        // We are passing undocumented parameters to the constructor
+        // @ts-expect-error ts(2554)
+        return new Ditto(null, null, config, dittoPointer);
+    }
+    /**
+     * Synchronously creates and returns a new `Ditto` instance using the provided
+     * configuration.
+     *
+     * This is a blocking convenience method for initializing Ditto, intended for
+     * use in non-async environments.
+     *
+     * This API is in **preview** and will become the standard way to initialize
+     * Ditto instances in v5, replacing the legacy
+     * {@link Ditto.constructor | Ditto constructor}.
+     *
+     * @param config - The configuration to initialize the new Ditto instance
+     *   with. Defaults to {@link DittoConfig.default}.
+     *
+     * @returns The newly created `Ditto` instance.
+     *
+     * @throws {@link DittoError} with code `persistenceDirectoryLocked` if the
+     *   chosen persistence directory is already in use by another Ditto instance.
+     *
+     * @throws {@link DittoError} with code `invalidDittoConfig` if the passed in
+     *   `DittoConfig`'s contents do not meet the required validation criteria.
+     *   For detailed information on the validation requirements, consult the
+     *   documentation of the individual properties of `DittoConfig`.
+     *
+     * @throws May throw other {@link DittoError}s for other initialization
+     * failures.
+     *
+     * @see {@link open | Ditto.open()} for an async alternative.
+     */
+    static openSync(config = DittoConfig.default) {
+        if (!(config instanceof DittoConfig)) {
+            throw new TypeError(`Ditto.openSync() expects a DittoConfig, but got ${typeof config}`);
+        }
+        if (typeof config.connect !== 'object') {
+            throw new TypeError(`Ditto.open() expects a DittoConfig with a \`connect\` property, but got ${typeof config.connect}`);
+        }
+        if (!Ditto.isEnvironmentSupported()) {
+            throw new Error('Ditto does not support this JavaScript environment. Please consult ' +
+                'the Ditto JavaScript documentation for a list of supported ' +
+                'environments and browsers. You can use ' +
+                '`Ditto.isEnvironmentSupported()` to run this check anytime.');
+        }
+        const dittoPointer = mapFFIErrors(() => dittoOpenThrows(config.toCBOR(), 'PlatformDependent', Ditto.DEFAULT_ROOT_DIRECTORY));
+        // We are passing undocumented parameters to the constructor
+        // @ts-expect-error ts(2554)
+        return new Ditto(null, null, config, dittoPointer);
+    }
     /**
      * Configure a custom identifier for this peer.
      *
@@ -9751,12 +11122,29 @@ class Ditto {
         }
         this._deviceName = value;
     }
-    /** Returns a string identifying the version of the Ditto SDK. */
+    /**
+     * Returns a string identifying the version of the Ditto SDK. *
+     *
+     * @deprecated This property is deprecated, use {@link Ditto.VERSION} instead.
+     */
     get sdkVersion() {
         return this.deferClose((dittoHandle) => {
             return dittoGetSDKVersion(dittoHandle.deref());
         });
     }
+    /**
+     * The (validated) identity this Ditto instance was initialized with.
+     *
+     * **Phased out in 4.x.** This API will be replaced by {@link DittoConfig} in
+     * v5.
+     */
+    get identity() {
+        if (this.configOrParameters.isConfig) {
+            Logger.warning('Accessing legacy `identity` property on a Ditto instance initialized ' +
+                'with the new DittoConfig API. The mapping may not be exact.');
+        }
+        return this.configOrParameters.identity;
+    }
     /**
      * The path this Ditto instance was initialized with, if no path was given at
      * construction time, the default value is returned (see constructor).
@@ -9765,9 +11153,80 @@ class Ditto {
      * new 'Ditto.persistenceDirectory' property instead.
      */
     get path() {
-        Logger.warning("⚠️ Deprecation Warning: The 'Ditto.path' property is deprecated. Please update your code to use the new 'Ditto.persistenceDirectory' property instead.");
+        Logger.warning("'Ditto.path' is deprecated. Use 'Ditto.persistenceDirectory' instead.");
         return this.persistenceDirectory;
     }
+    /**
+     * The configuration used to initialize this `Ditto` instance.
+     *
+     * This API is in **preview** and provides a read-only property to access the
+     * configuration used during initialization of a `Ditto` instance in v5.
+     *
+     * Note: Sensitive data such as passphrases and private keys are redacted from
+     * the returned configuration and replaced with the string `[REDACTED]`.
+     *
+     * If this instance was initialized using the deprecated parameter-based APIs,
+     * the returned configuration will be an incomplete approximation, since there
+     * is no exact 1:1 mapping between the old parameters and the new
+     * {@link DittoConfig}. In this case, a warning will be logged.
+     *
+     * - Warning: Accessing this property on a `Ditto` instance created with the
+     *   deprecated parameter-based APIs may result in a partially filled
+     *   configuration. Prefer using the new `DittoConfig`-based initialization
+     *   methods {@link Ditto.open | Ditto.open()} and
+     *   {@link Ditto.openSync | Ditto.openSync()} whenever possible.
+     */
+    get config() {
+        if (this.configOrParameters.isParameters) {
+            Logger.warning(`Attempted to access property 'config' of a 'Ditto' ` +
+                `instance initialized using the deprecated parameter-based APIs. ` +
+                `Since there is no exact 1:1 mapping between the old parameters ` +
+                `and the new 'DittoConfig', the returned configuration will be an ` +
+                `incomplete approximation.`);
+        }
+        return this.configOrParameters.config;
+    }
+    /**
+     * The persistence directory used by Ditto to persist data, represented by an
+     * absolute path.
+     *
+     * It is not recommended to directly read or write to this directory as its
+     * structure and contents are managed by Ditto and may change in future
+     * versions.
+     *
+     * When {@link Logger} is enabled, logs may be written to this directory even
+     * after a Ditto instance was deallocated. Please refer to the documentation
+     * of {@link Logger} for more information.
+     *
+     * In browsers, this string acts as a namespace for the in-memory data store
+     * and does not correspond to a file system directory.
+     */
+    get absolutePersistenceDirectory() {
+        return this.deferClose((dittoHandle) => {
+            return dittoAbsolutePersistenceDirectory(dittoHandle.deref());
+        });
+    }
+    /**
+     * 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.
+     *
+     * @deprecated replaced by
+     * {@link Ditto.absolutePersistenceDirectory | absolutePersistenceDirectory},
+     * which guarantees an absolute path.
+     */
+    get persistenceDirectory() {
+        return this.configOrParameters.persistenceDirectory;
+    }
     /**
      * Returns `true` if an offline license token has been set, otherwise returns `false`.
      *
@@ -9790,6 +11249,8 @@ class Ditto {
      * Returns `true` if sync is active, otherwise returns `false`. Use
      * {@link startSync | startSync()} to activate and
      * {@link stopSync | stopSync()} to deactivate sync.
+     *
+     * @deprecated use {@link Sync.isActive | ditto.sync.isActive} instead.
      */
     get isSyncActive() {
         return this.deferClose((dittoHandle) => {
@@ -9803,12 +11264,17 @@ class Ditto {
      * using this to create a Ditto instance in the web browser will throw an
      * exception.
      *
+     * **Phased out in 4.x** — replaced by
+     * {@link Ditto.open | Ditto.open()} and
+     * {@link Ditto.openSync | Ditto.openSync()} factory methods. This API will be
+     * replaced by the new factory methods in v5.
+     *
      * @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.
+     * 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}
@@ -9816,81 +11282,83 @@ class Ditto {
      * @throws {Error} for other failures during initialization of Ditto and
      * validation of the provided identity.
      */
+    // NOTE: This constructor takes undocumented additional parameters so that the
+    // async part of making a new Ditto instance can be done in Ditto.open() and
+    // this constructor uses the outputs of that to set up the Ditto instance.
     constructor(identity, persistenceDirectory) {
-        var _a, _b;
+        var _a, _b, _c, _d, _e;
         // ------------------------------------------------------------ Private ------
         this.deferCloseAllowed = true;
         this._isClosed = false;
         /** Set of pending operations that need to complete before the Ditto instance can be closed in a safe manner. */
         this.pendingOperations = new Set();
         if (!Ditto.isEnvironmentSupported()) {
-            throw new Error('Ditto does not support this JavaScript environment. Please consult the Ditto JavaScript documentation for a list of supported environments and browsers. You can use `Ditto.isEnvironmentSupported()` to run this check anytime.');
+            throw new Error('Ditto does not support this JavaScript environment. Please consult ' +
+                'the Ditto JavaScript documentation for a list of supported ' +
+                'environments and browsers. You can use ' +
+                '`Ditto.isEnvironmentSupported()` to run this check anytime.');
+        }
+        let dittoPointer = null;
+        let configOrParameters;
+        // See `Ditto.open()` and `Ditto.openSync()` where this constructor is
+        // called with undocumented parameters:
+        // - DittoConfig instance
+        // - FFI.Pointer<FFI.FFIDitto>
+        if (arguments.length === 4 && arguments[2] instanceof DittoConfig) {
+            // the constructor was called from Ditto.open() or Ditto.openSync()
+            if (identity != null || persistenceDirectory != null) {
+                throw new DittoError('internal', 'identity and persistenceDirectory params must be null when constructing Ditto with DittoConfig');
+            }
+            configOrParameters = new ConfigOrParameters(arguments[2]);
+            dittoPointer = arguments[3];
         }
-        loggerInit();
-        this.persistenceDirectory =
-            Ditto.initPersistenceDirectory(persistenceDirectory);
-        const identityOrDefault = identity !== null && identity !== void 0 ? identity : {
-            type: 'offlinePlayground',
-            appID: '',
-        };
-        const validIdentity = Object.freeze(this.validateIdentity(identityOrDefault));
-        this.identity = Object.freeze(validIdentity);
-        // Check if device name stays the same on sdk and core levels (#10729).
-        {
-            const os = require('os');
-            this._deviceName = os.hostname();
+        else {
+            // the constructor was called directly
+            const identityOrDefault = identity !== null && identity !== void 0 ? identity : DEFAULT_IDENTITY;
+            configOrParameters = new ConfigOrParameters(identityOrDefault, persistenceDirectory);
+        }
+        this.configOrParameters = configOrParameters.redactingSensitiveData();
+        // Legacy Ditto initialization
+        if (dittoPointer == null) {
+            const identityConfig = makeIdentityConfig(configOrParameters.identity);
+            // History tracking is an experimental and deprecated feature that is not
+            // supported in the JS SDK.
+            const historyTracking = 'Disabled';
+            // The JS SDK, unlike (nearly all of) the other SDKs, expects its `TransportConfig`s to have
+            // certain transports enabled/disabled by default. Specifically, it expects this to be
+            // determined for P2P transports based on the environment. We specify this here by setting
+            // `transportConfigMode` to 'PlatformDependent'.
+            const transportConfigMode = 'PlatformDependent';
+            dittoPointer = mapFFIErrors(() => dittoTryNewBlocking(configOrParameters.persistenceDirectory, identityConfig, historyTracking, transportConfigMode));
         }
-        this.keepAlive = new KeepAlive();
-        // WORKAROUND: the login provider triggers the registered callback right
-        // when the auth client is being constructed. At this point, we don't have
-        // the auth client, which would be needed to perform a login, nor did we
-        // have a chance to create an authenticator. Therefore catch that first
-        // callback, store the seconds remaining and proceed with propagating
-        // it after all pieces are in place.
-        let secondsRemainingUntilAuthenticationExpires = null;
-        const weakThis = new WeakRef(this);
-        const identityConfig = (() => {
-            var _a, _b, _c;
-            if (validIdentity.type === 'offlinePlayground') {
-                return dittoIdentityConfigMakeOfflinePlayground(validIdentity.appID, (_a = validIdentity.siteID) !== null && _a !== void 0 ? _a : 0);
-            }
-            if (validIdentity.type === 'manual') {
-                return dittoIdentityConfigMakeManual(validIdentity.certificate);
-            }
-            if (validIdentity.type === 'sharedKey') {
-                return dittoIdentityConfigMakeSharedKey(validIdentity.appID, validIdentity.sharedKey, validIdentity.siteID);
-            }
-            if (validIdentity.type === 'onlinePlayground') {
-                const authURL = (_b = validIdentity.customAuthURL) !== null && _b !== void 0 ? _b : defaultAuthURL(validIdentity.appID);
-                return dittoIdentityConfigMakeOnlinePlayground(validIdentity.appID, validIdentity.token, authURL);
-            }
-            if (validIdentity.type === 'onlineWithAuthentication') {
-                const authURL = (_c = validIdentity.customAuthURL) !== null && _c !== void 0 ? _c : defaultAuthURL(validIdentity.appID);
-                return dittoIdentityConfigMakeOnlineWithAuthentication(validIdentity.appID, authURL);
-            }
-            throw new Error(`Can't create Ditto, unsupported identity type: ${validIdentity}`);
-        })();
-        // History tracking is an experimental feature that is not supported in the JS SDK.
-        const historyTracking = 'Disabled';
-        // The JS SDK, unlike (nearly all of) the other SDKs, expects its `TransportConfig`s to have
-        // certain transports enabled/disabled by default. Specifically, it expects this to be
-        // determined for P2P transports based on the environment. We specify this here by setting
-        // `transportConfigMode` to 'PlatformDependent'.
-        const transportConfigMode = 'PlatformDependent';
-        const dittoPointer = mapFFIErrors(() => dittoTryNewBlocking(this.persistenceDirectory, identityConfig, historyTracking, transportConfigMode));
-        const appID = dittoAuthClientGetAppID(dittoPointer);
-        const siteID = dittoAuthClientGetSiteID(dittoPointer);
         Bridge.ditto.bridge(dittoPointer, this);
+        this._deviceName = defaultDeviceName();
+        // WORKAROUND (only for legacy identity): the login provider triggers the
+        // registered callback right when the auth client is being constructed. At
+        // this point, we don't have the auth client, which would be needed to
+        // perform a login, nor did we have a chance to create an authenticator.
+        // Therefore catch that first callback, store the seconds remaining and
+        // proceed with propagating it after all pieces are in place.
+        let secondsRemainingUntilAuthenticationExpires = null;
         let enableDittoCloudSync = false;
-        // IMPORTANT: Keeping the auth client around accumulates run-times and
-        // resources which becomes a problem specifically in tests (where we use one
-        // Ditto instance per test). We therefore keep it only if needed, i.e.
-        // _only_ for the onlineWithAuthentication and online identities and
-        // transfer ownership of it to the authenticator.
-        if (validIdentity.type === 'onlineWithAuthentication') {
-            enableDittoCloudSync = (_a = validIdentity.enableDittoCloudSync) !== null && _a !== void 0 ? _a : true;
-            this.auth = new OnlineAuthenticator(this.keepAlive, this, validIdentity.authHandler);
-            const loginProviderX = dittoAuthClientMakeLoginProvider(function (secondsRemaining) {
+        this.keepAlive = new KeepAlive();
+        if (configOrParameters.isConfig) {
+            // For the new config, no auth callback handler is set up in the Ditto
+            // constructor. Instead, it is set up every time an expiration handler is
+            // set.
+            this.auth = new OnlineAuthenticatorV2(this.keepAlive, this);
+        }
+        else if (((_a = configOrParameters.identity) === null || _a === void 0 ? void 0 : _a.type) === 'onlineWithAuthentication') {
+            // IMPORTANT: Keeping the auth client around accumulates run-times and
+            // resources which becomes a problem specifically in tests (where we use one
+            // Ditto instance per test). We therefore keep it only if needed, i.e.
+            // _only_ for the onlineWithAuthentication and online identities and
+            // transfer ownership of it to the authenticator.
+            enableDittoCloudSync =
+                (_c = (_b = configOrParameters.identity) === null || _b === void 0 ? void 0 : _b.enableDittoCloudSync) !== null && _c !== void 0 ? _c : true;
+            this.auth = new OnlineAuthenticator(this.keepAlive, this, configOrParameters.identity.authHandler);
+            const weakThis = new WeakRef(this);
+            const loginProviderPointer = dittoAuthClientMakeLoginProvider(function (secondsRemaining) {
                 const strongThis = weakThis.deref();
                 if (!strongThis) {
                     Logger.warning(`Internal inconsistency, LoginProvider callback fired after the corresponding Ditto instance has been deallocated.`);
@@ -9909,10 +11377,11 @@ class Ditto {
             // auth all happens in the background and so there are no guarantees we
             // need to uphold by making sure things are in a certain state before the
             // constructor finishes
-            void dittoAuthSetLoginProvider(dittoPointer, loginProviderX);
+            void dittoAuthSetLoginProvider(dittoPointer, loginProviderPointer);
         }
-        else if (validIdentity.type === 'onlinePlayground') {
-            enableDittoCloudSync = (_b = validIdentity.enableDittoCloudSync) !== null && _b !== void 0 ? _b : true;
+        else if (((_d = configOrParameters.identity) === null || _d === void 0 ? void 0 : _d.type) === 'onlinePlayground') {
+            enableDittoCloudSync =
+                (_e = configOrParameters.identity.enableDittoCloudSync) !== null && _e !== void 0 ? _e : true;
             this.auth = new OnlineAuthenticator(this.keepAlive, this, {
                 authenticationRequired: function (authenticator) {
                     // No-op.
@@ -9930,8 +11399,8 @@ class Ditto {
         //
         // Assign instance properties.
         //
-        this.appID = appID;
-        this.siteID = siteID;
+        this.appID = dittoAuthClientGetAppID(dittoPointer);
+        this.siteID = dittoAuthClientGetSiteID(dittoPointer);
         this.sync = new Sync(this);
         this.store = new Store(this);
         this.smallPeerInfo = new SmallPeerInfo(this);
@@ -9944,7 +11413,8 @@ class Ditto {
         disableDeadlockTimeoutWhenDebugging();
         // WORKAROUND: see description above where the
         // secondsRemainingUntilAuthenticationExpires variable is declared.
-        if (secondsRemainingUntilAuthenticationExpires != null) {
+        if (configOrParameters.isParameters &&
+            secondsRemainingUntilAuthenticationExpires != null) {
             this.auth['@ditto.authenticationExpiring'](secondsRemainingUntilAuthenticationExpires);
         }
     }
@@ -10025,69 +11495,6 @@ class Ditto {
         }
         return !isIE && hasRequiredAPIs;
     }
-    /**
-     * 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) {
-        let validatedPath;
-        if (path == null)
-            validatedPath = DEFAULT_PERSISTENCE_DIRECTORY;
-        else if (path.trim().length === 0)
-            throw new Error(`Invalid argument for path parameter: '${path}'`);
-        else
-            validatedPath = path;
-        {
-            const fs = require('fs');
-            const path = require('path');
-            if (process.platform === 'win32') {
-                // Normalize the path on Windows to prevent issues with its max path
-                // length (if needed). Windows has a hard limit at 260 characters
-                // for file paths [1]. When this limit is exceeded reads and writes
-                // may fail.
-                //
-                // [1]: https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#maximum-path-length-limitation
-                if (!validatedPath.startsWith('\\\\?\\'))
-                    validatedPath = `\\\\?\\${path.resolve(validatedPath)}`;
-            }
-            const absolutePath = path.resolve(validatedPath);
-            // We check if the directory exists before creating it to be able to
-            // provide a more helpful error message in case the directory is not
-            // writable.
-            let isDirectoryExisting = false;
-            try {
-                fs.statSync(absolutePath);
-                isDirectoryExisting = true;
-            }
-            catch (error) {
-                // On Windows, permissions can prevent us from checking if the directory
-                // exists: https://github.com/nodejs/node/issues/35853
-                if (error.code === 'EPERM') {
-                    throw new Error(`Missing read or write permissions for the persistence directory path '${absolutePath}'. Please update the permissions or use a different path.`);
-                }
-            }
-            if (!isDirectoryExisting) {
-                try {
-                    fs.mkdirSync(absolutePath, { recursive: true });
-                }
-                catch (error) {
-                    throw new Error(`Failed to create persistence directory at path '${absolutePath}'.\n\n${error}`);
-                }
-            }
-            // Caveat: It is still possible that these permissions are revoked during runtime.
-            if (!isDirectoryWritable(absolutePath)) {
-                throw new Error(`Missing read or write permissions for the persistence directory path '${absolutePath}'. Please update the permissions or use a different path.`);
-            }
-        }
-        return validatedPath;
-    }
     /**
      * Activate a `Ditto` instance by setting an offline only license token. You
      * cannot initiate sync with `Ditto` before you have activated it. The offline
@@ -10098,7 +11505,7 @@ class Ditto {
      * with. You can find yours on the [Ditto portal](https://portal.ditto.live).
      */
     setOfflineOnlyLicenseToken(licenseToken) {
-        if (IdentityTypesRequiringOfflineLicenseToken.includes(this.identity.type)) {
+        if (IdentityTypesRequiringOfflineLicenseToken.includes(this.configOrParameters.identity.type)) {
             this.deferClose((dittoHandle) => {
                 mapFFIErrors(() => {
                     tryVerifyLicense(dittoHandle.deref(), licenseToken);
@@ -10106,7 +11513,10 @@ class Ditto {
             });
         }
         else {
-            Logger.error(`The identity type '${this.identity.type}' does not require an offline license token.`);
+            const errorMessage = this.configOrParameters.isConfig
+                ? `The connect type '${this.config.connect.type}' does not require an offline license token.`
+                : `The identity type '${this.identity.type}' does not require an offline license token.`;
+            Logger.error(errorMessage);
         }
     }
     /**
@@ -10179,17 +11589,27 @@ class Ditto {
      *
      * @see {@link isSyncActive}
      * @see {@link stopSync | stopSync()}
+     * @deprecated use {@link Sync.start | ditto.sync.start()} instead.
      */
     startSync() {
         this.deferClose((dittoHandle) => {
-            if (IdentityTypesRequiringOfflineLicenseToken.includes(this.identity.type) &&
+            if (IdentityTypesRequiringOfflineLicenseToken.includes(this.configOrParameters.identity.type) &&
                 !this.isActivated) {
                 throw new Error('Sync could not be started because Ditto has not yet been activated. This can be achieved with a successful call to `setOfflineOnlyLicenseToken`. If you need to obtain a license token then please visit https://portal.ditto.live.');
             }
             if (!this.isSyncActive)
                 this.keepAlive.retain('sync');
             this._deviceName = dittoSetDeviceName(dittoHandle.deref(), this.deviceName);
-            dittoStartSync(dittoHandle.deref());
+            try {
+                mapFFIErrors(() => dittoTryStartSync(dittoHandle.deref()));
+            }
+            catch (error) {
+                // Don't keep the process alive if starting sync failed and sync is not
+                // already active.
+                if (!this.isSyncActive)
+                    this.keepAlive.release('sync');
+                throw error;
+            }
         });
     }
     /**
@@ -10200,6 +11620,7 @@ class Ditto {
      *
      * @see {@link isSyncActive}
      * @see {@link startSync | startSync()}
+     * @deprecated use {@link Sync.stop | ditto.sync.stop()} instead.
      */
     stopSync() {
         this.deferClose((dittoHandle) => {
@@ -10257,6 +11678,8 @@ class Ditto {
      * old data.
      *
      * This method does not have any effect when running Ditto in a browser.
+     *
+     * @deprecated this method is deprecated and will be removed in v5.0.0.
      */
     async runGarbageCollection() {
         return this.deferCloseAsync(async (dittoHandle) => {
@@ -10306,7 +11729,8 @@ class Ditto {
         this.transportConditionsManager.close();
         this.subscriptionManager.close();
         if (this.keepAlive.isActive) {
-            throw new Error('Internal inconsistency, still kept alive after the Ditto object has been close()-ed. ');
+            throw new Error('Internal inconsistency, still kept alive after the Ditto object has been close()-ed. Active IDs: ' +
+                this.keepAlive.currentIDs().join(', '));
         }
         // Await all pending operations before closing. Rejected promises are
         // ignored because they are handled at the original call site.
@@ -10382,55 +11806,6 @@ class Ditto {
         }
         return result;
     }
-    validateIdentity(identity) {
-        const validIdentity = { ...identity };
-        // @ts-expect-error we validate the existence of the value below.
-        const appID = identity.appID;
-        if (![
-            'offlinePlayground',
-            'sharedKey',
-            'manual',
-            'onlinePlayground',
-            'onlineWithAuthentication',
-        ].includes(identity.type)) {
-            throw new Error(`Can't create Ditto instance, unknown identity type: ${identity.type}`);
-        }
-        if ((identity.type === 'offlinePlayground' ||
-            identity.type === 'sharedKey' ||
-            identity.type === 'onlinePlayground' ||
-            identity.type === 'onlineWithAuthentication') &&
-            typeof appID === 'undefined')
-            throw new Error(`Property .appID must be given for identity, but isn't.`);
-        if (typeof appID !== 'undefined' && typeof appID !== 'string') {
-            throw new Error(`Property .appID must be be of type string, but is of type '${typeof appID}': ${appID}`);
-        }
-        if ((identity.type === 'offlinePlayground' ||
-            identity.type === 'sharedKey') &&
-            typeof identity.siteID !== 'undefined') {
-            const siteID = identity.siteID;
-            const isSiteIDNumberOrBigInt = typeof siteID === 'number' || typeof siteID === 'bigint';
-            if (!isSiteIDNumberOrBigInt) {
-                throw new Error("Can't create Ditto instance, siteID must be a number or BigInt");
-            }
-            if (siteID < 0)
-                throw new Error("Can't create Ditto instance, siteID must be >= 0");
-            if (siteID > BigInt('0xffffffffffffffff'))
-                throw new Error("Can't create Ditto instance, siteID must be < 2^64");
-        }
-        if (identity.type === 'sharedKey') ;
-        if (identity.type === 'manual') ;
-        if (identity.type === 'onlinePlayground') {
-            const token = identity.token;
-            if (typeof token === 'undefined') {
-                throw new Error(`Property .token must be given for identity but isn't. You can find the corresponding token on the Ditto Portal.`);
-            }
-            if (typeof token !== 'undefined' && typeof token !== 'string') {
-                throw new Error(`Property .token of identity must be be of type string, but is of type '${typeof token}': ${token}`);
-            }
-        }
-        if (identity.type === 'onlineWithAuthentication') ;
-        return validIdentity;
-    }
 }
 /**
  * Returns true if the current JS environment supports all required APIs.
@@ -10476,54 +11851,6 @@ const disableDeadlockTimeoutWhenDebugging = () => {
         }
     }
 };
-/**
- * Return true if we have read and write permissions for the given directory.
- *
- * Always returns `true` in the browser.
- *
- * Uses `fs.accessSync()` on all platforms except Windows, where ACLs are not
- * checked by that method [1]. On Windows, we try writing and removing a temp
- * file to the given path instead.
- *
- * [1]:
- * https://nodejs.org/docs/latest-v18.x/api/fs.html#fsaccesspath-mode-callback
- *
- * @internal
- */
-const isDirectoryWritable = (directoryPath) => {
-    {
-        const fs = require('fs');
-        const path = require('path');
-        if (process.platform === 'win32') {
-            const persistenceDirectory = path.resolve(directoryPath);
-            const testFilePath = path.join(persistenceDirectory, 'ditto-permissions-test.txt');
-            const testFileContents = 'permissions test';
-            try {
-                fs.writeFileSync(testFilePath, testFileContents);
-                const fileContents = fs.readFileSync(testFilePath, 'utf8');
-                if (fileContents !== testFileContents) {
-                    Logger.debug(`Failed to read back test file contents, expected '${testFileContents}' but got '${fileContents}'`);
-                    return false;
-                }
-                fs.unlinkSync(testFilePath);
-            }
-            catch (error) {
-                Logger.debug(`Failed to access persistence directory: ${error === null || error === void 0 ? void 0 : error.message}`);
-                return false;
-            }
-        }
-        else {
-            try {
-                fs.accessSync(directoryPath, fs.constants.W_OK | fs.constants.R_OK);
-            }
-            catch (error) {
-                Logger.debug(`Failed to access persistence directory: ${error === null || error === void 0 ? void 0 : error.message}`);
-                return false;
-            }
-        }
-    }
-    return true;
-};
 
 //
 // Copyright © 2025 DittoLive Incorporated. All rights reserved.
@@ -10741,7 +12068,6 @@ Bridge.ditto.registerType(Ditto);
 exports.Attachment = Attachment;
 exports.AttachmentFetcher = AttachmentFetcher;
 exports.AttachmentToken = AttachmentToken;
-exports.AuthenticationStatus = AuthenticationStatus;
 exports.Authenticator = Authenticator;
 exports.BasePendingCursorOperation = BasePendingCursorOperation;
 exports.BasePendingIDSpecificOperation = BasePendingIDSpecificOperation;
@@ -10750,9 +12076,11 @@ exports.Collection = Collection;
 exports.CollectionsEvent = CollectionsEvent;
 exports.ConnectionRequest = ConnectionRequest;
 exports.Counter = Counter;
+exports.DEFAULT_IDENTITY = DEFAULT_IDENTITY;
 exports.Diff = Diff;
 exports.Differ = Differ;
 exports.Ditto = Ditto;
+exports.DittoConfig = DittoConfig;
 exports.DittoError = DittoError;
 exports.Document = Document;
 exports.DocumentID = DocumentID;
@@ -10771,6 +12099,7 @@ exports.MutableRegister = MutableRegister;
 exports.NotAvailableAuthenticator = NotAvailableAuthenticator;
 exports.Observer = Observer;
 exports.OnlineAuthenticator = OnlineAuthenticator;
+exports.OnlineAuthenticatorV2 = OnlineAuthenticatorV2;
 exports.PendingCollectionsOperation = PendingCollectionsOperation;
 exports.PendingCursorOperation = PendingCursorOperation;
 exports.PendingIDSpecificOperation = PendingIDSpecificOperation;
@@ -10799,6 +12128,7 @@ exports.checkAPIs = checkAPIs;
 exports.disableDeadlockTimeoutWhenDebugging = disableDeadlockTimeoutWhenDebugging;
 exports.getBridgeLoad = getBridgeLoad;
 exports.init = init;
+exports.makeIdentityConfig = makeIdentityConfig;
 exports.mapFFIErrors = mapFFIErrors;
 exports.mapFFIErrorsAsync = mapFFIErrorsAsync;
 exports.transportConfigFromDeserializable = transportConfigFromDeserializable;