@matter/types 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/protocol/types/TlvDataVersionFilter.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { TlvUInt32 } from "../../tlv/TlvNumber.js";
+import { TlvField, TlvObject } from "../../tlv/TlvObject.js";
+import { TlvClusterPath } from "./TlvClusterPath.js";
+
+/** @see {@link MatterSpecification.v13.Core}, section 10.6.3 */
+
+export const TlvDataVersionFilter = TlvObject({
+    // DataVersionFilterIB
+    path: TlvField(0, TlvClusterPath),
+    dataVersion: TlvField(1, TlvUInt32),
+});

package/src/protocol/types/TlvEventData.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { EventPriority } from "../../cluster/Cluster.js";
+import { TlvEventNumber } from "../../datatype/EventNumber.js";
+import { TlvAny } from "../../tlv/TlvAny.js";
+import { TlvEnum, TlvPosixMs, TlvSysTimeMS } from "../../tlv/TlvNumber.js";
+import { TlvField, TlvObject, TlvOptionalField } from "../../tlv/TlvObject.js";
+import { TlvEventPath } from "./TlvEventPath.js";
+
+/** @see {@link MatterSpecification.v13.Core}, section 10.6.9 */
+
+export const TlvEventData = TlvObject({
+    // EventDataIB
+    path: TlvField(0, TlvEventPath),
+    eventNumber: TlvField(1, TlvEventNumber),
+    priority: TlvField(2, TlvEnum<EventPriority>()),
+    epochTimestamp: TlvOptionalField(3, TlvPosixMs),
+    systemTimestamp: TlvOptionalField(4, TlvSysTimeMS),
+    deltaEpochTimestamp: TlvOptionalField(5, TlvPosixMs),
+    deltaSystemTimestamp: TlvOptionalField(6, TlvSysTimeMS),
+    data: TlvOptionalField(7, TlvAny),
+});

package/src/protocol/types/TlvEventFilter.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { TlvNodeId } from "../../datatype/NodeId.js";
+import { TlvUInt64 } from "../../tlv/TlvNumber.js";
+import { TlvField, TlvObject, TlvOptionalField } from "../../tlv/TlvObject.js";
+
+/** @see {@link MatterSpecification.v13.Core}, section 10.6.6 */
+
+export const TlvEventFilter = TlvObject({
+    // EventFilterIB
+    nodeId: TlvOptionalField(0, TlvNodeId),
+    eventMin: TlvField(1, TlvUInt64),
+});

package/src/protocol/types/TlvEventPath.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { TlvClusterId } from "../../datatype/ClusterId.js";
+import { TlvEndpointNumber } from "../../datatype/EndpointNumber.js";
+import { TlvEventId } from "../../datatype/EventId.js";
+import { TlvNodeId } from "../../datatype/NodeId.js";
+import { TlvBoolean } from "../../tlv/TlvBoolean.js";
+import { TlvOptionalField, TlvTaggedList } from "../../tlv/TlvObject.js";
+
+/** @see {@link MatterSpecification.v13.Core}, section 10.6.8 */
+
+export const TlvEventPath = TlvTaggedList({
+    // EventPathIB
+    nodeId: TlvOptionalField(0, TlvNodeId),
+    endpointId: TlvOptionalField(1, TlvEndpointNumber),
+    clusterId: TlvOptionalField(2, TlvClusterId),
+    eventId: TlvOptionalField(3, TlvEventId),
+    isUrgent: TlvOptionalField(4, TlvBoolean),
+});

package/src/protocol/types/TlvEventReport.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { TlvObject, TlvOptionalField } from "../../tlv/TlvObject.js";
+import { TlvEventData } from "./TlvEventData.js";
+import { TlvEventStatus } from "./TlvEventStatus.js";
+
+/** @see {@link MatterSpecification.v13.Core}, section 10.6.10 */
+
+export const TlvEventReport = TlvObject({
+    // EventReportIB
+    eventStatus: TlvOptionalField(0, TlvEventStatus),
+    eventData: TlvOptionalField(1, TlvEventData),
+});

