@duet3d/objectmodel 3.7.0-beta.1 → 3.7.0-beta.11

package/README.md

@@ -4,13 +4,7 @@ TypeScript implementation of the Duet3D Object Model.
 
 ## Installation
 
-Install via `npm install @duet3d/objectmodel`. Users of Vue 2 must also run this command after the first import:
-
-```
-globalThis._duetModelSetArray = (array, index, value) => Vue.set(array, index, value);
-```
-
-This is required to make sure that change events for arrays are correctly fired.
+Install via `npm install @duet3d/objectmodel`.
 
 ## Bug reports
 

package/dist/ModelCollection.d.ts

@@ -1,4 +1,8 @@
 import type { IModelObject } from "./ModelObject";
+/**
+ * Factory creating the item for a given index
+ */
+export type ItemFactory<T> = (index: number) => T;
 /**
  * Class for storing model object items in an array
  */
@@ -6,10 +10,11 @@ export declare class ModelCollection<T extends IModelObject | null> extends Arra
     /**
      * Constructor of this class
      * @param itemConstructor Item constructor type that items must derive from
+     * @param itemFactory Factory to use for collections whose item class depends on the position, e.g. boards
      */
     constructor(itemConstructor: {
         new (): T;
-    });
+    }, itemFactory?: ItemFactory<T> | null);
     /**
      * Overridden push method to perform better type checks
      * @param items Items to add
@@ -18,9 +23,10 @@ export declare class ModelCollection<T extends IModelObject | null> extends Arra
     /**
      * Update this instance from the given data
      * @param jsonElement JSON data to upgrade this instance from
+     * @param authoritative Whether the given data is a complete snapshot of the items and everything below them
      * @returns Updated instance
      */
-    update(jsonElement: any): IModelObject | null;
+    update(jsonElement: any, authoritative?: boolean): IModelObject | null;
 }
 export default ModelCollection;
 /**

package/dist/ModelCollection.js

@@ -1,5 +1,15 @@
 import { isModelObject } from "./ModelObject";
-import { setArrayItem } from "./index";
+/**
+ * Create the item for a given index. This is deliberately not a method of the collection because
+ * a non-public member would make the class nominally typed, which breaks assignability of the
+ * reactive proxies consumers wrap the object model in
+ * @param collection Collection the item is created for
+ * @param index Index the new item is going to be stored at
+ * @returns New item
+ */
+function createItem(collection, index) {
+    return (collection.$itemFactory !== null) ? collection.$itemFactory(index) : new collection.$itemConstructor();
+}
 /**
  * Class for storing model object items in an array
  */
