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

package/src/decoration/decorators/response.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { FieldSemantics } from "#decoration/semantics/FieldSemantics.js";
+import { CommandElement } from "#elements/CommandElement.js";
+import { Decorator } from "#general";
+import { CommandModel } from "#models/CommandModel.js";
+import { DatatypeModel } from "#models/DatatypeModel.js";
+
+/**
+ * Specify the response type for a command.
+ */
+export function response(type: DatatypeModel): Decorator.ClassMethod {
+    return Decorator((_target, context) => {
+        const requestSemantics = FieldSemantics.of(context);
+
+        requestSemantics.modelType = CommandModel;
+        const request = requestSemantics.mutableModel as CommandModel;
+
+        const name = `${request.name}Response`;
+        new CommandModel({
+            name,
+            id: request.id,
+            parent: request.parent,
+            direction: CommandElement.Direction.Response,
+            operationalBase: type,
+        });
+
+        request.response = name;
+    });
+}

package/src/decoration/errors.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError } from "#general";
+
+export class MetadataError extends ImplementationError {}
+
+/**
+ * Thrown when a type is assigned to a class or property that is already typed.
+ */
+export class MetadataConflictError extends MetadataError {}
+
+/**
+ * Thrown when metadata is inappropriate for the decorated language element.
+ */
+export class InvalidMetadataError extends MetadataError {}
+
+/**
+ * Thrown when an error occurs instantiating a dummy instance of a class for introspection purposes.
+ */
+export class ClassIntrospectionError extends MetadataError {}
+
+/**
+ * Thrown when required metadata is missing.
+ */
+export class MissingMetadataError extends MetadataError {}

package/src/decoration/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./decorators/index.js";
+export * from "./errors.js";
+export * from "./semantics/index.js";

package/src/decoration/semantics/ClassSemantics.ts

