@matter/node 0.17.9-alpha.0-20260805-cb9a8ce7b → 0.17.9

package/src/behavior/state/managed/MemberKeys.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Val } from "@matter/protocol";
+import type { ValReference } from "./ValReference.js";
+
+/**
+ * The slot a member occupies in a container keyed by {@link ValReference.primaryKey}.
+ *
+ * The persisted key set ({@link RootSupervisor.persistentKeys}) and a datasource container's own keys must both
+ * derive from this function — if they diverge, attributes silently stop persisting.
+ */
+export function memberKeyFor(
+    primaryKey: ValReference.PrimaryKey,
+    name: string | number,
+    id: number | undefined,
+): string | number {
+    return primaryKey === "id" ? (id ?? name) : name;
+}
+
+/**
+ * The key under the other keying convention, if distinct from {@link memberKeyFor}'s — whether a reader may fall
+ * back to it is the reader's policy.
+ */
+export function memberFallbackKeyFor(
+    primaryKey: ValReference.PrimaryKey,
+    name: string | number,
+    id: number | undefined,
+): string | number | undefined {
+    const key = memberKeyFor(primaryKey, name, id);
+    return primaryKey === "id" ? (key === name ? undefined : name) : id;
+}
+
+/**
+ * Read a member from container at key, falling back to fallbackKey; a caller passes `undefined` for fallbackKey
+ * when it must not tolerate the fallback slot.
+ */
+export function memberValueOf(
+    container: Val.Struct,
+    key: string | number,
+    fallbackKey: string | number | undefined,
+): Val | undefined {
+    if (key in container) {
+        return container[key];
+    }
+
+    if (fallbackKey !== undefined && fallbackKey in container) {
+        return container[fallbackKey];
+    }
+
+    return undefined;
+}

package/src/behavior/state/managed/NameResolver.ts

@@ -9,6 +9,7 @@ import type { Schema } from "@matter/model";
 import { ClusterModel, Model, ValueModel, type FieldValue } from "@matter/model";
 import { Val } from "@matter/protocol";
 import { Internal } from "./Internal.js";
+import { memberValueOf } from "./MemberKeys.js";
 
 /**
  * Obtain a function that returns a visible property by name from the ownership hierarchy of a managed value.
@@ -70,10 +71,7 @@ export function NameResolver(
             if (struct === undefined || struct === null) {
                 return undefined;
             }
-            if (id in struct) {
-                return struct[id];
-            }
-            return struct[name];
+            return memberValueOf(struct, id, name);
         };
     }
 

package/src/behavior/state/managed/ValReference.ts

@@ -56,7 +56,7 @@ export interface ValReference<T extends Val = Val> {
      * How this container keys its own members.  Only a datasource root may key by element ID; every nested container
      * keys by property name (list entries, by index).
      */
-    readonly primaryKey: "id" | "name";
+    readonly primaryKey: ValReference.PrimaryKey;
 
     /**
      * The managed value that owns the reference.
@@ -78,3 +78,10 @@ export interface ValReference<T extends Val = Val> {
      */
     supervisionConfig?: Supervision.Config;
 }
+
+export namespace ValReference {
+    /**
+     * How a container keys its own members.
+     */
+    export type PrimaryKey = "id" | "name";
+}

package/src/behavior/state/managed/values/StructManager.ts

@@ -14,6 +14,7 @@ import type { ValueSupervisor } from "../../../supervision/ValueSupervisor.js";
 import { Instrumentation } from "../Instrumentation.js";
 import { Internal } from "../Internal.js";
 import { ManagedReference } from "../ManagedReference.js";
+import { memberFallbackKeyFor, memberKeyFor, memberValueOf } from "../MemberKeys.js";
 import { NameResolver } from "../NameResolver.js";
 import type { ValReference } from "../ValReference.js";
 import { PrimitiveManager } from "./PrimitiveManager.js";
@@ -193,17 +194,14 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
 
             // We allow attribute/field name or id as key.  If name is present id is ignored
             const pk = this[Internal.reference].primaryKey;
-            let key = ManagedReference.keyFor(this[Internal.reference], name, id);
+            let key = memberKeyFor(pk, name, id);
             let storedKey: undefined | number | string;
             if (key in this[Internal.reference].value) {
                 storedKey = key;
-            } else if (pk === "id") {
-                if (name in this[Internal.reference].value) {
-                    storedKey = name;
-                }
-            } else if (id !== undefined) {
-                if (id in this[Internal.reference].value) {
-                    storedKey = id;
+            } else {
+                const fallbackKey = memberFallbackKeyFor(pk, name, id);
+                if (fallbackKey !== undefined && fallbackKey in this[Internal.reference].value) {
+                    storedKey = fallbackKey;
                 }
             }
 
@@ -295,17 +293,12 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                     }
                 }
 
