@matter/general 0.12.4-alpha.0-20250211-56b2c53a0 → 0.12.4-alpha.0-20250213-1187f81eb

package/src/transaction/Participant.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MaybePromise } from "#util/Promises.js";
+
+/**
+ * Components with support for transactionality implement this interface.
+ */
+export interface Participant {
+    /**
+     * Description used in error messages.
+     */
+    toString(): string;
+
+    /**
+     * The "role" of a participant is an optional key you may use to retrieve
+     * a participant from the transaction.
+     */
+    role?: {};
+
+    /**
+     * Pre-commit logic.
+     *
+     * Pre-commit logic returns a boolean indicating whether it performed an action that affects state.  The transaction
+     * will cycle through participants continuously until all participants return false.
+     *
+     * Thus `preCommit` implementations must be stateful and expect to be invoked more than once for a single
+     * transaction.
+     */
+    preCommit?: () => MaybePromise<boolean>;
+
+    /**
+     * Commit phase one.
+     */
+    commit1(): MaybePromise;
+
+    /**
+     * Commit phase two.
+     */
+    commit2(): MaybePromise;
+
+    /**
+     * Post-commit logic.
+     */
+    postCommit?: () => MaybePromise;
+
+    /**
+     * Drop isolated writes and revert to original canonical source.
+     */
+    rollback(): MaybePromise;
+}

package/src/transaction/Resource.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Transaction } from "./Transaction.js";
+
+/**
+ * A transaction resource is the target a {@link Participant} is mutating. The {@link Coordinator} tracks the state of
+ * resources to ensure only a single transaction ever has exclusive access.
+ */
+export interface Resource {
+    /**
+     * Textual description of the resource used in error messages.
+     */
+    toString(): string;
+
+    /**
+     * Locking transaction, maintained by {@link Transaction}.
+     */
+    lockedBy?: Transaction;
+
+    /**
+     * Inform {@link Transaction} this resource is a standin for another resource.
+     */
+    [Resource.reference]?: Resource;
+}
+
+export namespace Resource {
+    export const reference = Symbol("reference");
+
+    export function isLocked(resource: Resource) {
+        while (resource[Resource.reference] !== undefined) {
+            resource = resource[Resource.reference];
+        }
+        return resource.lockedBy !== undefined;
+    }
+}

package/src/transaction/ResourceSet.ts

@@ -0,0 +1,160 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "#log/Logger.js";
+import { describeList } from "#util/String.js";
+import { SynchronousTransactionConflictError, TransactionDeadlockError, TransactionFlowError } from "./errors.js";
+import { Resource } from "./Resource.js";
+import type { Transaction } from "./Transaction.js";
+
+const logger = Logger.get("ResourceSet");
+
+/**
+ * An internal set of resources supporting bulk operations for {@link Transaction}.
+ */
+export class ResourceSet {
+    #transaction: Transaction;
+    #resources = new Set<Resource>();
+
+    constructor(transaction: Transaction, resources: Iterable<Resource> = transaction.resources) {
+        this.#transaction = transaction;
+        for (let resource of resources) {
+            while (resource[Resource.reference]) {
+                resource = resource[Resource.reference];
+            }
+            this.#resources.add(resource);
+        }
+    }
+
+    /**
+     * Wait until the resources have no exclusive transactions and then lock.
+     */
+    async acquireLocks() {
+        while (true) {
+            let blockedBy: undefined | Set<Transaction>;
+
+            for (const resource of this.#resources) {
+                const lockedBy = resource.lockedBy;
+                if (lockedBy && lockedBy !== this.#transaction) {
+                    if (!blockedBy) {
+                        blockedBy = new Set();
+                    }
+                    blockedBy.add(lockedBy);
+                }
+            }
+
+            if (!blockedBy) {
+                break;
+            }
+
+            this.#detectDeadlock(blockedBy);
+
+            await this.#transaction.waitFor(blockedBy);
+        }
+
+        return this.acquireLocksSync();
+    }
+
+    /**
+     * Acquire locks synchronously.
+     *
+     * Throws an error if resources aren't lockable.
+     */
+    acquireLocksSync() {
+        const toLock = new Set<Resource>();
+        const blocked = new Set<Resource>();
+        for (const resource of this.#resources) {
+            if (resource.lockedBy) {
+                if (resource.lockedBy === this.#transaction) {
+                    continue;
+                }
+                logger.warn("Transaction", this.#transaction.via, "blocked by", resource.lockedBy.via);
+                blocked.add(resource);
+            }
+            toLock.add(resource);
+        }
+        if (blocked.size) {
+            logger.warn("You may need to await transaction.begin() to acquire locks asynchronously");
+            const names = [...blocked].map(s => s.toString());
+            throw new SynchronousTransactionConflictError(`Cannot lock ${describeList("and", ...names)} synchronously`);
+        }
+
+        // Update resource status
+        for (const resource of toLock) {
+            resource.lockedBy = this.#transaction;
+        }
+
+        return toLock;
+    }
+
+    /**
+     * Release locks.
+     */
+    releaseLocks() {
+        const unlocked = new Set<Resource>();
+
+        for (const resource of this.#resources) {
+            if (resource.lockedBy === this.#transaction) {
+                delete resource.lockedBy;
+                unlocked.add(resource);
+            }
+        }
+
+        return unlocked;
+    }
+
+    /**
+     * Ensure that a transaction that is committing or rolling back has all resources locked.
+     *
+     * This is just a sanity check.
+     */
+    assertResourcesAreLocked(transaction: Transaction, why: string) {
+        for (const resource of transaction.resources) {
+            if (resource.lockedBy !== transaction) {
+                throw new TransactionFlowError(`Transaction attempted ${why} but does not have all resources locked`);
+            }
+        }
+    }
+
+    /**
+     * If two transactions would block each other then we would have a deadlock.
+     *
+     * This is unlikely but not impossible.  It can happen if an endpoint is added to an exclusive transaction but a
+     * second transaction already has exclusivity on the new endpoint *and* is waiting on the first transaction.
+     *
+     * So... detect if the wait graph would have cycles if we an endpoint.  If so, throw an error.
+     */
+    #detectDeadlock(blockedBy: Set<Transaction>) {
+        // Recursively examine the transaction holding each resource we wish to lock.  If any of them are waiting for a
+        // resource that I have locked then we've detected deadlock
+        const examined = new Set<Transaction>();
+        const examineBlocker = (transaction: Transaction) => {
+            examined.add(transaction);
+            if (transaction === this.#transaction) {
+                throw new TransactionDeadlockError(
+                    "Resource deadlock detected, write operation cannot proceed.  " +
+                        "To prevent this you can await transaction.begin() before modifying state",
+                );
+            }
+
+            if (transaction.waitingOn) {
+                for (const blocker of transaction.waitingOn) {
+                    if (!examined.has(blocker)) {
+                        examineBlocker(blocker);
+                    }
+                }
+            }
+        };
+
+        for (const transaction of blockedBy) {
+            examineBlocker(transaction);
+        }
+    }
+
+    [Symbol.iterator]() {
+        return this.#resources[Symbol.iterator]();
+    }
+}