@@ -0,0 +1,374 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Must import these via index to ensure proper initialization
+import { DatatypeModel, FieldModel, Model } from "#models/index.js";
+
+import { camelize } from "#general";
+import { Scope } from "#logic/Scope.js";
+import { any, struct } from "#standard/elements/models.js";
+import { InvalidMetadataError, MetadataConflictError } from "../errors.js";
+import { FieldSemantics } from "./FieldSemantics.js";
+import { Semantics } from "./Semantics.js";
+
+/**
+ * Our key into {@link DecoratorContext.metadata}.
+ *
+ * This is where we store the {@link ClassSemantics} associated with a decorated class.
+ */
+const matter = Symbol("matter");
+
+/**
+ * Our view of {@link DecoratorContext.metadata}.
+ *
+ * Note that in the case of class inheritance, the metadata also inherits from the parent metadata.  So we need to use
+ * {@link Object.hasOwn} to differentiate between the {@link ClassSemantics} for a class and that of its base class.
+ */
+interface MatterMetadata {
+    [matter]?: ClassSemantics;
+}
+
+/**
+ * Matter semantic metadata attached to a class via decorators.
+ *
+ * We use decorators to allow for definition of model elements in the context of a specific type.
+ *
+ * Currently there are JavaScript/TypeScript limitations to be aware of when decorating type definitions:
+ *
+ *   * Decorators may only be applied to JavaScript classes.  So if you want to define an interface without
+ *     implementation, you must implement as a class and use as an interface.  That's why this is "class" metadata.
+ *
+ *   * Decorators may not affect the TypeScript type of an object.  This means that you must define both the Matter type
+ *     (e.g. {@link uint32}) and TypeScript type (e.g. `number`).
+ */
+export class ClassSemantics extends Semantics {
+    #new?: ClassSemantics.Constructor;
+    #definedFields?: Map<string, FieldSemantics>;
+
+    /**
+     * The model that represents the semantics for this class.
+     *
+     * This may be {@link localModel} or {@link prototypeBaseModel}
+     */
+    get semanticModel() {
+        if (this.localModel) {
+            // Model is defined here
+            return this.localModel;
+        }
+
+        if (this.#definedFields) {
+            // Model has not been defined but should be due to decoration, so define it now
+            return this.mutableModel;
+        }
+
+        // Return model inherited via prototype, if any.  Otherwise we do not express semantics
+        return this.prototypeBaseModel;
+    }
+
+    /**
+     * Get the class constructor
+     */
+    get new(): ClassSemantics.Constructor | undefined {
+        return this.#new;
+    }
+
+    /**
+     * Assign the constructor for the class.
+     */
+    set new(fn: ClassSemantics.Constructor) {
+        if (this.#new === fn) {
+            return;
+        }
+
+        if (this.isFinal) {
+            throw new MetadataConflictError(
+                `Cannot install semantic constructor ${fn.name} because semantics are final`,
+            );
+        }
+
+        this.#new = fn;
+
+        // Set name to match class
+        if (this.localModel && !this.localModel.isFinal && this.localModel.name !== this.#new?.name) {
+            this.localModel.name = this.#new?.name;
+        }
+
+        // Update local semantics based on inherited semantics
+        if (this.localModel) {
+            // I have a model defined already so update according to base semantics
+            this.#applyBaseSemantics();
+        } else {
+            // I have no model defined yet so I am semantically equivalent to my base
+            const base = this.prototypeBaseModel;
+            if (base !== undefined) {
+                this.mutableModel = base;
+            }
+        }
+    }
+
+    /**
+     * The class {@link Model} inherited from {@link new}'s prototype chain, if any.
+     */
+    get prototypeBaseModel(): Model | undefined {
+        let current = this.#new?.prototype;
+        let base;
+
+        while (current) {
+            current = Object.getPrototypeOf(current) as unknown;
+            if (typeof current !== "object" || current === null) {
+                return;
+            }
+            const constructor = current.constructor;
+            if (constructor === Object) {
+                return;
+            }
+            base = ClassSemantics.maybeOf(constructor);
+
+            if (base?.localModel) {
+                // Semantics and model may not mutate once acting as a base
+                base.finalize();
+
+                return base.localModel;
+            }
+        }
+    }
+
+    /**
+     * Obtain a {@link FieldSemantics} for the named field.
+     */
+    fieldFor(name: string | symbol) {
+        if (typeof name !== "string") {
+            throw new InvalidMetadataError(`Cannot decorate symbolic function ${String(name)}`);
+        }
+
+        if (this.#definedFields === undefined) {
+            this.#definedFields = new Map();
+        }
+        let field = this.#definedFields.get(name);
+        if (field === undefined) {
+            if (this.isFinal) {
+                throw new MetadataConflictError(`Cannot install field ${name} because semantics are final`);
+            }
+
+            this.#definedFields.set(name, (field = new FieldSemantics(this, name)));
+        }
+        return field;
+    }
+
+    /**
+     * Add logical fields for unrecognized members of an object.
+     *
+     * This extends the model with untyped fields for properties that are not otherwise typed.
+     */
+    defineUnknownMembers(instance: unknown) {
+        if (instance === undefined || instance === null) {
+            return;
+        }
+
+        const known = this.semanticModel
+            ? new Set(
+                  Scope(this.semanticModel)
+                      .membersOf(this.semanticModel)
+                      .map(model => camelize(model.name)),
+              )
+            : new Set();
+
+        const descriptors = Object.getOwnPropertyDescriptors(instance);
+
+        for (const name in descriptors) {
+            // Skip if name is already known
+            if (known.has(camelize(name))) {
+                continue;
+            }
+
+            // We only model string properties
+            if (typeof name !== "string") {
+                continue;
+            }
+
+            // We do not support write-only fields
+            const descriptor = descriptors[name];
+            if (descriptor.set && !descriptor.get) {
+                continue;
+            }
+
+            // Methods are not fields
+            try {
+                if (typeof (instance as Record<string, unknown>)[name] === "function") {
+                    continue;
+                }
+            } catch (e) {
+                // We do not support inaccessible fields
+                continue;
+            }
+
+            const model = this.fieldFor(name).mutableModel as FieldModel;
+
+            model.operationalBase = any;
+
+            // Default to fixed if read-only
+            if (!descriptor.writable && !descriptor.set) {
+                model.quality = { ...model.quality, fixed: true };
+            }
+
+            this.fieldFor(name).mutableModel.operationalBase = any;
+        }
+    }
+
+    /**
+     * Obtain the {@link ClassSemantics} for {@link source}.
+     */
+    static override of(source: ClassSemantics.Source) {
+        // Source is the semantics
+        if (source instanceof ClassSemantics) {
+            return source;
+        }
+
+        // Source is decorator context
+        if (typeof source !== "function") {
+            const metadata = source.metadata as MatterMetadata;
+            if (Object.hasOwn(metadata, matter)) {
+                return metadata[matter]!;
+            }
+            return (metadata[matter] = new ClassSemantics());
+        }
+
+        // Source is a constructor
+        let metadata: MatterMetadata;
+        if (!Object.hasOwn(source, Symbol.metadata)) {
+            metadata = source[Symbol.metadata] = {};
+        } else {
+            metadata = source[Symbol.metadata] as MatterMetadata;
+        }
+
+        let semantics: ClassSemantics;
+        if (!Object.hasOwn(metadata, matter)) {
+            semantics = metadata[matter] = new ClassSemantics();
+        } else {
+            semantics = metadata[matter] as ClassSemantics;
+        }
+
+        // If the parent class is not decorated then this may be the first time we've seen the constructor associated
+        // with the metadata.  So always inform the metadata of its constructor
+        if (!semantics.new) {
+            semantics.new = source;
+        }
+
+        return semantics;
+    }
+
+    /**
+     * Determine {@link new} has semantic decoration.
+     */
+    static hasOwnSemantics(source: ClassSemantics.Constructor) {
+        return Object.hasOwn(source, Symbol.metadata) && Object.hasOwn(source[Symbol.metadata]!, matter);
+    }
+
+    /**
+     * Access the {@link ClassSemantics} of {@link new} if it is defined.
+     */
+    static maybeOf(source: ClassSemantics.Constructor) {
+        if (this.hasOwnSemantics(source)) {
+            return ClassSemantics.of(source);
+        }
+    }
+
+    static {
+        Semantics.classOf = this.of;
+    }
+
+    override finalize() {
+        if (this.isFinal) {
+            return;
+        }
+
+        // Invoke any custom extension logic
+        this.#new?.[ClassSemantics.extend]?.(this);
+
+        // Apply base finalization
+        super.finalize();
+
+        // Finalize fields
+        if (this.#definedFields) {
+            for (const field of this.#definedFields.values()) {
+                field.finalize();
+            }
+        }
+    }
+
+    #applyBaseSemantics() {
+        const base = this.prototypeBaseModel;
+        if (base === undefined) {
+            return;
+        }
+
+        // If my model does not yet have an explicit base, I extend my parent class's model
+        const { type, base: currentBase } = this.mutableModel;
+        if (type === undefined && (currentBase === undefined || currentBase === struct)) {
+            const operationalBase = this.prototypeBaseModel;
+            if (operationalBase) {
+                this.mutableModel.operationalBase = operationalBase;
+            }
+        }
+
+        // If my base is not a datatype, it forces the type of my model
+        if (base && base.tag !== "datatype" && this.mutableModel.tag !== base.tag) {
+            this.modelType = base.constructor as Model.ConcreteType;
+        }
+
+        // If ID is not already set, force ID to match base
+        if (this.mutableModel.id === undefined && base.id !== undefined) {
+            this.mutableModel.id = base.id;
+        }
+    }
+
+    protected override integrateModel(model: Model) {
+        // If local model is not yet set or is final, we have not extended; this is "swap base with no decoration" case
+        if (this.localModel === undefined || this.localModel.isFinal) {
+            return model;
+        }
+
+        // If incoming model is final, replace operational base of local model.  This is "swap base with decoration"
+        // case
+        if (model.isFinal) {
+            this.localModel.operationalBase = model;
+            return this.localModel;
+        }
+
+        // Neither model is final.  Move any children to new model.  This is "replace temporary model created by
+        // decorators" case
+        model.children.push(...this.localModel.children);
+
+        return model;
+    }
+
+    protected override createModel(type: Model.ConcreteType = DatatypeModel) {
+        let name = this.#new?.name;
+        if (name === undefined || name === "") {
+            name = "Unnamed";
+        }
+        return new type({ name, operationalBase: struct });
+    }
+}
+
+export namespace ClassSemantics {
+    /**
+     * A standard constructor with an optional decoration extension point.
+     */
+    export interface Constructor extends NewableFunction {
+        /**
+         * If present, invoked for custom decoration after installing constructor.
+         */
+        [extend]?: (semantics: ClassSemantics) => void;
+    }
+
+    /**
+     * An object for which you may obtain {@link ClassSemantics}.
+     */
+    export type Source = Constructor | DecoratorContext | ClassSemantics;
+
+    export const extend = Symbol("extend");
+}

