@matter/model 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/common/DataModelPath.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Utility for tracking location in the Matter data model.  This location is used for diagnostics.
+ *
+ * The path consists of a sequence of IDs, optionally with type information.
+ */
+export interface DataModelPath {
+    parent?: DataModelPath;
+
+    id: string | number;
+
+    type?: string;
+
+    at(name: string | number, type?: string): DataModelPath;
+
+    toString(includeType?: boolean): string;
+
+    toArray(): (string | number)[];
+}
+
+/**
+ * Create a {@link DataModelPath} rooted at {@link id}.
+ */
+export function DataModelPath(id: string | number, type?: string): DataModelPath {
+    function identity(this: DataModelPath, includeType?: boolean) {
+        if (this.type && includeType) {
+            return `${this.type}#${this.id}`;
+        }
+        return this.id;
+    }
+
+    function toString(this: DataModelPath, includeType?: boolean) {
+        if (this.parent) {
+            return `${this.parent}.${identity.call(this, includeType)}`;
+        }
+        return identity.call(this, includeType).toString();
+    }
+
+    function toArray(this: DataModelPath): (string | number)[] {
+        if (this.parent) {
+            return [...this.parent.toArray(), this.id];
+        }
+        return [this.id];
+    }
+
+    function at(this: DataModelPath, id: string | number, type?: string): DataModelPath {
+        return {
+            parent: this,
+            id,
+            type,
+            at,
+            toString,
+            toArray,
+        };
+    }
+
+    return {
+        id,
+        type,
+        at,
+        toString,
+        toArray,
+    };
+}

package/src/common/Datatype.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * An identifier for every non-derived datatype from the Matter Core
+ * Specification.
+ */
+export enum Datatype {
+    bool = "bool",
+    map8 = "map8",
+    map16 = "map16",
+    map32 = "map32",
+    map64 = "map64",
+    uint8 = "uint8",
+    uint16 = "uint16",
+    uint24 = "uint24",
+    uint32 = "uint32",
+    uint40 = "uint40",
+    uint48 = "uint48",
+    uint56 = "uint56",
+    uint64 = "uint64",
+    int8 = "int8",
+    int16 = "int16",
+    int24 = "int24",
+    int32 = "int32",
+    int40 = "int40",
+    int48 = "int48",
+    int56 = "int56",
+    int64 = "int64",
+    single = "single",
+    double = "double",
+    octstr = "octstr",
+    list = "list",
+    struct = "struct",
+
+    // Formally these are derived datatypes, however we largely treat them
+    // like non-derived so define them here
+    string = "string",
+    enum8 = "enum8",
+    enum16 = "enum16",
+
+    // Extension -- any value is allowed
+    any = "any",
+}

package/src/common/DefinitionError.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Describes an error in model construction.
+ */
+export type DefinitionError = {
+    code: string;
+    source: string;
+    message: string;
+    xref?: string;
+};

package/src/common/DeviceClassification.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Device type classification.  This is the Matter "device type classification".
+ *
+ * @see {@link MatterSpecification.v13.Core} § 7.15.3
+ */
+export enum DeviceClassification {
+    /**
+     * Officially a {@link Utility}.  Differentiating because there is only one base device type, which is its own
+     * thing.
+     */
+    Base = "base",
+
+    /**
+     * @see {@link MatterSpecification.v13.Core} § 7.15.3.1
+     */
+    Utility = "utility",
+
+    /**
+     * @see {@link MatterSpecification.v13.Core} § 7.15.3.2
+     */
+    Application = "application",
+
+    /**
+     * A subset of type {@link Application}.
+     *
+     * @see {@link MatterSpecification.v13.Core} § 7.15.3.3
+     */
+    Simple = "simple",
+
+    /**
+     * A subset of type {@link Application}.
+     *
+     * @see {@link MatterSpecification.v13.Core} § 7.15.3.4
+     */
+    Dynamic = "dynamic",
+
+    /**
+     * A subset of type {@link Utility}.  Not officially a device type but described in the same section.
+     *
+     * @see {@link MatterSpecification.v13.Core} § 7.15.3.5
+     */
+    Node = "node",
+}

