@dittolive/ditto 4.10.2 → 4.11.0-preview.1

package/node/ditto.cjs.js

@@ -344,7 +344,6 @@ function ditto_live_query_register_str_detached(...args) { return ditto.ditto_li
 function ditto_live_query_signal_available_next(...args) { return ditto.ditto_live_query_signal_available_next(...args) }
 function ditto_live_query_start(...args) { return ditto.ditto_live_query_start(...args) }
 function ditto_live_query_stop(...args) { return ditto.ditto_live_query_stop(...args) }
-function ditto_live_query_webhook_register_str(...args) { return ditto.ditto_live_query_webhook_register_str(...args) }
 function ditto_log(...args) { return ditto.ditto_log(...args) }
 function ditto_logger_emoji_headings_enabled(...args) { return ditto.ditto_logger_emoji_headings_enabled(...args) }
 function ditto_logger_emoji_headings_enabled_get(...args) { return ditto.ditto_logger_emoji_headings_enabled_get(...args) }
@@ -394,12 +393,16 @@ function dittoffi_connection_request_identity_service_metadata_json(...args) { r
 function dittoffi_connection_request_peer_key_string(...args) { return ditto.dittoffi_connection_request_peer_key_string(...args) }
 function dittoffi_connection_request_peer_metadata_json(...args) { return ditto.dittoffi_connection_request_peer_metadata_json(...args) }
 function dittoffi_crypto_generate_secure_random_token(...args) { return ditto.dittoffi_crypto_generate_secure_random_token(...args) }
+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_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_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) }
 function dittoffi_ditto_transport_config(...args) { return ditto.dittoffi_ditto_transport_config(...args) }
+function dittoffi_ditto_try_new_blocking(...args) { return ditto.dittoffi_ditto_try_new_blocking(...args) }
 function dittoffi_ditto_try_set_transport_config(...args) { return ditto.dittoffi_ditto_try_set_transport_config(...args) }
 function dittoffi_ditto_try_start_sync(...args) { return ditto.dittoffi_ditto_try_start_sync(...args) }
 function dittoffi_error_code(...args) { return ditto.dittoffi_error_code(...args) }
@@ -407,7 +410,6 @@ function dittoffi_error_description(...args) { return ditto.dittoffi_error_descr
 function dittoffi_error_free(...args) { return ditto.dittoffi_error_free(...args) }
 function dittoffi_get_sdk_semver(...args) { return ditto.dittoffi_get_sdk_semver(...args) }
 function dittoffi_logger_try_export_to_file_async(...args) { return ditto.dittoffi_logger_try_export_to_file_async(...args) }
-function dittoffi_make_with_transport_config_mode(...args) { return ditto.dittoffi_make_with_transport_config_mode(...args) }
 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) }
@@ -417,8 +419,15 @@ function dittoffi_query_result_item_cbor(...args) { return ditto.dittoffi_query_
 function dittoffi_query_result_item_count(...args) { return ditto.dittoffi_query_result_item_count(...args) }
 function dittoffi_query_result_item_free(...args) { return ditto.dittoffi_query_result_item_free(...args) }
 function dittoffi_query_result_item_json(...args) { return ditto.dittoffi_query_result_item_json(...args) }
+function dittoffi_query_result_item_new(...args) { return ditto.dittoffi_query_result_item_new(...args) }
 function dittoffi_query_result_mutated_document_id_at(...args) { return ditto.dittoffi_query_result_mutated_document_id_at(...args) }
 function dittoffi_query_result_mutated_document_id_count(...args) { return ditto.dittoffi_query_result_mutated_document_id_count(...args) }
+function dittoffi_store_begin_transaction_async_throws(...args) { return ditto.dittoffi_store_begin_transaction_async_throws(...args) }
+function dittoffi_store_transactions(...args) { return ditto.dittoffi_store_transactions(...args) }
+function dittoffi_transaction_complete_async_throws(...args) { return ditto.dittoffi_transaction_complete_async_throws(...args) }
+function dittoffi_transaction_execute_async_throws(...args) { return ditto.dittoffi_transaction_execute_async_throws(...args) }
+function dittoffi_transaction_free(...args) { return ditto.dittoffi_transaction_free(...args) }
+function dittoffi_transaction_info(...args) { return ditto.dittoffi_transaction_info(...args) }
 function dittoffi_try_add_sync_subscription(...args) { return ditto.dittoffi_try_add_sync_subscription(...args) }
 function dittoffi_try_base64_decode(...args) { return ditto.dittoffi_try_base64_decode(...args) }
 function dittoffi_try_exec_statement(...args) { return ditto.dittoffi_try_exec_statement(...args) }
@@ -544,6 +553,28 @@ var DittoCRDTType;
     DittoCRDTType[DittoCRDTType["rga"] = 3] = "rga";
     DittoCRDTType[DittoCRDTType["rwMap"] = 4] = "rwMap";
 })(DittoCRDTType || (DittoCRDTType = {}));
