@project-chip/matter.js 0.16.0-alpha.0-20250912-0d12bf718 → 0.16.0-alpha.0-20250916-d577beb1d

package/src/device/Endpoint.ts

@@ -10,7 +10,8 @@ import {
     FixedLabelCluster,
     UserLabelCluster,
 } from "#clusters";
-import { AtLeastOne, Diagnostic, ImplementationError, InternalError, NotImplementedError } from "#general";
+import { AtLeastOne, Diagnostic, Immutable, ImplementationError, InternalError, NotImplementedError } from "#general";
+import { Behavior, Commands as BehaviorCommands } from "#node";
 import { ClusterClientObj, SupportedAttributeClient, UnknownSupportedAttributeClient } from "#protocol";
 import {
     Attributes,
@@ -28,6 +29,7 @@ import {
 import { ClusterServer } from "../cluster/server/ClusterServer.js";
 import { ClusterServerObj, asClusterServerInternal } from "../cluster/server/ClusterServerTypes.js";
 import { DeviceTypeDefinition } from "./DeviceTypes.js";
+import { EndpointPropertiesProxy } from "./EndpointPropertiesProxy.js";
 
 export interface EndpointOptions {
     endpointId?: EndpointNumber;
@@ -37,13 +39,15 @@ export interface EndpointOptions {
 export class Endpoint {
     private readonly clusterServers = new Map<ClusterId, ClusterServerObj>();
     private readonly clusterClients = new Map<ClusterId, ClusterClientObj>();
-    private readonly childEndpoints: Endpoint[] = [];
+    private readonly childEndpoints = new Map<number, Endpoint>();
     number: EndpointNumber | undefined;
     uniqueStorageKey: string | undefined;
     name = "";
     private structureChangedCallback: () => void = () => {
         /** noop until officially set **/
     };
+    #stateProxy?: EndpointPropertiesProxy.State;
+    #commandsProxy?: EndpointPropertiesProxy.Commands;
 
     /**
      * Create a new Endpoint instance.
@@ -65,13 +69,74 @@ export class Endpoint {
         }
     }
 
+    /**
+     * Access to cached cluster state values using endpoint.state.clusterNameOrId.attributeNameOrId
+     * Returns immutable cached attribute values from cluster clients
+     */
+    get state() {
+        if (this.#stateProxy === undefined) {
+            this.#stateProxy = EndpointPropertiesProxy.state(this.clusterClients);
+        }
+        return this.#stateProxy;
+    }
+
+    /**
+     * Access to cluster commands using endpoint.commands.clusterNameOrId.commandName
+     * Returns async functions that can be called to invoke commands on cluster clients
+     */
+    get commands() {
+        if (this.#commandsProxy === undefined) {
+            this.#commandsProxy = EndpointPropertiesProxy.commands(this.clusterClients);
+        }
+        return this.#commandsProxy;
+    }
+
+    /**
+     * Access to typed cached cluster state values
+     * Returns immutable cached attribute values from cluster clients
+     */
+    stateOf<T extends Behavior.Type>(type: T) {
+        this.#clusterClientForBehaviorType(type); // just use to verify the existence of the cluster
+
+        return this.state[type.name] as Immutable<Behavior.StateOf<T>>;
+    }
+
+    /**
+     * Access to typed cluster commands
+     * Returns async functions that can be called to invoke commands on cluster clients
+     */
+    commandsOf<T extends Behavior.Type>(type: T) {
+        return this.#clusterClientForBehaviorType(type).commands as BehaviorCommands.OfBehavior<T>;
+    }
+
+    #clusterClientForBehaviorType<T extends Behavior.Type>(type: T): ClusterClientObj {
+        const clusterId = type.schema?.tag === "cluster" ? (type.schema.id as ClusterId) : undefined;
+        if (clusterId === undefined) {
+            throw new ImplementationError(`Behavior ${type.id} is not backed by a cluster`);
+        }
+        const clusterClient = this.clusterClients.get(clusterId);
+        if (!clusterClient) {
+            throw new ImplementationError(
+                `Cluster ${type.id} (0x${clusterId.toString(16)}) is not present on endpoint ${this.number}`,
+            );
+        }
+        return clusterClient;
+    }
+
+    /** Get all child endpoints aka parts */
+    get parts() {
+        return this.childEndpoints;
+    }
+
     get deviceType(): DeviceTypeId {
         return this.deviceTypes[0].code;
     }
 
     setStructureChangedCallback(callback: () => void) {
         this.structureChangedCallback = callback;
-        this.childEndpoints.forEach(endpoint => endpoint.setStructureChangedCallback(callback));
+        for (const endpoint of this.childEndpoints.values()) {
+            endpoint.setStructureChangedCallback(callback);
+        }
     }
 
     removeFromStructure() {
@@ -79,7 +144,9 @@ export class Endpoint {
         this.structureChangedCallback = () => {
             /** noop **/
         };
-        this.childEndpoints.forEach(endpoint => endpoint.removeFromStructure());
+        for (const endpoint of this.childEndpoints.values()) {
+            endpoint.removeFromStructure();
+        }
     }
 
     close() {
@@ -217,34 +284,34 @@ export class Endpoint {
 
     addChildEndpoint(endpoint: Endpoint): void {
         if (!(endpoint instanceof Endpoint)) {
-            throw new Error("Only supported EndpointInterface implementation is Endpoint");
+            throw new InternalError("Only supported EndpointInterface implementation is Endpoint");
         }
+        const id = endpoint.getNumber();
 
-        if (endpoint.number !== undefined && this.getChildEndpoint(endpoint.number) !== undefined) {
-            throw new ImplementationError(
-                `Endpoint with id ${endpoint.number} already exists as child from ${this.number}.`,
-            );
+        if (this.childEndpoints.has(id)) {
+            throw new ImplementationError(`Endpoint with id ${id} already exists as child from ${this.number}.`);
         }
 
-        this.childEndpoints.push(endpoint);
+        this.childEndpoints.set(id, endpoint);
         endpoint.setStructureChangedCallback(this.structureChangedCallback);
         this.structureChangedCallback(); // Inform parent about structure change
     }
 
     getChildEndpoint(id: EndpointNumber): Endpoint | undefined {
-        return this.childEndpoints.find(endpoint => endpoint.number === id);
+        return this.childEndpoints.get(id);
     }
 
     getChildEndpoints(): Endpoint[] {
-        return this.childEndpoints;
+        return Array.from(this.childEndpoints.values());
     }
 
     protected removeChildEndpoint(endpoint: Endpoint): void {
-        const index = this.childEndpoints.indexOf(endpoint);
-        if (index === -1) {
+        const id = endpoint.getNumber();
+        const knownEndpoint = this.childEndpoints.get(id);
+        if (knownEndpoint === undefined) {
             throw new ImplementationError(`Provided endpoint for deletion does not exist as child endpoint.`);
         }
-        this.childEndpoints.splice(index, 1);
+        this.childEndpoints.delete(id);
         endpoint.removeFromStructure();
         this.structureChangedCallback(); // Inform parent about structure change
     }

package/src/device/EndpointPropertiesProxy.ts

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Immutable } from "#general";
+import { ClusterClientObj } from "#protocol";
+import { AttributeId, ClusterId, CommandId } from "#types";
+
+enum EndpointPropertiesProxyType {
+    State = "state",
+    Commands = "commands",
+}
+
+/**
+ * Factory for creating proxy-based access to cached cluster state values for legacy Endpoint.
+ * This enables ClientNode-style state access patterns.
+ */
+export class EndpointPropertiesProxy {
+    #clusterClients: Map<ClusterId, ClusterClientObj>;
+    #nameIdMap?: Map<string, ClusterId>;
+
+    /**
+     * Create a state proxy that allows access via cluster names/IDs
+     */
+    static state(clusterClients: Map<ClusterId, ClusterClientObj>) {
+        return new EndpointPropertiesProxy(clusterClients).#proxy(
+            EndpointPropertiesProxyType.State,
+        ) as EndpointPropertiesProxy.State;
+    }
+
+    /**
+     * Create a commands proxy that allows access via cluster names/IDs
+     */
+    static commands(clusterClients: Map<ClusterId, ClusterClientObj>) {
+        return new EndpointPropertiesProxy(clusterClients).#proxy(
+            EndpointPropertiesProxyType.Commands,
+        ) as EndpointPropertiesProxy.Commands;
+    }
+
+    constructor(clusterClients: Map<ClusterId, ClusterClientObj>) {
+        this.#clusterClients = clusterClients;
+    }
+
+    #proxy(type: EndpointPropertiesProxyType) {
+        return new Proxy(
+            {},
+            {
+                get: (_target, prop) => {
+                    if (typeof prop !== "string") {
+                        return undefined;
+                    }
+
+                    // Try to find cluster by name first, then by id
+                    let clusterId = this.#clusterIdForName(prop);
+                    if (clusterId === undefined) {
+                        const id = parseInt(prop, 10);
+                        clusterId = Number.isFinite(id) ? ClusterId(id) : undefined;
+                    }
+                    if (clusterId !== undefined) {
+                        const clusterClient = this.#clusterClients.get(clusterId);
+
+                        if (clusterClient !== undefined) {
+                            switch (type) {
+                                case EndpointPropertiesProxyType.Commands:
+                                    return clusterClient.commands;
+                                case EndpointPropertiesProxyType.State:
+                                    return this.#createClusterStateProxy(clusterClient);
+                            }
+                        }
+                    }
+                    return undefined;
+                },
+            },
+        );
+    }
+
+    #createClusterStateProxy(clusterClient: ClusterClientObj): Immutable<Record<string | AttributeId, any>> {
+        return new Proxy(
+            {},
+            {
+                get: (_target, prop) => {
+                    if (typeof prop !== "string") {
+                        return undefined;
+                    }
+
+                    return clusterClient.attributes[prop]?.getLocal();
+                },
+            },
+        ) as Immutable<Record<string | AttributeId, any>>;
+    }
+
+    #clusterIdForName(name: string): ClusterId | undefined {
+        // Initialize map if not done yet or cluster structure changed
+        if (this.#nameIdMap === undefined || this.#nameIdMap.size !== this.#clusterClients.size) {
+            this.#nameIdMap = new Map<string, ClusterId>();
+            for (const [id, client] of this.#clusterClients) {
+                this.#nameIdMap.set(client.name.toLowerCase(), id);
+            }
+        }
+        return this.#nameIdMap.get(name.toLowerCase());
+    }
+}
+
+export namespace EndpointPropertiesProxy {
+    export type State = Immutable<{
+        [key: string | ClusterId]: Record<string | AttributeId, any> | undefined;
+    }>;
+
+    export type Commands = Immutable<{
+        [key: string | ClusterId]: Record<string | CommandId, (data: any) => Promise<unknown>> | undefined;
+    }>;
+}

package/src/device/PairedNode.ts

@@ -24,6 +24,7 @@ import {
     Time,
     Timer,
 } from "#general";
+import { Behavior, Commands } from "#node";
 import {
     AttributeClientValues,
     ChannelStatusResponseError,
@@ -70,6 +71,7 @@ import {
     getDeviceTypeDefinitionFromModelByCode,
 } from "./DeviceTypes.js";
 import { Endpoint } from "./Endpoint.js";
+import { EndpointPropertiesProxy } from "./EndpointPropertiesProxy.js";
 import { asClusterClientInternal, isClusterClient } from "./TypeHelpers.js";
 
 const logger = Logger.get("PairedNode");
@@ -235,7 +237,7 @@ interface SubscriptionHandlerCallbacks {
  * the CommissioningController on commissioning or when connecting.
  */
 export class PairedNode {
-    readonly #endpoints = new Map<EndpointNumber, Endpoint>();
+    readonly #endpoints = new Map<number, Endpoint>();
     #interactionClient: InteractionClient;
     #reconnectDelayTimer?: Timer;
     #newChannelReconnectDelayTimer = Time.getTimer(
@@ -395,7 +397,7 @@ export class PairedNode {
             if (
                 session.isInitiator || // If we initiated the session we do not need to react on it
                 session.peerNodeId !== this.nodeId || // no session for this node
-                this.state !== NodeStates.WaitingForDeviceDiscovery
+                this.connectionState !== NodeStates.WaitingForDeviceDiscovery
             ) {
                 return;
             }
@@ -412,7 +414,7 @@ export class PairedNode {
                 // This kicks of the remote initialization and automatic reconnection handling if it can not be connected
                 this.#initialize().catch(error => {
                     logger.info(`Node ${nodeId}: Error during remote initialization`, error);
-                    if (this.state !== NodeStates.Disconnected) {
+                    if (this.connectionState !== NodeStates.Disconnected) {
                         this.#setConnectionState(NodeStates.WaitingForDeviceDiscovery);
                         this.#scheduleReconnect();
                     }
@@ -430,7 +432,7 @@ export class PairedNode {
     }
 
     /** Returns the Node connection state. */
-    get state() {
+    get connectionState() {
         return this.#connectionState;
     }
 
@@ -955,7 +957,7 @@ export class PairedNode {
     }
 
     #scheduleReconnect(delay?: Duration) {
-        if (this.state !== NodeStates.WaitingForDeviceDiscovery) {
+        if (this.connectionState !== NodeStates.WaitingForDeviceDiscovery) {
             this.#setConnectionState(NodeStates.Reconnecting);
         }
 
@@ -988,7 +990,7 @@ export class PairedNode {
 
         if (updateStructure) {
             // Find out what we need to remove or retain
-            const endpointsToRemove = new Set<EndpointNumber>(this.#endpoints.keys());
+            const endpointsToRemove = new Set<number>(this.#endpoints.keys());
             for (const [endpointId] of Object.entries(allData)) {
                 const endpointIdNumber = EndpointNumber(parseInt(endpointId));
                 if (this.#endpoints.has(endpointIdNumber)) {
@@ -1198,6 +1200,11 @@ export class PairedNode {
         }
     }
 
+    /** Returns all parts (endpoints) known for the Root Endpoint of this node. */
+    get parts() {
+        return this.getRootEndpoint()?.parts ?? new Map<number, Endpoint>();
+    }
+
     /** Returns the functional devices/endpoints (the "childs" of the Root Endpoint) known for this node. */
     getDevices(): Endpoint[] {
         return this.#endpoints.get(EndpointNumber(0))?.getChildEndpoints() ?? [];
@@ -1432,4 +1439,44 @@ export class PairedNode {
             ],
         });
     }
+
+    /**
+     * Access to cached cluster state values of the root endpoint using node.state.clusterNameOrId.attributeNameOrId
+     * Returns immutable cached attribute values from cluster clients
+     */
+    get state() {
+        return this.getRootEndpoint()?.state ?? ({} as EndpointPropertiesProxy.State);
+    }
+
+    /**
+     * Access to cluster commands of the root endpoint using node.commands.clusterNameOrId.commandName
+     * Returns async functions that can be called to invoke commands on cluster clients
+     */
+    get commands() {
+        return this.getRootEndpoint()?.commands ?? ({} as EndpointPropertiesProxy.Commands);
+    }
+
+    /**
+     * Access to typed cached cluster state values of the root endpoint
+     * Returns immutable cached attribute values from cluster clients
+     */
+    stateOf<T extends Behavior.Type>(type: T) {
+        const root = this.getRootEndpoint();
+        if (root === undefined) {
+            throw new ImplementationError(`Root endpoint for node ${this.nodeId} not found.`);
+        }
+        return root.stateOf(type);
+    }
+
+    /**
+     * Access to typed cluster commands of the root endpoint
+     * Returns async functions that can be called to invoke commands on cluster clients
+     */
+    commandsOf<T extends Behavior.Type>(type: T): Commands.OfBehavior<T> {
+        const root = this.getRootEndpoint();
+        if (root === undefined) {
+            throw new ImplementationError(`Root endpoint for node ${this.nodeId} not found.`);
+        }
+        return root.commandsOf(type);
+    }
 }