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

package/dist/esm/transaction/Status.js

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { TransactionFlowError } from "./errors.js";
+var Status = /* @__PURE__ */ ((Status2) => {
+  Status2["ReadOnly"] = "read only";
+  Status2["Shared"] = "shared";
+  Status2["Waiting"] = "waiting";
+  Status2["Exclusive"] = "exclusive";
+  Status2["CommittingPhaseOne"] = "committing phase one";
+  Status2["CommittingPhaseTwo"] = "committing phase two";
+  Status2["RollingBack"] = "rolling back";
+  Status2["Destroyed"] = "destroyed";
+  return Status2;
+})(Status || {});
+((Status2) => {
+  function assert(transaction, acceptable, target) {
+    if (!acceptable.includes(transaction.status)) {
+      throw new TransactionFlowError(
+        `Cannot transition transaction from ${formatStatus(transaction.status)} to ${formatStatus(target)}`
+      );
+    }
+  }
+  Status2.assert = assert;
+  function formatStatus(status) {
+    return `<${status}>`;
+  }
+  Status2.formatStatus = formatStatus;
+})(Status || (Status = {}));
+export {
+  Status
+};
+//# sourceMappingURL=Status.js.map

package/dist/esm/transaction/Status.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/transaction/Status.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAS,4BAA4B;AAM9B,IAAK,SAAL,kBAAKA,YAAL;AAIH,EAAAA,QAAA,cAAW;AAKX,EAAAA,QAAA,YAAS;AAKT,EAAAA,QAAA,aAAU;AAMV,EAAAA,QAAA,eAAY;AAKZ,EAAAA,QAAA,wBAAqB;AAKrB,EAAAA,QAAA,wBAAqB;AAKrB,EAAAA,QAAA,iBAAc;AAKd,EAAAA,QAAA,eAAY;AAxCJ,SAAAA;AAAA,GAAA;AAAA,CA2CL,CAAUA,YAAV;AACI,WAAS,OAAO,aAA0B,YAAsB,QAAgB;AACnF,QAAI,CAAC,WAAW,SAAS,YAAY,MAAM,GAAG;AAC1C,YAAM,IAAI;AAAA,QACN,sCAAsC,aAAa,YAAY,MAAM,CAAC,OAAO,aAAa,MAAM,CAAC;AAAA,MACrG;AAAA,IACJ;AAAA,EACJ;AANO,EAAAA,QAAS;AAQT,WAAS,aAAa,QAAgB;AACzC,WAAO,IAAI,MAAM;AAAA,EACrB;AAFO,EAAAA,QAAS;AAAA,GATH;",
+  "names": ["Status"]
+}

