@dittolive/ditto 4.4.0 → 4.4.2-alpha1

package/node/ditto.cjs.js

@@ -70,10 +70,14 @@ KeepAlive.finalizationRegistry = new FinalizationRegistry(clearInterval);
  * alive, you have to keep a reference to the corresponding observer.
  */
 class Observer {
+    /** @internal */
+    get token() {
+        return this._token;
+    }
     /** @internal */
     constructor(observerManager, token, options = {}) {
         this.observerManager = observerManager;
-        this.token = token;
+        this._token = token;
         this.options = options;
         if (options.stopsWhenFinalized) {
             Observer.finalizationRegistry.register(this, { observerManager, token }, this);
@@ -84,7 +88,7 @@ class Observer {
      * method. Otherwise returns `false`.
      */
     get isStopped() {
-        return this.observerManager.hasObserver(this.token);
+        return this.token !== undefined && this.observerManager.hasObserver(this.token);
     }
     /**
      * Stops the observation. Calling this method multiple times has no effect.
@@ -92,7 +96,7 @@ class Observer {
     stop() {
         const token = this.token;
         if (token) {
-            delete this['token'];
+            delete this._token;
             Observer.finalizationRegistry.unregister(this);
             this.observerManager.removeObserver(token);
         }
@@ -121,24 +125,29 @@ class Value {
 // NOTE: we use a token to detect private invocation of the constructor. This is
 // not secure and just to prevent accidental private invocation on the client
 // side.
-const privateToken$1 = '@ditto.64d129224a5377b63e9727479ec987d9';
+const privateToken$1 = Symbol('privateConstructorToken');
 /**
  * Represents a CRDT counter that can be upserted as part of a document or
  * assigned to a property during an update of a document.
  */
 class Counter {
+    /** The value of the counter. */
+    get value() {
+        return this._value;
+    }
     /**
      * Creates a new counter that can be used as part of a document's content.
      */
     constructor() {
-        this.value = 0.0;
+        this._value = 0.0;
     }
     /** @internal */
     static '@ditto.create'(mutDoc, path, value) {
+        // @ts-expect-error - using hidden argument
         const counter = mutDoc ? new MutableCounter(privateToken$1) : new Counter();
         counter.mutDoc = mutDoc;
         counter.path = path;
-        counter['value'] = value;
+        counter._value = value;
         return counter;
     }
 }
@@ -160,15 +169,15 @@ class MutableCounter extends Counter {
      * otherwise an exception is thrown.
      */
     increment(amount) {
-        const mutDoc = this['mutDoc'];
-        const path = this['path'];
+        const mutDoc = this.mutDoc;
+        const path = this.path;
         if (!mutDoc) {
             throw new Error(`Can't increment counter, only possible within the closure of a collection's update() method.`);
         }
         mutDoc.at(path)['@ditto.increment'](amount);
         // We also increment the local value to make sure that the change is
         // reflected locally as well as in the underlying document
-        this['value'] += amount;
+        this._value += amount;
     }
     /** @internal */
     constructor() {
@@ -324,9 +333,11 @@ function ditto_document_set_cbor(...args) { return ditto.ditto_document_set_cbor
 function ditto_document_set_cbor_with_timestamp(...args) { return ditto.ditto_document_set_cbor_with_timestamp(...args) }
 function ditto_documents_hash(...args) { return ditto.ditto_documents_hash(...args) }
 function ditto_documents_hash_mnemonic(...args) { return ditto.ditto_documents_hash_mnemonic(...args) }
+function ditto_dql_response_free(...args) { return ditto.ditto_dql_response_free(...args) }
+function ditto_dql_response_results(...args) { return ditto.ditto_dql_response_results(...args) }
+function ditto_dql_result_free(...args) { return ditto.ditto_dql_result_free(...args) }
 function ditto_error_message(...args) { return ditto.ditto_error_message(...args) }
 function ditto_experimental_add_dql_subscription(...args) { return ditto.ditto_experimental_add_dql_subscription(...args) }
-function ditto_experimental_exec_statement_str(...args) { return ditto.ditto_experimental_exec_statement_str(...args) }
 function ditto_experimental_register_dql_live_query_str_detached(...args) { return ditto.ditto_experimental_register_dql_live_query_str_detached(...args) }
 function ditto_experimental_remove_dql_subscription(...args) { return ditto.ditto_experimental_remove_dql_subscription(...args) }
 function ditto_experimental_webhook_register_dql_live_query_str(...args) { return ditto.ditto_experimental_webhook_register_dql_live_query_str(...args) }
@@ -369,6 +380,7 @@ function ditto_register_transport_condition_changed_callback(...args) { return d
 function ditto_remove_multicast_transport(...args) { return ditto.ditto_remove_multicast_transport(...args) }
 function ditto_remove_subscription(...args) { return ditto.ditto_remove_subscription(...args) }
 function ditto_resolve_attachment(...args) { return ditto.ditto_resolve_attachment(...args) }
+function ditto_result_cbor(...args) { return ditto.ditto_result_cbor(...args) }
 function ditto_run_garbage_collection(...args) { return ditto.ditto_run_garbage_collection(...args) }
 function ditto_set_connect_retry_interval(...args) { return ditto.ditto_set_connect_retry_interval(...args) }
 function ditto_set_device_name(...args) { return ditto.ditto_set_device_name(...args) }
@@ -385,6 +397,9 @@ 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_error_description(...args) { return ditto.dittoffi_error_description(...args) }
+function dittoffi_error_free(...args) { return ditto.dittoffi_error_free(...args) }
+function dittoffi_try_experimental_exec_statement_str(...args) { return ditto.dittoffi_try_experimental_exec_statement_str(...args) }
 function getDeadlockTimeout$1(...args) { return ditto.getDeadlockTimeout(...args) }
 function jsDocsToCDocs(...args) { return ditto.jsDocsToCDocs(...args) }
 function mdns_client_free_handle(...args) { return ditto.mdns_client_free_handle(...args) }
@@ -636,13 +651,27 @@ async function collectionEvictQueryStr(ditto, collectionName, writeTransaction,
     const queryX = bytesFromString(query);
     return await ditto_collection_evict_query_str(ditto, collectionNameX, writeTransaction, queryX, queryArgsCBOR, orderBy, limit, offset);
 }
-/** @internal */
+/**
+ * This FFI can error:
+ * - DQL parser error
+ * - Incorrect arguments to query parameters
+ * - Collection is not found.
+ *
+ * @internal
+ */
 async function experimentalExecQueryStr(ditto, writeTransaction, query, queryArgsCBOR) {
     ensureInitialized();
     const queryBytesPointer = bytesFromString(query);
     // This doesn't need to convert error return codes into thrown js errors
     // because the ffi implementation already does that.
-    return await ditto_experimental_exec_statement_str(ditto, writeTransaction, queryBytesPointer, queryArgsCBOR);
+    const result = await dittoffi_try_experimental_exec_statement_str(ditto, writeTransaction, queryBytesPointer, queryArgsCBOR);
+    if (result.error !== null) {
+        // TODO: idiomatic js error class shim around `Pointer<FFIError>`.
+        const errorMsg = errorMessage(result.error);
+        dittoffi_error_free(result.error);
+        throw new Error(errorMsg);
+    }
+    return result.success;
 }
 /** @internal */
 function addSubscription(ditto, collectionName, query, queryArgsCBOR, orderBy, limit, offset) {
@@ -674,6 +703,49 @@ function experimentalRemoveDqlSubscription(ditto, query, queryArgsCBOR) {
     if (statusCode !== 0)
         throw new Error(errorMessage() || `ditto_experimental_remove_dql_subscription() failed with error code: ${statusCode}`);
 }
+// ----------------------------------------------------------- DqlResponse ------
+/**
+ * Doesn't error
+ *
+ * @internal
+ */
+function experimentalDqlResponseFree(self) {
+    ensureInitialized();
+    ditto_dql_response_free(self);
+}
+/**
+ * Doesn't error
+ *
+ * @internal
+ */
+function experimentalDqlResultFree(self) {
+    ensureInitialized();
+    ditto_dql_result_free(self);
+}
+/**
+ * Can error only on internal bug.
+ *
+ * @internal */
+function experimentalDqlResponseResults(self) {
+    ensureInitialized();
+    return ditto_dql_response_results(self);
+}
+/**
+ * The result CBOR contains a map/object with fields and values.
+ * No CRDTs are present there as they are not needed. Currently
+ * only values from registers are returned and non-register fields are
+ * ignored. Reading values from other CRDTs will be supported with
+ * definition support.
+ *
+ * Doesn't error
+ *
+ * @internal
+ */
+function experimentalDqlResultCBOR(self) {
+    ensureInitialized();
+    const cborBytes = ditto_result_cbor(self);
+    return boxCBytesIntoBuffer(cborBytes);
+}
 // ------------------------------------------------------------ LiveQuery ------
 /** @internal */
 function liveQueryRegister(ditto, collectionName, query, queryArgsCBOR, orderBy, limit, offset, eventHandler, 
@@ -1342,9 +1414,12 @@ function bytesFromString(jsString) {
     return textEncoder.encode(`${jsString}\0`);
 }
 /** @internal */
-function errorMessage() {
+function errorMessage(ffiError) {
     ensureInitialized();
-    const errorMessageCString = ditto_error_message();
+    // eslint-disable-next-line
+    const errorMessageCString = (typeof ffiError === 'undefined'
+        ? ditto_error_message()
+        : dittoffi_error_description(ffiError));
     return boxCStringIntoString(errorMessageCString);
 }
 /** @internal */
@@ -1521,7 +1596,7 @@ function awdlDestroy(awdl) {
 
 // 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.4.0';
+const fullBuildVersionString = '4.4.2-alpha1';
 
 //
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
@@ -1563,6 +1638,13 @@ async function init(options = {}) {
  * log messages with the Ditto logging infrastructure.
  */
 class Logger {
+    /**
+     * Registers a file path where logs will be written to, whenever Ditto wants
+     * to issue a log (on _top_ of emitting the log to the console).
+     */
+    static get logFile() {
+        return this._logFile;
+    }
     /**
      * On Node, registers a file path where logs will be written to, whenever
      * Ditto wants to issue a log (on _top_ of emitting the log to the console).
@@ -1575,11 +1657,11 @@ class Logger {
     static setLogFile(path) {
         if (path) {
             loggerSetLogFile(path);
-            this['logFile'] = path;
+            this._logFile = path;
         }
         else {
-            loggerSetLogFile(null);
-            delete this['logFile'];
+            loggerSetLogFile(undefined);
+            delete this._logFile;
         }
     }
     /**
@@ -1587,7 +1669,8 @@ class Logger {
      * {@link setLogFile | setLogFile()} with it.
      */
     static setLogFileURL(url) {
-        this.setLogFile(url === null || url === void 0 ? void 0 : url.pathname);
+        var _a;
+        this.setLogFile((_a = url === null || url === void 0 ? void 0 : url.pathname) !== null && _a !== void 0 ? _a : null);
     }
     /** Whether the logger is currently enabled. */
     static get enabled() {
@@ -1629,6 +1712,14 @@ class Logger {
     static set minimumLogLevel(minimumLogLevel) {
         loggerMinimumLogLevel(minimumLogLevel);
     }
+    /**
+     * Returns the current custom log callback, `undefined` by default. See
+     * {@link setCustomLogCallback | setCustomLogCallback()} for a detailed
+     * description.
+     */
+    static get customLogCallback() {
+        return this._customLogCallback;
+    }
     /**
      * Registers a custom callback that will be called to report each log entry.
      *
@@ -1639,11 +1730,11 @@ class Logger {
     static async setCustomLogCallback(callback) {
         if (callback) {
             await loggerSetCustomLogCb(callback);
-            this['customLogCallback'] = callback;
+            this._customLogCallback = callback;
         }
         else {
             await loggerSetCustomLogCb(null);
-            delete this['customLogCallback'];
+            delete this._customLogCallback;
         }
     }
     /**
@@ -1693,7 +1784,6 @@ class Logger {
     static verbose(message) {
         this.log('Verbose', message);
     }
-    // ------------------------------------------------------------ Private ------
     constructor() {
         throw new Error("Logger can't be instantiated, use its static properties & methods directly instead.");
     }
@@ -2839,7 +2929,7 @@ function validateDocumentIDCBOR(idCBOR) {
 }
 
 //
-// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
 //
 // REFACTOR: tweak the API to use Rust concepts of ownership. For example,
 // register() could be named something like yieldOwnership() while unregister()
@@ -3284,6 +3374,10 @@ Bridge.document = new Bridge(documentFree);
 /** @internal */
 Bridge.mutableDocument = new Bridge(documentFree);
 /** @internal */
+Bridge.dqlResponse = new Bridge(experimentalDqlResponseFree);
+/** @internal */
+Bridge.dqlResult = new Bridge(experimentalDqlResultFree);
+/** @internal */
 Bridge.staticTCPClient = new Bridge(staticTCPClientFreeHandle);
 /** @internal */
 Bridge.websocketClient = new Bridge(websocketClientFreeHandle);
@@ -4584,6 +4678,12 @@ class ObserverManager {
  * `OnlineWithAuthentication` or an `Online` identity.
  */
 class Authenticator {
+    /**
+     Returns the current authentication status.
+     */
+    get status() {
+        return this._status;
+    }
     /**
      * Log in to Ditto with a third-party token. Throws if authentication is not
      * available, which can be checked with {@link loginSupported}.
@@ -4632,7 +4732,7 @@ class Authenticator {
     /** @internal */
     constructor(keepAlive) {
         this.keepAlive = keepAlive;
-        this.status = { isAuthenticated: false, userID: null };
+        this._status = { isAuthenticated: false, userID: null };
         this.loginSupported = false;
         this.observerManager = new ObserverManager('AuthenticationStatusObservation', { keepAlive });
     }
@@ -4693,13 +4793,13 @@ class OnlineAuthenticator extends Authenticator {
         return ditto.deferCloseAsync(async () => {
             await dittoAuthClientLogout(dittoPointer);
             ditto.stopSync();
-            cleanupFn === null || cleanupFn === void 0 ? void 0 : cleanupFn(this.ditto);
+            cleanupFn === null || cleanupFn === void 0 ? void 0 : cleanupFn(ditto);
         });
     }
     constructor(keepAlive, ditto, authenticationHandler) {
         super(keepAlive);
-        this['loginSupported'] = true;
-        this['status'] = { isAuthenticated: false, userID: null };
+        this.loginSupported = true;
+        this._status = { isAuthenticated: false, userID: null };
         this.ditto = new WeakRef(ditto);
         this.authenticationHandler = authenticationHandler;
         this.updateAndNotify(false);
@@ -4734,7 +4834,7 @@ class OnlineAuthenticator extends Authenticator {
         const isAuthenticated = dittoAuthClientIsWebValid(dittoPointer);
         const userID = dittoAuthClientUserID(dittoPointer);
         const status = { isAuthenticated, userID };
-        this['status'] = status;
+        this._status = status;
         if (shouldNotify) {
             const sameStatus = !!wasAuthenticated === !!isAuthenticated && previousUserID === userID;
             if (!sameStatus) {
@@ -4927,6 +5027,7 @@ class TransportConfig {
      * Create a new transport config initialized with the default settings.
      */
     constructor() {
+        this._isFrozen = false;
         this.peerToPeer = {
             bluetoothLE: { isEnabled: false },
             awdl: { isEnabled: false },
@@ -4963,13 +5064,20 @@ class TransportConfig {
         this.peerToPeer.lan.isEnabled = enabled;
         this.peerToPeer.awdl.isEnabled = enabled;
     }
+    /**
+     * Returns `true` if the transport configuration is frozen, otherwise
+     * returns `false`.
+     */
+    get isFrozen() {
+        return this._isFrozen;
+    }
     /**
      * (Deep) freezes the receiver such that it can't be modified anymore.
      */
     freeze() {
         if (this.isFrozen)
             return this;
-        this['isFrozen'] = true;
+        this._isFrozen = true;
         Object.freeze(this.peerToPeer.bluetoothLE);
         Object.freeze(this.peerToPeer.awdl);
         Object.freeze(this.peerToPeer.lan);
@@ -4996,8 +5104,8 @@ class TransportConfig {
         copy.connect.tcpServers = this.connect.tcpServers.slice();
         copy.connect.websocketURLs = this.connect.websocketURLs.slice();
         copy.connect.retryInterval = this.connect.retryInterval;
-        copy.listen['tcp'] = { ...this.listen.tcp };
-        copy.listen['http'] = { ...this.listen.http };
+        copy.listen.tcp = { ...this.listen.tcp };
+        copy.listen.http = { ...this.listen.http };
         copy.global.syncGroup = this.global.syncGroup;
         copy.global.routingHint = this.global.routingHint;
         return copy;
@@ -5008,6 +5116,7 @@ class TransportConfig {
      */
     static areListenTCPsEqual(left, right) {
         /* eslint-disable */
+        // prettier-ignore
         return (left.isEnabled === right.isEnabled &&
             left.interfaceIP === right.interfaceIP &&
             left.port === right.port);
@@ -5019,6 +5128,7 @@ class TransportConfig {
      */
     static areListenHTTPsEqual(left, right) {
         /* eslint-disable */
+        // prettier-ignore
         return (left.isEnabled === right.isEnabled &&
             left.interfaceIP === right.interfaceIP &&
             left.port === right.port &&
@@ -5042,6 +5152,13 @@ class TransportConfig {
  * try to be kept up-to-date with the latest changes from remote peers.
  */
 class Subscription {
+    /**
+     * Returns `true` if subscription has been explicitly cancelled, `false`
+     * otherwise.
+     */
+    get isCancelled() {
+        return this._isCancelled;
+    }
     /**
      * The name of the collection that the subscription is based on.
      */
@@ -5053,18 +5170,14 @@ class Subscription {
      */
     cancel() {
         if (!this.isCancelled) {
-            this['isCancelled'] = true;
+            this._isCancelled = true;
             this.manager.remove(this);
         }
     }
     // ----------------------------------------------------------- Internal ------
     /** @internal */
     constructor(collection, query, queryArgsCBOR, orderBys, limit, offset) {
-        /**
-         * Returns `true` if subscription has been explicitly cancelled, `false`
-         * otherwise.
-         */
-        this.isCancelled = false;
+        this._isCancelled = false;
         // Query should be validated at this point.
         this.query = query;
         this.queryArgsCBOR = queryArgsCBOR;
@@ -5230,6 +5343,9 @@ class LiveQuery {
             this.liveQueryManager.stopLiveQuery(this);
         }
     }
+    get liveQueryID() {
+        return this._liveQueryID;
+    }
     /** @internal */
     constructor(query, queryArgs, queryArgsCBOR, orderBys, limit, offset, collection, handler) {
         // Query should be validated at this point.
@@ -5277,11 +5393,11 @@ class LiveQuery {
                 }
                 handler(documents, event, signalNext);
             });
-            if (!liveQueryID) {
-                throw new Error("Internal inconsistency, couldn't create a valid live query ID.");
-            }
-            this['liveQueryID'] = liveQueryID;
         });
+        if (!liveQueryID) {
+            throw new Error("Internal inconsistency, couldn't create a valid live query ID.");
+        }
+        this._liveQueryID = liveQueryID;
     }
     /** @internal */
     async signalNext() {
@@ -6360,26 +6476,29 @@ class ExperimentalReplicationSubscriptionManager {
  * @internal
  */
 class ExperimentalReplicationSubscription {
+    /**
+     * `true` when {@link cancel | cancel()} has been called or the Ditto instance
+     * managing this replication subscription has been closed.
+     */
+    // Recording this information on the replication subscription instance itself
+    // allows working with it even after Ditto has been closed and the replication
+    // subscription manager can not be accessed anymore.
+    get isCancelled() {
+        return this._isCancelled;
+    }
     /**
      * Cancels a replication subscription and releases all associated resources.
      */
     cancel() {
         if (!this.isCancelled) {
-            this['isCancelled'] = true;
+            this._isCancelled = true;
             this.manager.removeSubscription(this);
         }
     }
     // --------------------------- Internal --------------------------------------
     /** @internal */
     constructor(manager, query, queryArgsCBOR) {
-        /**
-         * `true` when {@link cancel | cancel()} has been called or the Ditto instance
-         * managing this replication subscription has been closed.
-         */
-        // Recording this information on the replication subscription instance itself
-        // allows working with it even after Ditto has been closed and the replication
-        // subscription manager can not be accessed anymore.
-        this.isCancelled = false;
+        this._isCancelled = false;
         this.query = query;
         this.queryArgsCBOR = queryArgsCBOR;
         this.contextInfo = {
@@ -6480,14 +6599,23 @@ class ExperimentalStore {
      * The returned {@link ExperimentalReplicationSubscription} object must be kept in scope
      * for as long as you want to keep receiving updates.
      *
+     * Use placeholders to incorporate values from the optional `queryArguments`
+     * parameter into the query. The keys of the `queryArguments` object must
+     * match the placeholders used within the query. You can not use placeholders
+     * in the `FROM` clause.
+     *
      * @internal
      * @param query a Ditto Query Language query string of the form SELECT * FROM
      * collection WHERE expression
+     * @param queryArguments an object with values to be incorporated into a
+     * query. The keys of the object must match the placeholders used within the
+     * query.
      * @returns {@link ExperimentalReplicationSubscription} object
      */
-    addReplicationSubscription(query) {
+    addReplicationSubscription(query, queryArguments) {
         Logger.debug(`ExperimentalStore.subscribe(query = ${query})`);
-        return new ExperimentalReplicationSubscription(this.replicationSubscriptionManager, query, null);
+        const queryArgumentsCBOR = queryArguments ? CBOR.encode(queryArguments) : null;
+        return new ExperimentalReplicationSubscription(this.replicationSubscriptionManager, query, queryArgumentsCBOR);
     }
     /** @internal */
     close() {
@@ -6497,18 +6625,25 @@ class ExperimentalStore {
     /**
      * Executes the given query in the local store and returns the result.
      *
+     * Use placeholders to incorporate values from the optional `queryArguments`
+     * parameter into the query. The keys of the `queryArguments` object must
+     * match the placeholders used within the query. You can not use placeholders
+     * in the `FROM` clause.
+     *
      * Limitations:
      *
      * - Supports `SELECT * FROM <collection name>` with optional `WHERE
      *   <expression>`
-     * - No query parameters as function arguments yet
      * - No transactions
      *
      * @internal
      * @param query a Ditto Query Language query string
+     * @param queryArguments an object with values to be incorporated into a
+     * query. The keys of the object must match the placeholders used within the
+     * query.
      * @returns a promise for an array of Ditto documents matching the query
      */
-    async execute(query) {
+    async execute(query, queryArguments) {
         Logger.debug(`ExperimentalStore.execute(query = ${query})`);
         const ditto = this.ditto;
         const dittoHandle = Bridge.ditto.handleFor(ditto);
@@ -6516,12 +6651,11 @@ class ExperimentalStore {
             // A one-off query execution uses a transaction internally but a
             // transaction API is not implemented yet.
             const writeTransaction = null;
-            // Not implemented yet.
-            const queryParameters = null;
-            const documentPointers = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
-                return await experimentalExecQueryStr(dittoHandle.deref(), writeTransaction, query, queryParameters);
+            const queryArgumentsCBOR = queryArguments ? CBOR.encode(queryArguments) : null;
+            const responsePointer = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
+                return await experimentalExecQueryStr(dittoHandle.deref(), writeTransaction, query, queryArgumentsCBOR);
             });
-            return documentPointers.map((documentPointer) => Bridge.document.bridge(documentPointer));
+            return Bridge.dqlResponse.bridge(responsePointer);
         });
     }
 }
@@ -7303,6 +7437,9 @@ class TransportConditionsManager extends ObserverManager {
 //
 /** @internal */
 class Sync {
+    get parameters() {
+        return this._parameters;
+    }
     constructor(ditto) {
         this.bluetoothLETransportPointer = null;
         this.awdlTransportPointer = null;
@@ -7313,11 +7450,11 @@ class Sync {
         const transportConfig = new TransportConfig();
         const parameters = { identity, transportConfig, ditto, isWebValid: false, isX509Valid: false, isSyncActive: false };
         this.ditto = ditto;
-        this.parameters = parameters;
+        this._parameters = parameters;
         this.state = stateFrom(parameters);
     }
     update(parameters) {
-        this['parameters'] = { ...parameters };
+        this._parameters = { ...parameters };
         // NOTE: updating is a two-step process. Given all parameters, we
         // first compute the final "state" we want the transports stuff to
         // be in via the `stateFrom()` function. We then take that "desired" state
@@ -7897,6 +8034,32 @@ class Ditto {
         Logger.warning("⚠️ Deprecation Warning: The 'Ditto.path' property is deprecated. Please update your code to use the new 'Ditto.persistenceDirectory' property instead.");
         return this.persistenceDirectory;
     }
+    /**
+     * Returns `true` if an offline license token has been set, otherwise returns `false`.
+     *
+     * @see {@link setOfflineOnlyLicenseToken | setOfflineOnlyLicenseToken()}
+     */
+    get isActivated() {
+        var _a;
+        return (_a = this._isActivated) !== null && _a !== void 0 ? _a : false;
+    }
+    /**
+     * `true` once {@link close | Ditto.close()} has been called, otherwise
+     * `false`.
+     */
+    get isClosed() {
+        var _a;
+        return (_a = this._isClosed) !== null && _a !== void 0 ? _a : false;
+    }
+    /**
+     * Returns `true` if sync is active, otherwise returns `false`. Use
+     * {@link startSync | startSync()} to activate and
+     * {@link stopSync | stopSync()} to deactivate sync.
+     */
+    get isSyncActive() {
+        var _a;
+        return (_a = this._isSyncActive) !== null && _a !== void 0 ? _a : false;
+    }
     /**
      * Initializes a new `Ditto` instance.
      *
@@ -7908,20 +8071,18 @@ class Ditto {
      * `offlinePlayground` with `appID` being the empty string `''`.
      *
      * @param persistenceDirectory optional string containing a directory path
-     * that Ditto will use for persistence. Defaults to `"ditto"`.
+     * 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}
      */
     constructor(identity, persistenceDirectory) {
-        /**
-         * `true` once {@link close | Ditto.close()} has been called, otherwise
-         * `false`.
-         */
-        this.isClosed = false;
         this.deferCloseAllowed = true;
         this.isWebValid = false;
         this.isX509Valid = false;
+        this._isSyncActive = false;
+        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()) {
@@ -8035,14 +8196,14 @@ class Ditto {
         //
         this.appID = appID;
         this.siteID = siteID;
-        this.transportConfig = transportConfig.copy().freeze();
+        this._transportConfig = transportConfig.copy().freeze();
         this.isX509Valid = isX509Valid;
         this.isWebValid = isWebValid;
         this.sync = new Sync(this);
         this.sync.update({ isSyncActive: false, isX509Valid, isWebValid, identity: validIdentity, ditto: this, transportConfig });
         // We don't need a license when running in the browser, so we
         // mark the instance as activated from the get-go in that case.
-        this.isActivated = !IdentityTypesRequiringOfflineLicenseToken.includes(validIdentity.type);
+        this._isActivated = !IdentityTypesRequiringOfflineLicenseToken.includes(validIdentity.type);
         this.store = new Store(this);
         this.presence = new Presence(this);
         this.presenceManager = new PresenceManager(this);
@@ -8152,11 +8313,42 @@ class Ditto {
         }
         {
             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. 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
+                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.mkdirSync(validatedPath, { recursive: true });
+                fs.statSync(absolutePath);
+                isDirectoryExisting = true;
             }
             catch (error) {
-                throw new Error(`Failed to create persistence directory at '${validatedPath}'`);
+                // 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;
@@ -8175,11 +8367,11 @@ class Ditto {
             if (IdentityTypesRequiringOfflineLicenseToken.includes(this.identity.type)) {
                 const { result, errorMessage } = verifyLicense(licenseToken);
                 if (result !== 'LicenseOk') {
-                    this['isActivated'] = false;
+                    this._isActivated = false;
                     throw new Error(errorMessage);
                 }
                 else {
-                    this['isActivated'] = true;
+                    this._isActivated = true;
                 }
             }
             else {
@@ -8187,6 +8379,20 @@ class Ditto {
             }
         }
     }
+    /**
+     * Returns the current transport configuration, frozen. If you want to modify
+     * the transport config, make a {@link TransportConfig.copy | copy} first. Or
+     * use the {@link updateTransportConfig | updateTransportConfig()}
+     * convenience method. By default peer-to-peer transports (Bluetooth, WiFi,
+     * and AWDL) are enabled if available in the current environment
+     * (Web, Node, OS, etc.).
+     *
+     * @see {@link setTransportConfig | setTransportConfig()}
+     * @see {@link updateTransportConfig | updateTransportConfig()}
+     */
+    get transportConfig() {
+        return this._transportConfig;
+    }
     /**
      * Assigns a new transports configuration. By default peer-to-peer transports
      * (Bluetooth, WiFi, and AWDL) are enabled. You may use this method to alter
@@ -8197,7 +8403,7 @@ class Ditto {
      * @see {@link updateTransportConfig | updateTransportConfig()}
      */
     setTransportConfig(transportConfig) {
-        this['transportConfig'] = transportConfig.copy().freeze();
+        this._transportConfig = transportConfig.copy().freeze();
         const transportConfigNew = this.transportConfig;
         const identity = this.identity;
         const isWebValid = this.isWebValid;
@@ -8334,7 +8540,7 @@ class Ditto {
         if (this.isClosed) {
             return;
         }
-        this['isClosed'] = true;
+        this._isClosed = true;
         this.stopSync();
         this.store.close();
         this.presence.close();
@@ -8424,8 +8630,8 @@ class Ditto {
     }
     validateIdentity(identity) {
         const validIdentity = { ...identity };
-        identity['appName'];
-        const appID = identity['appID'];
+        // @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}`);
         }
@@ -8471,7 +8677,7 @@ class Ditto {
             if (this.isSyncActive && !flag) {
                 this.keepAlive.release('sync');
             }
-            this['isSyncActive'] = flag;
+            this._isSyncActive = flag;
             const isWebValid = this.isWebValid;
             const isX509Valid = this.isX509Valid;
             const identity = this.identity;
@@ -8535,6 +8741,54 @@ 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;
+};
 
 /**
  * Get a count of bridged objects binned by bridge type.
@@ -8575,6 +8829,67 @@ class StaticTCPClient {
 class WebsocketClient {
 }
 
+//
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
+//
+/**
+ * Represents single result object.
+ * This API needs to be completed to navigate in the result object.
+ * The result object is retrieved via FFI.dqlResultCBOR(Pointer<FFIDqlResult>).
+ *
+ * Currently experimental.
+ *
+ * @internal
+ */
+class ExperimentalDqlResult {
+    get value() {
+        if (this.storedValue === undefined) {
+            const result = Bridge.dqlResult.handleFor(this);
+            const cbor = experimentalDqlResultCBOR(result.deref());
+            this.storedValue = CBOR.decode(cbor);
+        }
+        return this.storedValue;
+    }
+    /**
+     * FIXME: warn users who try to instantiate this class themselves
+     *
+     * @internal
+     */
+    constructor() { }
+}
+
+//
+// Copyright © 2023 DittoLive Incorporated. All rights reserved.
+//
+/**
+ * Represents the response from executing DQL statements.
+ * Currently experimental.
+ *
+ * The memory management is quite complex. Every time when Rust is called
+ * it will clone the result object. Rust mirror of DqlResponse contains
+ * the collection of result objects. During the getting results call
+ * Rust will copy DqlResult obejcts, thus JS here gets complete control
+ * of their lifetimes.
+ *
+ * @internal
+ */
+class ExperimentalDqlResponse {
+    get results() {
+        if (this.storedResults === undefined) {
+            const response = Bridge.dqlResponse.handleFor(this);
+            const results = experimentalDqlResponseResults(response.deref());
+            this.storedResults = results.map((r) => Bridge.dqlResult.bridge(r));
+        }
+        return this.storedResults;
+    }
+    /**
+     * FIXME: warn users who try to instantiate this class themselves
+     *
+     * @internal
+     */
+    constructor() { }
+}
+
 //
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
 //
@@ -8586,6 +8901,8 @@ class WebsocketClient {
 // immediately require the bridged type, oftentimes leading to an import cycle.
 Bridge.attachment.registerType(Attachment);
 Bridge.document.registerType(Document);
+Bridge.dqlResult.registerType(ExperimentalDqlResult);
+Bridge.dqlResponse.registerType(ExperimentalDqlResponse);
 Bridge.mutableDocument.registerType(MutableDocument);
 Bridge.staticTCPClient.registerType(StaticTCPClient);
 Bridge.websocketClient.registerType(WebsocketClient);