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

package/src/cluster/mutation/ClusterComposer.ts

@@ -0,0 +1,278 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { camelize, isDeepEqual, MatterError, serialize } from "#general";
+import { BitFlags } from "../../schema/BitmapSchema.js";
+import { ClusterType } from "../ClusterType.js";
+
+export class IllegalClusterError extends MatterError {}
+
+/**
+ * A "cluster composer" manages cluster configuration based on feature selection.
+ */
+export class ClusterComposer<const T extends ClusterType> {
+    constructor(public cluster: T) {}
+
+    /**
+     * Build a cluster using selected feature flags.
+     *
+     * @param selection the name(s) of optional features to support
+     * @throws {IllegalClusterError} if the feature combination is disallowed by the Matter specification
+     */
+    compose<const SelectionT extends ClusterComposer.FeatureSelection<T>>(selection: SelectionT) {
+        this.validateFeatureSelection(selection);
+
+        const extensions = this.cluster.extensions;
+        let cluster: ClusterType;
+
+        if (extensions) {
+            const base = this.cluster.base ?? this.cluster;
+
+            const baseElements = (type: "attributes" | "commands" | "events") => {
+                const elements = {} as Record<string, any>;
+                const clusterElements = this.cluster[type];
+                for (const name in base[type]) {
+                    elements[name] = clusterElements[name] ?? base[type][name];
+                }
+                return elements;
+            };
+
+            cluster = ClusterType({
+                ...base,
+                attributes: baseElements("attributes"),
+                commands: baseElements("commands"),
+                events: baseElements("events"),
+                supportedFeatures: BitFlags(this.cluster.features, ...selection),
+                base,
+            });
+
+            for (const selector of extensions) {
+                if (selector.component) {
+                    this.accept(cluster, selector.component, this.cluster, selector.flags);
+                } else {
+                    this.reject(cluster, selector.flags);
+                }
+            }
+        } else {
+            const supportedFeatures = BitFlags(this.cluster.features, ...selection);
+            if (isDeepEqual(supportedFeatures, this.cluster.supportedFeatures)) {
+                cluster = this.cluster;
+            } else {
+                cluster = ClusterType({
+                    ...this.cluster,
+                    supportedFeatures,
+                    base: this.cluster.base ?? this.cluster,
+                });
+            }
+        }
+
+        return cluster as ClusterComposer.Of<T, SelectionT>;
+    }
+
+    /**
+     * Validates a set of feature flags against the features supported by a cluster.
+     */
+    private validateFeatureSelection(features: ClusterComposer.FeatureSelection<any>) {
+        for (const f of features) {
+            if (!this.cluster.features[camelize(f)]) {
+                throw new IllegalClusterError(`"${f}" is not a valid feature identifier`);
+            }
+        }
+    }
+
+    /**
+     * Injects a component into a cluster if the cluster supports the specified features.  Uses matching element from
+     * "original" if present.  This allows for component insertion without overwrite of other changes to the named
+     * element.
+     */
+    private accept(
+        definition: ClusterComposer.WritableDefinition,
+        component: Partial<ClusterType.Elements>,
+        original: Partial<ClusterType> | undefined,
+        flags: ClusterComposer.FeatureFlags,
+    ) {
+        for (const k in flags) {
+            if (!!definition.supportedFeatures[k] !== !!flags[k]) {
+                return;
+            }
+        }
+
+        ClusterComposer.injectElements(definition, component, original);
+    }
+
+    static injectElements(
+        definition: Partial<ClusterType.Options>,
+        component: Partial<ClusterType.Options>,
+        original?: Partial<ClusterType>,
+    ) {
+        function installElements(name: "attributes" | "commands" | "events") {
+            const src = component[name];
+            if (!src) {
+                return;
+            }
+
+            let dest = definition[name] as Record<string, unknown> | undefined;
+            if (dest) {
+                dest = { ...dest } as Record<string, unknown>;
+            } else {
+                dest = {};
+            }
+            (definition as Record<string, unknown>)[name] = dest;
+
+            for (const key in src) {
+                const orig = original?.[name]?.[key];
+                if (orig) {
+                    dest[key] = orig;
+                } else {
+                    dest[key] = src[key];
+                }
+            }
+        }
+
+        installElements("attributes");
+        installElements("commands");
+        installElements("events");
+    }
+
+    /**
+     * Throws an error if a feature combination is illegal per the Matter specification.
+     */
+    private reject(definition: ClusterType, flags: ClusterComposer.FeatureFlags) {
+        for (const k in flags) {
+            if (!!definition.supportedFeatures[k] !== !!flags[k]) {
+                return;
+            }
+        }
+        throw new IllegalClusterError(
+            `Feature combination ${serialize(flags)} is disallowed by the Matter specification`,
+        );
+    }
+}
+
+export namespace ClusterComposer {
+    export type Component = Partial<ClusterType.Elements>;
+
+    /**
+     * An array of names indicating features to be injected.
+     */
+    export type FeatureSelection<T extends ClusterType> = readonly Capitalize<string & keyof T["features"]>[];
+
+    /**
+     * A set of boolean values indicating whether a feature is enabled.
+     */
+    export type FeatureFlags = Record<string, boolean | undefined>;
+
+    /**
+     * Describes the output of {@link ClusterComposer.compose}.
+     */
+    export type Of<ClusterT extends ClusterType, FeaturesT extends FeatureSelection<ClusterT>> = WithFeatures<
+        ClusterT,
+        FeaturesT
+    >;
+
+    /**
+     * The base of a cluster.
+     */
+    export type BaseOf<T extends ClusterType> = T["base"] extends ClusterType ? T["base"] : T;
+
+    /**
+     * The result of composition.
+     */
+    export type WithFeatures<ClusterT extends ClusterType, FeaturesT extends FeatureSelection<BaseOf<ClusterT>>> = Omit<
+        BaseOf<ClusterT>,
+        "supportedFeatures" | "base" | ElementType
+    > & {
+        supportedFeatures: FeaturesAsFlags<BaseOf<ClusterT>, FeaturesT>;
+        base: BaseOf<ClusterT>;
+    } & ExtendedElements<
+            ClusterT,
+            SelectedElements<
+                FeaturesAsFlags<ClusterT, FeaturesT>,
+                ClusterT["extensions"] extends object ? ClusterT["extensions"] : []
+            >
+        >;
+
+    /**
+     * Convert a {@link FeatureSelection} array into a {@link FeatureFlags} object.
+     */
+    export type FeaturesAsFlags<ClusterT extends ClusterType, FlagsT extends FeatureSelection<ClusterT>> = {
+        [K in keyof ClusterT["features"]]: K extends string
+            ? Capitalize<K> extends `${FlagsT[number]}`
+                ? true
+                : false
+            : never;
+
+        // Formerly we used this.  TS bugs (as of 5.4) caused this to fail to match in specific circumstances.  See
+        // ClusterComposerTest "extends with default components"
+        //[K in keyof ClusterT["features"]]: K extends Uncapitalize<FlagsT[number]> ? true : false;
+    };
+
+    /**
+     * Choose elements from applicable extensions.
+     */
+    export type SelectedElements<
+        FlagsT extends FeatureFlags,
+        extensionsT extends readonly ClusterType.Extension[],
+    > = extensionsT extends readonly [
+        infer S extends ClusterType.Extension,
+        ...infer R extends readonly ClusterType.Extension[],
+    ]
+        ? SelectorContribution<FlagsT, S> & SelectedElements<FlagsT, R>
+        : {};
+
+    /**
+     * Determine the type contributed to feature selection by a specific selector.
+     */
+    export type SelectorContribution<
+        FlagsT extends FeatureFlags,
+        SelectorT extends ClusterType.Extension,
+    > = FlagsT extends SelectorT["flags"]
+        ? SelectorT["component"] extends false
+            ? never
+            : SelectorT["component"] & { attributes: {}; commands: {}; events: {} }
+        : { attributes: {}; commands: {}; events: {} };
+
+    /**
+     * Cluster elements extended with .
+     *
+     * Note that we have to track the base separate from the originating cluster.  If we are removing features, we want
+     * to maintain only those features present in the base or selected components.
+     */
+    export type ExtendedElements<ClusterT extends ClusterType, ComponentT extends Component> = [ComponentT] extends [
+        never,
+    ]
+        ? never
+        : {
+              [TypeT in ElementType]: Pick<
+                  // Include elements in current cluster if valid according to base and extensions
+                  ClusterT[TypeT],
+                  keyof ClusterT[TypeT] & (keyof BaseOf<ClusterT>[TypeT] | keyof ComponentT[TypeT])
+              > &
+                  // Include extension elements if not present in current cluster
+                  Omit<ComponentT[TypeT], keyof ClusterT[TypeT]> &
+                  // Include base elements if not present in current cluster or extensions
+                  Omit<BaseOf<ClusterT>[TypeT], keyof ClusterT[TypeT] | keyof ComponentT[TypeT]>;
+          };
+
+    /**
+     * A cluster extended by multiple components.
+     */
+    export type WithComponents<ClusterT extends ClusterType, RestT extends Component[]> = RestT extends [
+        infer ComponentT extends Component,
+        ...infer RestT extends Component[],
+    ]
+        ? WithComponents<Omit<ClusterT, ElementType> & ExtendedElements<ClusterT, ComponentT>, RestT>
+        : ClusterT;
+
+    /**
+     * A "WritableDefinition" is a Cluster with fields that may be modified.
+     */
+    export type WritableDefinition = {
+        -readonly [Key in keyof ClusterType]: ClusterType[Key];
+    };
+
+    export type ElementType = "attributes" | "commands" | "events";
+}

