@matter/model 0.12.0-alpha.0-20241228-9f74a0273 → 0.12.0-alpha.0-20241231-14ac774ba

package/src/common/FieldValue.ts

@@ -47,6 +47,11 @@ export namespace FieldValue {
     export const none = "none";
     export type none = typeof none;
 
+    /**
+     * A field value that allows type extension.
+     */
+    export type Open = FieldValue | { type: string };
+
     /**
      * If a field value isn't a primitive type, it's an object with a type field indicating one of these types.
      */
@@ -55,7 +60,7 @@ export namespace FieldValue {
     /**
      * Test for one of the special placeholder types.
      */
-    export function is(value: FieldValue | undefined, type: Type) {
+    export function is(value: Open | undefined, type: Type) {
         return value && (value as any).type === type;
     }
 
@@ -150,7 +155,7 @@ export namespace FieldValue {
             return `${(value as Celsius).value}°C`;
         }
         if (is(value, percent)) {
-            return `${(value as Percent).value}%';`;
+            return `${(value as Percent).value}%`;
         }
         if (is(value, properties)) {
             return stringSerialize((value as Properties).properties) ?? "?";
@@ -161,7 +166,7 @@ export namespace FieldValue {
     /**
      * 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) {
+    export function numericValue(value: Open | undefined, typeName?: string) {
         if (typeof value === "boolean") {
             return value ? 1 : 0;
         }
@@ -240,7 +245,7 @@ export namespace FieldValue {
     /**
      * Get the referenced name if the FieldValue is a reference.
      */
-    export function referenced(value: FieldValue | undefined) {
+    export function referenced(value: Open | undefined) {
         if (is(value, reference)) {
             return (value as Reference).name;
         }
@@ -254,7 +259,7 @@ export namespace FieldValue {
      *
      * @returns the cast value or FieldValue.Invalid if cast is not possible
      */
-    export function cast(type: Metatype, value: any): FieldValue | FieldValue.Invalid | undefined {
+    export function cast<const T extends Metatype>(type: T, value: any): FieldValue | FieldValue.Invalid | undefined {
         if (value === undefined || value === null || type === "any") {
             return value;
         }

package/src/common/Metatype.ts

@@ -74,6 +74,27 @@ export namespace Metatype {
         }
     }
 
+    /**
+     * Map metatype value to JS type.
+     */
+    export type Native<T> = T extends "boolean"
+        ? boolean
+        : T extends "integer" | "float"
+          ? number
+          : T extends "string"
+            ? string
+            : T extends "bitmap" | "object"
+              ? Record<string, unknown>
+              : T extends "array"
+                ? unknown[]
+                : T extends "bytes"
+                  ? Uint8Array
+                  : T extends "date"
+                    ? Date
+                    : T extends "any"
+                      ? unknown
+                      : never;
+
     /**
      * Functions that perform conversion of arbitrary values to a metatype.
      *
@@ -82,243 +103,241 @@ export namespace Metatype {
      *
      * @throws {@link UnsupportedCastError} if the cast is deemed impossible
      */
-    export const cast: Record<Metatype, (value: any) => any> = {
-        any(value: any) {
+    export function cast<const T extends `${Metatype}`>(type: T, value: unknown) {
+        const caster = cast[type];
+        return caster(value) as Native<T>;
+    }
+
+    cast.any = (value: unknown) => value;
+
+    cast.boolean = (value: unknown): boolean | null | undefined => {
+        if (typeof value === "boolean" || value === null || value === undefined) {
             return value;
-        },
+        }
 
-        boolean(value: any): boolean | null | undefined {
-            if (typeof value === "boolean" || value === null || value === undefined) {
-                return value;
+        if (typeof value === "string") {
+            const normalized = value.toLowerCase().trim();
+            switch (normalized) {
+                case "":
+                case "0":
+                case "off":
+                case "no":
+                case "false":
+                    return false;
+
+                case "1":
+                case "on":
+                case "yes":
+                case "true":
+                    return true;
             }
+        }
+
+        if (typeof value === "number" || typeof value === "bigint") {
+            return !!value;
+        }
 
-            if (typeof value === "string") {
-                const normalized = value.toLowerCase().trim();
-                switch (normalized) {
-                    case "":
-                    case "0":
-                    case "off":
-                    case "no":
-                    case "false":
-                        return false;
-
-                    case "1":
-                    case "on":
-                    case "yes":
-                    case "true":
-                        return true;
+        if (ArrayBuffer.isView(value)) {
+            for (const byte of new Uint8Array(value.buffer)) {
+                if (byte) {
+                    return true;
                 }
             }
+            return false;
+        }
 
-            if (typeof value === "number" || typeof value === "bigint") {
-                return !!value;
-            }
+        throw new UnsupportedCastError(`Cannot convert "${value}" to boolean`);
+    };
 
-            if (ArrayBuffer.isView(value)) {
-                for (const byte of new Uint8Array(value.buffer)) {
-                    if (byte) {
-                        return true;
-                    }
-                }
-                return false;
-            }
+    cast.bitmap = (value: any): number | bigint | Record<string, number> | null | undefined => {
+        if (value === null || value === undefined) {
+            return value;
+        }
 
-            throw new UnsupportedCastError(`Cannot convert "${value}" to boolean`);
-        },
+        if (typeof value === "string") {
+            value = cast.integer(value);
+        }
 
-        bitmap(value: any): number | bigint | Record<string, number> | null | undefined {
-            if (value === null || value === undefined) {
+        if (typeof value === "number") {
+            if (Number.isFinite(value)) {
                 return value;
             }
+        } else if (typeof value === "bigint") {
+            return value;
+        } else if (isObject(value)) {
+            return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, cast.integer(v)])) as Record<
+                string,
+                number
+            >;
+        }
 
-            if (typeof value === "string") {
-                value = cast.integer(value);
-            }
+        throw new UnsupportedCastError(`Cannot convert "${value}" to bitmap`);
+    };
 
-            if (typeof value === "number") {
-                if (Number.isFinite(value)) {
-                    return value;
-                }
-            } else if (typeof value === "bigint") {
+    cast.enum = (value: any): number | string | null | undefined => {
+        if (typeof value === "string") {
+            if (value.trim().match(/^(?:[0-9]+|0x[0-9a-f]+|0b[01]+)$/)) {
+                value = Number.parseInt(value);
+            } else {
                 return value;
-            } else if (isObject(value)) {
-                return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, cast.integer(v)])) as Record<
-                    string,
-                    number
-                >;
             }
+        }
 
-            throw new UnsupportedCastError(`Cannot convert "${value}" to bitmap`);
-        },
+        if (typeof value === "number" && !Number.isNaN(value) && Number.isFinite(value)) {
+            return value;
+        }
 
-        enum(value: any): number | string | null | undefined {
-            if (typeof value === "string") {
-                if (value.trim().match(/^(?:[0-9]+|0x[0-9a-f]+|0b[01]+)$/)) {
-                    value = Number.parseInt(value);
-                } else {
-                    return value;
-                }
-            }
+        throw new UnsupportedCastError(`Cannot convert "${value}" to an enum value`);
+    };
 
-            if (typeof value === "number" && !Number.isNaN(value) && Number.isFinite(value)) {
-                return value;
-            }
+    cast.integer = (value: any): number | bigint | null | undefined => {
+        if (value === null || value === undefined) {
+            return value;
+        }
 
-            throw new UnsupportedCastError(`Cannot convert "${value}" to an enum value`);
-        },
+        switch (typeof value) {
+            case "number":
+                return Math.floor(value);
 
-        integer(value: any): number | bigint | null | undefined {
-            if (value === null || value === undefined) {
+            case "bigint":
                 return value;
-            }
-
-            switch (typeof value) {
-                case "number":
-                    return Math.floor(value);
-
-                case "bigint":
-                    return value;
 
-                case "boolean":
-                    return value ? 1 : 0;
-            }
+            case "boolean":
+                return value ? 1 : 0;
+        }
 
-            if (value instanceof Date) {
-                return value.getTime();
-            }
+        if (value instanceof Date) {
+            return value.getTime();
+        }
 
-            if (typeof value === "string") {
-                try {
-                    const big = BigInt(value);
-                    const little = Number.parseInt(value);
-                    if (big === BigInt(little)) {
-                        return little;
-                    }
-                    return big;
-                } catch (e) {
-                    if (!(e instanceof SyntaxError)) {
-                        throw e;
-                    }
+        if (typeof value === "string") {
+            try {
+                const big = BigInt(value);
+                const little = Number.parseInt(value);
+                if (big === BigInt(little)) {
+                    return little;
+                }
+                return big;
+            } catch (e) {
+                if (!(e instanceof SyntaxError)) {
+                    throw e;
                 }
             }
+        }
 
-            throw new UnsupportedCastError(`Cannot convert "${value}" to an integer`);
-        },
+        throw new UnsupportedCastError(`Cannot convert "${value}" to an integer`);
+    };
 
-        float(value: any): number | null | undefined {
-            if (typeof value === "number" || value === null || value === undefined) {
-                return value;
-            }
+    cast.float = (value: any): number | null | undefined => {
+        if (typeof value === "number" || value === null || value === undefined) {
+            return value;
+        }
 
-            if (value instanceof Date) {
-                return value.getTime();
-            }
+        if (value instanceof Date) {
+            return value.getTime();
+        }
 
-            const number = Number(value);
-            if (!Number.isNaN(number) && Number.isFinite(value)) {
-                return number;
-            }
+        const number = Number(value);
+        if (!Number.isNaN(number) && Number.isFinite(value)) {
+            return number;
+        }
 
-            throw new UnsupportedCastError(`Cannot convert "${value}" to a float`);
-        },
+        throw new UnsupportedCastError(`Cannot convert "${value}" to a float`);
+    };
 
-        bytes(value: any): Uint8Array | null | undefined {
-            if (value === undefined || value === null || value instanceof Uint8Array) {
-                return value;
-            }
+    cast.bytes = (value: any): Uint8Array | null | undefined => {
+        if (value === undefined || value === null || value instanceof Uint8Array) {
+            return value;
+        }
 
-            if (typeof value === "string") {
-                return Bytes.fromHex(value);
-            }
+        if (typeof value === "string") {
+            return Bytes.fromHex(value);
+        }
 
-            if (typeof value === "boolean") {
-                return new Uint8Array([value ? 1 : 0]);
-            }
+        if (typeof value === "boolean") {
+            return new Uint8Array([value ? 1 : 0]);
+        }
 
-            if (typeof value === "number" || typeof value === "bigint") {
-                return Bytes.fromHex(value.toString(16));
-            }
+        if (typeof value === "number" || typeof value === "bigint") {
+            return Bytes.fromHex(value.toString(16));
+        }
 
-            throw new UnsupportedCastError(`Cannot convert "${value}" to bytes`);
-        },
+        throw new UnsupportedCastError(`Cannot convert "${value}" to bytes`);
+    };
 
-        array(value: any): Array<unknown> | null | undefined {
-            if (value === undefined || value === null || Array.isArray(value)) {
-                return value;
-            }
+    cast.array = (value: any): Array<unknown> | null | undefined => {
+        if (value === undefined || value === null || Array.isArray(value)) {
+            return value;
+        }
 
-            if (typeof value === "string") {
-                try {
-                    const parsed = JSON.parse(value);
-                    if (Array.isArray(parsed)) {
-                        return parsed;
-                    }
-                } catch (e) {
-                    if (!(e instanceof SyntaxError)) {
-                        throw e;
-                    }
+        if (typeof value === "string") {
+            try {
+                const parsed = JSON.parse(value);
+                if (Array.isArray(parsed)) {
+                    return parsed;
+                }
+            } catch (e) {
+                if (!(e instanceof SyntaxError)) {
+                    throw e;
                 }
             }
+        }
 
-            throw new UnsupportedCastError(`Cannot convert "${value}" to array`);
-        },
+        throw new UnsupportedCastError(`Cannot convert "${value}" to array`);
+    };
 
-        object(value: any): Record<string, unknown> | null | undefined {
-            if (
-                value === undefined ||
-                (typeof value === "object" && !Array.isArray(value) && !(value instanceof Date))
-            ) {
-                return value;
-            }
+    cast.object = (value: any): Record<string, unknown> | null | undefined => {
+        if (value === undefined || (typeof value === "object" && !Array.isArray(value) && !(value instanceof Date))) {
+            return value;
+        }
 
-            if (typeof value === "string") {
-                try {
-                    const parsed = JSON.parse(value);
-                    return parsed;
-                } catch (e) {
-                    if (!(e instanceof SyntaxError)) {
-                        throw e;
-                    }
+        if (typeof value === "string") {
+            try {
+                const parsed = JSON.parse(value);
+                return parsed;
+            } catch (e) {
+                if (!(e instanceof SyntaxError)) {
+                    throw e;
                 }
             }
+        }
 
-            throw new UnsupportedCastError(`Cannot convert "${value}" to object`);
-        },
+        throw new UnsupportedCastError(`Cannot convert "${value}" to object`);
+    };
 
-        string(value: any): string | null | undefined {
-            if (value === undefined || value === null) {
-                return value;
-            }
+    cast.string = (value: any): string | null | undefined => {
+        if (value === undefined || value === null) {
+            return value;
+        }
 
-            if (typeof value === "string") {
-                return value;
-            }
+        if (typeof value === "string") {
+            return value;
+        }
 
-            if (value instanceof Date) {
-                return value.toISOString();
-            }
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
 
-            if (typeof value === "object" || Array.isArray(value)) {
-                return JSON.stringify(value);
-            }
+        if (typeof value === "object" || Array.isArray(value)) {
+            return JSON.stringify(value);
+        }
 
-            return value.toString();
-        },
+        return value.toString();
+    };
 
-        date(value: any): Date | null | undefined {
-            if (value === undefined || value === null || value instanceof Date) {
-                return value;
-            }
+    cast.date = (value: any): Date | null | undefined => {
+        if (value === undefined || value === null || value instanceof Date) {
+            return value;
+        }
 
-            if (typeof value === "number" || typeof value === "string") {
-                const date = new Date(value);
-                if (!Number.isNaN(date.getTime())) {
-                    return date;
-                }
+        if (typeof value === "number" || typeof value === "string") {
+            const date = new Date(value);
+            if (!Number.isNaN(date.getTime())) {
+                return date;
             }
+        }
 
-            throw new UnexpectedDataError();
-        },
+        throw new UnexpectedDataError();
     };
 
     /**

package/src/common/Specification.ts

@@ -44,7 +44,7 @@ export namespace Specification {
     /**
      * Matter specification version.
      */
-    export type Revision = `${number}.${number}`;
+    export type Revision = `${number}.${number}` | `${number}.${number}.${number}.${number}`;
 
     /**
      * The default specification revision for Matter.js.

package/src/logic/ModelDiff.ts

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ElementTag } from "#common/ElementTag.js";
+import { Specification } from "#index.js";
+import { Model } from "#models/Model.js";
+import { Diagnostic } from "@matter/general";
+import { ModelVariantTraversal, VariantDetail } from "./ModelVariantTraversal.js";
+
+/**
+ * A high level summary of changes between two models.
+ */
+export type ModelDiff = ModelDiff.Add | ModelDiff.Delete | ModelDiff.List | ModelDiff.Summary;
+
+/**
+ * Diff two models.
+ */
+export function ModelDiff(from: Model, to: Model, depth = 2) {
+    const traversal = new DiffTraversal(depth);
+    return traversal.traverse({ from, to });
+}
+
+class DiffTraversal extends ModelVariantTraversal<ModelDiff | undefined> {
+    #detailDepth: number;
+    #currentDepth = 0;
+
+    constructor(depth: number) {
+        super(Specification.REVISION, ["from", "to"]);
+        this.#detailDepth = depth;
+    }
+
+    protected override visit(variants: VariantDetail, recurse: () => (ModelDiff | undefined)[]): ModelDiff | undefined {
+        if (variants.map.to === undefined) {
+            if (variants.map.from === undefined) {
+                return;
+            }
+            return {
+                kind: "delete",
+                tag: variants.tag,
+                name: variants.name,
+            };
+        }
+
+        if (variants.map.from === undefined) {
+            return {
+                kind: "add",
+                tag: variants.tag,
+                name: variants.name,
+            };
+        }
+
+        if (this.#currentDepth >= this.#detailDepth) {
+            return;
+        }
+
+        this.#currentDepth++;
+        const children = recurse().filter(child => child !== undefined);
+        this.#currentDepth--;
+
+        if (!children.length) {
+            return;
+        }
+
+        if (this.#currentDepth < this.#detailDepth - 1) {
+            return {
+                kind: "list",
+                tag: variants.tag,
+                name: variants.name,
+                children,
+            };
+        }
+
+        const changes = {} as ModelDiff.Summary["changes"];
+        for (const child of children) {
+            changes[child.tag] = (changes[child.tag] ?? 0) + 1;
+        }
+
+        return {
+            kind: "summary",
+            tag: variants.tag,
+            name: variants.name,
+            changes,
+        };
+    }
+}
+
+export namespace ModelDiff {
+    /**
+     * Convert a diff to a diagnostic for serialization.
+     */
+    export function diagnosticOf(diff: ModelDiff | undefined): unknown {
+        const id = `${diff?.tag}#${diff?.name}`;
+        switch (diff?.kind) {
+            case "add":
+                return Diagnostic.added(id);
+
+            case "delete":
+                return Diagnostic.deleted(id);
+
+            case "list":
+                if (diff.children.length) {
+                    return [id, Diagnostic.list(diff.children.map(diagnosticOf))];
+                }
+                break;
+
+            case "summary":
+                const changes = Object.entries(diff.changes).map(([tag, count]) => {
+                    if (count < 0) {
+                        return Diagnostic.deleted(`${-count} ${tag}`);
+                    }
+
+                    if (count > 0) {
+                        return Diagnostic.added(`${count} ${tag}`);
+                    }
+
+                    return Diagnostic.weak(`${0} ${tag}`);
+                });
+
+                return [`${id}`, ...changes];
+        }
+
+        return Diagnostic.weak("(unchanged)");
+    }
+
+    export interface Identity {
+        name: string;
+        tag: ElementTag;
+    }
+
+    export interface Add extends Identity {
+        kind: "add";
+    }
+
+    export interface Delete extends Identity {
+        kind: "delete";
+    }
+
+    export interface List extends Identity {
+        kind: "list";
+        children: ModelDiff[];
+    }
+
+    export interface Summary extends Identity {
+        kind: "summary";
+        changes: Record<ElementTag, number>;
+    }
+}

package/src/logic/definition-validation/ValueValidator.ts

@@ -49,7 +49,7 @@ export class ValueValidator<T extends ValueModel> extends ModelValidator<T> {
     private validateAspect(name: string) {
         const aspect = (this.model as any)[name] as Aspect;
         if (aspect?.errors) {
-            aspect.errors.forEach((e: DefinitionError) => this.model.error(e.code, e.message));
+            aspect.errors.forEach((e: DefinitionError) => this.model.error(e.code, `${e.source}: ${e.message}`));
         }
     }