package/dist/esm/transaction/Transaction.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @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";
+/**
+ * .
+ *
+ * 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 declare 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>;
+    ReadOnly: {
+        "__#14458@#participants": Set<Participant>;
+        "__#14458@#roles": Map<{}, Participant>;
+        "__#14458@#resources": Set<Resource>;
+        "__#14458@#status": Status;
+        "__#14458@#waitingOn"?: Iterable<Transaction>;
+        "__#14458@#via": string;
+        "__#14458@#shared"?: import("../index.js").Observable<[]>;
+        "__#14458@#closed"?: import("../index.js").Observable<[]>;
+        "__#14458@#isAsync": boolean;
+        close(): void;
+        readonly via: string;
+        readonly status: Status;
+        readonly participants: Set<Participant>;
+        readonly resources: Set<Resource>;
+        readonly waitingOn: Iterable<Transaction> | undefined;
+        get isAsync(): boolean;
+        set isAsync(isAsync: true);
+        onShared(listener: () => void, once?: boolean): void;
+        onClose(listener: () => void): void;
+        addResources(...resources: Resource[]): Promise<void>;
+        addResourcesSync(...resources: Resource[]): void;
+        begin(): Promise<void>;
+        beginSync(): void;
+        addParticipants(...participants: Participant[]): void;
+        getParticipant(role: {}): Participant | undefined;
+        commit(): MaybePromise;
+        rollback(): Promise<void> | undefined;
+        waitFor(others: Set<Transaction>): Promise<void>;
+        toString(): string;
+        "__#14458@#finalize"(status: Status, why: string, finalizer: () => MaybePromise): Promise<void> | undefined;
+        "__#14458@#executePreCommit"(): MaybePromise<void>;
+        "__#14458@#executeCommit"(): MaybePromise;
+        "__#14458@#executeCommit1"(): MaybePromise;
+        "__#14458@#executeCommit2"(): Promise<void> | undefined;
+        "__#14458@#executePostCommit"(participants: Participant[]): MaybePromise;
+        "__#14458@#executeRollback"(): Promise<void> | undefined;
+        "__#14458@#locksChanged"(resources: Set<Resource>, how?: string): void;
+        "__#14458@#assertAvailable"(): void;
+    };
+    Status: typeof Status;
+    Resource: typeof Resource;
+    [Symbol.toStringTag]: string;
+};
+export declare namespace Transaction {
+    type Status = StatusType;
+    type Resource = ResourceType;
+    type ResourceSet = ResourceSetType;
+    type Participant = ParticipantType;
+}
+export {};
+//# sourceMappingURL=Transaction.d.ts.map

package/dist/esm/transaction/Transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transaction.d.ts","sourceRoot":"","sources":["../../../src/transaction/Transaction.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,WAAW;IACxB;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC;IAEtD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAElD;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAEjC;;;;;OAKG;IACH,YAAY,CAAC,GAAG,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtD;;;;;OAKG;IACH,gBAAgB,CAAC,GAAG,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAEjD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;;OAKG;IACH,SAAS,IAAI,IAAI,CAAC;IAElB;;OAEG;IACH,eAAe,CAAC,GAAG,YAAY,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAEtD;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,EAAE,GAAG,WAAW,GAAG,SAAS,CAAC;IAElD;;;;;;;OAOG;IACH,MAAM,IAAI,YAAY,CAAC;IAEvB;;;;;;;OAOG;IACH,QAAQ,IAAI,YAAY,CAAC;IAEzB;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED,KAAK,UAAU,GAAG,MAAM,CAAC;AACzB,KAAK,YAAY,GAAG,QAAQ,CAAC;AAC7B,KAAK,eAAe,GAAG,WAAW,CAAC;AACnC,KAAK,eAAe,GAAG,WAAW,CAAC;AAEnC,eAAO,MAAM,WAAW;IACpB;;;;;;;OAOG;QACC,CAAC,OAAO,MAAM,SAAS,CAAC,WAAW,EAAE,WAAW,KAAK,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAY7F,CAAC;AAKF,yBAAiB,WAAW,CAAC;IACzB,KAAY,MAAM,GAAG,UAAU,CAAC;IAEhC,KAAY,QAAQ,GAAG,YAAY,CAAC;IAEpC,KAAY,WAAW,GAAG,eAAe,CAAC;IAE1C,KAAY,WAAW,GAAG,eAAe,CAAC;CAC7C"}

package/dist/esm/transaction/Transaction.js

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Resource } from "./Resource.js";
+import { Status } from "./Status.js";
+import { ReadOnlyTransaction, act } from "./Tx.js";
+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(via, actor) {
+    return act(via, actor);
+  },
+  ReadOnly: ReadOnlyTransaction,
+  Status,
+  Resource,
+  [Symbol.toStringTag]: "Transaction"
+};
+Transaction.act = act;
+export {
+  Transaction
+};
+//# sourceMappingURL=Transaction.js.map

package/dist/esm/transaction/Transaction.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/transaction/Transaction.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,SAAS,gBAAgB;AAEzB,SAAS,cAAc;AACvB,SAAS,qBAAqB,WAAW;AAgJlC,MAAM,cAAc;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASvB,IAAO,KAAa,OAAuE;AAEvF,WAAO,IAAI,KAAK,KAAK;AAAA,EACzB;AAAA,EAEA,UAAU;AAAA,EAEV;AAAA,EAEA;AAAA,EAEA,CAAC,OAAO,WAAW,GAAG;AAC1B;AAGA,YAAY,MAAM;",
+  "names": []
+}

package/dist/esm/transaction/Tx.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MaybePromise } from "#util/Promises.js";
+import type { Participant } from "./Participant.js";
+import type { Resource } from "./Resource.js";
+import { Status } from "./Status.js";
+import { Transaction } from "./Transaction.js";
+/**
+ * This is the only public interface to this file.
+ */
+export declare function act<T>(via: string, actor: (transaction: Transaction) => T): T;
+/**
+ * The concrete implementation of the Transaction interface.
+ */
+declare class Tx implements Transaction {
+    #private;
+    constructor(via: string, readonly?: boolean);
+    close(): void;
+    get via(): string;
+    get status(): Status;
+    get participants(): Set<Participant>;
+    get resources(): Set<Resource>;
+    get waitingOn(): Iterable<Transaction> | undefined;
+    get isAsync(): boolean;
+    set isAsync(isAsync: true);
+    onShared(listener: () => void, once?: boolean): void;
+    onClose(listener: () => void): void;
+    addResources(...resources: Resource[]): Promise<void>;
+    addResourcesSync(...resources: Resource[]): void;
+    begin(): Promise<void>;
+    beginSync(): void;
+    addParticipants(...participants: Participant[]): void;
+    getParticipant(role: {}): Participant | undefined;
+    commit(): MaybePromise;
+    rollback(): Promise<void> | undefined;
+    waitFor(others: Set<Transaction>): Promise<void>;
+    toString(): string;
+}
+/**
+ * A read-only offline transaction you may use without context.
+ */
+export declare const ReadOnlyTransaction: Tx;
+export {};
+//# sourceMappingURL=Tx.d.ts.map

package/dist/esm/transaction/Tx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tx.d.ts","sourceRoot":"","sources":["../../../src/transaction/Tx.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAU/C;;GAEG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,CAAC,GAAG,CAAC,CA8F7E;AAED;;GAEG;AACH,cAAM,EAAG,YAAW,WAAW;;gBAWf,GAAG,EAAE,MAAM,EAAE,QAAQ,UAAQ;IASzC,KAAK;IAQL,IAAI,GAAG,WAEN;IAED,IAAI,MAAM,WAET;IAED,IAAI,YAAY,qBAEf;IAED,IAAI,SAAS,kBAEZ;IAED,IAAI,SAAS,sCAEZ;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,OAAO,CAAC,OAAO,EAAE,IAAI,EAOxB;IAED,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,IAAI,CAAC,EAAE,OAAO;IAW7C,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI;IAatB,YAAY,CAAC,GAAG,SAAS,EAAE,QAAQ,EAAE;IAY3C,gBAAgB,CAAC,GAAG,SAAS,EAAE,QAAQ,EAAE;IAgBnC,KAAK;IAsBX,SAAS;IAqBT,eAAe,CAAC,GAAG,YAAY,EAAE,WAAW,EAAE;IAyB9C,cAAc,CAAC,IAAI,EAAE,EAAE;IAMvB,MAAM;IAyBN,QAAQ;IAMR,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC;IAuBhC,QAAQ;CAyVX;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,IAA2B,CAAC"}