@matter/protocol 0.15.2-alpha.0-20250717-3607eeac6 → 0.15.2-alpha.0-20250719-e4aeb457c

package/src/action/response/WriteResult.ts

@@ -5,9 +5,13 @@
  */
 
 import { Write } from "#action/request/Write.js";
-import type { AttributeId, AttributePath, ClusterId, EndpointNumber, NodeId, StatusCode } from "#types";
+import { ExpandedPath } from "#common/ExpandedPath.js";
+import { ExpandedStatus } from "#common/ExpandedStatus.js";
+import { PathError } from "#common/PathError.js";
+import { MatterAggregateError } from "#general";
+import { Status, type AttributeId, type AttributePath, type ClusterId, type EndpointNumber, type NodeId } from "#types";
 
-export type WriteResult<T extends Write> = Promise<
+export type WriteResult<T extends Write = Write> = Promise<
     T extends { suppressResponse: true } ? void : WriteResult.AttributeStatus[]
 >;
 
@@ -23,7 +27,27 @@ export namespace WriteResult {
     export interface AttributeStatus {
         kind: "attr-status";
         path: ConcreteAttributePath;
-        status: StatusCode;
+        status: Status;
         clusterStatus?: number;
     }
+
+    export function assertSuccess(result: AttributeStatus[]) {
+        const errors = result
+            .filter(attr => attr.status !== Status.Success)
+            .map(attr => {
+                const path = ExpandedPath({ ...attr, kind: "attribute" });
+                const status = new ExpandedStatus(attr);
+                return new PathError({ path, status });
+            });
+
+        if (!errors.length) {
+            return;
+        }
+
+        if (errors.length === 1) {
+            throw errors[0];
+        }
+
+        throw new MatterAggregateError(errors, "Multiple writes failed");
+    }
 }

package/src/common/ExpandedPath.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { camelize } from "#general";
+import {
+    AttributeModel,
+    ClusterModel,
+    CommandModel,
+    DataModelPath,
+    EventModel,
+    Matter,
+    MatterModel,
+    Model,
+} from "#model";
+import { AttributePath, CommandPath, EventPath } from "#types";
+
+/**
+ * Creates a {@link DataModelPath} from a Matter wire-format {@link AttributePath}, {@link EventPath}, or
+ * {@link CommandPath}.
+ *
+ * This is useful for creating human-readable diagnostics.
+ */
+export function ExpandedPath({ path, matter, base, kind }: ExpandedPath.Definition): DataModelPath {
+    if (matter === undefined) {
+        matter = Matter;
+    }
+
+    if (base && "path" in base) {
+        base = base.path;
+    }
+
+    const endpointIdent = path.endpointId ?? "*";
+    base = base ? base.at(endpointIdent, "endpoint") : DataModelPath(endpointIdent, "endpoint");
+
+    let cluster: ClusterModel | undefined;
+    base = base.at(identityOf(matter, ClusterModel, path.clusterId), "cluster");
+
+    if ("attributeId" in path) {
+        base = base.at("state").at(identityOf(cluster, AttributeModel, path.attributeId));
+        if (path.listIndex) {
+            return base.at(path.listIndex, "entry");
+        }
+        return base;
+    }
+
+    if ("commandId" in path) {
+        return base.at(identityOf(cluster, CommandModel, path.commandId));
+    }
+
+    if ("eventId" in path) {
+        return base.at("events").at(identityOf(cluster, EventModel, path.eventId));
+    }
+
+    return base.at("*", kind ?? "element");
+
+    function identityOf(parent: undefined | Model, type: Model.Type, id: undefined | number | string) {
+        if (id === undefined) {
+            return "*";
+        }
+
+        const instance = parent?.get(type, id);
+        if (instance === undefined) {
+            if (typeof id === "string") {
+                return camelize(id);
+            }
+            return id;
+        }
+
+        if (type === ClusterModel) {
+            cluster = instance as ClusterModel;
+        }
+
+        return camelize(instance.name);
+    }
+}
+
+export namespace ExpandedPath {
+    export interface Definition {
+        path: AttributePath | EventPath | CommandPath;
+        matter?: MatterModel;
+        base?: DataModelPath | { path: DataModelPath };
+        kind?: "attribute" | "command" | "event" | "entry";
+    }
+}

package/src/common/ExpandedStatus.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { decamelize } from "#general";
+import { ClusterModel, Matter, MatterModel } from "#model";
+import { ClusterId, Status } from "#types";
+
+/**
+ * Detailed status information expanded from status codes.
+ *
+ * TODO - maybe update codegen to include description in operational models so we can use as detailed error message
+ */
+export class ExpandedStatus {
+    id: string;
+    status: Status;
+    clusterStatus?: number;
+
+    constructor({ matter, status, cluster, clusterStatus }: ExpandedStatus.Definition) {
+        this.status = status ?? Status.Failure;
+        this.clusterStatus = clusterStatus;
+
+        let statusStr: undefined | string;
+        if (status !== Status.Failure) {
+            const name = Status[this.status];
+            if (name === undefined) {
+                statusStr = `unknown-${this.status}`;
+            } else {
+                statusStr = decamelize(name);
+            }
+        }
+
+        if (clusterStatus === undefined) {
+            this.id = statusStr ?? "failure";
+            return;
+        }
+
+        let clusterStr;
+        if (typeof cluster === "number") {
+            matter ??= Matter;
+            const model = matter.get(ClusterModel, cluster);
+            if (model === undefined) {
+                clusterStr = `cluster-${cluster}`;
+            } else {
+                clusterStr = decamelize(model.name);
+            }
+        } else if (cluster) {
+            clusterStr = decamelize(cluster.name);
+        } else {
+            clusterStr = "unknown-cluster";
+        }
+
+        if (statusStr === undefined) {
+            this.id = clusterStr;
+            return;
+        }
+
+        this.id = `${statusStr}+${clusterStr}`;
+    }
+}
+
+export namespace ExpandedStatus {
+    export interface Definition {
+        matter?: MatterModel;
+        status?: Status;
+        cluster?: ClusterModel | ClusterId;
+        clusterStatus?: number;
+    }
+}

package/src/common/PathError.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ExpandedStatus } from "#common/ExpandedStatus.js";
+import { camelize, capitalize, decamelize, MatterAggregateError } from "#general";
+import { DataModelPath } from "#model";
+import { StatusResponseError } from "#types";
+
+/**
+ * A protocol error associated with a specific data model path.
+ */
+export class PathError extends StatusResponseError {
+    #id: string;
+    #path: DataModelPath;
+
+    constructor({ path, status: { id, status, clusterStatus }, message }: PathError.Definition) {
+        if (message === undefined) {
+            message = capitalize(decamelize(camelize(id), " "));
+        }
+
+        super(message, status, clusterStatus);
+        this.#id = id;
+        this.#path = path;
+    }
+
+    override get id() {
+        return this.#id;
+    }
+
+    get path() {
+        return this.#path;
+    }
+}
+
+export namespace PathError {
+    export interface Definition {
+        path: DataModelPath;
+        status: ExpandedStatus;
+        message?: string;
+    }
+}
+
+export class AggregatePathError extends MatterAggregateError {}

package/src/common/index.ts

@@ -5,6 +5,7 @@
  */
 
 export * from "../peer/PeerAddress.js";
+export * from "./ExpandedPath.js";
 export * from "./FailsafeContext.js";
 export * from "./FailsafeTimer.js";
 export * from "./InstanceBroadcaster.js";