-                const key = ManagedReference.keyFor(this[Internal.reference], name, id);
-                if (key in struct) {
-                    return struct[key];
-                }
-
-                const key2 = this[Internal.reference].primaryKey === "id" ? name : id;
-                if (key2 !== undefined && key2 in struct) {
-                    return struct[key2];
-                }
-
-                return undefined;
+                const primaryKey = this[Internal.reference].primaryKey;
+                return memberValueOf(
+                    struct,
+                    memberKeyFor(primaryKey, name, id),
+                    memberFallbackKeyFor(primaryKey, name, id),
+                );
             }
         };
     } else {
@@ -338,7 +331,8 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
 
             // Obtain the value.  Normally just struct[key] except in the case of Val.Dynamic
             const struct = this[Internal.reference].value;
-            const key = ManagedReference.keyFor(this[Internal.reference], name, id);
+            const primaryKey = this[Internal.reference].primaryKey;
+            const key = memberKeyFor(primaryKey, name, id);
             if ((struct as Val.Dynamic)[Val.properties]) {
                 const properties = (struct as Val.Dynamic)[Val.properties](
                     this[Internal.reference].rootOwner,
@@ -351,10 +345,13 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                 }
             } else if (key in struct) {
                 value = struct[key];
-            } else if (id !== undefined && key !== id && id in struct) {
+            } else if (primaryKey === "name") {
                 // A value decoded without a schema — an unknown cluster or attribute, including one a later model
-                // learns about — keys its members by TLV tag number, so a name-keyed container accepts the ID too
-                value = struct[id];
+                // learns about — keys its members by TLV tag number, so a name-keyed container accepts the ID too.
+                const fallbackKey = memberFallbackKeyFor(primaryKey, name, id);
+                if (fallbackKey !== undefined && fallbackKey in struct) {
+                    value = struct[fallbackKey];
+                }
             }
 
             // Note that we only mask values that are unreadable.  This is appropriate when the parent object is

package/src/behavior/supervision/RootSupervisor.ts

@@ -20,6 +20,8 @@ import {
 } from "@matter/model";
 import { AccessControl, Val } from "@matter/protocol";
 import { AttributeId } from "@matter/types";
+import { memberKeyFor } from "../state/managed/MemberKeys.js";
+import type { ValReference } from "../state/managed/ValReference.js";
 import { ValueCaster } from "../state/managed/values/ValueCaster.js";
 import { ValueManager } from "../state/managed/values/ValueManager.js";
 import { ValuePatcher } from "../state/managed/values/ValuePatcher.js";
@@ -155,7 +157,7 @@ export class RootSupervisor implements ValueSupervisor {
     /**
      * Retrieve names or IDs of fields configured as non-volatile.
      */
-    persistentKeys(key: "id" | "name" = "name") {
+    persistentKeys(primaryKey: ValReference.PrimaryKey = "name") {
         const persistent = new Set<string>();
 
         for (const member of this.#members) {
@@ -166,14 +168,7 @@ export class RootSupervisor implements ValueSupervisor {
                 (member.tag === ElementTag.Attribute &&
                     (member.effectiveAccess.writable || member.effectiveAccess.fabricScoped))
             ) {
-                if (key === "id") {
-                    const id = member.effectiveId;
-                    if (id !== undefined) {
-                        persistent.add(id.toString());
-                        continue;
-                    }
-                }
-                persistent.add(member.propertyName);
+                persistent.add(String(memberKeyFor(primaryKey, member.propertyName, member.effectiveId)));
             }
         }
         return persistent;

package/src/node/client/ClientStructure.ts

@@ -7,6 +7,8 @@
 import { ClusterBehavior } from "#behavior/cluster/ClusterBehavior.js";
 import type { ClusterBehaviorType } from "#behavior/cluster/ClusterBehaviorType.js";
 import { Datasource } from "#behavior/state/managed/Datasource.js";
+import { memberValueOf } from "#behavior/state/managed/MemberKeys.js";
+import type { ValReference } from "#behavior/state/managed/ValReference.js";
 import { Endpoint } from "#endpoint/Endpoint.js";
 import { EndpointType } from "#endpoint/type/EndpointType.js";
 import { RootEndpoint } from "#endpoints/root";
@@ -62,13 +64,13 @@ const SERVER_LIST_ATTR_NAME = "serverList";
 const PARTS_LIST_ATTR_NAME = "partsList";
 
 /**
- * Read a value from store initial values using either numeric attribute ID or property name.
+ * Read a value from store initial values, preferring the numeric attribute ID slot over the property name slot.
  */
 function getStoreValue(values: Record<string | number, unknown> | undefined, id: number, name: string): unknown {
     if (values === undefined) {
         return undefined;
     }
-    return id in values ? values[id] : values[name];
+    return memberValueOf(values, id, name);
 }
 
 /**
@@ -1178,7 +1180,7 @@ export namespace ClientStructure {
     export type StoreFactory = (
         endpoint: Endpoint,
         behaviorId: string,
-        primaryKey: "id" | "name",
+        primaryKey: ValReference.PrimaryKey,
     ) => Datasource.ExternallyMutableStore;
 
     export interface Options {