/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { camelize } from "@matter/general"; import { DataModelPath } from "@matter/model"; import type { ClusterId, CommandId } from "@matter/types"; import { ClusterType, EndpointNumber, Global, TlvSchema } from "@matter/types"; import { MalformedRequestError } from "./MalformedRequestError.js"; /** * A "specifier" addresses a specific element of the Matter data model in the context of a request. */ export namespace Specifier { /** * Minimal structural type for clusters used in requests. {@link ClusterType.Concrete} satisfies this. */ export interface ClusterLike { readonly id: ClusterId; readonly name: string; readonly attributes?: Record; readonly commands?: Record; readonly events?: Record; } /** * Clusters we designate with an object to convey structural and type information. The second form of this union * allows for specification with a host object (such as a ClusterBehavior instance or class). */ export type Cluster = ClusterLike | { cluster: ClusterLike }; /** * You may address endpoints with a bare ID but the object form allows an "endpoint object" as input and optionally * conveys additional metadata. */ export type Endpoint = | EndpointNumber | { number: EndpointNumber; versions?: Record; minEvent?: number }; /** * An attribute specifier may be the name of a cluster attribute or the name of a cluster or global attribute. */ export type Attribute = | ClusterType.Attribute | (string & keyof NonNullable) | GlobalAttributeName; /** * A command specifier may be the name of a cluster command or a command object. */ export type Command = | ClusterType.Command | (string & keyof NonNullable); /** * @deprecated Scheduled for removal in 0.19. * Legacy command specifier from ClusterType. Use {@link ClusterType.Command}. */ export interface ClusterTypeCommand { requestId: CommandId; requestSchema: TlvSchema; responseSchema: TlvSchema; timed: boolean; } /** * An event specifier may be the name of a cluster event or an event object. */ export type Event = | ClusterType.Event | (string & keyof NonNullable); export type GlobalAttributeName = keyof typeof Global.attributes; /** * Extract a cluster type from a cluster specifier type. */ export type ClusterFor = T extends ClusterLike ? T : T extends { cluster: ClusterLike } ? T["cluster"] : never; /** * Extract a cluster type from a cluster specifier. */ export function clusterFor(specifier?: T) { if (specifier === undefined) { throw new MalformedRequestError(`Cannot designate command "${specifier}" without a cluster`); } if ("cluster" in specifier) { return specifier["cluster"] as ClusterFor; } return specifier as ClusterFor; } /** * Extract an attribute object from a cluster and attribute specifier. */ export function attributeFor(cluster: ClusterLike | undefined, specifier: Specifier.Attribute) { if (typeof specifier === "object") { return specifier; } if (cluster === undefined) { const attr = Global.attributes[specifier as GlobalAttributeName]; if (attr === undefined) { throw new MalformedRequestError(`Cannot designate attribute "${specifier}" without a cluster`); } return attr; } const attr = cluster.attributes?.[specifier] ?? Global.attributes[specifier as GlobalAttributeName]; if (attr === undefined) { throw new MalformedRequestError(`Cluster ${cluster.name} does not define attribute ${specifier}`); } return attr; } /** * Extract a command type from a cluster type and command specifier. */ export type CommandFor> = CMD extends string ? C["commands"] extends Record ? C["commands"][CMD] : ClusterType.Command : CMD extends ClusterType.Command ? CMD : ClusterType.Command; export function commandFor>( cluster: C | undefined, specifier: CMD, ): CommandFor { if (typeof specifier !== "string") { return specifier as CommandFor; } if (cluster === undefined) { throw new MalformedRequestError(`Cannot designate command "${specifier}" without a cluster`); } const command = cluster.commands?.[specifier]; if (command === undefined) { throw new MalformedRequestError(`Cluster ${cluster.name} does not define command ${specifier}`); } return command as CommandFor; } /** * Extract an event object from a cluster and event specifier. */ export function eventFor(cluster: ClusterLike | undefined, specifier: Specifier.Event) { if (typeof specifier === "object") { return specifier; } if (cluster === undefined) { throw new MalformedRequestError(`Cannot designate event "${specifier}" without a cluster`); } const event = cluster.events?.[specifier]; if (event === undefined) { throw new MalformedRequestError(`Cluster ${cluster.name} does not define event ${specifier}`); } return event; } /** * Extract the cluster type from a cluster request type. */ export type ClusterOf = T extends { cluster: Specifier.Cluster } ? Specifier.ClusterFor : undefined; /** * Extract the cluster type from an element request. */ export function clusterOf(request: T): ClusterOf { if (request.cluster) { return Specifier.clusterFor(request.cluster) as ClusterOf; } return undefined as ClusterOf; } /** * Determine endpoint number for an object with an endpoint specifier. */ export function endpointIdOf(request: T): EndpointNumber | undefined { if (typeof request.endpoint === "number") { return request.endpoint; } return request.endpoint?.number; } } /** * Resolve a request-side specifier location into a {@link DataModelPath} for human-readable diagnostics. * * Mirrors the segment shape of {@link ExpandedPath} (state./events./markers) so client-side specifier paths and * server-side wire paths render consistently. Element names fall back to camelized hex IDs when the element is * unknown. */ export function resolvePathForSpecifier(location: { endpoint?: Specifier.Endpoint; cluster?: Specifier.Cluster; attribute?: Specifier.Attribute>; event?: Specifier.Event>; command?: Specifier.Command>; isUrgent?: boolean; listIndex?: number | null; }): DataModelPath { const endpointId = Specifier.endpointIdOf(location); const cluster = location.cluster ? Specifier.clusterFor(location.cluster) : undefined; let dmPath = new DataModelPath(endpointId ?? "*", "endpoint"); dmPath = dmPath.at(cluster ? camelize(cluster.name) : "*", "cluster"); if (location.attribute !== undefined) { const name = nameForElement(location.attribute, cluster && Specifier.attributeFor(cluster, location.attribute)); dmPath = dmPath.at("state").at(name); if (location.listIndex === null) { dmPath = dmPath.at("[ADD]", "marker"); } return dmPath; } if (location.event !== undefined) { const name = nameForElement(location.event, cluster && Specifier.eventFor(cluster, location.event)); dmPath = dmPath.at("events").at(name); if (location.isUrgent) { dmPath = dmPath.at("!", "marker"); } return dmPath; } if (location.command !== undefined) { const name = nameForElement(location.command, cluster && Specifier.commandFor(cluster, location.command)); return dmPath.at(name); } return dmPath.at("*", "element"); function nameForElement(specifier: string | object, resolved: { id?: number; name?: string } | undefined) { if (typeof specifier === "string") { return camelize(specifier); } if (resolved?.name !== undefined) { return camelize(resolved.name); } if (resolved?.id !== undefined) { return `0x${resolved.id.toString(16)}`; } return "?"; } }