package/src/protocol/types/TlvEventStatus.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { TlvField, TlvObject } from "../../tlv/TlvObject.js";
+import { TlvEventPath } from "./TlvEventPath.js";
+import { TlvStatus } from "./TlvStatus.js";
+
+/** @see {@link MatterSpecification.v13.Core}, section 10.6.15 */
+
+export const TlvEventStatus = TlvObject({
+    // EventStatusIB
+    path: TlvField(0, TlvEventPath),
+    status: TlvField(1, TlvStatus),
+});

package/src/protocol/types/TlvInvokeResponseData.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { TlvObject, TlvOptionalField } from "../../tlv/TlvObject.js";
+import { TlvCommandData } from "./TlvCommandData.js";
+import { TlvCommandStatus } from "./TlvCommandStatus.js";
+
+/** @see {@link MatterSpecification.v13.Core}, section 10.6.13 */
+
+export const TlvInvokeResponseData = TlvObject({
+    // InvokeResponseIB
+    command: TlvOptionalField(0, TlvCommandData),
+    status: TlvOptionalField(1, TlvCommandStatus),
+});

package/src/protocol/types/TlvStatus.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { StatusCode } from "../../common/StatusCode.js";
+import { TlvEnum } from "../../tlv/TlvNumber.js";
+import { TlvObject, TlvOptionalField } from "../../tlv/TlvObject.js";
+
+/** @see {@link MatterSpecification.v13.Core}, section 10.6.17 */
+
+export const TlvStatus = TlvObject({
+    // StatusIB
+    status: TlvOptionalField(0, TlvEnum<StatusCode>()), // 8Bit
+    clusterStatus: TlvOptionalField(1, TlvEnum<StatusCode>()),
+});

package/src/protocol/types/WildcardPathFlagsBitmap.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { BitFlag } from "../../schema/BitmapSchema.js";
+
+/** @see {@link MatterSpecification.v13.Core} section XXX */
+
+export const WildcardPathFlagsBitmap = {
+    /** Skip the Root Node endpoint (endpoint 0) during wildcard expansion. */
+    skipRootNode: BitFlag(0),
+
+    /** Skip several large global attributes during wildcard expansion. */
+    skipGlobalAttributes: BitFlag(1),
+
+    /** Skip the AttributeList global attribute during wildcard expansion. */
+    skipAttributeList: BitFlag(2),
+
+    /** Skip the EventList global attribute during wildcard expansion. */
+    skipEventList: BitFlag(3),
+
+    /** Skip the AcceptedCommandList and GeneratedCommandList global attributes during wildcard expansion. */
+    skipCommandLists: BitFlag(4),
+
+    /** Skip any manufacturer-specific clusters or attributes during wildcard expansion. */
+    skipCustomElements: BitFlag(5),
+
+    /** Skip any Fixed (F) quality attributes during wildcard expansion. */
+    skipFixedAttributes: BitFlag(6),
+
+    /** Skip any Changes Omitted (C) quality attributes during wildcard expansion. */
+    skipChangesOmittedAttributes: BitFlag(7),
+
+    /** Skip all clusters with the Diagnostics (K) quality during wildcard expansion. */
+    skipDiagnosticsClusters: BitFlag(8),
+};

package/src/protocol/types/index.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./TlvAttributeData.js";
+export * from "./TlvAttributePath.js";
+export * from "./TlvAttributeReport.js";
+export * from "./TlvAttributeReportData.js";
+export * from "./TlvAttributeStatus.js";
+export * from "./TlvClusterPath.js";
+export * from "./TlvCommandData.js";
+export * from "./TlvCommandPath.js";
+export * from "./TlvDataVersionFilter.js";
+export * from "./TlvEventData.js";
+export * from "./TlvEventFilter.js";
+export * from "./TlvEventPath.js";
+export * from "./TlvEventReport.js";
+export * from "./TlvEventStatus.js";
+export * from "./TlvInvokeResponseData.js";
+export * from "./TlvStatus.js";
+export * from "./WildcardPathFlagsBitmap.js";

package/src/schema/Base38Schema.ts

