@matter/node 0.15.1 → 0.15.2-alpha.0-20250703-2e16aba2b

package/src/behavior/internal/ClientBehaviorBacking.ts

@@ -5,26 +5,69 @@
  */
 
 import { Behavior } from "#behavior/Behavior.js";
+import { GlobalAttributeState } from "#behavior/cluster/ClusterState.js";
 import { Datasource } from "#behavior/state/managed/Datasource.js";
 import { Endpoint } from "#endpoint/Endpoint.js";
 import { SupportedElements } from "#endpoint/properties/Behaviors.js";
-import { EndpointStore } from "#endpoint/storage/EndpointStore.js";
-import { NotImplementedError } from "#general";
+import { camelize } from "#general";
+import { ClusterModel } from "#model";
+import { AttributeId, CommandId } from "#types";
 import { BehaviorBacking } from "./BehaviorBacking.js";
 
 /**
  * This class backs the client implementation of a behavior.
  */
 export class ClientBehaviorBacking extends BehaviorBacking {
-    protected override store: Datasource.Store | undefined;
+    protected override store: Datasource.ExternallyMutableStore;
+    #elements?: SupportedElements;
 
-    constructor(endpoint: Endpoint, behavior: Behavior.Type, endpointStore: EndpointStore, options?: Behavior.Options) {
+    constructor(
+        endpoint: Endpoint,
+        behavior: Behavior.Type,
+        store: Datasource.ExternallyMutableStore,
+        options?: Behavior.Options,
+    ) {
         super(endpoint, behavior, options);
 
-        this.store = endpointStore.storeForBehavior(behavior.id);
+        this.store = store;
     }
 
     get elements(): SupportedElements | undefined {
-        throw new NotImplementedError();
+        if (this.#elements) {
+            return this.#elements;
+        }
+
+        const { attributeList, acceptedCommandList } = this.endpoint.stateOf(this.type) as GlobalAttributeState;
+        const schema = this.type.schema as ClusterModel;
+
+        const attributes = new Set<string>();
+        const attributeIds = new Set(attributeList);
+        for (const attr of schema.attributes) {
+            if (attributeIds.has(attr.id as AttributeId)) {
+                attributes.add(camelize(attr.name));
+            }
+        }
+
+        const commands = new Set<string>();
+        const commandIds = new Set(acceptedCommandList);
+        for (const cmd of schema.commands) {
+            if (cmd.isRequest && commandIds.has(cmd.id as CommandId)) {
+                commands.add(camelize(cmd.name));
+            }
+        }
+
+        return (this.#elements = {
+            attributes,
+            commands,
+
+            // TODO
+            events: new Set(),
+        });
+    }
+
+    protected override get datasourceOptions() {
+        const options = super.datasourceOptions;
+        options.primaryKey = "id";
+        return options;
     }
 }

package/src/behavior/internal/Reactors.ts