package/src/decoration/semantics/FieldSemantics.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InvalidMetadataError } from "#decoration/errors.js";
+import { InternalError } from "#general";
+import { FieldModel } from "#models/FieldModel.js";
+import type { Model } from "#models/Model.js";
+import type { ClassSemantics } from "./ClassSemantics.js";
+import { Semantics } from "./Semantics.js";
+
+/**
+ * Decorator metadata associated with a specific class field.
+ */
+export class FieldSemantics extends Semantics {
+    constructor(owner: ClassSemantics, name: string) {
+        super();
+
+        this.mutableModel = new FieldModel({ name, parent: owner.mutableModel });
+    }
+
+    protected override createModel(): Model {
+        // We create our model unconditionally so this shouldn't happen
+        throw new InternalError("Unexpected FieldSemantics.createModel");
+    }
+
+    protected override integrateModel(model: Model): Model {
+        if (this.localModel === undefined) {
+            return model;
+        }
+        this.mutableModel.operationalBase = model;
+        return this.mutableModel;
+    }
+
+    static override of(source: FieldSemantics.Source) {
+        if (source.kind === "class") {
+            throw new InvalidMetadataError(
+                `Cannot retrieve field semantics for class decorator ${source.name ?? "of anonymous class"}`,
+            );
+        }
+        return Semantics.classOf(source).fieldFor(source.name);
+    }
+}
+
+export namespace FieldSemantics {
+    export type Source = DecoratorContext;
+}