@@ -0,0 +1,95 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { UnexpectedDataError } from "#general";
+import { Schema } from "./Schema.js";
+
+const BASE38_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ-.";
+
+/** See {@link MatterSpecification.v10.Core} § 5.1.3.1 */
+class Base38Schema extends Schema<Uint8Array, string> {
+    protected encodeInternal(bytes: Uint8Array): string {
+        const length = bytes.length;
+        let offset = 0;
+        const result = new Array<string>();
+        while (offset < length) {
+            const remaining = length - offset;
+            if (remaining > 2) {
+                result.push(this.encodeBase38(bytes[offset++] | (bytes[offset++] << 8) | (bytes[offset++] << 16), 5));
+            } else if (remaining == 2) {
+                result.push(this.encodeBase38(bytes[offset++] | (bytes[offset++] << 8), 4));
+                break;
+            } else {
+                result.push(this.encodeBase38(bytes[offset++], 2));
+                break;
+            }
+        }
+        return result.join("");
+    }
+
+    private encodeBase38(value: number, charCount: number) {
+        let result = "";
+        for (let i = 0; i < charCount; i++) {
+            const remainder = value % 38;
+            result += BASE38_ALPHABET[remainder];
+            value = (value - remainder) / 38;
+        }
+        return result;
+    }
+
+    protected decodeInternal(encoded: string): Uint8Array {
+        const encodedLength = encoded.length;
+        const remainderEncodedLength = encodedLength % 5;
+        let decodeLength = ((encodedLength - remainderEncodedLength) / 5) * 3;
+        switch (remainderEncodedLength) {
+            case 4:
+                decodeLength += 2;
+                break;
+            case 2:
+                decodeLength += 1;
+                break;
+            default:
+                throw new UnexpectedDataError(`Invalid base38 encoded string length: ${encodedLength}`);
+        }
+        const result = new Uint8Array(decodeLength);
+        let decodedOffset = 0;
+        let encodedOffset = 0;
+        while (encodedOffset < encodedLength) {
+            const remaining = encodedLength - encodedOffset;
+            if (remaining > 5) {
+                const value = this.decodeBase38(encoded, encodedOffset, 5);
+                result[decodedOffset++] = value & 0xff;
+                result[decodedOffset++] = (value >> 8) & 0xff;
+                result[decodedOffset++] = (value >> 16) & 0xff;
+                encodedOffset += 5;
+            } else if (remaining == 4) {
+                const value = this.decodeBase38(encoded, encodedOffset, 4);
+                result[decodedOffset++] = value & 0xff;
+                result[decodedOffset++] = (value >> 8) & 0xff;
+                break;
+            } else {
+                const value = this.decodeBase38(encoded, encodedOffset, 2);
+                result[decodedOffset++] = value & 0xff;
+                break;
+            }
+        }
+        return result;
+    }
+
+    private decodeBase38(encoded: string, offset: number, charCount: number) {
+        let result = 0;
+        for (let i = charCount - 1; i >= 0; i--) {
+            const char = encoded[offset + i];
+            // TODO: replace this with a lookup table for performance
+            const code = BASE38_ALPHABET.indexOf(char);
+            if (code === -1) throw new UnexpectedDataError(`Unexpected character ${char} at ${offset + i}`);
+            result = result * 38 + code;
+        }
+        return result;
+    }
+}
+
+export const Base38 = new Base38Schema();

package/src/schema/BitmapSchema.ts