+// ------------------------------------------------------------- Differ --------
+function differNew() {
+    ensureInitialized();
+    return dittoffi_differ_new();
+}
+function differDiff(differ, items) {
+    ensureInitialized();
+    return dittoffi_differ_diff(differ, items);
+}
+function differFree(differ) {
+    ensureInitialized();
+    dittoffi_differ_free(differ);
+}
+// HACK: underlying safer-ffi doesn't equivalent a CDitto with dittoffi_store_t
+// although they are C aliases so we need to force it's type.
+/** @internal */
+function dittoPointerToStorePointer(dittoHandle) {
+    return {
+        addr: dittoHandle.addr,
+        type: 'dittoffi_store_t const *',
+    };
+}
 // ------------------------------------------------------------- Document ------
 /** @internal */
 function documentSetCBORWithTimestamp(document, path, cbor, timestamp) {
@@ -878,6 +909,12 @@ function queryResultItemJSON(queryResultItemPointer) {
     const jsonBytes = dittoffi_query_result_item_json(queryResultItemPointer);
     return boxCStringIntoString(jsonBytes);
 }
+function queryResultItemNew(jsonData) {
+    ensureInitialized();
+    const result = dittoffi_query_result_item_new(jsonData);
+    throwOnErrorResult(result.error, 'dittoffi_query_result_item_new');
+    return result.success;
+}
 // ------------------------------------------------------------ LiveQuery ------
 /** @internal */
 function liveQueryRegister(ditto, collectionName, query, queryArgsCBOR, orderBy, limit, offset, eventHandler, 
@@ -931,20 +968,6 @@ async function liveQuerySignalAvailableNext(ditto, liveQueryID) {
     ensureInitialized();
     await ditto_live_query_signal_available_next(ditto, liveQueryID);
 }
-// ------------------------------------------------------------ Webhook ------
-/** @internal */
-async function liveQueryWebhookRegister(ditto, collectionName, query, orderBy, limit, offset, url) {
-    ensureInitialized();
-    const collectionNameBuffer = bytesFromString(collectionName);
-    const queryBuffer = bytesFromString(query);
-    const urlBuffer = bytesFromString(url);
-    const { status_code: errorCode, id } = await ditto_live_query_webhook_register_str(ditto, collectionNameBuffer, queryBuffer, orderBy, limit, offset, urlBuffer);
-    if (errorCode !== 0) {
-        throw new Error(errorMessage() ||
-            `\`ditto_live_query_webhook_register_str()\` failed with error code: ${errorCode}`);
-    }
-    return boxCBytesIntoBuffer(id);
-}
 // ------------------------------------------------------ ReadTransaction ------
 /** @internal */
 async function readTransaction(ditto) {
@@ -1225,12 +1248,68 @@ function authenticationStatusFree(ffiAuthenticationStatus) {
     ensureInitialized();
     dittoffi_authentication_status_free(ffiAuthenticationStatus);
 }
+// --------------------------------------------------------- Transactions ------
+function storeTransactions(store) {
+    ensureInitialized();
+    const cborBytes = dittoffi_store_transactions(store);
+    return boxCBytesIntoBuffer(cborBytes);
+}
+async function storeBeginTransaction(store, options) {
+    ensureInitialized();
+    const ffiOptions = {
+        is_read_only: options.isReadOnly,
+        hint: bytesFromString(options.hint),
+    };
+    return new Promise((resolve, reject) => {
+        const callback = wrapBackgroundCbForFFI(reject, (resultObj) => {
+            throwOnErrorResult(resultObj.error, 'dittoffi_store_begin_transaction_async_throws');
+            resolve(resultObj.success);
+        });
+        dittoffi_store_begin_transaction_async_throws(store, ffiOptions, callback);
+    });
+}
+async function transactionCompleteAsync(transaction, action) {
+    ensureInitialized();
+    return new Promise((resolve, reject) => {
+        const callback = wrapBackgroundCbForFFI(reject, (resultObj) => {
+            throwOnErrorResult(resultObj.error, 'dittoffi_transaction_complete_async_throws');
+            const action = resultObj.success;
+            resolve(action);
+        });
+        dittoffi_transaction_complete_async_throws(transaction, action, callback);
+    });
+}
+async function transactionExecuteAsync(transaction, query, queryArgsCbor) {
+    ensureInitialized();
+    return new Promise((resolve, reject) => {
+        const callback = wrapBackgroundCbForFFI(reject, (resultObj) => {
+            throwOnErrorResult(resultObj.error, 'dittoffi_transaction_execute_async_throws');
+            resolve(resultObj.success);
+        });
+        const queryBytes = bytesFromString(query);
+        dittoffi_transaction_execute_async_throws(transaction, queryBytes, queryArgsCbor, callback);
+    });
+}
+function transactionInfo(transaction) {
+    ensureInitialized();
+    const cborBytes = dittoffi_transaction_info(transaction);
+    return boxCBytesIntoBuffer(cborBytes);
+}
+function transactionFree(transaction) {
+    ensureInitialized();
+    dittoffi_transaction_free(transaction);
+}
 // ---------------------------------------------------------------- Ditto ------
 /** @internal */
-function dittoMakeWithTransportConfigMode(path, identityConfig, historyTracking, transportConfigMode) {
+function dittoTryNewBlocking(path, identityConfig, historyTracking, transportConfigMode) {
     ensureInitialized();
+    // Encryption is not supported by the JS SDK.
+    const experimentalPassphrase = null;
     const pathPointer = bytesFromString(path);
-    return dittoffi_make_with_transport_config_mode(pathPointer, identityConfig, historyTracking, transportConfigMode);
+    const experimentalPassphrasePointer = bytesFromString(experimentalPassphrase);
+    const result = dittoffi_ditto_try_new_blocking(pathPointer, identityConfig, historyTracking, experimentalPassphrasePointer, transportConfigMode);
+    throwOnErrorResult(result.error, 'dittoffi_ditto_try_new_blocking');
+    return result.success;
 }
 /** @internal */
 async function dittoGetCollectionNames(self) {
@@ -1403,17 +1482,17 @@ function dittoSmallPeerInfoGetIsEnabled(dittoPointer) {
     return ditto_small_peer_info_get_is_enabled(dittoPointer);
 }
 /** @internal */
-async function dittoSmallPeerInfoSetEnabled(dittoPointer, isEnabled) {
+function dittoSmallPeerInfoSetEnabled(dittoPointer, isEnabled) {
     ensureInitialized();
-    ditto_small_peer_info_set_enabled(dittoPointer, isEnabled);
+    return ditto_small_peer_info_set_enabled(dittoPointer, isEnabled);
 }
 /** @internal */
-async function dittoSmallPeerInfoGetSyncScope(dittoPointer) {
+function dittoSmallPeerInfoGetSyncScope(dittoPointer) {
     ensureInitialized();
     return ditto_small_peer_info_get_sync_scope(dittoPointer);
 }
 /** @internal */
-async function dittoSmallPeerInfoSetSyncScope(dittoPointer, syncScope) {
+function dittoSmallPeerInfoSetSyncScope(dittoPointer, syncScope) {
     ensureInitialized();
     return ditto_small_peer_info_set_sync_scope(dittoPointer, syncScope);
 }
@@ -1448,7 +1527,6 @@ function dittoSmallPeerInfoSetMetadata(dittoPointer, metadata) {
 function dittoRegisterTransportConditionChangedCallback(self, cb) {
     ensureInitialized();
     if (!cb) {
-        // @Konstantin: do we do this?
         ditto_register_transport_condition_changed_callback(self, null);
     }
     else {
@@ -1813,8 +1891,12 @@ const ERROR_CODES = {
     'store/crdt': 'An error occurred processing a CRDT.',
     /** Error for a document not found. */
     'store/document-not-found': 'The document with the provided ID could not be found.',
+    /** Error for writing to a read-only transaction. */
+    'store/transaction-read-only': 'A mutating DQL query was attempted using a read-only transaction.',
     /** Error for an invalid document ID. */
     'store/document-id': 'The document ID is invalid.',
+    /** Error when the chosen persistence directory is already in use by another Ditto instance. */
+    'store/persistence-directory-locked': 'The chosen persistence directory is already in use by another Ditto instance.',
     /** Permission has been denied for a file operation when working with attachments. */
     'store/attachment-file-permission-denied': 'Permission has been denied for a file operation when working with attachments.',
     /** The source file for an attachment does not exist. */
@@ -1854,6 +1936,21 @@ const ERROR_CODES = {
     'validation/not-json-compatible': 'Value is not serializable as JSON.',
     /** A validation error where a size limit was exceeded. */
     'validation/size-limit-exceeded': 'The size limit has been exceeded.',
+    //
+    // Encryption errors
+    //
+    /**
+     * Error when a passphrase was provided but the store is not encrypted.
+     *
+     * This error is not in use for the JavaScript SDK, which currently does not
+     * support encrypted stores.
+     */
+    'encryption/extraneous-passphrase-given': 'Unexpected passphrase provided for the currently unencrypted store.',
+    //
+    // Differ errors
+    //
+    /** */
+    'differ/identity-key-path-invalid': 'A provided identity key path is invalid.',
 };
 
 //
@@ -1897,12 +1994,20 @@ const DEFAULT_STATUS_CODE_MAPPING = {
     StoreQuery: ['query/execution'],
     ParameterQuery: ['query/parameter'],
     //
+    // Encryption errors
+    //
+    EncryptionExtraneousPassphraseGiven: [
+        'encryption/extraneous-passphrase-given',
+    ],
+    //
     // Store errors
     //
     StoreDatabase: ['store/backend'],
     StoreDocumentId: ['store/document-id'],
     StoreDocumentNotFound: ['store/document-not-found'],
+    StoreTransactionReadOnly: ['store/transaction-read-only'],
     Crdt: ['store/crdt'],
+    LockedDittoWorkingDirectory: ['store/persistence-directory-locked'],
     //
     // Validation errors
     //
@@ -1918,17 +2023,12 @@ const DEFAULT_STATUS_CODE_MAPPING = {
     ValidationNotAMap: ['validation/not-an-object'],
     ValidationSizeLimitExceeded: ['validation/size-limit-exceeded'],
     //
+    // Differ errors
+    //
+    DifferIdentityKeyPathInvalid: ['differ/identity-key-path-invalid'],
+    //
     // Lifecycle errors
     //
-    // FIXME: A locked Ditto working directory should eventually not result in an
-    // `internal` error. Here it is mapped to that until
-    // https://github.com/getditto/ditto/issues/12096 is fixed, and this kind of
-    // error is actually thrown instead of the SDK panicking when the persistence
-    // directory is locked.
-    LockedDittoWorkingDirectory: [
-        'internal',
-        'Ditto working directory is locked.',
-    ],
     Transport: ['internal', 'Transport error.'],
     Unsupported: ['sdk/unsupported'],
     Unknown: ['internal/unknown-error'], // May be updated in v5, c.f. #12755
@@ -2174,7 +2274,7 @@ 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.10.2';
+const fullBuildVersionString = '4.11.0-preview.1';
 
 //
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
@@ -4057,6 +4157,10 @@ Bridge.queryResult = new _a(queryResultFree);
 /** @internal */
 Bridge.queryResultItem = new _a(queryResultItemFree);
 /** @internal */
+Bridge.transaction = new _a(transactionFree);
+/** @internal */
+Bridge.differ = new _a(differFree);
+/** @internal */
 Bridge.ditto = new _a(async (dittoPointer) => {
     // HACK: quick and dirty, clear all presence callbacks. This covers presence
     // v1 and v2 callbacks. v3 should be cleared properly by the `Presence`
@@ -4407,6 +4511,9 @@ async function step(closure) {
 // See PR #4833 for details:
 // https://github.com/getditto/ditto/pull/4833
 const performAsyncToWorkaroundNonAsyncFFIAPI = step;
+function capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
 
 //
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
@@ -7914,6 +8021,69 @@ class WriteTransaction {
     }
 }
 
+/**  Encapsulates information about a transaction.
+ *
+ * @see {@link Store.transaction | ditto.store.transaction()}
+ */
+class TransactionInfo {
+    constructor(id, isReadOnly, hint) {
+        this.id = id;
+        this.hint = hint;
+        this.isReadOnly = isReadOnly;
+    }
+}
+/**
+ * Represents a transaction in the Ditto store.
+ *
+ * A `Transaction` groups multiple operations into a single atomic unit,
+ * ensuring that all operations within the transaction are either fully applied
+ * or not applied at all, thereby maintaining data integrity.
+ *
+ * For more information on creating and using transactions, refer to the
+ * {@link Store.transaction | ditto.store.transaction()} method. For a comprehensive guide on
+ * transactions, please visit the
+ * [Ditto documentation](https://docs.ditto.live/sdk/latest/crud/transactions).
+ */
+class Transaction {
+    constructor(store) {
+        this.store = store;
+    }
+    /** Provides information about the current transaction. */
+    get info() {
+        const transactionHandle = Bridge.transaction.handleFor(this);
+        const cborData = transactionInfo(transactionHandle.deref());
+        const options = CBOR.decode(cborData);
+        return new TransactionInfo(options.id, options.is_read_only, options.hint);
+    }
+    async execute(query, queryArguments) {
+        if (typeof query !== 'string') {
+            throw new DittoError('query/invalid', `Expected parameter 'query' to be of type 'string', found: ${typeof query}`);
+        }
+        return this.store.ditto.deferCloseAsync(async () => {
+            let queryArgumentsCBOR = null;
+            if (queryArguments) {
+                try {
+                    const queryArgumentsJSON = desugarJSObject(queryArguments);
+                    queryArgumentsCBOR = CBOR.encode(queryArgumentsJSON);
+                }
+                catch (error) {
+                    throw new DittoError('query/arguments-invalid', `Unable to encode query arguments: ${error.message}`);
+                }
+            }
+            const transactionHandle = Bridge.transaction.handleFor(this);
+            const queryResultPointer = await mapFFIErrorsAsync(async () => transactionExecuteAsync(transactionHandle.deref(), query, queryArgumentsCBOR));
+            return Bridge.queryResult.bridge(queryResultPointer, () => new QueryResult(queryResultPointer));
+        });
+    }
+    // ----------------------------------------------------------- Internal ------
+    /** @internal */
+    async complete(action) {
+        const transactionHandle = Bridge.transaction.handleFor(this);
+        const result = await mapFFIErrorsAsync(async () => await transactionCompleteAsync(transactionHandle.deref(), capitalize(action)));
+        return result.toLowerCase();
+    }
+}
+
 //
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
 //
@@ -7925,6 +8095,22 @@ class WriteTransaction {
  * {@link Ditto} instance via its {@link Ditto.store | store} property.
  */
 class Store {
+    /** @internal */
+    // NOTE: currently, this property will only return the currently _running_
+    // transactions rather than all pending. This means it's at most a single
+    // read-write transaction, and potentially multiple read-only transactions.
+    // Ideally, we'd want to have all _enqueued_ transactions appear here but
+    // we don't have the infrastructure in the Rust Core for this yet.
+    // Therefore, we'll keep this property internal for the time being,
+    // which is still useful for some tests.
+    get transactions() {
+        return this.ditto.deferClose((dittoHandle) => {
+            const storePointer = dittoPointerToStorePointer(dittoHandle.deref());
+            const cborData = storeTransactions(storePointer);
+            const data = CBOR.decode(cborData);
+            return data.map((t) => new TransactionInfo(t.id, t.is_read_only, t.hint));
+        });
+    }
     /**
      * Register a handler to be called whenever a query's results change in the
      * local store.
@@ -8072,31 +8258,6 @@ class Store {
             return mapFFIErrors(() => dittoGetCollectionNames(dittoHandle.deref()));
         });
     }
-    /**
-     * Executes a DQL query and returns matching items as a query result.
-     *
-     * **Note:** only returns results from the local store without waiting for any
-     * {@link SyncSubscription | sync subscriptions} to have caught up with the
-     * latest changes. Only use this method if your program must proceed with
-     * immediate results. Use a {@link StoreObserver | store observer} to receive
-     * updates to query results as soon as they have been synced to this peer.
-     *
-     * @param query A string containing a valid query expressed in DQL.
-     * @param queryArguments An object of values keyed by the placeholder name
-     * without the leading `:`. Example: `{ "name": "John" }` for a query like
-     * `SELECT * FROM people WHERE name = :name`.
-     * @template T The type of items returned by the query. This is a convenience
-     * type that is neither inferred from the `query` parameter nor validated
-     * against it.
-     * @template U The type of the query arguments
-     * @returns A promise for a {@link QueryResult} containing a
-     * {@link QueryResultItem} for each match.
-     * @throws {@link DittoError} `query/invalid`: if `query` argument is not a
-     * string or not valid DQL.
-     * @throws {@link DittoError} `query/arguments-invalid`: if `queryArguments`
-     * argument is invalid (e.g. contains unsupported types).
-     * @throws {@link DittoError} may throw other errors.
-     */
     async execute(query, queryArguments) {
         if (typeof query !== 'string') {
             throw new DittoError('query/invalid', `Expected parameter 'query' to be of type 'string', found: ${typeof query}`);
@@ -8408,6 +8569,131 @@ class Store {
         this.attachmentFetchers = Object.freeze(newAttachmentFetchers);
         return true;
     }
+    // ------------------------------------------ Working with Transactions ------
+    /**
+     * Executes multiple DQL queries within a single atomic transaction.
+     *
+     * This ensures that either all statements are executed successfully, or none
+     * are executed at all, providing strong consistency guarantees. Certain mesh
+     * configurations may impose limitations on these guarantees. For more
+     * details, refer to the [Ditto
+     * documentation](https://docs.ditto.live/sdk/latest/crud/transactions).
+     *
+     * Transactions are initiated as read-write by default, and only one
+     * read-write transaction can be executed at any given time. Any other
+     * read-write transaction started concurrently will wait until the current
+     * transaction has been committed or rolled back. Therefore, it is crucial to
+     * ensure a transaction finishes as early as possible to prevent blocking
+     * other read-write transactions.
+     *
+     * A transaction can also be configured to be read-only using the `isReadOnly`
+     * parameter. Multiple read-only transactions can be executed concurrently.
+     * However, executing a mutating DQL statement in a read-only transaction will
+     * throw an error.
+     *
+     * If errors occur in an `execute()` call within a transaction block and the
+     * error is caught and handled within the block, the transaction will continue
+     * to run and not be rolled back. When an error is thrown at any point inside
+     * the transaction block or while committing the transaction, the transaction
+     * is implicitly rolled back, and the error is propagated to the caller.
+     *
+     * When a Ditto instance goes out of scope, it will drive all pending
+     * transactions to completion before being shut down.
+     *
+     * **Warning:** Calling `ditto.store.execute()` or creating a nested
+     * transaction within a transaction may lead to a deadlock.
+     *
+     * The transaction closure provided here can either return a
+     * {@link TransactionCompletionAction} or an arbitrary value, either of which
+     * will then also be returned by the call to this method itself. If one of the
+     * {@link TransactionCompletionAction} values `'commit'` or `'rollback'` is
+     * returned from the closure, that action is applied. If any other value,
+     * including `null`, is returned, the transaction is committed unless an error
+     * is thrown from the closure.
+     *
+     * Example usage (explicit completion):
+     *
+     * ```ts
+     * await store.transaction(async (transaction) => {
+     *   // ...
+     *   return 'commit'
+     * })
+     * ```
+     *
+     * Example usage (returning a custom type):
+     *
+     * ```ts
+     * interface UserData {
+     *   id: string
+     *   name: string
+     * }
+     *
+     * const user: UserData = await store.transaction<UserData>(async (transaction) => {
+     *   // ...
+     *   return { id: 'u1', name: 'Alice' }
+     * })
+     * ```
+     *
+     * @template T The type of the value returned from the `scope` function.
+     * Defaults to `TransactionCompletionAction`.
+     * @param {Function} scope A function that provides access to a transaction
+     * object to execute DQL queries.
+     * @param {TransactionOptions} [options] Optional settings for the
+     * transaction.
+     * @returns {Promise<T>} A promise that resolves to the value returned by the
+     * scope function. If that value is a {@link TransactionCompletionAction}, the
+     * transaction is completed with the same action.
+     * @throws {DittoError} Throws `DittoError` of `store/transaction-read-only`
+     * if a mutating query is executed in a read-only transaction.
+     * @throws {DittoError} May throw other `DittoError`s.
+     * @throws Will rethrow any error thrown within the `scope` function.
+     * @see {@link Transaction}
+     * @see {@link TransactionOptions}
+     */
+    async transaction(scope, options = {}) {
+        return this.ditto.deferCloseAsync(async () => {
+            if ((options === null || options === void 0 ? void 0 : options.isReadOnly) && typeof options.isReadOnly !== 'boolean')
+                throw new TypeError("Expected 'options.isReadOnly' to be a boolean");
+            if ((options === null || options === void 0 ? void 0 : options.hint) && typeof options.hint !== 'string')
+                throw new TypeError("Expected 'options.hint' to be a string");
+            const transaction = await this.beginTransaction(options);
+            // REFACTOR: completing with action `rollback` should never fail even
+            // though the API is fallible (because `commit` _can_ fail). The Rust Core
+            // will log an error if anything goes wrong here, so we simply ignore any
+            // `transaction.complete()` errors.
+            let result;
+            try {
+                result = await scope(transaction);
+            }
+            catch (error) {
+                await transaction.complete('rollback');
+                throw error;
+            }
+            if (result === 'rollback' || result === 'commit') {
+                return (await transaction.complete(result));
+            }
+            await transaction.complete('commit');
+            return result;
+        });
+    }
+    // ----------------------------------------------------------- Internal ------
+    /** @internal */
+    async beginTransaction(options = {}) {
+        return this.ditto.deferCloseAsync(async (dittoHandle) => {
+            var _a, _b;
+            // We explicitely set the default value here to maintain consistency with
+            // other API that we already have, while acknowledging that default values
+            // are generally better to be dictated from Core (via a factory method).
+            const isReadOnly = (_a = options.isReadOnly) !== null && _a !== void 0 ? _a : false;
+            const hint = (_b = options.hint) !== null && _b !== void 0 ? _b : null;
+            const storePointer = dittoPointerToStorePointer(dittoHandle.deref());
+            const transactionPointer = await storeBeginTransaction(storePointer, {
+                isReadOnly,
+                hint,
+            });
+            return Bridge.transaction.bridge(transactionPointer, () => new Transaction(this));
+        });
+    }
     /** @internal */
     close() {
         for (const observer of this.observers)
@@ -8417,17 +8703,6 @@ class Store {
         // NOTE: live query webhook is taken care of by the FFI's
         // `ditto_shutdown()`, no need to unregister it here.
     }
-    /**
-     * Private method, used only by the Portal https://github.com/getditto/ditto/pull/3652
-     * @internal
-     */
-    async registerLiveQueryWebhook(collectionName, query, url) {
-        return this.ditto.deferCloseAsync(async (dittoHandle) => {
-            const validatedQuery = validateQuery(query);
-            const idCBOR = await liveQueryWebhookRegister(dittoHandle.deref(), collectionName, validatedQuery, [], 0, 0, url);
-            return new DocumentID(idCBOR, true);
-        });
-    }
 }
 
 //
@@ -9323,8 +9598,8 @@ class SmallPeerInfo {
     set isEnabled(newValue) {
         if (typeof newValue !== 'boolean')
             throw new TypeError(`Expected boolean, got ${typeof newValue}`);
-        void this.ditto.deferCloseAsync(async (dittoHandle) => {
-            return dittoSmallPeerInfoSetEnabled(dittoHandle.deref(), newValue);
+        this.ditto.deferClose((dittoHandle) => {
+            dittoSmallPeerInfoSetEnabled(dittoHandle.deref(), newValue);
         });
     }
     /**
@@ -9385,15 +9660,35 @@ class SmallPeerInfo {
             dittoSmallPeerInfoSetMetadata(dittoHandle.deref(), metadata);
         });
     }
+    /**
+     * Determines which "kind" of peers the small peer info will be replicated to.
+     *
+     * Defaults to `LocalPeerOnly`, which means no replication. Set this to
+     * `BigPeerOnly` to replicate collected info to the Big Peer.
+     *
+     * @throws when set to a value other than `BigPeerOnly` or `LocalPeerOnly`.
+     */
+    get syncScope() {
+        return this.ditto.deferClose((dittoHandle) => {
+            return dittoSmallPeerInfoGetSyncScope(dittoHandle.deref());
+        });
+    }
+    set syncScope(syncScope) {
+        this.ditto.deferClose((dittoHandle) => {
+            return dittoSmallPeerInfoSetSyncScope(dittoHandle.deref(), syncScope);
+        });
+    }
     /**
      * 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.
      */
     async getSyncScope() {
-        return this.ditto.deferCloseAsync(async (dittoHandle) => {
+        return this.ditto.deferClose((dittoHandle) => {
             return dittoSmallPeerInfoGetSyncScope(dittoHandle.deref());
         });
     }
@@ -9404,9 +9699,10 @@ 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.
      */
     async setSyncScope(syncScope) {
-        return this.ditto.deferCloseAsync(async (dittoHandle) => {
+        return this.ditto.deferClose((dittoHandle) => {
             return dittoSmallPeerInfoSetSyncScope(dittoHandle.deref(), syncScope);
         });
     }
@@ -9581,7 +9877,7 @@ class Ditto {
         // determined for P2P transports based on the environment. We specify this here by setting
         // `transportConfigMode` to 'PlatformDependent'.
         const transportConfigMode = 'PlatformDependent';
-        const dittoPointer = dittoMakeWithTransportConfigMode(this.persistenceDirectory, identityConfig, historyTracking, transportConfigMode);
+        const dittoPointer = mapFFIErrors(() => dittoTryNewBlocking(this.persistenceDirectory, identityConfig, historyTracking, transportConfigMode));
         const appID = dittoAuthClientGetAppID(dittoPointer);
         const siteID = dittoAuthClientGetSiteID(dittoPointer);
         Bridge.ditto.bridge(dittoPointer, this);
@@ -9753,11 +10049,13 @@ class Ditto {
             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.
+                // 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
-                validatedPath = `\\\\?\\${path.resolve(validatedPath)}`;
+                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
@@ -10227,6 +10525,58 @@ const isDirectoryWritable = (directoryPath) => {
     return true;
 };
 
+//
+// Copyright © 2025 DittoLive Incorporated. All rights reserved.
+//
+/**
+ * Represents a diff between two arrays.
+ *
+ * Create a diff between arrays of {@link QueryResultItem} using a {@link Differ}.
+ */
+class Diff {
+    constructor(cborData) {
+        const object = CBOR.decode(cborData);
+        this.insertions = object.insertions;
+        this.deletions = object.deletions;
+        this.updates = object.updates;
+        this.moves = object.moves.map(([from, to]) => ({ from, to }));
+    }
+}
+/**
+ * Calculates diffs between arrays of {@link QueryResultItem}.
+ *
+ * Use a {@link Differ} with a {@link StoreObserver} to get the diff between
+ * subsequent query results delivered by the store observer.
+ */
+class Differ {
+    /** Create a new differ. */
+    constructor() {
+        const ffiDiffer = differNew();
+        return Bridge.differ.bridge(ffiDiffer, this);
+    }
+    /**
+     * Calculate the diff of the provided items against the last set of items that
+     * were passed to this differ.
+     *
+     * The returned {@link Diff} identifies changes from the old array of items
+     * to the new array of items using indices into both arrays.
+     *
+     * Initially, the differ has no items, so the first call to this method will
+     * always return a diff showing all items as insertions.
+     *
+     * The identity of items is determined by their `_id` field.
+     */
+    diff(items) {
+        const pointers = items.map((item) => item.deref());
+        const cborData = differDiff(this.deref(), pointers);
+        return new Diff(cborData);
+    }
+    /** @internal */
+    deref() {
+        return Bridge.differ.handleFor(this).deref();
+    }
+}
+
 //
 // Copyright © 2023 DittoLive Incorporated. All rights reserved.
 //
@@ -10314,8 +10664,7 @@ class QueryResultItem {
      * method once and keep it for as long as needed.
      */
     cborData() {
-        const resultItemHandle = Bridge.queryResultItem.handleFor(this);
-        return queryResultItemCBOR(resultItemHandle.deref());
+        return queryResultItemCBOR(this.deref());
     }
     /**
      * Returns the content of the item as a JSON string.
@@ -10324,8 +10673,7 @@ class QueryResultItem {
      * method once and keep it for as long as needed.
      */
     jsonString() {
-        const resultItemHandle = Bridge.queryResultItem.handleFor(this);
-        return queryResultItemJSON(resultItemHandle.deref());
+        return queryResultItemJSON(this.deref());
     }
     // ----------------------------------------------------------- Internal ------
     /**
@@ -10339,6 +10687,15 @@ class QueryResultItem {
     }
     /** @internal */
     constructor() { }
+    /** @internal */
+    static fromJSON(jsonData) {
+        const encodedData = new TextEncoder().encode(jsonData);
+        return Bridge.queryResultItem.bridge(queryResultItemNew(encodedData));
+    }
+    /** @internal */
+    deref() {
+        return Bridge.queryResultItem.handleFor(this).deref();
+    }
 }
 
 /**
@@ -10375,6 +10732,8 @@ Bridge.attachment.registerType(Attachment);
 Bridge.connectionRequest.registerType(ConnectionRequest);
 Bridge.document.registerType(Document);
 Bridge.queryResultItem.registerType(QueryResultItem);
+Bridge.differ.registerType(Differ);
+Bridge.transaction.registerType(Transaction);
 Bridge.queryResult.registerType(QueryResult);
 Bridge.mutableDocument.registerType(MutableDocument);
 Bridge.ditto.registerType(Ditto);
@@ -10391,6 +10750,8 @@ exports.Collection = Collection;
 exports.CollectionsEvent = CollectionsEvent;
 exports.ConnectionRequest = ConnectionRequest;
 exports.Counter = Counter;
+exports.Diff = Diff;
+exports.Differ = Differ;
 exports.Ditto = Ditto;
 exports.DittoError = DittoError;
 exports.Document = Document;
@@ -10424,6 +10785,8 @@ exports.StoreObserver = StoreObserver;
 exports.Subscription = Subscription;
 exports.Sync = Sync;
 exports.SyncSubscription = SyncSubscription;
+exports.Transaction = Transaction;
+exports.TransactionInfo = TransactionInfo;
 exports.TransportConfig = TransportConfig;
 exports.UpdateResult = UpdateResult;
 exports.UpdateResultsMap = UpdateResultsMap;