package/src/cluster/mutation/ElementModifier.ts

@@ -0,0 +1,210 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ClusterType } from "../ClusterType.js";
+
+/**
+ * An "element modifier" mutates cluster elements based on a predefined set of
+ * alterations described in the Matter device library.
+ */
+export class ElementModifier<const T extends ClusterType> {
+    constructor(public cluster: T) {}
+
+    /**
+     * Create a new cluster with modified elements.
+     */
+    alter<const AlterationsT extends ElementModifier.Alterations<T>>(alterations: AlterationsT) {
+        return modifyElements(this.cluster, alterations, (element, alteration: any) => {
+            for (const property in alteration) {
+                element[property] = alteration[property];
+            }
+        }) as ElementModifier.WithAlterations<T, AlterationsT>;
+    }
+
+    /**
+     * Create a new cluster with different attribute defaults.
+     *
+     * This "sets" the values of attributes when the cluster is created
+     * for the first time with no persistent state.
+     */
+    set<const ValuesT extends Partial<ClusterType.InputAttributeValues<T>>>(values: ValuesT) {
+        return modifyElements(this.cluster, { attributes: values }, (element, defaultValue) => {
+            element.default = defaultValue;
+        }) as ElementModifier.WithValues<T, ValuesT>;
+    }
+
+    /**
+     * Create a new cluster with additional features marked "mandatory".
+     *
+     * This informs matter.js that an application supports these elements.
+     */
+    enable<const FlagsT extends ElementModifier.ElementFlags<T>>(flags: FlagsT) {
+        return modifyElements(this.cluster, flags, (element, flag) => {
+            if (flag === true) {
+                element.optional = false;
+            } else if (flag === false) {
+                element.optional = true;
+            }
+        }) as ElementModifier.WithAlterations<T, ElementModifier.ElementFlagAlterations<FlagsT>>;
+    }
+}
+
+export namespace ElementModifier {
+    /**
+     * A set of modifications to cluster elements of a specific type.
+     */
+    export type ElementSetAlterations<AlterationT extends ElementAlteration, ElementSetT> = {
+        [name in keyof ElementSetT]?: AlterationT;
+    };
+
+    export interface ElementAlteration {
+        optional?: boolean;
+    }
+
+    export interface AttributeAlteration extends ElementAlteration {
+        default?: any;
+        min?: any;
+        max?: any;
+    }
+
+    /**
+     * A set of modifications to a cluster's elements.
+     *
+     * Note - cannot specify ElementsT as extending ClusterElements because it
+     * triggers a bug in TS 5.2 declaration generation
+     */
+    export type Alterations<OriginalT extends ClusterType> = {
+        attributes?: ElementSetAlterations<AttributeAlteration, OriginalT["attributes"]>;
+        commands?: ElementSetAlterations<ElementAlteration, OriginalT["commands"]>;
+        events?: ElementSetAlterations<ElementAlteration, OriginalT["events"]>;
+    };
+
+    /**
+     * Alterations applied to a specific element set, element or element field.
+     */
+    export type AlteredElements<OriginalT, ElementT, AlterationT> = {
+        [name in keyof OriginalT]: OriginalT[name] extends infer OrigT extends ElementT
+            ? AlterationT extends { [n in name]: { optional: infer O extends boolean } }
+                ? Omit<OrigT, "optional"> & { optional: O }
+                : OrigT
+            : never;
+    };
+
+    /**
+     * A definition with alterations applied.
+     */
+    export type WithAlterations<T extends ClusterType, AlterationsT extends Alterations<any>> = Omit<
+        T,
+        "attributes" | "commands" | "events"
+    > & {
+        attributes: AlteredElements<T["attributes"], ClusterType.Attribute, AlterationsT["attributes"]>;
+        commands: AlteredElements<T["commands"], ClusterType.Command, AlterationsT["commands"]>;
+        events: AlteredElements<T["events"], ClusterType.Event, AlterationsT["events"]>;
+    };
+
+    /**
+     * A definition with attribute defaults updated.
+     */
+    export type WithValues<
+        T extends ClusterType,
+        ValuesT extends Partial<ClusterType.InputAttributeValues<T>>,
+    > = WithAlterations<T, AttributeValueAlterations<ValuesT>>;
+
+    /**
+     * A definition with elements enabled.
+     */
+    export type WithFlags<T extends ClusterType, FlagsT extends ElementFlags<T>> = WithAlterations<
+        T,
+        ElementFlagAlterations<FlagsT>
+    >;
+
+    /**
+     * Alterations implied by AttributeValues.
+     */
+    export type AttributeValueAlterations<ValuesT extends Partial<ClusterType.InputAttributeValues<any>>> = {
+        attributes: {
+            [K in keyof ValuesT]: { default: ValuesT[K] };
+        };
+    };
+
+    export type ElementSetFlags<ElementsT extends ClusterType.ElementSet<any> | undefined> = {
+        [key in keyof ElementsT]?: boolean;
+    };
+
+    /**
+     * Flags indicating elements to enable.
+     */
+    export type ElementFlags<ClusterT extends ClusterType> = {
+        attributes?: ElementSetFlags<ClusterType.AttributesOf<ClusterT>>;
+        commands?: ElementSetFlags<ClusterType.CommandsOf<ClusterT>>;
+        events?: ElementSetFlags<ClusterType.EventsOf<ClusterT>>;
+    };
+
+    export type ElementSetFlagAlterations<ElementsT extends ElementSetFlags<any> | undefined> = ElementsT extends {}
+        ? { [key in keyof ElementsT]: { optional: ElementsT[key] extends true ? false : true } }
+        : undefined;
+
+    /**
+     * Alterations implied by ElementFlags.
+     */
+    export type ElementFlagAlterations<T extends ElementFlags<any>> = {
+        [K in keyof T]: T[K] extends ElementSetFlags<any> ? ElementSetFlagAlterations<T[K]> : never;
+    };
+
+    /**
+     * An "extender" is a function that creates a cluster with specific
+     * features enabled.
+     */
+    export type Extender = (...features: any) => ClusterType;
+}
+
+/**
+ * Helper routine used by alteration builder methods.
+ */
+function modifyElements(
+    definition: ClusterType,
+    modifications: Record<string, Record<string, any> | undefined>,
+    modifier: (element: any, modification: any) => any,
+) {
+    const result = { ...definition };
+
+    for (const elementType of ["attributes", "commands", "events"] as const) {
+        const mods = modifications[elementType];
+        if (mods === undefined) {
+            continue;
+        }
+
+        let elements = result[elementType];
+        if (elements === undefined) {
+            continue;
+        }
+
+        let replaced = false;
+
+        for (const elementName in mods) {
+            const mod = mods[elementName];
+            if (mod === undefined) {
+                continue;
+            }
+
+            const element = elements[elementName];
+            if (!element) {
+                continue;
+            }
+
+            if (!replaced) {
+                elements = result[elementType] = { ...result[elementType] } as {};
+                replaced = true;
+            }
+
+            elements[elementName] = { ...element };
+
+            modifier(elements[elementName], mod);
+        }
+    }
+
+    return result;
+}