@@ -0,0 +1,232 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { capitalize, Merge, UnexpectedDataError } from "#general";
+import { Schema } from "./Schema.js";
+
+const enum BitRangeType {
+    Flag,
+    Number,
+    Enum,
+}
+
+type BitRange<T, TType extends BitRangeType = BitRangeType> = {
+    type: TType;
+    offset: number;
+    length: number;
+    _type?: T;
+};
+const BitRange = <T, TType extends BitRangeType = BitRangeType>(
+    type: TType,
+    offset: number,
+    length: number,
+): BitRange<T, TType> => ({ type, offset, length });
+
+/** Defines the bit position of a boolean flag. */
+export type BitFlag = BitRange<boolean, BitRangeType.Flag>;
+export const BitFlag = (offset: number): BitFlag => BitRange(BitRangeType.Flag, offset, 1);
+
+/** Defines the bit position and bit length of a numeric value. */
+export type BitField = BitRange<number, BitRangeType.Number>;
+export const BitField = (offset: number, length: number): BitField => BitRange(BitRangeType.Number, offset, length);
+
+/** Defines the bit position and bit length of an enum flag. */
+export type BitFieldEnum<E extends number> = BitRange<E, BitRangeType.Enum>;
+export const BitFieldEnum = <E extends number>(offset: number, length: number): BitFieldEnum<E> =>
+    BitRange(BitRangeType.Enum, offset, length);
+
+export type BitSchema = { [key: string]: BitFlag | BitField | BitFieldEnum<any> };
+export type TypeFromBitSchema<T extends BitSchema> = {
+    [K in keyof T]: T[K] extends BitFieldEnum<infer E> ? E : T[K] extends BitField ? number : boolean;
+};
+export type TypeFromPartialBitSchema<T extends BitSchema> = {
+    [K in keyof T]?: T[K] extends BitFieldEnum<infer E> ? E : T[K] extends BitField ? number : boolean;
+};
+export type TypeFromBitmapSchema<S extends Schema<any, any>> = S extends Schema<infer T, any> ? T : never;
+
+type MaskFromBitSchema<T extends BitSchema> = { [K in keyof T]: number };
+type MaskOffsetFromBitSchema<T extends BitSchema> = {
+    [K in keyof T]: { mask: number; byteOffset: number; bitOffset: number };
+};
+
+export class BitmapSchemaInternal<T extends BitSchema> extends Schema<TypeFromBitSchema<T>, number> {
+    private readonly masks: MaskFromBitSchema<T>;
+
+    constructor(private readonly bitSchemas: T) {
+        super();
+
+        const masks = <MaskFromBitSchema<T>>{};
+        for (const name in this.bitSchemas) {
+            const { offset, length } = this.bitSchemas[name];
+            masks[name] = ((1 << length) - 1) << offset;
+        }
+        this.masks = masks;
+        // TODO: validate that bitSchemas is coherent
+    }
+
+    /**
+     * Allow to use a fully defined Bitmap schema as input, but also allow one where only the entries of bits set are
+     * provided, rest is unset.
+     */
+    override encode(value: TypeFromPartialBitSchema<T>) {
+        return super.encode(value as TypeFromBitSchema<T>);
+    }
+
+    override encodeInternal(value: TypeFromPartialBitSchema<T>) {
+        let result = 0;
+        for (const name in this.bitSchemas) {
+            const { type, offset } = this.bitSchemas[name];
+            switch (type) {
+                case BitRangeType.Flag:
+                    if (value[name]) result |= this.masks[name];
+                    break;
+                case BitRangeType.Enum:
+                case BitRangeType.Number:
+                    result |= (value[name] as number) << offset;
+            }
+        }
+        return result;
+    }
+
+    override decodeInternal(bitmap: number) {
+        const result = {} as any;
+        for (const name in this.bitSchemas) {
+            const { type, offset } = this.bitSchemas[name];
+            const mask = this.masks[name];
+            if (type === BitRangeType.Flag) {
+                result[name] = (bitmap & mask) !== 0;
+            } else {
+                result[name] = (bitmap & mask) >> offset;
+            }
+        }
+        return result as TypeFromBitSchema<T>;
+    }
+}
+
+export class ByteArrayBitmapSchemaInternal<T extends BitSchema> extends Schema<TypeFromBitSchema<T>, Uint8Array> {
+    private readonly byteArrayLength: number;
+    private readonly maskOffset: MaskOffsetFromBitSchema<T>;
+
+    constructor(private readonly bitSchemas: T) {
+        super();
+
+        let maxBitLength = 0;
+        const maskOffset = <MaskOffsetFromBitSchema<T>>{};
+        for (const name in this.bitSchemas) {
+            const { type, offset, length } = this.bitSchemas[name];
+            const bitOffset = offset % 8;
+            const byteOffset = (offset - bitOffset) / 8;
+            let mask: number;
+            if (type === BitRangeType.Flag) {
+                mask = 1 << bitOffset;
+            } else {
+                // Do not shift number mask, they might go beyond 2^32
+                mask = (1 << length) - 1;
+            }
+            maskOffset[name] = { bitOffset, byteOffset, mask };
+            maxBitLength = Math.max(maxBitLength, offset + length);
+        }
+        this.byteArrayLength = Math.ceil(maxBitLength / 8);
+        this.maskOffset = maskOffset;
+    }
+
+    override encodeInternal(value: TypeFromBitSchema<T>) {
+        const result = new Uint8Array(this.byteArrayLength);
+        for (const name in this.bitSchemas) {
+            const { type } = this.bitSchemas[name];
+            let { bitOffset, byteOffset } = this.maskOffset[name];
+            const { mask } = this.maskOffset[name];
+            switch (type) {
+                case BitRangeType.Flag:
+                    if (value[name]) result[byteOffset] |= mask;
+                    break;
+                case BitRangeType.Enum:
+                case BitRangeType.Number: {
+                    let numValue = (value[name] as number) & mask;
+                    while (numValue !== 0) {
+                        result[byteOffset++] |= (numValue << bitOffset) & 0xff;
+                        const bitWritten = 8 - bitOffset;
+                        bitOffset = 0;
+                        numValue = numValue >> bitWritten;
+                    }
+                }
+            }
+        }
+        return result;
+    }
+
+    override decodeInternal(bitmap: Uint8Array) {
+        if (bitmap.length !== this.byteArrayLength)
+            throw new UnexpectedDataError(`Unexpected length: ${bitmap.length}. Expected ${this.byteArrayLength}`);
+        const result = {} as any;
+        for (const name in this.bitSchemas) {
+            const { type } = this.bitSchemas[name];
+            let { mask, bitOffset, byteOffset } = this.maskOffset[name];
+            if (type === BitRangeType.Flag) {
+                result[name] = (bitmap[byteOffset] & mask) !== 0;
+            } else {
+                let value = 0;
+                let valueBitOffset = 0;
+                while (mask !== 0) {
+                    value |= ((bitmap[byteOffset++] >> bitOffset) & mask) << valueBitOffset;
+                    const bitRead = 8 - bitOffset;
+                    bitOffset = 0;
+                    valueBitOffset += bitRead;
+                    mask = mask >> bitRead;
+                }
+                result[name] = value;
+            }
+        }
+        return result as TypeFromBitSchema<T>;
+    }
+}
+
+/** Create a partial bitmap from a flag sequence */
+export type FlagsToBitmap<T extends string[]> = {
+    [name in Uncapitalize<T[number]>]: true;
+};
+
+/** Create a type with specified bit flags set */
+export type BitFlags<T extends BitSchema, F extends Capitalize<Extract<keyof T, string>>[]> = Merge<
+    { [key in keyof T]: false },
+    FlagsToBitmap<F>
+>;
+
+/** Create a bitmap schema with a named subset of flags set */
+export function BitFlags<T extends BitSchema, F extends Capitalize<Extract<keyof T, string>>[]>(
+    bitSchemas: T,
+    ...flags: [...F]
+) {
+    return Object.fromEntries(
+        Object.keys(bitSchemas).map(name => [
+            name,
+            !(flags.indexOf(capitalize(name as Extract<keyof T, string>)) == -1),
+        ]),
+    ) as BitFlags<T, F>;
+}
+
+/** Create a full bitmap schema from a partial bitmap schema */
+export function BitsFromPartial<S extends BitSchema, P extends TypeFromPartialBitSchema<S>>(schema: S, bits: P) {
+    const result = {} as { [key: string]: boolean | number };
+
+    for (const k in schema) {
+        const value = bits[k];
+        if (value !== undefined) {
+            result[k] = value;
+        } else {
+            result[k] = 0;
+        }
+    }
+
+    return result as TypeFromBitSchema<S>;
+}
+
+/** Declares a bitmap schema by indicating the bit position and their names. */
+export const BitmapSchema = <T extends BitSchema>(bitSchemas: T) => new BitmapSchemaInternal(bitSchemas);
+
+/** Declares a bitmap schema backed by a ByteArray by indicating the bit position and their names. */
+export const ByteArrayBitmapSchema = <T extends BitSchema>(bitSchemas: T) =>
+    new ByteArrayBitmapSchemaInternal(bitSchemas);