@@ -311,7 +311,7 @@ class ReactorBacking<T extends any[], R> {
             // construction and destruction
             //
             // Also, do not inject activity here.  No reason to have both the reactor and the context registered
-            let result: MaybePromise<Awaited<R> | undefined> = OfflineContext.act(this.toString(), undefined, reactor, {
+            let result: MaybePromise<Awaited<R> | undefined> = OfflineContext.act(this.toString(), reactor, {
                 command,
             });
 

package/src/behavior/internal/ServerBehaviorBacking.ts

@@ -7,11 +7,12 @@
 import { ClusterBehavior } from "#behavior/cluster/ClusterBehavior.js";
 import { GlobalAttributeState } from "#behavior/cluster/ClusterState.js";
 import { ValidatedElements } from "#behavior/cluster/ValidatedElements.js";
-import type { SupportedElements } from "#endpoint/index.js";
+import type { SupportedElements } from "#endpoint/properties/Behaviors.js";
 import { camelize } from "#general";
 import { FieldValue } from "#model";
-import { ServerNodeStore } from "#node/storage/ServerNodeStore.js";
 import { Val } from "#protocol";
+import { NodeStore } from "#storage/NodeStore.js";
+import { DatasourceStore } from "#storage/server/DatasourceStore.js";
 import { ClusterType, TlvNoResponse } from "#types";
 import { Behavior } from "../Behavior.js";
 import { Datasource } from "../state/managed/Datasource.js";
@@ -28,13 +29,15 @@ export class ServerBehaviorBacking extends BehaviorBacking {
 
     override get store() {
         if (!this.#store) {
-            this.#store = this.#serverStore.endpointStores
-                .storeForEndpoint(this.endpoint)
-                .storeForBehavior(this.type.id);
+            this.#store = this.createStore();
         }
         return this.#store;
     }
 
+    protected createStore() {
+        return this.#nodeStore.storeForEndpoint(this.endpoint).createStoreForBehavior(this.type.id, DatasourceStore);
+    }
+
     get elements() {
         return this.#elements;
     }
@@ -67,8 +70,8 @@ export class ServerBehaviorBacking extends BehaviorBacking {
         finalizeState();
     }
 
-    get #serverStore() {
-        return this.endpoint.env.get(ServerNodeStore);
+    get #nodeStore() {
+        return this.endpoint.env.get(NodeStore);
     }
 
     /**

package/src/behavior/state/managed/Datasource.ts

@@ -5,6 +5,7 @@
  */
 
 import {
+    camelize,
     Crypto,
     deepCopy,
     ImplementationError,
@@ -80,6 +81,8 @@ export interface Datasource<T extends StateType = StateType> extends Transaction
 export function Datasource<const T extends StateType = StateType>(options: Datasource.Options<T>): Datasource<T> {
     const internals = configure(options);
 
+    configureExternalChanges(internals);
+
     let readOnlyView: undefined | InstanceType<T>;
 
     return {
@@ -194,12 +197,20 @@ export namespace Datasource {
         /**
          * Optional storage for non-volatile values.
          */
-        store?: Store;
+        store?: Store | ExternallyMutableStore;
 
         /**
          * The object that owns the datasource.  This is passed as the "owner" parameter to {@link Val.Dynamic}.
          */
         owner?: any;
+
+        /**
+         * The internal key used for storage of attributes and struct properties.  Defaults to name.  If set to ID but
+         * the schema has no ID, uses name instead.
+         *
+         * For structs we also support the other key (id or name) for input, but always write using the preferred key.
+         */
+        primaryKey?: "name" | "id";
     }
 
     /**
@@ -220,6 +231,33 @@ export namespace Datasource {
         set(transaction: Transaction, values: Val.Struct): Promise<void>;
     }
 
+    /**
+     * An extended {@link Store} that represents cached values that may mutate independently from the datasource.
+     */
+    export interface ExternallyMutableStore extends Store {
+        /**
+         * Apply changes from an external source.
+         *
+         * Uses the same semantics as {@link set}.
+         */
+        externalSet(values: Val.Struct): Promise<void>;
+
+        /**
+         * A listener that reacts to data changes.
+         */
+        externalChangeListener?: (changes: Val.Struct) => Promise<void>;
+
+        /**
+         * The current version of the data.
+         */
+        version: number;
+    }
+
+    /**
+     * The version we report until we've recorded a version.
+     */
+    export const UNKNOWN_VERSION = -1;
+
     export interface ValueObserver {
         (value: Val, oldValue: Val, context?: ValueSupervisor.Session): void;
     }
@@ -239,10 +277,13 @@ interface SessionContext {
 interface Internals extends Datasource.Options {
     values: Val.Struct;
     version: number;
+    manageVersion: boolean;
+    primaryKey: "name" | "id";
     sessions?: Map<ValueSupervisor.Session, SessionContext>;
     featuresKey?: string;
     interactionObserver(session?: AccessControl.Session): MaybePromise<void>;
     events: Datasource.InternalEvents;
+    changedEventFor(key: string): undefined | Datasource.Events[any];
 }
 
 /**
@@ -257,6 +298,9 @@ interface CommitChanges {
     changeList: Set<string>;
 }
 
+/**
+ * Initialize the internal version of the datasource.
+ */
 function configure(options: Datasource.Options): Internals {
     const values = new options.type() as Val.Struct;
 
@@ -293,12 +337,16 @@ function configure(options: Datasource.Options): Internals {
     const events = (options.events ?? {}) as Datasource.InternalEvents;
     events[changed] = new Observable();
 
+    let changedEventIndex: undefined | Map<string, undefined | Datasource.InternalEvents[`${string}$Changed`]>;
+
     return {
         ...options,
+        primaryKey: options.primaryKey === "id" ? "id" : "name",
         events,
         version: options.crypto.randomUint32,
-        values: values,
+        values,
         featuresKey,
+        manageVersion: true,
 
         interactionObserver(session?: ValueSupervisor.Session) {
             function handleObserverError(error: any) {
@@ -316,6 +364,107 @@ function configure(options: Datasource.Options): Internals {
                 }
             }
         },
+
+        changedEventFor(key: string) {
+            if (changedEventIndex === undefined) {
+                changedEventIndex = new Map();
+            } else if (changedEventIndex.has(key)) {
+                return changedEventIndex.get(key);
+            }
+
+            const id = Number.parseInt(key);
+            let event;
+            if (Number.isNaN(id)) {
+                event = events[`${key}$Changed`];
+            } else {
+                const field = options.supervisor.schema.member(id);
+                if (field !== undefined) {
+                    event = events[`${camelize(field.name)}$Changed`];
+                }
+            }
+
+            changedEventIndex.set(key, event);
+
+            return event;
+        },
+    };
+}
+
+/**
+ * If the store supports external mutation, add a listener to update internal state and notify observers.
+ *
+ * Currently ignores locks.  This is probably OK because locks should only be held if we're updating the source of
+ * truth.
+ */
+function configureExternalChanges(internals: Internals) {
+    const { store } = internals;
+    if (!store || !("externalSet" in store)) {
+        return;
+    }
+
+    internals.version = store.version;
+    internals.manageVersion = false;
+
+    store.externalChangeListener = async (potentialChanges: Val.Struct) => {
+        const { values } = internals;
+
+        let changes: undefined | Val.Struct;
+        let oldValues: undefined | Val.Struct;
+
+        for (const name in potentialChanges) {
+            if (isDeepEqual(values[name], potentialChanges[name])) {
+                continue;
+            }
+
+            if (changes === undefined) {
+                changes = { [name]: potentialChanges[name] };
+                oldValues = { [name]: values[name] };
+            } else {
+                changes[name] = potentialChanges[name];
+                oldValues![name] = values[name];
+            }
+        }
+
+        internals.version = store.version;
+
+        if (!changes) {
+            return;
+        }
+
+        internals.values = {
+            ...internals.values,
+            ...changes,
+        };
+
+        if (internals.sessions) {
+            for (const context of internals.sessions.values()) {
+                context.onChange(oldValues!);
+            }
+        }
+
+        const iterator = Object.keys(changes)[Symbol.iterator]();
+
+        return emitChanged();
+
+        function emitChanged(): MaybePromise<void> {
+            while (true) {
+                const n = iterator.next();
+                if (n.done) {
+                    return;
+                }
+
+                const name = n.value;
+                const event = internals.changedEventFor(name);
+                if (!event?.isObserved) {
+                    continue;
+                }
+
+                const result = event.emit(changes![name], oldValues![name]);
+                if (MaybePromise.is(result)) {
+                    return Promise.resolve(result).then(emitChanged);
+                }
+            }
+        }
     };
 }
 
@@ -362,6 +511,8 @@ function createReference(resource: Transaction.Resource, internals: Internals, s
 
     // This is the actual reference
     const reference: Val.Reference<Val.Struct> = {
+        primaryKey: internals.primaryKey,
+
         get original() {
             return internals.values;
         },
@@ -501,6 +652,10 @@ function createReference(resource: Transaction.Resource, internals: Internals, s
 
     // Increment data version
     function incrementVersion() {
+        if (!internals.manageVersion) {
+            return;
+        }
+
         // Update version
         internals.version++;
         if (internals.version > 0xffff_ffff) {
@@ -614,7 +769,7 @@ function createReference(resource: Transaction.Resource, internals: Internals, s
                     changes.persistent[name] = values[name];
                 }
 
-                const event = internals.events?.[`${name}$Changed`];
+                const event = internals.changedEventFor(name);
                 if (event?.isObserved) {
                     changes.notifications.push({
                         event,

package/src/behavior/state/managed/ManagedReference.ts

@@ -26,7 +26,9 @@ type Container = Record<string | number, Val>;
  * separate ManagedReference.
  *
  * @param parent a reference to the container we reference
- * @param index the key we reference
+ * @param primaryKey the preferred key for lookup
+ * @param name the name (in the case of structs) or index (in case of lists)
+ * @param id the lookup ID in the case of structs
  * @param assertWriteOk enforces ACLs and read-only
  * @param clone clones the container prior to write; undefined if not transactional
  *
@@ -34,26 +36,35 @@ type Container = Record<string | number, Val>;
  */
 export function ManagedReference(
     parent: Val.Reference<Val.Collection>,
-    index: string | number,
+    primaryKey: "name" | "id",
+    name: string | number,
+    id: number | undefined,
     assertWriteOk: (value: Val) => void,
     clone: (container: Val) => Val,
 ) {
-    let value = (parent.value as Container)[index];
     let expired = false;
     let location = {
         ...parent.location,
-        path: parent.location.path.at(index),
+        path: parent.location.path.at(name),
     };
 
+    const key = primaryKey === "id" ? (id ?? name) : name;
+    const altKey = primaryKey === "id" ? (key === name ? undefined : name) : id;
+    let value: unknown;
+    if (key in (parent.value as Container)) {
+        value = (parent.value as Container)[key];
+    } else if (altKey !== undefined) {
+        value = (parent.value as Container)[altKey];
+    }
+
     const reference: Val.Reference = {
+        primaryKey,
+        parent,
+
         get rootOwner() {
             return parent.rootOwner;
         },
 
-        get parent() {
-            return parent;
-        },
-
         get value() {
             // Authorization is unnecessary here because the reference would not exist if access is unauthorized
 
@@ -85,14 +96,24 @@ export function ManagedReference(
             replaceValue(newValue);
 
             // Now use change to complete the update
-            this.change(() => ((parent.value as Container)[index] = newValue));
+            this.change(() => {
+                (parent.value as Container)[key] = newValue;
+                if (altKey !== undefined && altKey in parent.value) {
+                    delete (parent.value as Container)[altKey];
+                }
+            });
         },
 
         get original() {
             if (!parent.original) {
                 return undefined;
             }
-            return (parent.original as Container)[index];
+            if (key in parent.original) {
+                return (parent.original as Container)[key];
+            }
+            if (altKey !== undefined) {
+                return (parent.original as Container)[altKey];
+            }
         },
 
         change(mutator: () => void) {
@@ -104,7 +125,10 @@ export function ManagedReference(
                 // In transactions, clone the value if we haven't done so yet
                 if (clone && value === this.original) {
                     const newValue = clone(value);
-                    (parent.value as Container)[index] = newValue;
+                    (parent.value as Container)[key] = newValue;
+                    if (altKey !== undefined && altKey in (parent.value as Container)) {
+                        delete (parent.value as Container)[altKey];
+                    }
                     replaceValue(newValue);
                 }
 
@@ -123,14 +147,22 @@ export function ManagedReference(
                 replaceValue(undefined);
                 return;
             }
-            replaceValue((parent.value as Container)[index]);
+
+            let value;
+            if (key in parent.value) {
+                value = (parent.value as Container)[key];
+            } else if (altKey !== undefined && altKey in parent.value) {
+                value = (parent.value as Container)[altKey];
+            }
+
+            replaceValue(value);
         },
     };
 
     if (!parent.subrefs) {
         parent.subrefs = {};
     }
-    parent.subrefs[index] = reference;
+    parent.subrefs[key] = reference;
 
     return reference;
 

package/src/behavior/state/managed/values/ListManager.ts

@@ -144,7 +144,9 @@ function createProxy(config: ListConfig, reference: Val.Reference<Val.List>, ses
             if (subref === undefined) {
                 subref = ManagedReference(
                     reference,
-                    index,
+                    "name",
+                    index, // For managed reference's purposes this is our "name"
+                    undefined,
 
                     () => true,
 

package/src/behavior/state/managed/values/StructManager.ts

@@ -191,14 +191,22 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
             access.authorizeWrite(this[Internal.session], this[Internal.reference].location);
 
             // We allow attribute/field name or id as key.  If name is present id is ignored
-            let storedKey =
-                name in this[Internal.reference].value
-                    ? name
-                    : id !== undefined && id in this[Internal.reference]
-                      ? id
-                      : name;
+            const pk = this[Internal.reference].primaryKey;
+            let key = pk === "id" ? (id ?? name) : name;
+            let storedKey: undefined | number | string;
+            if (key in this[Internal.reference].value) {
+                storedKey = key;
+            } else if (pk === "id") {
+                if (name in this[Internal.reference].value) {
+                    storedKey = name;
+                }
+            } else if (id !== undefined) {
+                if (id in this[Internal.reference].value) {
+                    storedKey = id;
+                }
+            }
 
-            const oldValue = this[Internal.reference].value[storedKey];
+            const oldValue = storedKey === undefined ? undefined : this[Internal.reference].value[storedKey];
 
             const self = this;
 
@@ -213,7 +221,7 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                         this[Internal.session],
                     );
                     if (name in properties) {
-                        storedKey = name;
+                        key = storedKey = name;
                         target = properties;
                     } else {
                         target = struct;
@@ -228,7 +236,7 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                 }
 
                 // Modify the value
-                if (fabricScopedList && Array.isArray(value) && Array.isArray(target[storedKey])) {
+                if (fabricScopedList && Array.isArray(value) && Array.isArray(oldValue)) {
                     // In the case of fabric-scoped write to established list we use the managed proxy to perform update
                     // as it will sort through values and only modify those with correct fabricIndex
                     const proxy = self[name] as Val.List;
@@ -238,7 +246,10 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                     proxy.length = value.length;
                 } else {
                     // Direct assignment
-                    target[storedKey] = value;
+                    target[key] = value;
+                    if (storedKey !== undefined && storedKey !== key) {
+                        delete target[storedKey];
+                    }
                 }
 
                 if (!this[Internal.session].acceptInvalid && validate) {
@@ -258,7 +269,7 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                     } catch (e) {
                         // Undo our change on error.  Rollback will take care of this when transactional but this
                         // handles the cases of 1.) no transaction, and 2.) error is caught within transaction
-                        target[storedKey] = oldValue;
+                        target[key] = oldValue;
 
                         throw e;
                     }
@@ -285,12 +296,17 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                     }
                 }
 
-                const value = struct[name];
-                if (value !== undefined || id === undefined) {
-                    return value;
+                const key = this[Internal.reference].primaryKey === "id" ? (id ?? name) : name;
+                if (key in struct) {
+                    return struct[key];
                 }
 
-                return struct[id];
+                const key2 = this[Internal.reference].primaryKey === "id" ? name : id;
+                if (key2 !== undefined && key2 in struct) {
+                    return struct[key2];
+                }
+
+                return undefined;
             }
         };
     } else {
@@ -321,8 +337,10 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
         descriptor.get = function (this: Struct) {
             let value;
 
-            // Obtain the value.  Normally just struct[name] except in the case of Val.Dynamic
+            // Obtain the value.  Normally just struct[key] except in the case of Val.Dynamic
+            const pk = this[Internal.reference].primaryKey;
             const struct = this[Internal.reference].value;
+            const key = pk === "id" ? (id ?? name) : name;
             if ((struct as Val.Dynamic)[Val.properties]) {
                 const properties = (struct as Val.Dynamic)[Val.properties](
                     this[Internal.reference].rootOwner,
@@ -334,9 +352,13 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                     value = struct[name];
                 }
             } else {
-                value = struct[name];
-                if (value === undefined && id !== undefined) {
-                    value = struct[id];
+                if (key in struct) {
+                    value = struct[key];
+                } else {
+                    const key2 = pk === "id" ? id : name;
+                    if (key2 !== undefined && key2 in struct) {
+                        value = struct[key2];
+                    }
                 }
             }
 
@@ -372,7 +394,7 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
             };
 
             // Clone the container before write
-            const ref = ManagedReference(this[Internal.reference], name, assertWriteOk, cloneContainer);
+            const ref = ManagedReference(this[Internal.reference], pk, name, id, assertWriteOk, cloneContainer);
 
             ref.owner = manage(ref, this[Internal.session]);