package/src/cluster/mutation/MutableCluster.ts

@@ -0,0 +1,145 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ClusterId } from "../../datatype/ClusterId.js";
+import { ConditionalFeatureList } from "../Cluster.js";
+import { ClusterType } from "../ClusterType.js";
+import { ClusterComposer } from "./ClusterComposer.js";
+import { ElementModifier } from "./ElementModifier.js";
+
+/**
+ * A "mutable cluster" is a {@link ClusterType} with builder methods that support a limited number of modifications as
+ * defined by the Matter specification.
+ */
+export type MutableCluster<
+    T extends ClusterType.Options,
+    C extends ClusterComposer.Component[] = [],
+> = ClusterComposer.WithComponents<ClusterType.Of<T>, C> & MutableCluster.Methods<ClusterType.Of<T>>;
+
+/**
+ * Define a new {@link MutableCluster}.
+ */
+export function MutableCluster<const T extends ClusterType.Options, const C extends ClusterComposer.Component[]>(
+    options: T,
+    ...components: C
+) {
+    const cluster = ClusterType(options);
+
+    for (const component of components) {
+        ClusterComposer.injectElements(cluster, component);
+    }
+
+    Object.assign(cluster, {
+        with(...features: ClusterComposer.FeatureSelection<typeof cluster>) {
+            return new ClusterComposer(cluster).compose(features);
+        },
+
+        alter(alterations: ElementModifier.Alterations<typeof cluster>) {
+            return new ElementModifier(cluster).alter(alterations);
+        },
+
+        set(values: ClusterType.InputAttributeValues<typeof cluster>) {
+            return new ElementModifier(cluster).set(values);
+        },
+
+        enable(flags: ElementModifier.ElementFlags<typeof cluster>) {
+            return new ElementModifier(cluster).enable(flags);
+        },
+    });
+
+    return cluster as MutableCluster<T, C>;
+}
+
+export namespace MutableCluster {
+    /**
+     * Define a component.
+     */
+    export function Component<const T extends Partial<ClusterType.Options>>(elements: T) {
+        return elements;
+    }
+
+    /**
+     * Define a cluster's extension set.
+     */
+    export function Extensions<const T extends readonly ClusterType.Extension[]>(...extensions: T) {
+        return extensions;
+    }
+
+    export interface Methods<T extends ClusterType> {
+        /**
+         * Select features using {@link ClusterComposer.compose}.
+         */
+        with<const SelectionT extends ClusterComposer.FeatureSelection<T>>(
+            ...selection: SelectionT
+        ): ClusterComposer.Of<T, SelectionT>;
+
+        /**
+         * Modify elements using {@link ElementModifier.alter}.
+         */
+        alter<const AlterationsT extends ElementModifier.Alterations<T>>(
+            alterations: AlterationsT,
+        ): ElementModifier.WithAlterations<T, AlterationsT>;
+
+        /**
+         * Modify elements using {@link ElementModifier.set}.
+         */
+        set<const ValuesT extends ClusterType.InputAttributeValues<T>>(
+            values: ValuesT,
+        ): ElementModifier.WithValues<T, ValuesT>;
+
+        /**
+         * Modify elements using {@link ElementModifier.enable}.
+         */
+        enable<const FlagsT extends ElementModifier.ElementFlags<T>>(
+            flags: FlagsT,
+        ): ElementModifier.WithFlags<T, FlagsT>;
+    }
+
+    /**
+     * ExtensibleOnly creates a factory that produces a {@link MutableCluster} when the user selects features.
+     *
+     * We define clusters this way if the Matter specification defines a cluster with a set of features, one of which is
+     * required, but none of which is required if others are enabled.
+     */
+    export interface ExtensibleOnly<T extends ClusterType.Options> {
+        id: ClusterId;
+        name: string;
+
+        with: Methods<ClusterType.Of<T>>["with"];
+    }
+
+    /**
+     * Create a factory for clusters that require extension.
+     */
+    export function ExtensibleOnly<const T extends ClusterType.Options>(options: T) {
+        return {
+            id: options.id,
+            name: options.name,
+
+            with(...features: ClusterComposer.FeatureSelection<ClusterType.Of<T>>) {
+                return new ClusterComposer(ClusterType(options)).compose(features);
+            },
+        } as ExtensibleOnly<T>;
+    }
+
+    /**
+     * Create a conditional version of an unconditional element definition.
+     */
+    export function AsConditional<
+        const ClusterT extends ClusterType,
+        const E extends ClusterType.Attribute | ClusterType.Command | ClusterType.Event,
+        const OI extends ConditionalFeatureList<ClusterT["features"]>,
+        const MI extends ConditionalFeatureList<ClusterT["features"]>,
+    >(element: E, { optionalIf, mandatoryIf }: { optionalIf?: OI; mandatoryIf?: MI }) {
+        return {
+            ...element,
+            optional: true,
+            isConditional: true,
+            optionalIf: optionalIf ?? [],
+            mandatoryIf: mandatoryIf ?? [],
+        } as const;
+    }
+}

package/src/cluster/mutation/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./ClusterComposer.js";
+export * from "./ElementModifier.js";
+export * from "./MutableCluster.js";