@project-chip/matter.js 0.9.2 → 0.9.4

package/src/tlv/TlvObject.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { UnexpectedDataError } from "../common/MatterError.js";
+import { InternalError, UnexpectedDataError } from "../common/MatterError.js";
 import { tryCatch } from "../common/TryCatchHandler.js";
 import { ValidationError } from "../common/ValidationError.js";
 import { Globals } from "../model/index.js";
@@ -12,7 +12,7 @@ import { Merge } from "../util/Type.js";
 import { TlvAny } from "./TlvAny.js";
 import { LengthConstraints } from "./TlvArray.js";
 import { TlvTag, TlvType, TlvTypeLength } from "./TlvCodec.js";
-import { TlvReader, TlvSchema, TlvWriter } from "./TlvSchema.js";
+import { TlvEncodingOptions, TlvReader, TlvSchema, TlvWriter } from "./TlvSchema.js";
 
 export interface FieldType<T> {
     id: number;
@@ -79,11 +79,17 @@ export class ObjectSchema<F extends TlvFields> extends TlvSchema<TypeFromFields<
         }
     }
 
-    #encodeEntryToTlv(writer: TlvWriter, name: string, value: TypeFromFields<F>, forWriteInteraction?: boolean) {
+    #encodeEntryToTlv(writer: TlvWriter, name: string, value: TypeFromFields<F>, options?: TlvEncodingOptions) {
         const { id, schema, optional: isOptional, repeated: isRepeated } = this.fieldDefinitions[name];
+        const { forWriteInteraction = false, allowMissingFieldsForNonFabricFilteredRead = false } = options ?? {};
+        if (forWriteInteraction && allowMissingFieldsForNonFabricFilteredRead) {
+            throw new InternalError(
+                "Encode options can not indicate a write interaction and a fabric filtered read interaction at the same time.",
+            );
+        }
         const fieldValue = (value as any)[name];
         if (fieldValue === undefined) {
-            if (!isOptional) {
+            if (!isOptional && !allowMissingFieldsForNonFabricFilteredRead) {
                 if (forWriteInteraction && id === <number>Globals.FabricIndex.id) {
                     // FabricIndex field should not be included in encoded data for write interactions
                     return;
@@ -97,36 +103,36 @@ export class ObjectSchema<F extends TlvFields> extends TlvSchema<TypeFromFields<
                 throw new ValidationError(`Repeated field ${name} should be an array.`, name);
             }
             for (const element of fieldValue) {
-                schema.encodeTlvInternal(writer, element, { id }, forWriteInteraction);
+                schema.encodeTlvInternal(writer, element, { id }, options);
             }
         } else {
-            schema.encodeTlvInternal(writer, fieldValue, { id }, forWriteInteraction);
+            schema.encodeTlvInternal(writer, fieldValue, { id }, options);
         }
     }
 
     /**
      * Encode the object as Structure, by the order of field definitions.
      */
-    #encodeStructure(writer: TlvWriter, value: TypeFromFields<F>, forWriteInteraction?: boolean) {
+    #encodeStructure(writer: TlvWriter, value: TypeFromFields<F>, options?: TlvEncodingOptions) {
         for (const name in this.fieldDefinitions) {
-            this.#encodeEntryToTlv(writer, name, value, forWriteInteraction);
+            this.#encodeEntryToTlv(writer, name, value, options);
         }
     }
 
     /**
      * Encode the object as List, by the order of the fields in the object.
      */
-    #encodeList(writer: TlvWriter, value: TypeFromFields<F>, forWriteInteraction?: boolean) {
+    #encodeList(writer: TlvWriter, value: TypeFromFields<F>, options?: TlvEncodingOptions) {
         const encodedFields = new Set<string>();
         // Encode object fields
         for (const name of Object.keys(value)) {
-            this.#encodeEntryToTlv(writer, name, value, forWriteInteraction);
+            this.#encodeEntryToTlv(writer, name, value, options);
             encodedFields.add(name);
         }
         // Verify the potentially missing fields
         for (const name in this.fieldDefinitions) {
             if (encodedFields.has(name)) continue;
-            this.#encodeEntryToTlv(writer, name, value, forWriteInteraction);
+            this.#encodeEntryToTlv(writer, name, value, options);
         }
     }
 
