fix(types): populate reverse mapping in cluster enum runtime objects (#3666)

Apollon77 · claude · web-flow · commit 3b65344185a2 · 2026-04-28T13:22:29.000+02:00
* fix(types): populate reverse mapping in cluster enum runtime objects

Cluster `.d.ts` files declare `NodeOperationalCertStatus` etc. as TypeScript
numeric enums, which would carry value→name reverse mapping at runtime. The
matter.js runtime equivalent built by `EnumForValueModel` only populated
forward (name→value) entries, so `Cluster.SomeEnum[code]` returned `undefined`.

This produced useless logs like

  Commission error for "updateFabricLabel": undefined (10), undefined

(reported as matterjs-server#581). Reverse mapping now matches the declared
TS shape so generic diagnostic call sites can resolve a member name from a
numeric code.

Also:
- `StatusResponseError.is()` becomes a `error is StatusResponseError` type
  guard. Body still uses `of()` so cause-chain matching is preserved.
- ControllerCommissioningFlow: drop the unreachable `LabelConflict` branch
  inside the `addNoc` block (AddNoc has no Label argument and cannot return
  this status per spec). Add a matching branch for `updateFabricLabel`,
  throwing `FabricLabelConflictError` with a descriptive message that names
  the conflicting label.
- CommissioningController.validateAndUpdateFabricLabel: detect a
  `LabelConflict` `clusterCode` via `StatusResponseError.of()` and surface
  `FabricLabelConflictError` with the same wording so post-commission label
  updates produce the same actionable error as the commissioning-time path.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;

* fix(types): tighten EnumForValueModel return type, drop is() type guard

Address PR review feedback:

- Replace `Record&lt;string, string | number&gt;` with `EnumLikeObject` =
  `{ [k: string]: number } &amp; { [k: number]: string }`. Forward lookups by
  name remain `number`; reverse lookups by id are `string`. Restores the
  numeric-enum typing that external callers relied on.
- Revert `StatusResponseError.is()` to `boolean` return. Type-guarding to
  `error is StatusResponseError` was a partial lie because the body uses
  `of()` which matches the cause chain — for wrappers the original `error`
  is not actually an SRE. Callers needing the matched instance should use
  `StatusResponseError.of(error)` directly.
- Add unit tests covering forward, reverse, and unknown-key lookups against
  `OperationalCredentials.NodeOperationalCertStatus` to lock in the runtime
  enum shape.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/packages/matter.js/src/CommissioningController.ts b/packages/matter.js/src/CommissioningController.ts
@@ -44,6 +44,7 @@ import {
     DiscoveryData,
     Fabric,
     FabricGroups,
+    FabricLabelConflictError,
     NodeSession,
     PeerSet,
     SecureSession,
@@ -56,10 +57,12 @@ import {
     FabricId,
     FabricIndex,
     NodeId,
+    StatusResponseError,
     TypeFromPartialBitSchema,
     VendorId,
 } from "@matter/types";
 import { BasicInformation } from "@matter/types/clusters/basic-information";
+import { OperationalCredentials } from "@matter/types/clusters/operational-credentials";
 import { CommissioningControllerNodeOptions, NodeStates, PairedNode } from "./device/PairedNode.js";
 import { MatterController, PairedNodeDetails } from "./MatterController.js";
 
@@ -908,10 +911,20 @@ export class CommissioningController {
                 this.fabric.addressOf(nodeId),
                 `Fabric label "${fabric.label}" does not match requested admin fabric Label "${label}". Updating...`,
             );
-            await node.node.commandsOf(OperationalCredentialsClient).updateFabricLabel({
-                label,
-                fabricIndex: fabric.fabricIndex,
-            });
+            try {
+                await node.node.commandsOf(OperationalCredentialsClient).updateFabricLabel({
+                    label,
+                    fabricIndex: fabric.fabricIndex,
+                });
+            } catch (error) {
+                const sre = StatusResponseError.of(error);
+                if (sre?.clusterCode === OperationalCredentials.NodeOperationalCertStatus.LabelConflict) {
+                    throw new FabricLabelConflictError(
+                        `Cannot set fabric label to "${label}" because another fabric on this device already uses this name. Please adjust fabric labels to be unique.`,
+                    );
+                }
+                throw error;
+            }
         }
     }
 
diff --git a/packages/protocol/src/peer/ControllerCommissioningFlow.ts b/packages/protocol/src/peer/ControllerCommissioningFlow.ts
@@ -593,11 +593,14 @@ export class ControllerCommissioningFlow {
                 throw new MaximumCommissionedFabricsReachedError(
                     `Commission error: This device reached the maximum number of fabrics it can be part of. Please remove a fabric before trying to add another one.`,
                 );
-            } else if (statusCode === OperationalCredentials.NodeOperationalCertStatus.LabelConflict) {
-                throw new FabricLabelConflictError(
-                    `Commission error: This device is already commissioned with a fabric with the same label. Please choose a different label.`,
-                );
             }
+        } else if (
+            context === "updateFabricLabel" &&
+            statusCode === OperationalCredentials.NodeOperationalCertStatus.LabelConflict
+        ) {
+            throw new FabricLabelConflictError(
+                `Cannot set fabric label to "${this.fabric.label}" because another fabric on this device already uses this name. Please adjust fabric labels to be unique.`,
+            );
         }
         throw new CommissioningError(
             `Commission error for "${context}": ${OperationalCredentials.NodeOperationalCertStatus[statusCode]} (${statusCode}), ${debugText}${
@@ -1254,7 +1257,6 @@ export class ControllerCommissioningFlow {
                 }),
             );
         } catch (error) {
-            // convert error
             throw repackErrorAs(error, RecoverableCommissioningError);
         }
 
diff --git a/packages/types/src/cluster/EnumForValueModel.ts b/packages/types/src/cluster/EnumForValueModel.ts
@@ -6,30 +6,35 @@
 
 import { Schema, ValueModel } from "@matter/model";
 
-const cache = new WeakMap<ValueModel, Record<string, number>>();
+/**
+ * Runtime shape of a TypeScript numeric enum: name→number forward lookup, number→name reverse lookup.
+ */
+export type EnumLikeObject = { [k: string]: number } & { [k: number]: string };
+
+const cache = new WeakMap<ValueModel, EnumLikeObject>();
 
 /**
- * Create a frozen enum object for an enum value model.
+ * Create a frozen enum object with the runtime shape of a TypeScript numeric enum (forward and reverse mapping).
  *
- * The returned object maps enum member names to their numeric IDs.  Schema is associated via {@link Schema.set} so it
- * can be resolved by `@field` decorators.
+ * Schema is associated via {@link Schema.set} so it can be resolved by `@field` decorators.
  *
  * Results are cached per model instance.
  */
-export function EnumForValueModel(model: ValueModel): Record<string, number> {
+export function EnumForValueModel(model: ValueModel): EnumLikeObject {
     let result = cache.get(model);
     if (result !== undefined) {
         return result;
     }
 
-    const values: Record<string, number> = {};
+    const values: Record<string | number, string | number> = {};
     for (const child of model.children) {
         if (typeof child.id === "number") {
             values[child.name] = child.id;
+            values[child.id] = child.name;
         }
     }
 
-    result = Object.freeze(values);
+    result = Object.freeze(values) as EnumLikeObject;
     Schema.set(result, model);
 
     cache.set(model, result);
diff --git a/packages/types/test/cluster/EnumForValueModelTest.ts b/packages/types/test/cluster/EnumForValueModelTest.ts
@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { OperationalCredentials } from "#clusters/operational-credentials.js";
+
+describe("EnumForValueModel runtime shape", () => {
+    it("exposes forward name→value mapping like a TS numeric enum", () => {
+        expect(OperationalCredentials.NodeOperationalCertStatus.Ok).equal(0);
+        expect(OperationalCredentials.NodeOperationalCertStatus.LabelConflict).equal(10);
+        expect(OperationalCredentials.NodeOperationalCertStatus.InvalidFabricIndex).equal(11);
+    });
+
+    it("exposes reverse value→name mapping like a TS numeric enum", () => {
+        expect(OperationalCredentials.NodeOperationalCertStatus[0]).equal("Ok");
+        expect(OperationalCredentials.NodeOperationalCertStatus[10]).equal("LabelConflict");
+        expect(OperationalCredentials.NodeOperationalCertStatus[11]).equal("InvalidFabricIndex");
+    });
+
+    it("returns undefined for unknown values", () => {
+        expect(OperationalCredentials.NodeOperationalCertStatus[999]).equal(undefined);
+    });
+});