package/src/common/ElementTag.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Types of elements per the Matter specification.
+ *
+ * We use "tag" to differentiate elements so we can use "type" for datatypes.
+ */
+export enum ElementTag {
+    Fabric = "fabric",
+    Node = "node",
+    Endpoint = "endpoint",
+    Cluster = "cluster",
+    Command = "command",
+    Event = "event",
+    Attribute = "attribute",
+    DeviceType = "deviceType",
+    Datatype = "datatype",
+    Field = "field",
+
+    // Semantic tag information - not formally "elements" in the specification
+    SemanticNamespace = "semanticNamespace",
+    SemanticTag = "semanticTag",
+
+    // Device cluster element requirement - not formally an "element" in the specification
+    Requirement = "requirement",
+
+    // Root element type - not formally part of specification
+    Matter = "matter",
+}

package/src/common/FeatureSet.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { isDeepEqual } from "@matter/general";
+import type { ValueModel } from "../models/index.js";
+
+/**
+ * A "feature set" is a set of features for a cluster.  The names of features present appear in this set.
+ *
+ * TODO - Feature metadata is a bit messy and needs a refactor to consolidate available/supported and names/codes
+ */
+export class FeatureSet extends Set<FeatureSet.Flag> {
+    /**
+     * Create a new feature set from an iterable that returns active names or from an object of the form { [featureName:
+     * string]: true }
+     */
+    constructor(definition?: FeatureSet.Definition) {
+        if (typeof definition === "string") {
+            super([definition]);
+            return;
+        }
+
+        if (definition && typeof (definition as any)[Symbol.iterator] !== "function") {
+            definition = Object.entries(definition)
+                .filter(([_k, v]) => v)
+                .map(([k]) => k);
+        }
+
+        super(definition as Iterable<any>);
+    }
+
+    /**
+     * Access features as an array of feature names.
+     */
+    get array() {
+        return Array.from(this);
+    }
+
+    /**
+     * Access features as an object mapping feature name -> true.
+     */
+    get record() {
+        return Object.fromEntries(this.map(f => [f, true]));
+    }
+
+    /**
+     * Determine if I am identical to another set.
+     */
+    is(other?: FeatureSet) {
+        return isDeepEqual([...this].sort(), other ? [...other].sort() : []);
+    }
+
+    map<T>(fn: (name: FeatureSet.Flag) => T): T[] {
+        return this.array.map(fn);
+    }
+}
+
+export namespace FeatureSet {
+    export type Flag = string;
+    export type Flags = Iterable<FeatureSet.Flag>;
+    export type Definition = Flags | { [name: string]: boolean | undefined };
+
+    /**
+     * Normalize the feature map and list of supported feature names into sets of "all" and "supported" features by
+     * abbreviation.
+     *
+     * The input feature set may reference features by short name ("LT") or long name ("lighting").  Name match is case
+     * insensitive.
+     */
+    export function normalize(featureMap: ValueModel, supportedFeatures?: FeatureSet) {
+        const featuresAvailable = new FeatureSet();
+        const featuresSupported = new FeatureSet();
+
+        const supported = supportedFeatures ? new Set([...supportedFeatures].map(f => f.toLowerCase())) : undefined;
+
+        for (const feature of featureMap.children) {
+            featuresAvailable.add(feature.name);
+            if (
+                supported?.has(feature.name.toLowerCase()) ||
+                (feature.description && supported?.has(feature.description.toLowerCase()))
+            ) {
+                featuresSupported.add(feature.name);
+            }
+        }
+
+        return {
+            featuresAvailable,
+            featuresSupported,
+        };
+    }
+}

package/src/common/FieldValue.ts

