@matter/model 0.16.0-alpha.0-20251018-dd1ea6a8a → 0.16.0-alpha.0-20251020-3f6e46245

package/src/models/Children.ts

@@ -556,9 +556,9 @@ export function Children<T extends Model = Model>(
         });
     }
 
-    function freeze() {
+    function finalize() {
         for (const child of self) {
-            (child as Model).freeze();
+            (child as Model).finalize();
         }
         Object.freeze(children);
     }
@@ -621,7 +621,7 @@ export function Children<T extends Model = Model>(
                     return splice;
 
                 case "freeze":
-                    return freeze;
+                    return finalize;
 
                 case "toString":
                     return () => `[Children: ${children.length}]`;

package/src/models/CommandModel.ts

@@ -71,6 +71,7 @@ export class CommandModel extends ValueModel<CommandElement> implements CommandE
     }
 
     static Tag = CommandElement.Tag;
+    static requiresId = true;
 }
 
 CommandModel.register();

package/src/models/EventModel.ts

@@ -34,6 +34,7 @@ export class EventModel extends ValueModel<EventElement> implements EventElement
     }
 
     static Tag = EventElement.Tag;
+    static requiresId = true;
 }
 
 EventModel.register();

package/src/models/Model.ts

@@ -31,7 +31,7 @@ export abstract class Model<E extends BaseElement = BaseElement, C extends Model
 
     #id: E["id"];
     #name: string;
-    #frozen?: boolean;
+    #isFinal?: boolean;
     #resource?: Resource;
 
     /**
@@ -65,7 +65,7 @@ export abstract class Model<E extends BaseElement = BaseElement, C extends Model
     set id(value: E["id"]) {
         const oldId = this.effectiveId;
         this.#id = value;
-        (this.#parent?.children as InternalChildren).updateId(this, oldId);
+        (this.#parent?.children as InternalChildren | undefined)?.updateId(this, oldId);
     }
 
     get name() {
@@ -75,7 +75,7 @@ export abstract class Model<E extends BaseElement = BaseElement, C extends Model
     set name(value: string) {
         const oldName = this.#name;
         this.#name = value;
-        (this.#parent?.children as InternalChildren).updateName(this, oldName);
+        (this.#parent?.children as InternalChildren | undefined)?.updateName(this, oldName);
     }
 
     /**
@@ -598,28 +598,36 @@ export abstract class Model<E extends BaseElement = BaseElement, C extends Model
         if (children.length) {
             this.children.push(...children);
         }
+
+        if (!isClone && definition.parent) {
+            this.parent = definition.parent;
+        }
     }
 
     /**
-     * Freeze the model hierarchy rooted at this model.
+     * Finalize the model hierarchy rooted at this model.
      *
      * When using a model as operational schema we implement various optimizations that assume the schema is immutable.
      * This function enforces that assumption and caches a few values that only make sense with frozen schema.
      *
-     * To make changes to a frozen model use {@link clone}.
+     * To make changes to a final model use {@link clone}.
      */
