@matter/model 0.11.9-alpha.0-20241203-06077d82e → 0.11.9-alpha.0-20241206-22f233334

package/src/models/Model.ts

@@ -34,11 +34,6 @@ export abstract class Model<T extends BaseElement = BaseElement> {
     #name: string;
     #frozen?: boolean;
 
-    /**
-     * Indicates that an element may have type definitions as children.
-     */
-    isTypeScope?: boolean;
-
     /**
      * Indicates that an element defines a datatype.
      */
@@ -59,7 +54,7 @@ export abstract class Model<T extends BaseElement = BaseElement> {
      */
     operationalShadow?: Model | null;
 
-    #children?: Children<Model>;
+    #children?: Children;
     #parent?: Model;
 
     /**
@@ -269,6 +264,15 @@ export abstract class Model<T extends BaseElement = BaseElement> {
         return [this.tag];
     }
 
+    /**
+     * Update a subset of fields.
+     */
+    patch(values: Partial<T>) {
+        for (const [k, v] of Object.entries(values.valueOf())) {
+            this[k as keyof this] = v;
+        }
+    }
+
     /**
      * Determine whether this element applies to a specific revision.
      */
@@ -357,9 +361,10 @@ export abstract class Model<T extends BaseElement = BaseElement> {
             switch (key) {
                 case "parent":
                 case "errors":
-                case "isTypeScope":
+                case "scope":
                 case "isType":
                 case "operationalBase":
+                case "isScope":
                     continue;
 
                 default:
@@ -379,6 +384,13 @@ export abstract class Model<T extends BaseElement = BaseElement> {
         return new ModelTraversal().visit(this, visitor);
     }
 
+    /**
+     * Visit this model and each of its ancestors.
+     */
+    forEachAncestor(fn: (model: Model) => boolean | void) {
+        new ModelTraversal().visitInheritance(this, fn);
+    }
+
     /**
      * Find all children that reference a specific type.
      */
@@ -412,10 +424,14 @@ export abstract class Model<T extends BaseElement = BaseElement> {
      * Create an operational extension of the model.  This creates a new model that inherits from this model for
      * operational purposes.
      */
-    extend<This extends Model>(this: This, properties?: Partial<BaseElement.Properties<T>>): This {
+    extend<This extends Model>(
+        this: This,
+        properties?: Partial<BaseElement.Properties<T>>,
+        ...children: Model.Definition<Model>[]
+    ): This {
         const constructor = this.constructor as new (properties: unknown) => This;
 
-        const extension = new constructor({
+        const definition = {
             id: this.id,
             name: this.name,
 
@@ -423,14 +439,24 @@ export abstract class Model<T extends BaseElement = BaseElement> {
 
             tag: this.tag,
             operationalBase: this,
-        });
+        };
+
+        if (children.length) {
+            if (definition.children) {
+                definition.children = [...definition.children, ...children];
+            } else {
+                definition.children = children;
+            }
+        }
+
+        const extension = new constructor(definition);
 
         return extension;
     }
 
     constructor(definition: Model<T> | BaseElement.Properties<T>, ...children: Model.Definition<Model>[]) {
         if (typeof definition !== "object") {
-            throw new ImplementationError(`Model definition must be an object, not "${typeof definition}"`);
+            throw new ImplementationError(`Model definition must be an object, not ${typeof definition}`);
         }
 
         const isClone = definition instanceof Model;
@@ -556,7 +582,7 @@ export namespace Model {
     /**
      * Obtain the element type of a model type.
      */
-    export type ElementOf<T> = T extends Model<infer E extends AnyElement> ? E : never;
+    export type ElementOf<T> = T extends Model<infer E extends AnyElement> ? E : AnyElement;
 
     /**
      * Obtain the child type of a model type.

package/src/models/ScopeModel.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { SchemaImplementationError } from "#common/errors.js";
+import { BaseElement } from "#elements/BaseElement.js";
+import { ModelTraversal } from "#logic/ModelTraversal.js";
+import { Scope } from "#logic/Scope.js";
+import { Model } from "./Model.js";
+
+/**
+ * A "scope" is a model provides name resolution for other models.
+ *
+ * {@link Model#type} must reference a model named in a parent scope.
+ */
+export abstract class ScopeModel<T extends BaseElement = BaseElement> extends Model<T> {
+    #operationalScope: undefined | Scope;
+
+    readonly isScope = true;
+
+    get scope() {
+        if (this.#operationalScope !== undefined) {
+            return this.#operationalScope;
+        }
+        return Scope(this);
+    }
+
+    override freeze() {
+        if (!this.#operationalScope) {
+            this.#operationalScope = Scope(this);
+        }
+        super.freeze();
+        return this;
+    }
+
+    static is(model: Model): model is ScopeModel {
+        return !!(model as ScopeModel).isScope;
+    }
+
+    static of(model: Model) {
+        if ((model as ScopeModel).isScope) {
+            return model as ScopeModel;
+        }
+
+        const scope = new ModelTraversal().findScope(model);
+
+        if (scope === undefined) {
+            throw new SchemaImplementationError(model, `No parent scope`);
+        }
+
+        return scope;
+    }
+}

package/src/models/ValueModel.ts

@@ -14,10 +14,8 @@ import { PropertyModel } from "./PropertyModel.js";
 
 // These are circular dependencies so just to be safe we only import the types.  We also need the class, though, at
 // runtime.  So we use the references in the Model.constructors factory pool.
-import { camelize } from "@matter/general";
-import { DefaultValue } from "../logic/DefaultValue.js";
+import { Scope } from "#logic/Scope.js";
 import { Children } from "./Children.js";
-import { type ClusterModel } from "./ClusterModel.js";
 import { type FieldModel } from "./FieldModel.js";
 
 const CONSTRAINT: unique symbol = Symbol("constraint");
@@ -135,14 +133,6 @@ export abstract class ValueModel<T extends ValueElement = ValueElement> extends
         }
     }
 
-    /**
-     * The value to use as a default.  The "default" field has a manually supplied value but this property decodes the
-     * default and/or generates a default from subfields.
-     */
-    get effectiveDefault() {
-        return DefaultValue(this);
-    }
-
     /**
      * Get the first derived ancestor with children, if any.
      */
@@ -176,34 +166,10 @@ export abstract class ValueModel<T extends ValueElement = ValueElement> extends
     }
 
     /**
-     * All {@link FieldModel} children}.
+     * All {@link FieldModel} children in the context of the model's containing scope.
      */
     get members(): PropertyModel[] {
-        return new ModelTraversal().findChildren(this, [ElementTag.Field]) as PropertyModel[];
-    }
-
-    /**
-     * A subset of {@link members} with conflicts resolved by conformance.
-     */
-    get activeMembers() {
-        const cluster = this.owner(Model.types[ElementTag.Cluster]) as ClusterModel | undefined;
-        return new ModelTraversal().findActiveMembers(this, false, cluster);
-    }
-
-    /**
-     * The subset of {@link members} that are conformant.
-     */
-    get conformantMembers() {
-        const cluster = this.owner(Model.types[ElementTag.Cluster]) as ClusterModel | undefined;
-        return new ModelTraversal().findActiveMembers(this, true, cluster);
-    }
-
-    /**
-     * Active members keyed by property name.
-     */
-    get fields() {
-        const members = this.activeMembers;
-        return Object.fromEntries(members.map(member => [camelize(member.name), member]));
+        return Scope(this).membersOf(this) as PropertyModel[];
     }
 
     /**
@@ -290,6 +256,18 @@ export abstract class ValueModel<T extends ValueElement = ValueElement> extends
         return new ModelTraversal().findBitDefinition(this, bit);
     }
 
+    /**
+     * Clone the model with minimum metadata required to ensure model is valid.
+     */
+    cloneAsReference<This extends ValueModel>(this: This): This {
+        const Type = this.constructor as new (definition: T) => This;
+        return new Type(this.requiredFields as T);
+    }
+
+    get requiredFields() {
+        return { name: this.name } as T;
+    }
+
     override valueOf() {
         const result = super.valueOf() as any;
         for (const k of ["conformance", "access", "quality", "constraint"]) {
@@ -304,8 +282,8 @@ export abstract class ValueModel<T extends ValueElement = ValueElement> extends
         return result as T;
     }
 
-    constructor(definition: BaseElement.Properties<T>) {
-        super(definition);
+    constructor(definition: BaseElement.Properties<T>, ...children: Model.Definition<FieldModel>[]) {
+        super(definition, ...children);
 
         const match = this.type?.match(/^list\[(.*)\]$/);
         if (match) {

package/src/models/index.ts

@@ -19,6 +19,7 @@ export * from "./Model.js";
 export * from "./NodeModel.js";
 export * from "./PropertyModel.js";
 export * from "./RequirementModel.js";
+export * from "./ScopeModel.js";
 export * from "./SemanticNamespaceModel.js";
 export * from "./SemanticTagModel.js";
 export * from "./ValueModel.js";

package/src/standard/elements/ColorControl.ts

@@ -166,7 +166,7 @@ export const ColorControl = Cluster({
 
         Attribute({
             name: "ColorMode", id: 0x8, type: "enum8", access: "R V", conformance: "M", constraint: "0 to 2",
-            default: 1, quality: "N",
+            quality: "N",
 
             details: "The ColorMode attribute indicates which attributes are currently determining the color of the " +
                 "device." +
@@ -178,9 +178,9 @@ export const ColorControl = Cluster({
 
             xref: { document: "cluster", section: "3.2.7.10" },
             children: [
-                Field({ name: "CurrentHueAndCurrentSaturation", id: 0x0 }),
-                Field({ name: "CurrentXAndCurrentY", id: 0x1 }),
-                Field({ name: "ColorTemperatureMireds", id: 0x2 })
+                Field({ name: "CurrentHueAndCurrentSaturation", id: 0x0, conformance: "HS" }),
+                Field({ name: "CurrentXAndCurrentY", id: 0x1, conformance: "XY" }),
+                Field({ name: "ColorTemperatureMireds", id: 0x2, conformance: "CT" })
             ]
         }),
 

package/src/standard/elements/ModeBase.ts

@@ -204,7 +204,7 @@ export const ModeBase = Cluster({
                 }),
 
                 Field({
-                    name: "Value", id: 0x1, type: "enum16", conformance: "M",
+                    name: "Value", id: 0x1, type: "ModeTag", conformance: "M",
                     details: "This field shall indicate the mode tag within a mode tag namespace which is either manufacturer " +
                         "specific or standard.",
                     xref: { document: "cluster", section: "1.10.5.1.2" }

package/src/standard/elements/PumpConfigurationAndControl.ts

@@ -388,26 +388,10 @@ export const PumpConfigurationAndControl = Cluster({
         }),
 
         Attribute({
-            name: "AlarmMask", id: 0x1d, type: "map16", access: "R V", conformance: "D", constraint: "desc",
+            name: "AlarmMask", id: 0x22, type: "uint16", access: "R V", conformance: "D", constraint: "desc",
             default: 0, quality: "N",
-            xref: { document: "cluster", section: "4.2.7" },
-
-            children: [
-                Field({
-                    name: "InitializationFailure", constraint: "0",
-                    details: "The device failed to complete initialization at powerup"
-                }),
-                Field({
-                    name: "HardwareFailure", constraint: "1",
-                    details: "The device has detected a hardware fault"
-                }),
-                Field({
-                    name: "SelfCalibrationFailure", constraint: "2",
-                    details: "The device was unable to complete self calibration"
-                })
-            ]
+            xref: { document: "cluster", section: "4.2.7" }
         }),
-
         Event({
             name: "SupplyVoltageLow", id: 0x0, access: "V", conformance: "O", priority: "info",
             xref: { document: "cluster", section: "4.2.8" }

package/src/standard/elements/UserLabel.ts

@@ -18,18 +18,14 @@ export const UserLabel = Cluster({
     details: "This cluster provides a feature to tag an endpoint with zero or more labels.",
     xref: { document: "core", section: "9.9" },
 
-    children: [
-        Attribute({ name: "ClusterRevision", id: 0xfffd, type: "ClusterRevision", default: 1 }),
-
-        Attribute({
-            name: "LabelList", id: 0x0, type: "list", access: "RW VM", conformance: "M", constraint: "min 0",
-            default: [], quality: "N",
-            details: "An implementation shall support at least 4 list entries per node for all User Label cluster " +
-                "instances on the node.",
-            xref: { document: "core", section: "9.9.4.1" },
-            children: [Field({ name: "entry", type: "LabelStruct" })]
-        })
-    ]
+    children: [Attribute({
+        name: "LabelList", id: 0x0, type: "list", access: "RW VM", conformance: "M", constraint: "min 0",
+        default: [], quality: "N",
+        details: "An implementation shall support at least 4 list entries per node for all User Label cluster " +
+            "instances on the node.",
+        xref: { document: "core", section: "9.9.4.1" },
+        children: [Field({ name: "entry", type: "LabelStruct" })]
+    })]
 });
 
 MatterDefinition.children.push(UserLabel);

package/src/standard/elements/WildcardPathFlagsBitmap.ts

@@ -28,10 +28,7 @@ export const WildcardPathFlagsBitmap = Datatype({
             name: "WildcardSkipAttributeList", constraint: "2",
             description: "Skip the AttributeList global attribute during wildcard expansion."
         }),
-        Field({
-            name: "WildcardSkipEventList", constraint: "3",
-            description: "Skip the EventList global attribute during wildcard expansion."
-        }),
+        Field({ name: "Reserved", constraint: "3", description: "Reserved" }),
         Field({
             name: "WildcardSkipCommandLists", constraint: "4",
             description: "Skip the AcceptedCommandList and GeneratedCommandList global attributes during wildcard expansion."

package/src/standard/elements/WindowCovering.ts

@@ -403,7 +403,7 @@ export const WindowCovering = Cluster({
                     name: "LiftPercent100thsValue", id: 0x0, type: "percent100ths", conformance: "M",
                     constraint: "desc"
                 }),
-                Field({ name: "Ignored", id: 0x1, type: "percent100ths", conformance: "D", constraint: "desc" })
+                Field({ name: "Ignored", id: 0x1, type: "percent100ths", conformance: "X", constraint: "desc" })
             ]
         }),
 
@@ -447,7 +447,7 @@ export const WindowCovering = Cluster({
                     name: "TiltPercent100thsValue", id: 0x0, type: "percent100ths", conformance: "M",
                     constraint: "desc"
                 }),
-                Field({ name: "Ignored", id: 0x1, type: "percent100ths", conformance: "D", constraint: "desc" })
+                Field({ name: "Ignored", id: 0x1, type: "percent100ths", conformance: "X", constraint: "desc" })
             ]
         }),