package/src/decoration/semantics/Semantics.ts

@@ -0,0 +1,170 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MetadataConflictError } from "#decoration/errors.js";
+import { InternalError } from "#general";
+import type { Model } from "#models/Model.js";
+import * as models from "#standard/elements/models.js";
+import type { ClassSemantics } from "./ClassSemantics.js";
+
+const standardModels = new Set(Object.values(models) as Model[]);
+
+/**
+ * Base class for Matter semantics associated with JavaScript classes and properties.
+ *
+ * We model semantics using {@link Model}.  The model may be built declaratively with decorators or programmatically
+ * using this interface directly.
+ */
+export abstract class Semantics {
+    #localModel?: Model;
+    #isFinal = false;
+
+    /**
+     * Determine whether these semantics are final.
+     *
+     * Once final no further mutation is allowed.
+     */
+    get isFinal(): boolean {
+        return this.#isFinal;
+    }
+
+    /**
+     * Finalize the model.
+     */
+    finalize() {
+        if (this.#isFinal) {
+            return;
+        }
+
+        this.#isFinal = true;
+        Object.freeze(this);
+        this.#localModel?.finalize();
+    }
+
+    /**
+     * The {@link Model} defined by local decoration, if any.
+     */
+    get localModel() {
+        return this.#localModel;
+    }
+
+    /**
+     * Set the model.
+     *
+     * When "setting" the model we need to merge semantics coming from decorators, the prototype hierarchy, and models
+     * provided programmatically.
+     *
+     * This may set the local model, change it or set its operational base.  We use local state and the finalization
+     * status of the model to determine how to integrate.
+     */
+    set mutableModel(model: Model) {
+        if (this.#isFinal) {
+            throw new MetadataConflictError(`Cannot modify final semantics of ${this.#localModel?.name ?? "(none)"}`);
+        }
+
+        if (this.#localModel === model) {
+            return;
+        }
+
+        // We don't finalize global models by default for performance reasons, but do finalize them here to prevent
+        // accidental mutation
+        if (standardModels.has(model)) {
+            model.finalize();
+        }
+
+        this.#localModel = this.integrateModel(model);
+    }
+
+    /**
+     * Replace the "base" of {@link localModel} and return an updated model.
+     */
+    protected abstract integrateModel(model: Model): Model;
+
+    /**
+     * Obtain a model unconditionally for mutation purposes.
+     */
+    get mutableModel() {
+        if (this.#isFinal) {
+            throw new MetadataConflictError(`Cannot modify final semantics of ${this.#localModel?.name ?? "(none)"}`);
+        }
+
+        if (this.#localModel === undefined) {
+            this.#localModel = this.createModel();
+        } else if (this.#localModel.isFinal) {
+            this.#localModel = this.#localModel.extend();
+        }
+        return this.#localModel;
+    }
+
+    /**
+     * The model's {@link Model.Type}.
+     *
+     * Field decorators operate prior to class decorators, so we may need to transition the model to a new type when the
+     * class is decorated.  This is slightly lossy so type-specific decoration should always occur after assigning kind.
+     */
+    get modelType(): Model.Type | undefined {
+        if (this.#localModel === undefined) {
+            return;
+        }
+        return this.mutableModel.constructor as Model.ConcreteType;
+    }
+
+    set modelType(type: Model.ConcreteType) {
+        if (this.#localModel === undefined) {
+            this.#localModel = this.createModel(type);
+            return;
+        }
+
+        if (this.#localModel instanceof type) {
+            return;
+        }
+
+        // Detach original model
+        const original = this.#localModel as Model;
+        const { parent } = original;
+        original.parent = undefined;
+
+        // Create replacement
+        const replacement = new type({
+            name: original.name,
+            id: original.id,
+            type: original.type,
+            parent,
+            operationalBase: original.operationalBase,
+            children: original.children,
+        });
+
+        if ("quality" in original && "quality" in replacement) {
+            replacement.quality = original.quality;
+        }
+
+        this.#localModel = replacement;
+    }
+
+    protected abstract createModel(type?: Model.ConcreteType): Model;
+}
+
+export namespace Semantics {
+    /**
+     * Access the {@link Semantics} of a {@link DecoratorContext}.
+     */
+    export function of(context: DecoratorContext) {
+        const classSemantics = classOf(context);
+        if (context.kind === "class") {
+            return classSemantics;
+        }
+        return classSemantics.fieldFor(context.name);
+    }
+
+    /**
+     * Access the {@link ClassSemantics} of a constructor or decorator context.
+     */
+    // eslint-disable-next-line prefer-const
+    export let classOf = (_source: ClassSemantics.Source): ClassSemantics => {
+        // This should be replaced by ClassSemantics
+        throw new InternalError(`Class decoration lookup not installed`);
+    };
+}

package/src/decoration/semantics/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./ClassSemantics.js";
+export * from "./FieldSemantics.js";
+export * from "./Semantics.js";

package/src/index.ts

@@ -6,6 +6,7 @@
 
 export * from "./aspects/index.js";
 export * from "./common/index.js";
+export * from "./decoration/index.js";
 export * from "./elements/index.js";
 export * from "./logic/index.js";
 export * from "./Matter.js";

package/src/models/AttributeModel.ts

@@ -51,6 +51,7 @@ export class AttributeModel extends PropertyModel<AttributeElement> implements A
     }
 
     static Tag = AttributeElement.Tag;
+    static requiresId = true;
 }
 
 AttributeModel.register();