-    freeze() {
-        if (this.#frozen) {
+    finalize() {
+        if (this.#isFinal) {
             return;
         }
 
         const base = this.operationalBase ?? (this.operationalBase = this.base ?? null);
         const shadow = this.operationalShadow ?? (this.operationalShadow = this.shadow ?? null);
-        this.#frozen = true;
+        this.#isFinal = true;
         (this.children as InternalChildren<C>).freeze();
         Object.freeze(this);
-        base?.freeze();
-        shadow?.freeze();
+        base?.finalize();
+        shadow?.finalize();
+    }
+
+    get isFinal() {
+        return this.#isFinal;
     }
 
     toString() {
@@ -743,9 +751,20 @@ export namespace Model {
      * In most places elements and models are interchangeable on input.
      */
     export type Definition<T extends Model> =
-        | (BaseElement.Properties<ElementOf<T>> & { operationalBase?: Model; operationalShadow?: Model })
+        | (BaseElement.Properties<ElementOf<T>> & {
+              parent?: Model;
+              operationalBase?: Model;
+              operationalShadow?: Model;
+          })
         | T;
 
+    /**
+     * An object that may be used in some places where a model is required.
+     *
+     * This is either a model, a class constructor or a DecoratorContext.
+     */
+    export type Source = Model | NewableFunction;
+
     /**
      * Tagged input.  Like {@link Definition} but for places where model type is not implied.
      */
@@ -769,7 +788,10 @@ export namespace Model {
     /**
      * A model constructor for a specific element type.
      */
-    export type ConcreteType<T extends Model = Model> = (new (definition: any) => T) & { Tag: ElementTag };
+    export type ConcreteType<T extends Model = Model> = (new (definition: any) => T) & {
+        Tag: ElementTag;
+        requiresId?: boolean;
+    };
 
     /**
      * A patch to a model tree.

package/src/models/Schema.ts

@@ -4,11 +4,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { ImplementationError } from "#general";
 import type { ClusterModel } from "#models/ClusterModel.js";
 import { DatatypeModel } from "#models/DatatypeModel.js";
+import type { Model } from "#models/Model.js";
 import type { ValueModel } from "#models/ValueModel.js";
+import { MissingMetadataError } from "../decoration/errors.js";
+import { Semantics } from "../decoration/semantics/Semantics.js";
 
 /**
+ * Matter data structure semantics
+ *
  * Here we use the term "schema" to mean any model element that defines a datatype.  For schema we allow any Matter
  * model for such an element.
  *
@@ -18,9 +24,54 @@ import type { ValueModel } from "#models/ValueModel.js";
  * to JS objects and arrays respectively.  Thus we tend to use struct/object and list/array interchangeably.
  *
  * If schema is a {@link ClusterModel}, it models a struct with attributes as fields.
+ *
+ * Schema is immutable and cannot change moving forward.
  */
 export type Schema = ClusterModel | ValueModel;
 
+/**
+ * Obtain {@link Schema} for a {@link Schema.Source} if present.
+ */
+export function Schema(source: Model.Source) {
+    let model;
+    if ("tag" in source) {
+        source.finalize();
+
+        model = source;
+    } else {
+        const semantics = Semantics.classOf(source);
+
+        semantics.finalize();
+
+        model = semantics.semanticModel;
+    }
+
+    if (!model) {
+        return;
+    }
+
+    if (model.tag !== "cluster" && !model.isType) {
+        throw new ImplementationError(`Model ${model.name} tag ${model.tag} is not legal for schema`);
+    }
+
+    return model as Schema;
+}
+
 export namespace Schema {
+    /**
+     * Obtain {@link Schema} that is required for operation.
+     */
+    export function Required(source: Model.Source) {
+        const schema = Schema(source);
+
+        if (schema === undefined) {
+            throw new MissingMetadataError(`Metadata missing for class ${source.name}`);
+        }
+
+        return schema;
+    }
+
+    export type Source = Schema | NewableFunction;
+
     export const empty = new DatatypeModel({ name: "Empty", type: "struct" });
 }

package/src/models/ScopeModel.ts

@@ -33,11 +33,11 @@ export abstract class ScopeModel<
         return Scope(this);
     }
 
-    override freeze() {
+    override finalize() {
         if (!this.#operationalScope) {
             this.#operationalScope = Scope(this);
         }
-        super.freeze();
+        super.finalize();
         return this;
     }
 

package/src/standard/elements/definitions.ts

@@ -210,7 +210,7 @@ export * from "./locationdesc.element.js";
 export * from "./wildcard-path-flags-bitmap.element.js";
 export * from "./software-version-certification-status-enum.element.js";
 export * from "./any.element.js";
-export * from "./interval.element.js";
+export * from "./duration.element.js";
 export * from "./subject-id.element.js";
 export * from "./cluster-revision.element.js";
 export * from "./feature-map.element.js";

package/src/standard/elements/models.ts

@@ -230,7 +230,7 @@ export const SoftwareVersionCertificationStatusEnum = new DatatypeModel(
     definitions.SoftwareVersionCertificationStatusEnum,
 );
 export const any = new DatatypeModel(definitions.any);
-export const interval = new DatatypeModel(definitions.duration);
+export const duration = new DatatypeModel(definitions.duration);
 export const subjectId = new DatatypeModel(definitions.subjectId);
 export const ClusterRevision = new AttributeModel(definitions.ClusterRevision);
 export const FeatureMap = new AttributeModel(definitions.FeatureMap);

package/dist/cjs/standard/elements/interval.element.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"interval.element.d.ts","sourceRoot":"","sources":["../../../../src/standard/elements/interval.element.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,eAAe,IAAI,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEtE,eAAO,MAAM,QAAQ,UAAuD,CAAC"}

package/dist/esm/standard/elements/interval.element.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"interval.element.d.ts","sourceRoot":"","sources":["../../../../src/standard/elements/interval.element.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,eAAe,IAAI,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEtE,eAAO,MAAM,QAAQ,UAAuD,CAAC"}