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

package/src/logic/Scope.ts

@@ -0,0 +1,400 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ElementTag } from "#common/ElementTag.js";
+import { SchemaImplementationError } from "#common/errors.js";
+import { FeatureSet } from "#common/FeatureSet.js";
+import { ImplementationError } from "@matter/general";
+import { ModelTraversal } from "./ModelTraversal.js";
+
+// These must be types to avoid circular references
+import type { ClusterModel, Model, ScopeModel, ValueModel } from "#models/index.js";
+
+const DEFAULT_TAGS = new Set([ElementTag.Field, ElementTag.Attribute]);
+const GLOBAL_IDS = new Set([0xfffd, 0xfffc, 0xfffb, 0xfffa, 0xfff9, 0xfff8]);
+
+const cache = new WeakMap<Model, Scope>();
+
+/**
+ * Tracks extensions for a scope to models in parent scopes.
+ *
+ * A child model with the same {tag, name, type} tuple in a derived scope is a semantic extension of the model in the
+ * parent scope even if it does not explicitly inherit from the parent via {@link Model#type}.  We refer to the implicit
+ * base class as a *shadow* and the implicit child class as an *extension*.
+ *
+ * Note that "type" in above tuple includes either undefined, the model's own name, or extension of the exact same type
+ * in both the shadow and the extension.  In the former case the shadow is implicit; in the latter case it is explicit.
+ *
+ * This utility provideds optimized lookup of extensions present in a particular scope.
+ *
+ * If the scope is frozen the analysis is cached.
+ *
+ * TODO - there is remaining ambiguity in shadow selection, fine for now but could be eliminated with conformance
+ *
+ * TODO - currently we only consider shadows at scope root but shadows of nested children is possible with this approach
+ */
+export interface Scope {
+    /**
+     * The model analyzed.
+     */
+    owner: Model;
+
+    /**
+     * Determine if the model is a shadow.
+     */
+    isShadow(model?: Model): boolean;
+
+    /**
+     * Retrieve the extension for an element if it is a shadow.
+     */
+    extensionOf<T extends Model>(model?: T): undefined | T;
+
+    /**
+     * Obtain canonical definition for model.  If the input model is a shadow returns the extension, otherwise returns
+     * the input model.
+     */
+    modelFor<T extends Model>(model: T): T;
+
+    /**
+     * Identify members (child properties) of the designated model in this scope.
+     */
+    membersOf<T extends Model>(parent: T, options?: Scope.MemberOptions): Model.ChildOf<T>[];
+}
+
+/**
+ * Obtain the scope for a model.
+ *
+ * By default, if {@link subject} is not a {@link ScopeModel} the scope returned is for the nearest owning
+ * {@link ScopeModel}.
+ */
+export function Scope(subject: Model, options: Scope.ScopeOptions = {}) {
+    let owner: Model;
+
+    if ((subject as ScopeModel).isScope || options.forceOwner) {
+        owner = subject as ScopeModel;
+    } else {
+        const scope = new ModelTraversal().findScope(subject);
+
+        if (scope === undefined) {
+            throw new SchemaImplementationError(subject, `No parent scope`);
+        }
+
+        owner = scope;
+    }
+
+    const useCache = options.forceCache || Object.isFrozen(owner);
+
+    let deconflictedMemberCache: Map<Model, Model[]> | undefined;
+    let conformantMemberCache: Map<Model, Model[]> | undefined;
+
+    let { featureNames, supportedFeatures } = owner as ClusterModel;
+    if (!featureNames) {
+        featureNames = new FeatureSet();
+    }
+    if (!supportedFeatures) {
+        supportedFeatures = new FeatureSet();
+    }
+
+    if (useCache && !options.disableCache) {
+        const cached = cache.get(owner);
+        if (cached) {
+            return cached;
+        }
+        deconflictedMemberCache = new Map();
+        conformantMemberCache = new Map();
+    }
+
+    let shadows: undefined | WeakMap<Model /* shadow */, Model[] /* canonical */>;
+    const canonicalIdentityLevels = {} as Record<string, { level: number; models: Model[] }>;
+    let level = 0;
+
+    new ModelTraversal().visitInheritance(owner, scope => {
+        level++;
+
+        for (const model of scope.children) {
+            for (const identity of [`n${model.tag}␜${model.name}␜${model.discriminator ?? ""}`]) {
+                const canonical = canonicalIdentityLevels[identity];
+                if (canonical === undefined) {
+                    canonicalIdentityLevels[identity] = {
+                        level,
+                        models: [model],
+                    };
+                } else if (canonical.level === level) {
+                    canonical.models.push(model);
+                } else {
+                    if (!shadows) {
+                        shadows = new WeakMap();
+                    }
+                    shadows.set(model, canonical.models);
+                }
+            }
+        }
+    });
+
+    const result: Scope = {
+        owner,
+        isShadow: shadows ? model => shadows!.has(model as ValueModel) : () => false,
+        extensionOf: shadows
+            ? <T extends Model>(model?: T) => shadows!.get(model as unknown as ValueModel)?.[0] as T | undefined
+            : <T extends Model>(model?: T) => model,
+        modelFor: shadows
+            ? <T extends Model>(model: T) =>
+                  (shadows!.get(model as unknown as ValueModel)?.[0] as T | undefined) ?? model
+            : <T extends Model>(model: T) => model,
+        membersOf,
+    };
+
+    function membersOf<T extends Model>(parent: T, options: Scope.MemberOptions = {}) {
+        const { conformance: conformanceMode, tags } = options;
+        const allMembers = findAllMembers(parent, Array.isArray(tags) ? new Set(tags) : (tags ?? DEFAULT_TAGS), result);
+
+        if (parent.tag === ElementTag.Cluster) {
+            injectGlobalAttributes(owner, allMembers);
+        }
+
+        if (!conformanceMode || conformanceMode === "ignore") {
+            return allMembers as Model.ChildOf<T>[];
+        }
+
+        const conformantOnly = conformanceMode === "conformant";
+
+        if (!conformantOnly && conformanceMode !== "deconflicted") {
+            throw new ImplementationError(`Invalid member conformance mode ${conformanceMode}`);
+        }
+
+        return filterWithConformance(
+            parent,
+            allMembers,
+            featureNames,
+            supportedFeatures,
+            conformantOnly,
+            conformantOnly ? deconflictedMemberCache : conformantMemberCache,
+        ) as Model.ChildOf<T>[];
+    }
+
+    if (useCache) {
+        cache.set(owner, result);
+    }
+
+    return result;
+}
+
+export namespace Scope {
+    /**
+     * Configuration for scope creation.
+     */
+    export interface ScopeOptions {
+        /**
+         * Force the result to cache regardless of whether model is frozen.
+         */
+        forceCache?: boolean;
+
+        /**
+         * Disable loading of model from cache.  Will still write to cache if {@link forceCache} is true.
+         */
+        disableCache?: boolean;
+
+        /**
+         * Force the input model as an owner even if it is not a {@link ScopeOwner}.
+         */
+        forceOwner?: boolean;
+    }
+
+    /**
+     * Return all members regardless of conformance.
+     */
+    export const IgnoreConformance = "ignore";
+
+    /**
+     * Use conformance to resolve conflicts but otherwise return all members.  Useful to detect errors in input
+     * that may contain non-conformant values.
+     */
+    export const DeconflictedConformance = "deconflicted";
+
+    /**
+     * Only return conformant members.
+     */
+    export const ConformantConformance = "conformant";
+
+    /**
+     * Determines how to apply conformance when selecting members.
+     */
+    export type ConformanceMode =
+        | typeof IgnoreConformance
+        | typeof DeconflictedConformance
+        | typeof ConformantConformance;
+
+    export interface MemberOptions {
+        /**
+         * Conformance filtering mode.
+         */
+        conformance?: ConformanceMode;
+
+        /**
+         * Applicable tags.  Defaults to "field" and "attribute".
+         */
+        tags?: Set<ElementTag> | ElementTag[];
+    }
+}
+
+/**
+ * Selects all candidate members for a model.
+ */
+function findAllMembers(parent: Model, tags: Set<ElementTag>, scope: Scope) {
+    const members = Array<Model>();
+
+    // This is a map of identity (based on tag + id/name + discriminator) to a priority based on inheritance depth
+    const defined = {} as Record<string, number | undefined>;
+
+    const visited = new Set<Model>();
+
+    const traversal = new ModelTraversal();
+
+    let level = 0;
+    const childSearchVisitor = (model: Model) => {
+        // If the model has an extension that we haven't yet visited, we need to move search to the extension.  This
+        // occurs if e.g. an attribute extends an attribute in a base cluster that references a datatype that is
+        // extended in the extended cluster
+        const extension = scope.modelFor(model);
+        if (extension !== model && !visited.has(extension)) {
+            traversal.visitInheritance(extension, childSearchVisitor);
+            return false;
+        }
+
+        visited.add(model);
+
+        level++;
+        for (const child of model.children) {
+            if (!tags.has(child.tag)) {
+                continue;
+            }
+
+            // Omit shadows
+            const nameIdentity = `s␜${child.tag}␜${child.name}␜${child.discriminator ?? ""}`;
+            const nameLevel = defined[nameIdentity];
+            if (nameLevel !== undefined && nameLevel < level) {
+                continue;
+            }
+
+            // Mark the level in which we saw these members
+            defined[nameIdentity] = level;
+
+            // Found a member
+            members.push(child);
+        }
+    };
+    traversal.visitInheritance(parent, childSearchVisitor);
+
+    return members;
+}
+
+/**
+ * We consider the standard set of "global" attributes members of all clusters.  This injects those members that are
+ * not otherwise defined in the cluster.
+ */
+function injectGlobalAttributes(scope: Model, members: Model[]) {
+    const missingGlobalIds = new Set(GLOBAL_IDS);
+    for (const m of members) {
+        if (m.tag === ElementTag.Attribute && m.id) {
+            missingGlobalIds.delete(m.id);
+        }
+    }
+
+    if (missingGlobalIds.size) {
+        const root = new ModelTraversal().findRoot(scope);
+        if (root) {
+            for (const id of missingGlobalIds) {
+                const global = root.children.select(id, [ElementTag.Attribute]);
+                if (global) {
+                    members.push(global);
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Filter selected members as follows:
+ *
+ *   - If the member is deprecated, ignore it
+ *
+ *   - If there is only a single member of a given name, select that member
+ *
+ *   - If there are multiple members with the same name but there is no cluster, throw an error
+ *
+ *   - If there are multiple members with the same name, use conformance to select the member that is applicable based
+ *     on active features in the provided cluster
+ *
+ *   - If there are multiple applicable members based on conformance the definitions conflict; and throw an error
+ *
+ * If the model is frozen we cache the return value.
+ *
+ * Note that "active" in this case does not imply the member is conformant, only that conflicts are resolved.
+ *
+ * Note 2 - members may not be differentiated with conformance rules that rely on field values in this way. That will
+ * probably never be necessary and would require an entirely different (more complicated) structure.
+ */
+function filterWithConformance(
+    parent: Model,
+    members: Model[],
+    features: FeatureSet,
+    supportedFeatures: FeatureSet,
+    conformantOnly: boolean,
+    cache?: Map<Model, Model[]>,
+) {
+    const cached = cache?.get(parent);
+    if (cached) {
+        return cached;
+    }
+
+    const selectedMembers = {} as Record<string, Model>;
+    for (const member of members) {
+        const { conformance } = member as ValueModel;
+
+        if (!conformance) {
+            throw new ImplementationError(
+                `Conformance filtering invoked on ${member} which does not support conformance`,
+            );
+        }
+
+        if (conformantOnly && !conformance.isApplicable(features, supportedFeatures)) {
+            continue;
+        }
+
+        const other = selectedMembers[member.name];
+        if (other !== undefined) {
+            if (!conformantOnly && !conformance.isApplicable(features, supportedFeatures)) {
+                continue;
+            }
+
+            const { conformance: otherConformance } = other as ValueModel;
+            if (!otherConformance) {
+                throw new ImplementationError(
+                    `Conformance filtering invoked on ${other} which does not support conformance`,
+                );
+            }
+
+            if (otherConformance.isApplicable(features, supportedFeatures)) {
+                throw new SchemaImplementationError(
+                    parent,
+                    `There are multiple definitions of "${member.name}" that cannot be differentiated by conformance`,
+                );
+            }
+
+            // This member takes precedence and will overwrite below
+        }
+
+        selectedMembers[member.name] = member;
+    }
+
+    const result = Object.values(selectedMembers);
+
+    if (cache) {
+        cache.set(parent, result);
+    }
+
+    return result;
+}

package/src/logic/index.ts

@@ -13,5 +13,6 @@ export * from "./ClusterVariance.js";
 export * from "./DefaultValue.js";
 export * from "./MergedModel.js";
 export * from "./ModelVariantTraversal.js";
+export * from "./Scope.js";
 export * from "./ValidateModel.js";
 import "./definition-validation/index.js";

package/src/models/AttributeModel.ts

@@ -36,6 +36,10 @@ export class AttributeModel extends PropertyModel<AttributeElement> implements A
         return this.effectiveQuality.changesOmitted;
     }
 
+    override get requiredFields() {
+        return { ...super.requiredFields, id: this.id };
+    }
+
     constructor(definition: AttributeElement.Properties) {
         super(definition);
     }

package/src/models/Children.ts

@@ -54,6 +54,11 @@ export interface Children<T extends Model = Model> extends Array<T> {
      */
     selectAll(selector: Children.Selector, allowedTags?: Children.TagSelector, except?: Set<Model>): Model.ChildOf<T>[];
 
+    /**
+     * Create a new child or patch existing children.
+     */
+    patchOrPush<C extends Model.Definition<T>>(child: C): void;
+
     /**
      * Models invoke this when their ID changes so we can update internal bookkeeping.
      */
@@ -245,7 +250,7 @@ export function Children<T extends Model = Model>(
     }
 
     /**
-     * Add a child of the model.  Adopts the mdodel and adds to any applicable indices.
+     * Add a child of the model.  Adopts the model and adds to any applicable indices.
      */
     function addChild(child: Model) {
         if ((child.parent?.children as unknown) === children) {
@@ -428,6 +433,21 @@ export function Children<T extends Model = Model>(
         return results;
     }
 
+    function patchOrPush(child: Model.Definition<T>) {
+        validateChild(child);
+
+        const existing = selectAll.call(self, child.name, [child.tag as ElementTag]);
+        if (existing.length) {
+            // Patch
+            for (const toPatch of existing) {
+                toPatch.patch(child);
+            }
+        } else {
+            // Push
+            self.push(child);
+        }
+    }
+
     function updateId(child: Model, oldId: number | undefined) {
         if (!indices) {
             return;
@@ -541,6 +561,9 @@ export function Children<T extends Model = Model>(
                 case "selectAll":
                     return selectAll;
 
+                case "patchOrPush":
+                    return patchOrPush;
+
                 case "updateId":
                     return updateId;
 

package/src/models/ClusterModel.ts

@@ -11,7 +11,6 @@ import { SchemaImplementationError } from "../common/errors.js";
 import { ElementTag, FeatureSet, Metatype } from "../common/index.js";
 import { Mei } from "../common/Mei.js";
 import { ClusterElement } from "../elements/index.js";
-import { ModelTraversal } from "../logic/ModelTraversal.js";
 import { ClusterRevision } from "../standard/elements/ClusterRevision.js";
 import { FeatureMap } from "../standard/elements/FeatureMap.js";
 import { Aspects } from "./Aspects.js";
@@ -22,16 +21,15 @@ import { DatatypeModel } from "./DatatypeModel.js";
 import { EventModel } from "./EventModel.js";
 import type { FieldModel } from "./FieldModel.js";
 import { Model } from "./Model.js";
-import { PropertyModel } from "./PropertyModel.js";
+import { ScopeModel } from "./ScopeModel.js";
 
 const QUALITY = Symbol("quality");
 
-export class ClusterModel extends Model<ClusterElement> implements ClusterElement {
+export class ClusterModel extends ScopeModel<ClusterElement> implements ClusterElement {
     override tag: ClusterElement.Tag = ClusterElement.Tag;
     declare id: Mei;
     declare classification?: ClusterElement.Classification;
     declare pics?: string;
-    override isTypeScope = true;
 
     override get children(): Children<ClusterModel.Child> {
         return super.children as Children<ClusterModel.Child>;
@@ -71,53 +69,15 @@ export class ClusterModel extends Model<ClusterElement> implements ClusterElemen
         return this.all(DatatypeModel);
     }
 
-    get members(): PropertyModel[] {
-        const traversal = new ModelTraversal();
-
-        // Formally a field element cannot be a cluster child but we allow it for metadata control when a field should
-        // not be published
-        const members = traversal.findChildren(this, [ElementTag.Field, ElementTag.Attribute]) as PropertyModel[];
-
-        // We consider the standard set of "global" attributes members of all clusters
-        const missingGlobalIds = new Set(AttributeModel.globalIds);
-        for (const m of members) {
-            if (m instanceof AttributeModel && m.id) {
-                missingGlobalIds.delete(m.id);
-            }
-        }
-
-        if (missingGlobalIds.size) {
-            const root = traversal.findRoot(this);
-            if (root) {
-                for (const id of missingGlobalIds) {
-                    const global = root.get(AttributeModel, id);
-                    if (global) {
-                        members.push(global);
-                    }
-                }
-            }
-        }
-
-        return members;
-    }
-
-    get activeMembers() {
-        return new ModelTraversal().findActiveMembers(this, false, this);
-    }
-
-    get conformantMembers() {
-        return new ModelTraversal().findActiveMembers(this, true, this);
-    }
-
     /**
      * Get attributes, commands and events whether inherited or defined directly in this model.
      */
     get allAces() {
-        return new ModelTraversal().findChildren(this, [
-            ElementTag.Attribute,
-            ElementTag.Command,
-            ElementTag.Event,
-        ]) as (AttributeModel | CommandModel | EventModel)[];
+        return this.scope.membersOf(this, { tags: [ElementTag.Attribute, ElementTag.Command, ElementTag.Event] }) as (
+            | AttributeModel
+            | CommandModel
+            | EventModel
+        )[];
     }
 
     get revision() {
@@ -202,8 +162,8 @@ export class ClusterModel extends Model<ClusterElement> implements ClusterElemen
         return result as ClusterElement;
     }
 
-    constructor(definition: ClusterElement.Properties) {
-        super(definition);
+    constructor(definition: ClusterModel.Definition, ...children: Model.Definition<ClusterModel.Child>[]) {
+        super(definition, ...children);
 
         if (definition instanceof Model) {
             Aspects.cloneAspects(definition, this, QUALITY);
@@ -218,13 +178,14 @@ export class ClusterModel extends Model<ClusterElement> implements ClusterElemen
 }
 
 export namespace ClusterModel {
+    export type Definition = ClusterElement.Properties & { supportedFeatures?: FeatureSet.Definition };
+
     export type Child =
         | DatatypeModel
         | AttributeModel
         | CommandModel
         | EventModel
 
-        // Fields are not cluster children in canonical schema but we allow
-        // them as private values in operational schema
+        // Fields are not cluster children in canonical schema but we allow them as private values in operational schema
         | FieldModel;
 }

package/src/models/CommandModel.ts

@@ -36,6 +36,10 @@ export class CommandModel extends ValueModel<CommandElement> implements CommandE
         return this.direction ?? (new ModelTraversal().findShadow(this) as CommandModel | undefined)?.direction;
     }
 
+    override get requiredFields() {
+        return { ...super.requiredFields, id: this.id };
+    }
+
     /**
      * Commands may re-use the ID for request and response so identification requires the ID in conjunction with the
      * direction.

package/src/models/DatatypeModel.ts

@@ -27,5 +27,3 @@ export class DatatypeModel extends ValueModel<DatatypeElement> implements Dataty
         Model.types[DatatypeElement.Tag] = this;
     }
 }
-const x = {} as DatatypeModel;
-x.children;

package/src/models/EventModel.ts

@@ -22,6 +22,10 @@ export class EventModel extends ValueModel<EventElement> implements EventElement
         return this.effectiveAccess.fabricSensitive;
     }
 
+    override get requiredFields() {
+        return { ...super.requiredFields, id: this.id };
+    }
+
     static {
         Model.types[EventElement.Tag] = this;
     }

package/src/models/MatterModel.ts

@@ -16,14 +16,14 @@ import { FabricModel } from "./FabricModel.js";
 import { FieldModel } from "./FieldModel.js";
 import { Globals } from "./Globals.js";
 import { Model } from "./Model.js";
+import { ScopeModel } from "./ScopeModel.js";
 import { SemanticNamespaceModel } from "./SemanticNamespaceModel.js";
 
 /**
  * The root of a Matter model.  This is the parent for global models.
  */
-export class MatterModel extends Model<MatterElement> implements MatterElement {
+export class MatterModel extends ScopeModel<MatterElement> implements MatterElement {
     override tag: MatterElement.Tag = MatterElement.Tag;
-    override isTypeScope = true;
     declare revision?: Specification.Revision;
 
     override get children(): Children<MatterModel.Child> {
@@ -89,9 +89,10 @@ export class MatterModel extends Model<MatterElement> implements MatterElement {
      *
      * @param definition the MatterElement that defines the model
      */
-    constructor(definition: MatterElement.Properties = { name: "Matter", children: [] }) {
-        const children = [...(definition.children || [])];
-        super({ ...definition, name: definition.name, children });
+    constructor(definition: MatterElement.Definition, ...children: Model.Definition<MatterModel.Child>[]) {
+        const name = definition.name ?? "Matter";
+        const definitionChildren = [...(definition.children || [])];
+        super({ ...definition, name, children: definitionChildren }, ...children);
     }
 
     /**