package/src/transaction/Status.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { TransactionFlowError } from "./errors.js";
+import type { Transaction } from "./Transaction.js";
+
+/**
+ * The lifecycle of a transaction adheres to the following discrete stages.
+ */
+export enum Status {
+    /**
+     * Transaction may be used only for read operations.
+     */
+    ReadOnly = "read only",
+
+    /**
+     * Transaction is registered but there are no ACID guarantees.
+     */
+    Shared = "shared",
+
+    /**
+     * Transaction is waiting to obtain exclusive access to resources.
+     */
+    Waiting = "waiting",
+
+    /**
+     * Transaction has exclusive access.  Reads will maintain consistency
+     * and writes are allowed.
+     */
+    Exclusive = "exclusive",
+
+    /**
+     * Transaction is in the process of committing, phase one.
+     */
+    CommittingPhaseOne = "committing phase one",
+
+    /**
+     * Transaction is in the process of committing, phase two.
+     */
+    CommittingPhaseTwo = "committing phase two",
+
+    /**
+     * Transaction is in the process of rolling back.
+     */
+    RollingBack = "rolling back",
+
+    /**
+     * Transaction is destroyed, no further operations permitted.
+     */
+    Destroyed = "destroyed",
+}
+
+export namespace Status {
+    export function assert(transaction: Transaction, acceptable: Status[], target: Status) {
+        if (!acceptable.includes(transaction.status)) {
+            throw new TransactionFlowError(
+                `Cannot transition transaction from ${formatStatus(transaction.status)} to ${formatStatus(target)}`,
+            );
+        }
+    }
+
+    export function formatStatus(status: Status) {
+        return `<${status}>`;
+    }
+}

package/src/transaction/Transaction.ts