@@ -134,15 +140,15 @@ export class ObjectSchema<F extends TlvFields> extends TlvSchema<TypeFromFields<
         writer: TlvWriter,
         value: TypeFromFields<F>,
         tag?: TlvTag,
-        forWriteInteraction?: boolean,
+        options?: TlvEncodingOptions,
     ): void {
         writer.writeTag({ type: this.type }, tag);
 
         if (this.type === TlvType.Structure) {
             // Encode in order of field definitions
-            this.#encodeStructure(writer, value, forWriteInteraction);
+            this.#encodeStructure(writer, value, options);
         } else {
-            this.#encodeList(writer, value, forWriteInteraction);
+            this.#encodeList(writer, value, options);
         }
 
         writer.writeTag({ type: TlvType.EndOfContainer });

package/src/tlv/TlvSchema.ts

@@ -10,6 +10,20 @@ import { DataReader } from "../util/DataReader.js";
 import { DataWriter } from "../util/DataWriter.js";
 import { TlvCodec, TlvTag, TlvToPrimitive, TlvTypeLength } from "./TlvCodec.js";
 
+export type TlvEncodingOptions = {
+    /**
+     * When true, the fabricIndex field will be excluded from the TLV encoding for list entries.
+     * This flag must not be set together with the following flag.
+     */
+    forWriteInteraction?: boolean;
+
+    /**
+     * When true, mandatory field validation is skipped when encoding TLV for list entries.
+     * This flag must not be set together with the former flag.
+     */
+    allowMissingFieldsForNonFabricFilteredRead?: boolean;
+};
+
 export abstract class TlvSchema<T> extends Schema<T, ByteArray> implements TlvSchema<T> {
     override decodeInternal(encoded: ByteArray): T {
         return this.decodeTlvInternal(new TlvByteArrayReader(encoded)).value;
@@ -21,9 +35,9 @@ export abstract class TlvSchema<T> extends Schema<T, ByteArray> implements TlvSc
         return writer.toByteArray();
     }
 
-    encodeTlv(value: T, forWriteInteraction = false): TlvStream {
+    encodeTlv(value: T, options?: TlvEncodingOptions): TlvStream {
         const writer = new TlvArrayWriter();
-        this.encodeTlvInternal(writer, value, undefined, forWriteInteraction);
+        this.encodeTlvInternal(writer, value, undefined, options);
         return writer.toTlvArray();
     }
 
@@ -38,7 +52,7 @@ export abstract class TlvSchema<T> extends Schema<T, ByteArray> implements TlvSc
 
     abstract decodeTlvInternalValue(reader: TlvReader, typeLength: TlvTypeLength): T;
 
-    abstract encodeTlvInternal(writer: TlvWriter, value: T, tag?: TlvTag, forWriteInteraction?: boolean): void;
+    abstract encodeTlvInternal(writer: TlvWriter, value: T, tag?: TlvTag, options?: TlvEncodingOptions): void;
 
     injectField(value: T, _fieldId: number, _fieldValue: any, _injectChecker: (fieldValue: any) => boolean): T {
         return value;

package/src/tlv/TlvWrapper.ts

@@ -5,7 +5,7 @@
  */
 
 import { TlvTag, TlvTypeLength } from "./TlvCodec.js";
-import { TlvReader, TlvSchema, TlvWriter } from "./TlvSchema.js";
+import { TlvEncodingOptions, TlvReader, TlvSchema, TlvWriter } from "./TlvSchema.js";
 
 export class TlvWrapper<O, T> extends TlvSchema<O> {
     constructor(
@@ -20,8 +20,8 @@ export class TlvWrapper<O, T> extends TlvSchema<O> {
         return this.unwrap(this.underlyingSchema.decodeTlvInternalValue(reader, typeLength));
     }
 
-    override encodeTlvInternal(writer: TlvWriter, value: O, tag?: TlvTag, forWriteInteraction?: boolean): void {
-        this.underlyingSchema.encodeTlvInternal(writer, this.wrap(value), tag, forWriteInteraction);
+    override encodeTlvInternal(writer: TlvWriter, value: O, tag?: TlvTag, options?: TlvEncodingOptions): void {
+        this.underlyingSchema.encodeTlvInternal(writer, this.wrap(value), tag, options);
     }
 
     override validate(value: O): void {