@@ -7,11 +17,13 @@ export class ModelCollection extends Array {
     /**
      * Constructor of this class
      * @param itemConstructor Item constructor type that items must derive from
+     * @param itemFactory Factory to use for collections whose item class depends on the position, e.g. boards
      */
-    constructor(itemConstructor) {
+    constructor(itemConstructor, itemFactory = null) {
         super();
         Object.setPrototypeOf(this, ModelCollection.prototype);
         Object.defineProperty(this, "$itemConstructor", { enumerable: false, value: itemConstructor });
+        Object.defineProperty(this, "$itemFactory", { enumerable: false, value: itemFactory });
     }
     // Unfortunately it isn't possible to override index operators in JS/TS
     /**
@@ -25,7 +37,7 @@ export class ModelCollection extends Array {
                 super.push(item);
             }
             else {
-                const newItem = new that.$itemConstructor();
+                const newItem = createItem(that, this.length);
                 super.push(newItem.update(item));
             }
         }
@@ -34,9 +46,10 @@ export class ModelCollection extends Array {
     /**
      * Update this instance from the given data
      * @param jsonElement JSON data to upgrade this instance from
+     * @param authoritative Whether the given data is a complete snapshot of the items and everything below them
      * @returns Updated instance
      */
-    update(jsonElement) {
+    update(jsonElement, authoritative = false) {
         if (jsonElement === null) {
             return null;
         }
@@ -52,23 +65,23 @@ export class ModelCollection extends Array {
             if (currentItem === null) {
                 const newItem = jsonElement[i];
                 if (newItem instanceof that.$itemConstructor) {
-                    setArrayItem(this, i, jsonElement[i]);
+                    this[i] = jsonElement[i];
                 }
                 else {
-                    const refItem = new that.$itemConstructor();
-                    setArrayItem(this, i, refItem.update(newItem));
+                    const refItem = createItem(that, i);
+                    this[i] = refItem.update(newItem, authoritative);
                 }
             }
             else if (isModelObject(currentItem)) {
-                const newItem = currentItem.update(jsonElement[i]);
+                const newItem = currentItem.update(jsonElement[i], authoritative);
                 if (currentItem !== newItem) {
-                    setArrayItem(this, i, newItem);
+                    this[i] = newItem;
                 }
             }
             else {
                 const newItem = jsonElement[i];
                 if (currentItem !== newItem) {
-                    setArrayItem(this, i, newItem);
+                    this[i] = newItem;
                 }
             }
         }
@@ -79,8 +92,8 @@ export class ModelCollection extends Array {
                 super.push(itemToAdd);
             }
             else {
-                const newItem = new that.$itemConstructor();
-                super.push(newItem.update(itemToAdd));
+                const newItem = createItem(that, i);
+                super.push(newItem.update(itemToAdd, authoritative));
             }
         }
         return this;

package/dist/ModelDictionary.d.ts

@@ -15,14 +15,16 @@ export declare class ModelDictionary<T> extends Map<string, T | null> implements
      * Overridden set method to perform type-checks and update
      * @param key Key to set
      * @param value Value to set
+     * @param authoritative Whether the given value is a complete snapshot of the item and everything below it
      */
-    set(key: string, value: T | null): this;
+    set(key: string, value: T | null, authoritative?: boolean): this;
     /**
      * Update this instance from the given data
      * @param jsonElement JSON data to upgrade this instance from
+     * @param authoritative Whether the given data is a complete snapshot of the items and everything below them
      * @returns Updated instance
      */
-    update(jsonElement: any): IModelObject | null;
+    update(jsonElement: any, authoritative?: boolean): IModelObject | null;
     /**
      * Convert this object to JSON
      * @returns JSON object

package/dist/ModelDictionary.js

@@ -18,8 +18,9 @@ export class ModelDictionary extends Map {
      * Overridden set method to perform type-checks and update
      * @param key Key to set
      * @param value Value to set
+     * @param authoritative Whether the given value is a complete snapshot of the item and everything below it
      */
-    set(key, value) {
+    set(key, value, authoritative = false) {
         const that = this;
         if (value === null) {
             if (that.$nullDeletesKeys) {
@@ -33,13 +34,13 @@ export class ModelDictionary extends Map {
             if (that.$itemConstructor !== null && !(value instanceof that.$itemConstructor)) {
                 const newItem = new that.$itemConstructor();
                 if (isModelObject(newItem)) {
-                    const updatedItem = newItem.update(value);
+                    const updatedItem = newItem.update(value, authoritative);
                     return super.set(key, updatedItem);
                 }
             }
         }
         else if (isModelObject(currentItem)) {
-            const newItem = currentItem.update(value);
+            const newItem = currentItem.update(value, authoritative);
             if (currentItem !== newItem) {
                 return super.set(key, value);
             }
@@ -50,20 +51,21 @@ export class ModelDictionary extends Map {
     /**
      * Update this instance from the given data
      * @param jsonElement JSON data to upgrade this instance from
+     * @param authoritative Whether the given data is a complete snapshot of the items and everything below them
      * @returns Updated instance
      */
-    update(jsonElement) {
+    update(jsonElement, authoritative = false) {
         if (jsonElement === null) {
             this.clear();
         }
         else if (jsonElement instanceof Map) {
             for (const [key, value] of jsonElement.entries()) {
-                this.set(key, value);
+                this.set(key, value, authoritative);
             }
         }
         else {
             for (const [key, value] of Object.entries(jsonElement)) {
-                this.set(key, value);
+                this.set(key, value, authoritative);
             }
         }
         return this;

package/dist/ModelObject.d.ts

@@ -5,9 +5,12 @@ export interface IModelObject {
     /**
      * Update this instance from the given data
      * @param jsonElement JSON data to upgrade this instance from
+     * @param authoritative Whether the given data is a complete snapshot of this instance and everything below it,
+     * so that properties missing from it are known to be null. Set this only for responses that were not filtered
+     * by the sender, i.e. full object model key queries but never live/patch updates
      * @returns Updated instance (may not equal the original instance)
      */
-    update(jsonElement: any): IModelObject | null;
+    update(jsonElement: any, authoritative?: boolean): IModelObject | null;
 }
 /**
  * Check whether a given value provides model update functionality
@@ -18,12 +21,20 @@ export declare function isModelObject(value: any): value is IModelObject;
  * Base class for object model classes
  */
 export declare abstract class ModelObject implements IModelObject {
+    /**
+     * Whether an authoritative update may reset the properties of this class that are missing from it.
+     * Set to false where an instance never receives a complete snapshot of itself. Deliberately static
+     * because an instance member would become part of the structural type and break consumers that hold
+     * a mapped version of the model, such as a Pinia store
+     */
+    static readonly resetsMissingProperties: boolean;
     /**
      * Update this instance from the given data
      * @param jsonElement JSON data to upgrade this instance from
+     * @param authoritative Whether the given data is a complete snapshot of this instance and everything below it
      * @returns Updated instance (may not equal the original instance)
      */
-    update(jsonElement: any): IModelObject | null;
+    update(jsonElement: any, authoritative?: boolean): IModelObject | null;
     /**
      * Wrap a nullable model object property so that type checks can be performed
      * @param key Property key of the derived class

package/dist/ModelObject.js

@@ -1,4 +1,34 @@
-import { ModelCollection, setArrayItem } from "./index";
+import { ModelCollection } from "./index";
+/**
+ * Names of the properties that default to null, per model object class. Queried from a pristine instance because
+ * TS types are gone at runtime, so a null default is the only remaining evidence that a property may hold null
+ */
+const nullableProperties = new WeakMap();
+/**
+ * Get the names of the properties of the given instance's class that may hold null
+ * @param instance Instance to inspect the class of
+ */
+function getNullableProperties(instance) {
+    let result = nullableProperties.get(instance.constructor);
+    if (result === undefined) {
+        result = new Set();
+        try {
+            for (const [key, value] of Object.entries(new instance.constructor())) {
+                if (value === null) {
+                    result.add(key);
+                }
+            }
+        }
+        catch (e) {
+            // A class that cannot be constructed without arguments simply opts out of null reconstruction
+            if (process.env.NODE_ENV !== "production") {
+                console.warn(`Failed to determine nullable properties of ${instance.constructor.name}`, e);
+            }
+        }
+        nullableProperties.set(instance.constructor, result);
+    }
+    return result;
+}
 /**
  * Check whether a given value provides model update functionality
  * @param value Value to check
@@ -13,19 +43,27 @@ export class ModelObject {
     /**
      * Update this instance from the given data
      * @param jsonElement JSON data to upgrade this instance from
+     * @param authoritative Whether the given data is a complete snapshot of this instance and everything below it
      * @returns Updated instance (may not equal the original instance)
      */
-    update(jsonElement) {
+    update(jsonElement, authoritative = false) {
         if (jsonElement === null) {
             return null;
         }
+        if (authoritative && this.constructor.resetsMissingProperties) {
+            for (const key of getNullableProperties(this)) {
+                if (!(key in jsonElement)) {
+                    this[key] = null;
+                }
+            }
+        }
         for (const [key, value] of Object.entries(jsonElement)) {
             if (key in this) {
                 const ownKey = key;
                 const prop = this[ownKey];
                 if (isModelObject(prop)) {
                     // Update model objects
-                    const updatedObject = prop.update(value);
+                    const updatedObject = prop.update(value, authoritative);
                     if (prop !== updatedObject) {
                         const propDescriptor = Object.getOwnPropertyDescriptor(this, key);
                         if (propDescriptor !== undefined) {
@@ -49,12 +87,12 @@ export class ModelObject {
                         for (let i = 0; i < Math.min(prop.length, value.length); i++) {
                             const propItem = prop[i];
                             if (propItem === null) {
-                                setArrayItem(prop, i, value[i]);
+                                prop[i] = value[i];
                             }
                             else {
                                 const newItem = value[i];
                                 if (propItem !== newItem) {
-                                    setArrayItem(prop, i, newItem);
+                                    prop[i] = newItem;
                                 }
                             }
                         }
@@ -219,6 +257,13 @@ export class ModelObject {
         });
     }
 }
+/**
+ * Whether an authoritative update may reset the properties of this class that are missing from it.
+ * Set to false where an instance never receives a complete snapshot of itself. Deliberately static
+ * because an instance member would become part of the structural type and break consumers that hold
+ * a mapped version of the model, such as a Pinia store
+ */
+ModelObject.resetsMissingProperties = true;
 export default ModelObject;
 /**
  * Initialize a model object from the given data

package/dist/ObjectModel.d.ts

@@ -24,6 +24,11 @@ import LedStrip from "./ledStrips";
  */
 export declare class ObjectModel extends ModelObject {
     constructor();
+    /**
+     * A payload handed to the root always covers a subset of the top-level keys rather than the whole model,
+     * so authoritative reconstruction has to start one level below it
+     */
+    static readonly resetsMissingProperties: boolean;
     readonly boards: ModelCollection<Board>;
     readonly directories: Directories;
     readonly fans: ModelCollection<Fan | null>;

package/dist/ObjectModel.js

@@ -1,7 +1,7 @@
 import ModelCollection from "./ModelCollection";
 import ModelDictionary from "./ModelDictionary";
 import ModelObject from "./ModelObject";
-import Board from "./boards";
+import Board, { getBoard } from "./boards";
 import Directories from "./directories";
 import Fan from "./fans";
 import Heat from "./heat";
@@ -25,7 +25,7 @@ import LedStrip from "./ledStrips";
 export class ObjectModel extends ModelObject {
     constructor() {
         super();
-        this.boards = new ModelCollection(Board);
+        this.boards = new ModelCollection(Board, getBoard);
         this.directories = new Directories();
         this.fans = new ModelCollection(Fan);
         this.global = new ModelDictionary(false);
@@ -47,4 +47,9 @@ export class ObjectModel extends ModelObject {
         ModelObject.wrapModelProperty(this, "sbc", SBC);
     }
 }
+/**
+ * A payload handed to the root always covers a subset of the top-level keys rather than the whole model,
+ * so authoritative reconstruction has to start one level below it
+ */
+ObjectModel.resetsMissingProperties = false;
 export default ObjectModel;

package/dist/boards/directDisplay/DirectDisplayScreen.d.ts

@@ -1,6 +1,6 @@
 import type { IModelObject } from "../../ModelObject";
 import DirectDisplayScreenBase from "./DirectDisplayScreenBase";
 export declare class DirectDisplayScreen extends DirectDisplayScreenBase {
-    update(jsonElement: any): IModelObject | null;
+    update(jsonElement: any, authoritative?: boolean): IModelObject | null;
 }
 export default DirectDisplayScreen;

package/dist/boards/directDisplay/DirectDisplayScreen.js

@@ -1,14 +1,14 @@
 import { getDirectDisplayScreen } from ".";
 import DirectDisplayScreenBase from "./DirectDisplayScreenBase";
 export class DirectDisplayScreen extends DirectDisplayScreenBase {
-    update(jsonElement) {
+    update(jsonElement, authoritative = false) {
         if (jsonElement === null) {
             return null;
         }
         if (typeof jsonElement.controller === "string" && jsonElement.controller !== this.controller) {
-            return getDirectDisplayScreen(jsonElement.controller).update(jsonElement);
+            return getDirectDisplayScreen(jsonElement.controller).update(jsonElement, authoritative);
         }
-        return super.update(jsonElement);
+        return super.update(jsonElement, authoritative);
     }
 }
 export default DirectDisplayScreen;

package/dist/boards/directDisplay/DirectDisplayScreenST7567.d.ts

@@ -4,6 +4,6 @@ export declare class DirectDisplayScreenST7567 extends DirectDisplayScreenBase {
     constructor();
     contrast: number;
     resistorRatio: number;
-    update(jsonElement: any): IModelObject | null;
+    update(jsonElement: any, authoritative?: boolean): IModelObject | null;
 }
 export default DirectDisplayScreenST7567;

package/dist/boards/directDisplay/DirectDisplayScreenST7567.js

@@ -6,14 +6,14 @@ export class DirectDisplayScreenST7567 extends DirectDisplayScreenBase {
         this.contrast = 30;
         this.resistorRatio = 6;
     }
-    update(jsonElement) {
+    update(jsonElement, authoritative = false) {
         if (jsonElement === null) {
             return null;
         }
         if (typeof jsonElement.controller === "string" && jsonElement.controller !== this.controller) {
-            return getDirectDisplayScreen(jsonElement.controller).update(jsonElement);
+            return getDirectDisplayScreen(jsonElement.controller).update(jsonElement, authoritative);
         }
-        return super.update(jsonElement);
+        return super.update(jsonElement, authoritative);
     }
 }
 export default DirectDisplayScreenST7567;

package/dist/boards/index.d.ts

@@ -30,29 +30,43 @@ export declare class Board extends ModelObject {
     constructor();
     accelerometer: Accelerometer | null;
     canAddress: number | null;
-    closedLoop: BoardClosedLoop | null;
-    directDisplay: DirectDisplay | null;
     drivers: ModelCollection<Driver> | null;
     firmwareDate: string;
     firmwareFileName: string;
-    firmwareName: string;
     firmwareVersion: string;
     freeRam: number | null;
-    iapFileNameSBC: string | null;
-    iapFileNameSD: string | null;
-    inductiveSensor: InductiveSensor | null;
-    maxHeaters: number;
     maxMotors: number;
     mcuTemp: MinMaxCurrent | null;
     name: string;
     shortName: string;
-    state: BoardState;
-    supportsDirectDisplay: boolean;
     uniqueId: string | null;
     v12: MinMaxCurrent | null;
     vIn: MinMaxCurrent | null;
+}
+export declare class MainBoard extends Board {
+    constructor();
+    directDisplay: DirectDisplay | null;
+    firmwareName: string;
+    iapFileNameSBC: string | null;
+    iapFileNameSD: string | null;
+    maxHeaters: number;
+    supportsDirectDisplay: boolean;
     wifiFirmwareFileName: string | null;
 }
+export declare class ExpansionBoard extends Board {
+    constructor();
+    closedLoop: BoardClosedLoop | null;
+    inductiveSensor: InductiveSensor | null;
+    state: BoardState;
+    timeout: number;
+}
 export default Board;
+/**
+ * Create the board instance for a given index. The first item is always the mainboard,
+ * every other item is an expansion board connected over CAN
+ * @param index Index in the boards array
+ * @returns New board instance
+ */
+export declare function getBoard(index: number): Board;
 export * from "./directDisplay";
 export * from "./Driver";

package/dist/boards/index.js

@@ -41,38 +41,58 @@ export class Board extends ModelObject {
         super();
         this.accelerometer = null;
         this.canAddress = null;
-        this.closedLoop = null;
-        this.directDisplay = null;
         this.drivers = null;
         this.firmwareDate = "";
         this.firmwareFileName = "";
-        this.firmwareName = "";
         this.firmwareVersion = "";
         this.freeRam = null;
-        this.iapFileNameSBC = null;
-        this.iapFileNameSD = null;
-        this.inductiveSensor = null;
-        this.maxHeaters = 0;
         this.maxMotors = 0;
         this.mcuTemp = null;
         this.name = "";
         this.shortName = "";
-        this.state = BoardState.unknown;
-        this.supportsDirectDisplay = false;
         this.uniqueId = null;
         this.v12 = null;
         this.vIn = null;
-        this.wifiFirmwareFileName = null;
         ModelObject.wrapModelProperty(this, "accelerometer", Accelerometer);
-        ModelObject.wrapModelProperty(this, "closedLoop", BoardClosedLoop);
-        ModelObject.wrapModelProperty(this, "directDisplay", DirectDisplay);
         ModelObject.wrapModelCollectionProperty(this, "drivers", Driver);
-        ModelObject.wrapModelProperty(this, "inductiveSensor", InductiveSensor);
         ModelObject.wrapModelProperty(this, "mcuTemp", MinMaxCurrent);
         ModelObject.wrapModelProperty(this, "v12", MinMaxCurrent);
         ModelObject.wrapModelProperty(this, "vIn", MinMaxCurrent);
     }
 }
+export class MainBoard extends Board {
+    constructor() {
+        super();
+        this.directDisplay = null;
+        this.firmwareName = "";
+        this.iapFileNameSBC = null;
+        this.iapFileNameSD = null;
+        this.maxHeaters = 0;
+        this.supportsDirectDisplay = false;
+        this.wifiFirmwareFileName = null;
+        ModelObject.wrapModelProperty(this, "directDisplay", DirectDisplay);
+    }
+}
+export class ExpansionBoard extends Board {
+    constructor() {
+        super();
+        this.closedLoop = null;
+        this.inductiveSensor = null;
+        this.state = BoardState.unknown;
+        this.timeout = 10;
+        ModelObject.wrapModelProperty(this, "closedLoop", BoardClosedLoop);
+        ModelObject.wrapModelProperty(this, "inductiveSensor", InductiveSensor);
+    }
+}
 export default Board;
+/**
+ * Create the board instance for a given index. The first item is always the mainboard,
+ * every other item is an expansion board connected over CAN
+ * @param index Index in the boards array
+ * @returns New board instance
+ */
+export function getBoard(index) {
+    return (index === 0) ? new MainBoard() : new ExpansionBoard();
+}
 export * from "./directDisplay";
 export * from "./Driver";