@@ -0,0 +1,190 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MaybePromise } from "#util/Promises.js";
+import { Participant } from "./Participant.js";
+import { Resource } from "./Resource.js";
+import { ResourceSet } from "./ResourceSet.js";
+import { Status } from "./Status.js";
+import { ReadOnlyTransaction, act } from "./Tx.js";
+
+/**
+ * .
+ *
+ * Transactions are either shared (for reads) or exclusive (for writes). Exclusive transactions do not block shared
+ * transactions but state updates will not be visible until the transaction completes.
+ *
+ * Writes do block other writes.  Transactions start automatically when a write occurs.  Since this usually happens
+ * synchronously, the best Matter.js can do is throw an error if two write transactions would conflict.  However, you
+ * can avoid this by using {@link begin} which will wait for other transactions to complete before acquiring resource
+ * locks.
+ *
+ * Persistence is implemented by a list of participants.  Commits are two phase.  If an error throws in phase one all
+ * participants roll back. An error in phase 2 could result in data inconsistency as we don't have any form of retry as
+ * of yet.
+ *
+ * TODO - does prevent deadlock but we should probably add a timeout for resource locking
+ */
+export interface Transaction {
+    /**
+     * Diagnostic description of the transaction's source.
+     */
+    readonly via: string;
+
+    /**
+     * The status of the transaction.
+     */
+    readonly status: Status;
+
+    /**
+     * Transaction participants.
+     */
+    readonly participants: Set<Participant>;
+
+    /**
+     * Resources addressed by the participants.
+     */
+    readonly resources: Set<Resource>;
+
+    /**
+     * The transactions currently blocking this transaction, if any.
+     */
+    readonly waitingOn: Iterable<Transaction> | undefined;
+
+    /**
+     * Listen for transaction commit or roll back.  This may occur more than once for a given.
+     */
+    onShared(actor: () => void, once?: boolean): void;
+
+    /**
+     * Listen for {@link Transaction.status} close.
+     */
+    onClose(actor: () => void): void;
+
+    /**
+     * Add {@link Resources} to the transaction.
+     *
+     * If the transaction is exclusive (writing) the transaction will acquire the lock on each {@link ResourceType},
+     * waiting for other writers to finish if necessary.
+     */
+    addResources(...resources: Resource[]): Promise<void>;
+
+    /**
+     * Add {@link ResourceType}s to the transaction synchronously.
+     *
+     * Unlike {@link addResources}, this method will throw an error if the
+     * transaction is exclusive and the resources cannot be locked.
+     */
+    addResourcesSync(...resources: Resource[]): void;
+
+    /**
+     * Begin an exclusive transaction.
+     *
+     * Transactions begin automatically on write but there are a few reasons you may want to use this method to start an
+     * exclusive transaction explicitly:
+     *
+     *   1. Automatic transactions are started in a synchronous context so conflicting transactions will throw an error.
+     *      If you start a transaction, your code will await any transaction that would otherwise throw an error.
+     *
+     *   2. Transaction isolation means your view of data may become stale if a write occurs in another transaction.
+     *      Once you start a transaction you block other writers so can be assured you're dealing with newest state.
+     *
+     *   3. Say transaction A has an exclusive lock on resource 1 and awaits resource 2.  Transaction B has an exclusive
+     *      lock on resource 2. Transaction B cannot then await resource 1 without causing a deadlock.  Matter.js will
+     *      detect the deadlock and throw an error. One way to prevent this is to begin a transaction and acquire locks
+     *      in a specific order.
+     *
+     * None of the issues above are likely and are probably not a concern for your application.  If you do encounter
+     * these issues the error message will suggest solutions.
+     */
+    begin(): Promise<void>;
+
+    /**
+     * Begin an exclusive transaction in a synchronous context.
+     *
+     * Unlike {@link begin}, this method will throw an error if any participant has already joined an exclusive
+     * transaction.
+     */
+    beginSync(): void;
+
+    /**
+     * Add {@link ParticipantType}s to the transaction.
+     */
+    addParticipants(...participants: Participant[]): void;
+
+    /**
+     * Retrieve a participant with a specific role.
+     */
+    getParticipant(role: {}): Participant | undefined;
+
+    /**
+     * Commit the transaction.
+     *
+     * Matter.js commits automatically when an interaction completes.  You may commit manually to publish your changes
+     * mid-interaction.
+     *
+     * After commit an exclusive transaction becomes shared and data references refresh to the most recent value.
+     */
+    commit(): MaybePromise;
+
+    /**
+     * Roll back the transaction.
+     *
+     * Matter.js rolls back automatically when an interaction fails.  You may roll back manually to undo your changes
+     * mid-interaction.
+     *
+     * After rollback an exclusive transaction becomes shared and data references refresh to the most recent value.
+     */
+    rollback(): MaybePromise;
+
+    /**
+     * Wait for a set of transactions to complete.
+     *
+     * @param others the set of transactions to await; cleared on return
+     */
+    waitFor(others: Set<Transaction>): Promise<void>;
+}
+
+type StatusType = Status;
+type ResourceType = Resource;
+type ResourceSetType = ResourceSet;
+type ParticipantType = Participant;
+
+export const Transaction = {
+    /**
+     * Perform a transactional operation.  This is the only way to obtain a read/write transaction.
+     *
+     * The transaction will commit automatically if it is exclusive (write mode) after the actor returns.
+     *
+     * The transaction is destroyed when {@link act} returns.  You will receive an error if you access it after it is
+     * destroyed.
+     */
+    act<T>(via: string, actor: (transaction: Transaction) => MaybePromise<T>): MaybePromise<T> {
+        // This function is replaced below so do not edit
+        return act(via, actor);
+    },
+
+    ReadOnly: ReadOnlyTransaction,
+
+    Status,
+
+    Resource,
+
+    [Symbol.toStringTag]: "Transaction",
+};
+
+// This is functionally equivalent to the definition above but removes a stack frame
+Transaction.act = act;
+
+export namespace Transaction {
+    export type Status = StatusType;
+
+    export type Resource = ResourceType;
+
+    export type ResourceSet = ResourceSetType;
+
+    export type Participant = ParticipantType;
+}