@@ -0,0 +1,391 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes as ByteUtils, serialize as stringSerialize, UnexpectedDataError } from "@matter/general";
+import type { Metatype } from "./Metatype.js";
+
+/**
+ * A FieldValue represents a concrete value for a datatype.  Most values are primitives but some values we encode with
+ * specialized typed objects so we can capture the original semantic meaning.
+ */
+export type FieldValue =
+    | null
+    | string
+    | number
+    | bigint
+    | boolean
+    | Date
+    | FieldValue[]
+    | FieldValue.Properties
+    | FieldValue.Reference
+    | FieldValue.Percent
+    | FieldValue.Celsius
+    | FieldValue.Bytes;
+
+export namespace FieldValue {
+    // Typing with constants should be just as type safe as using an enum but simplifies type definitions
+
+    export const percent = "percent";
+    export type percent = typeof percent;
+
+    export const celsius = "celsius";
+    export type celsius = typeof celsius;
+
+    export const reference = "reference";
+    export type reference = typeof reference;
+
+    export const properties = "properties";
+    export type properties = typeof properties;
+
+    export const bytes = "bytes";
+    export type bytes = typeof bytes;
+
+    /**
+     * If a field value isn't a primitive type, it's an object with a type field indicating one of these types.
+     */
+    export type Type = percent | celsius | reference | properties | bytes;
+
+    /**
+     * Test for one of the special placeholder types.
+     */
+    export function is(value: FieldValue | undefined, type: Type) {
+        return value && (value as any).type === type;
+    }
+
+    /**
+     * Flag for an invalid value.  Not part of the FieldValue union but returned when casting to a field value if the
+     * cast is impossible
+     */
+    export const Invalid: unique symbol = Symbol("invalid");
+    export type Invalid = typeof Invalid;
+
+    /**
+     * Reference to a named field
+     */
+    export type Reference = {
+        type: reference;
+        name: string;
+    };
+
+    export function Reference(name: string): Reference {
+        return { type: reference, name };
+    }
+
+    /**
+     * Celsius value, typically .1°C or .01°C
+     */
+    export type Celsius = {
+        type: celsius;
+        value: number;
+    };
+
+    export function Celsius(value: number): Celsius {
+        return { type: celsius, value };
+    }
+
+    /**
+     * Percent value, units of either 1% (.01) or .01% (.0001)
+     */
+    export type Percent = {
+        type: percent;
+        value: number;
+    };
+
+    export function Percent(value: number): Percent {
+        return { type: percent, value };
+    }
+
+    /**
+     * A set of struct property values keyed by name.
+     */
+    export type Properties = {
+        type: properties;
+        properties: { [name: string]: FieldValue };
+    };
+
+    /**
+     * Byte value, encoded as hex string.
+     */
+    export type Bytes = {
+        type: bytes;
+        value: string;
+    };
+
+    export function Bytes(value: Uint8Array | string): Bytes {
+        return { type: bytes, value: ArrayBuffer.isView(value) ? ByteUtils.toHex(value) : value };
+    }
+
+    /**
+     * Convert the field value to a "defacto-standard" form.
+     */
+    export function serialize(value: FieldValue): string {
+        if (value === null) {
+            return "null";
+        }
+        if (is(value, reference)) {
+            return (value as Reference).name;
+        }
+        if (is(value, celsius)) {
+            return `${(value as Celsius).value}°C`;
+        }
+        if (is(value, percent)) {
+            return `${(value as Percent).value}%';`;
+        }
+        if (is(value, properties)) {
+            return stringSerialize((value as Properties).properties) ?? "?";
+        }
+        return value.toString();
+    }
+
+    /**
+     * Given a type name as a hint, do our best to convert a field value to a number.
+     */
+    export function numericValue(value: FieldValue | undefined, typeName?: string) {
+        if (typeof value === "boolean") {
+            return value ? 1 : 0;
+        }
+
+        if (typeof value === "number") {
+            return value;
+        }
+
+        if (is(value, celsius)) {
+            switch (typeName) {
+                case "temperature":
+                case "temp-diff":
+                    return (value as Celsius).value * 100;
+
+                case "temp-u8":
+                case "temp-s8":
+                    return (value as Celsius).value * 10;
+            }
+
+            // Not sure how to interpret the value
+            return;
+        }
+
+        if (is(value, percent)) {
+            switch (typeName) {
+                case "percent100ths":
+                    return (value as Percent).value * 100;
+
+                default:
+                    return (value as Percent).value;
+            }
+        }
+    }
+
+    /**
+     * Extract object properties from the value.
+     */
+    export function objectValue(value: FieldValue | undefined) {
+        if (is(value, properties)) {
+            return (value as Properties).properties;
+        }
+    }
+
+    /**
+     * Unwrap wrapped values, leave others as-is.
+     */
+    export function unwrap(value: FieldValue | undefined, typeName?: string) {
+        if (value === null || typeof value !== "object" || Array.isArray(value) || value instanceof Date) {
+            return value;
+        }
+
+        const type = value.type;
+        switch (type) {
+            case "properties":
+                return objectValue(value);
+
+            case "reference":
+                // This needs to be handled at a higher level
+                return;
+
+            case "percent":
+            case "celsius":
+                return numericValue(value, typeName);
+
+            case undefined:
+                throw new UnexpectedDataError(`Field value objects must be wrappers with "type" field`);
+
+            default:
+                throw new UnexpectedDataError(`Unsupported wrapped object type "${type}"`);
+        }
+    }
+
+    /**
+     * Get the referenced name if the FieldValue is a reference.
+     */
+    export function referenced(value: FieldValue | undefined) {
+        if (is(value, reference)) {
+            return (value as Reference).name;
+        }
+    }
+
+    /**
+     * Convert an arbitrary value to a proper FieldValue.
+     *
+     * @param type casts to a native equivalent of this type
+     * @param value value to cast
+     *
+     * @returns the cast value or FieldValue.Invalid if cast is not possible
+     */
+    export function cast(type: Metatype, value: any): FieldValue | FieldValue.Invalid | undefined {
+        if (value === undefined || value === null || type === "any") {
+            return value;
+        }
+
+        if (value === "null") {
+            return null;
+        }
+
+        if (value === "") {
+            if (type === "string") {
+                return "";
+            }
+            return undefined;
+        }
+
+        if (FieldValue.is(value, FieldValue.reference)) {
+            return value;
+        }
+
+        switch (type) {
+            case "string":
+                return value.toString();
+
+            case "boolean":
+                if (typeof value === "string") {
+                    value = value.trim().toLowerCase();
+                }
+                return value !== "false" && value !== "no" && !!value;
+
+            case "bitmap":
+            case "enum":
+                if (FieldValue.is(value, FieldValue.properties) && type === "bitmap") {
+                    return value;
+                }
+
+                const id = Number(value);
+                if (Number.isNaN(id)) {
+                    if (typeof value === "string") {
+                        // Key name
+                        return value;
+                    }
+                    return;
+                }
+
+                // Value
+                return id;
+
+            case "integer":
+                if (typeof value === "string") {
+                    // Specialized support for percentages and temperatures
+                    let type: FieldValue.celsius | FieldValue.percent | undefined;
+                    if (value.endsWith("°C")) {
+                        type = FieldValue.celsius;
+                    } else if (value.endsWith("%")) {
+                        type = FieldValue.percent;
+                    }
+                    if (type) {
+                        value = Number.parseInt(value);
+                        if (Number.isNaN(value)) {
+                            return FieldValue.Invalid;
+                        }
+                        return { type, value };
+                    }
+
+                    // Strip off extra garbage like Number.parseInt would but BigInt doesn't
+                    const match = value.match(/^(0x[0-9a-f]+|0b[01]+|\d+)/i);
+                    if (match) {
+                        value = match[1];
+                    }
+                }
+
+                try {
+                    switch (typeof value) {
+                        case "string":
+                        case "number":
+                        case "bigint":
+                        case "boolean":
+                            break;
+
+                        default:
+                            if (FieldValue.is(value, FieldValue.celsius) || FieldValue.is(value, FieldValue.percent)) {
+                                return value;
+                            }
+                            return FieldValue.Invalid;
+                    }
+                    const i = BigInt(value);
+                    const n = Number(i);
+                    if (BigInt(n) === i) {
+                        return n;
+                    }
+                    return i;
+                } catch (e) {
+                    if (e instanceof SyntaxError) {
+                        return FieldValue.Invalid;
+                    }
+                    throw e;
+                }
+
+            case "float":
+                const float = Number(value);
+                if (Number.isNaN(float)) {
+                    return FieldValue.Invalid;
+                }
+                return float.valueOf();
+
+            case "date":
+                if (value instanceof Date) {
+                    return value;
+                }
+                if (typeof value !== "string") {
+                    return FieldValue.Invalid;
+                }
+                value = new Date(value);
+                if (Number.isNaN(value.valueOf())) {
+                    return FieldValue.Invalid;
+                }
+                return value;
+
+            case "object":
+                if (FieldValue.is(value, FieldValue.properties)) {
+                    return value;
+                }
+                break;
+
+            case "bytes":
+                if (value === "empty") {
+                    return undefined;
+                }
+                if (FieldValue.is(value, FieldValue.bytes)) {
+                    return value;
+                }
+                if (typeof value === "string" || value instanceof Uint8Array) {
+                    return Bytes(value);
+                }
+                break;
+
+            case "array":
+                // Eject garbage we've seen in the spec
+                if (value === "0" || value === "{0,0}") {
+                    return;
+                }
+                if (value === "empty" || value === "[]" || value === "{}") {
+                    return [];
+                }
+                if (Array.isArray(value)) {
+                    return value;
+                }
+
+                // The only supported literal is an empty array
+                return FieldValue.Invalid;
+        }
+
+        return FieldValue.Invalid;
+    }
+}