@project-chip/matter.js 0.0.0 → 0.0.1

package/README.md

@@ -1,2 +1,13 @@
 # matter.js
+
+![experimental](https://img.shields.io/badge/status-Experimental-red) [![license](https://img.shields.io/badge/license-Apache2-green.svg)](https://raw.githubusercontent.com/project-chip/matter.js/master/LICENSE)
+
 Implementation of Matter protocol in typescript with no native dependencies (and very limited dependencies).
+
+## Tests
+
+Run tests in node.js: npm run test
+
+Run tests in the browser: npm run test-web
+
+test-web will create a /coverage directory conatining the test code coverage

package/dist/matter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from "./schema/BitmapSchema.js";
+export * from "./schema/Schema.js";
+export * from "./spec/Specifications.js";
+export * from "./util/Number.js";
+export * from "./util/ByteArray.js";
+export * from "./util/DataReader.js";
+export * from "./util/DataWriter.js";
+export * from "./tlv/TlvAny.js";
+export * from "./tlv/TlvArray.js";
+export * from "./tlv/TlvBoolean.js";
+export * from "./tlv/TlvSchema.js";
+export * from "./tlv/TlvNullable.js";
+export * from "./tlv/TlvObject.js";
+export * from "./tlv/TlvString.js";
+export * from "./tlv/TlvNumber.js";
+export * from "./tlv/TlvVoid.js";
+export * from "./tlv/TlvWrapper.js";

package/dist/matter.js

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from "./schema/BitmapSchema.js";
+export * from "./schema/Schema.js";
+export * from "./spec/Specifications.js";
+export * from "./util/Number.js";
+export * from "./util/ByteArray.js";
+export * from "./util/DataReader.js";
+export * from "./util/DataWriter.js";
+export * from "./tlv/TlvAny.js";
+export * from "./tlv/TlvArray.js";
+export * from "./tlv/TlvBoolean.js";
+export * from "./tlv/TlvSchema.js";
+export * from "./tlv/TlvNullable.js";
+export * from "./tlv/TlvObject.js";
+export * from "./tlv/TlvString.js";
+export * from "./tlv/TlvNumber.js";
+export * from "./tlv/TlvVoid.js";
+export * from "./tlv/TlvWrapper.js";

package/dist/schema/BitmapSchema.d.ts

@@ -1,21 +1,47 @@
-export interface BitPosition {
-    position: number;
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Schema } from "./Schema.js";
+declare const enum BitRangeType {
+    Flag = 0,
+    Number = 1,
+    Enum = 2
 }
-export declare const BitPosition: (position: number) => {
-    position: number;
+type BitRange<T> = {
+    type: BitRangeType;
+    offset: number;
+    mask: number;
 };
-declare type BitSchema = {
-    [key: string]: BitPosition;
-};
-declare type TypeFromBitSchema<T extends BitSchema> = {
-    [K in keyof T]: boolean;
+declare const BitRange: <T>(type: BitRangeType, offset: number, length: number) => BitRange<T>;
+/** Defines the bit position of a boolean flag. */
+export interface BitFlag extends BitRange<boolean> {
+    type: BitRangeType.Flag;
+}
+export declare const BitFlag: (offset: number) => BitFlag;
+/** Defines the bit position and bit length of a numeric value. */
+export interface BitField extends BitRange<number> {
+    type: BitRangeType.Number;
+}
+export declare const BitField: (offset: number, length: number) => BitField;
+/** Defines the bit position and bit length of an enum flag. */
+export interface BitFieldEnum<E extends number> extends BitRange<E> {
+    type: BitRangeType.Enum;
+}
+export declare const BitFieldEnum: <E extends number>(offset: number, length: number) => BitFieldEnum<E>;
+export type BitSchema = {
+    [key: string]: BitFlag | BitField | BitFieldEnum<any>;
 };
-export declare const BitmapSchema: (bitSchemas: BitSchema) => {
-    readonly bitSchemas: BitSchema;
-    encodeInternal(value: TypeFromBitSchema<BitSchema>): number;
-    decodeInternal(bitmap: number): TypeFromBitSchema<BitSchema>;
-    encode(value: TypeFromBitSchema<BitSchema>): number;
-    decode(encoded: number): TypeFromBitSchema<BitSchema>;
-    validate(value: TypeFromBitSchema<BitSchema>): void;
+export type TypeFromBitSchema<T extends BitSchema> = {
+    [K in keyof T]: T[K] extends BitFieldEnum<infer E> ? E : (T[K] extends BitField ? number : boolean);
 };
+declare class BitmapSchemaInternal<T extends BitSchema> extends Schema<TypeFromBitSchema<T>, number> {
+    readonly bitSchemas: T;
+    constructor(bitSchemas: T);
+    encodeInternal(value: TypeFromBitSchema<T>): number;
+    decodeInternal(bitmap: number): TypeFromBitSchema<T>;
+}
+/** Declares a bitmap schema by indicating the bit position and their names. */
+export declare const BitmapSchema: <T extends BitSchema>(bitSchemas: T) => BitmapSchemaInternal<T>;
 export {};

package/dist/schema/BitmapSchema.js

@@ -1,28 +1,48 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.BitmapSchema = exports.BitPosition = void 0;
-const Schema_1 = require("./Schema");
-const BitPosition = (position) => ({ position });
-exports.BitPosition = BitPosition;
-const BitmapSchema = (bitSchemas) => new class extends Schema_1.Schema {
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Schema } from "./Schema.js";
+const BitRange = (type, offset, length) => ({ type, mask: ((1 << length) - 1) << offset, offset });
+export const BitFlag = (offset) => BitRange(0 /* BitRangeType.Flag */, offset, 1);
+export const BitField = (offset, length) => BitRange(1 /* BitRangeType.Number */, offset, length);
+export const BitFieldEnum = (offset, length) => BitRange(2 /* BitRangeType.Enum */, offset, length);
+class BitmapSchemaInternal extends Schema {
     constructor(bitSchemas) {
         super();
         this.bitSchemas = bitSchemas;
+        // TODO: validate that bitSchemas is coherent
     }
     encodeInternal(value) {
         let result = 0;
         for (const name in this.bitSchemas) {
-            if (value[name])
-                result |= 1 << this.bitSchemas[name].position;
+            const { type, offset, mask } = this.bitSchemas[name];
+            switch (type) {
+                case 0 /* BitRangeType.Flag */:
+                    if (value[name])
+                        result |= mask;
+                    break;
+                case 2 /* BitRangeType.Enum */:
+                case 1 /* BitRangeType.Number */:
+                    result |= value[name] << offset;
+            }
         }
         return result;
     }
     decodeInternal(bitmap) {
         const result = {};
         for (const name in this.bitSchemas) {
-            result[name] = (bitmap & (1 << this.bitSchemas[name].position)) !== 0;
+            const { type, offset, mask } = this.bitSchemas[name];
+            if (type === 0 /* BitRangeType.Flag */) {
+                result[name] = (bitmap & mask) !== 0;
+            }
+            else {
+                result[name] = (bitmap & mask) >> offset;
+            }
         }
         return result;
     }
-}(bitSchemas);
-exports.BitmapSchema = BitmapSchema;
+}
+/** Declares a bitmap schema by indicating the bit position and their names. */
+export const BitmapSchema = (bitSchemas) => new BitmapSchemaInternal(bitSchemas);

package/dist/schema/Schema.d.ts

@@ -1,7 +1,16 @@
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Define a schema to encode / decode convert type T to type E. */
 export declare abstract class Schema<T, E> {
+    /** Encodes the value using the schema. */
     encode(value: T): E;
+    /** Decodes the encoded data using the schema. */
     decode(encoded: E): T;
     protected abstract encodeInternal(value: T): E;
     protected abstract decodeInternal(encoded: E): T;
-    validate(value: T): void;
+    /** Optional validator that can be used to enforce constraints on the data before encoding / after decoding. */
+    validate(_value: T): void;
 }

package/dist/schema/Schema.js

@@ -1,17 +1,22 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Schema = void 0;
-class Schema {
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Define a schema to encode / decode convert type T to type E. */
+export class Schema {
+    /** Encodes the value using the schema. */
     encode(value) {
         this.validate(value);
         return this.encodeInternal(value);
     }
+    /** Decodes the encoded data using the schema. */
     decode(encoded) {
         const result = this.decodeInternal(encoded);
         this.validate(result);
         return result;
     }
-    validate(value) {
+    /** Optional validator that can be used to enforce constraints on the data before encoding / after decoding. */
+    validate(_value) {
     }
 }
-exports.Schema = Schema;

package/dist/spec/Specifications.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** {@link https://csa-iot.org/developer-resource/specifications-download-request/ Matter Core Specification 1.0} */
+export interface MatterCoreSpecificationV1_0 {
+}
+/** {@link https://csa-iot.org/developer-resource/specifications-download-request/ Matter Application Cluster Specification 1.0} */
+export interface MatterApplicationClusterSpecificationV1_0 {
+}
+/** {@link https://csa-iot.org/developer-resource/specifications-download-request/ Matter Device Library Specification 1.0} */
+export interface MatterDeviceLibrarySpecificationV1_0 {
+}

package/dist/spec/Specifications.js

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/tlv/TlvAny.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { TlvTag, TlvTypeLength } from "./TlvCodec.js";
+import { TlvReader, TlvSchema, TlvStream, TlvWriter } from "./TlvSchema.js";
+export declare class AnySchema extends TlvSchema<TlvStream> {
+    encodeTlvInternal(writer: TlvWriter, tlvStream: TlvStream, tagAssigned?: TlvTag | undefined): void;
+    decodeTlvInternalValue(reader: TlvReader, typeLength: TlvTypeLength): TlvStream;
+    decodeTlvValueRec(reader: TlvReader, typeLength: TlvTypeLength, tlvStream: TlvStream, tag?: TlvTag): TlvStream;
+}
+export declare const TlvAny: AnySchema;

package/dist/tlv/TlvAny.js

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { TlvSchema } from "./TlvSchema.js";
+export class AnySchema extends TlvSchema {
+    encodeTlvInternal(writer, tlvStream, tagAssigned) {
+        tlvStream.forEach(({ tag, typeLength, value }) => {
+            if (tagAssigned !== undefined) {
+                // Assign the tag to the 1st TLV element in the stream
+                tag = tagAssigned;
+                tagAssigned = undefined;
+            }
+            switch (typeLength.type) {
+                case 20 /* TlvType.Null */:
+                case 8 /* TlvType.Boolean */:
+                case 22 /* TlvType.Array */:
+                case 21 /* TlvType.Structure */:
+                case 23 /* TlvType.List */:
+                case 24 /* TlvType.EndOfContainer */:
+                    writer.writeTag(typeLength, tagAssigned !== null && tagAssigned !== void 0 ? tagAssigned : tag);
+                    break;
+                case 4 /* TlvType.UnsignedInt */:
+                case 0 /* TlvType.SignedInt */:
+                case 10 /* TlvType.Float */:
+                case 12 /* TlvType.Utf8String */:
+                case 16 /* TlvType.ByteString */:
+                    writer.writeTag(typeLength, tagAssigned !== null && tagAssigned !== void 0 ? tagAssigned : tag);
+                    writer.writePrimitive(typeLength, value);
+                    break;
+            }
+        });
+    }
+    decodeTlvInternalValue(reader, typeLength) {
+        return this.decodeTlvValueRec(reader, typeLength, new Array());
+    }
+    decodeTlvValueRec(reader, typeLength, tlvStream, tag) {
+        switch (typeLength.type) {
+            case 20 /* TlvType.Null */:
+            case 8 /* TlvType.Boolean */:
+            case 4 /* TlvType.UnsignedInt */:
+            case 0 /* TlvType.SignedInt */:
+            case 10 /* TlvType.Float */:
+            case 12 /* TlvType.Utf8String */:
+            case 16 /* TlvType.ByteString */:
+                tlvStream.push({ tag, typeLength, value: reader.readPrimitive(typeLength) });
+                break;
+            case 22 /* TlvType.Array */:
+            case 21 /* TlvType.Structure */:
+            case 23 /* TlvType.List */:
+                tlvStream.push({ tag, typeLength });
+                while (true) {
+                    const { tag: elementTag, typeLength: typeLengthElement } = reader.readTagType();
+                    this.decodeTlvValueRec(reader, typeLengthElement, tlvStream, elementTag);
+                    if (typeLengthElement.type === 24 /* TlvType.EndOfContainer */)
+                        break;
+                }
+                break;
+            case 24 /* TlvType.EndOfContainer */:
+                tlvStream.push({ tag, typeLength });
+                break;
+        }
+        return tlvStream;
+    }
+}
+export const TlvAny = new AnySchema();

package/dist/tlv/TlvArray.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { TlvTag, TlvTypeLength } from "./TlvCodec.js";
+import { TlvReader, TlvSchema, TlvWriter } from "./TlvSchema.js";
+type LengthConstraints = {
+    minLength?: number;
+    maxLength?: number;
+    length?: number;
+};
+/**
+ * Schema to encode an array or string in TLV.
+ *
+ * @see {@link MatterCoreSpecificationV1_0} § A.11.2 and A.11.4
+ */
+export declare class ArraySchema<T> extends TlvSchema<T[]> {
+    private readonly elementSchema;
+    private readonly minLength;
+    private readonly maxLength;
+    constructor(elementSchema: TlvSchema<T>, minLength?: number, maxLength?: number);
+    encodeTlvInternal(writer: TlvWriter, value: T[], tag?: TlvTag): void;
+    decodeTlvInternalValue(reader: TlvReader, typeLength: TlvTypeLength): T[];
+    validate({ length }: T[]): void;
+}
+/** Array TLV schema. */
+export declare const TlvArray: <T>(elementSchema: TlvSchema<T>, { minLength, maxLength, length }?: LengthConstraints) => ArraySchema<T>;
+export {};

package/dist/tlv/TlvArray.js

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { TlvSchema } from "./TlvSchema.js";
+/**
+ * Schema to encode an array or string in TLV.
+ *
+ * @see {@link MatterCoreSpecificationV1_0} § A.11.2 and A.11.4
+ */
+export class ArraySchema extends TlvSchema {
+    constructor(elementSchema, minLength = 0, maxLength = 1024) {
+        super();
+        this.elementSchema = elementSchema;
+        this.minLength = minLength;
+        this.maxLength = maxLength;
+    }
+    encodeTlvInternal(writer, value, tag = {}) {
+        writer.writeTag({ type: 22 /* TlvType.Array */ }, tag);
+        value.forEach(element => this.elementSchema.encodeTlvInternal(writer, element));
+        writer.writeTag({ type: 24 /* TlvType.EndOfContainer */ });
+    }
+    decodeTlvInternalValue(reader, typeLength) {
+        if (typeLength.type !== 22 /* TlvType.Array */)
+            throw new Error(`Unexpected type ${typeLength.type}.`);
+        const result = new Array();
+        while (true) {
+            const { tag: elementTag, typeLength: elementTypeLength } = reader.readTagType();
+            if (elementTag !== undefined)
+                throw new Error("Array element tags should be anonymous.");
+            if (elementTypeLength.type === 24 /* TlvType.EndOfContainer */)
+                break;
+            result.push(this.elementSchema.decodeTlvInternalValue(reader, elementTypeLength));
+        }
+        this.validate(result);
+        return result;
+    }
+    validate({ length }) {
+        if (length > this.maxLength)
+            throw new Error(`Array is too long: ${length}, max ${this.maxLength}.`);
+        if (length < this.minLength)
+            throw new Error(`Array is too short: ${length}, min ${this.minLength}.`);
+    }
+}
+/** Array TLV schema. */
+export const TlvArray = (elementSchema, { minLength, maxLength, length } = {}) => new ArraySchema(elementSchema, length !== null && length !== void 0 ? length : minLength, length !== null && length !== void 0 ? length : maxLength);

package/dist/tlv/TlvBoolean.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { TlvTag, TlvTypeLength } from "./TlvCodec.js";
+import { TlvReader, TlvSchema, TlvWriter } from "./TlvSchema.js";
+/**
+ * Schema to encode a boolean in TLV.
+ *
+ * @see {@link MatterCoreSpecificationV1_0} § A.11.3
+ */
+export declare class BooleanSchema extends TlvSchema<boolean> {
+    encodeTlvInternal(writer: TlvWriter, value: boolean, tag?: TlvTag): void;
+    decodeTlvInternalValue(_reader: TlvReader, typeLength: TlvTypeLength): boolean;
+}
+/** Boolean TLV schema. */
+export declare const TlvBoolean: BooleanSchema;

package/dist/tlv/TlvBoolean.js

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { TlvSchema } from "./TlvSchema.js";
+/**
+ * Schema to encode a boolean in TLV.
+ *
+ * @see {@link MatterCoreSpecificationV1_0} § A.11.3
+ */
+export class BooleanSchema extends TlvSchema {
+    encodeTlvInternal(writer, value, tag = {}) {
+        writer.writeTag({ type: 8 /* TlvType.Boolean */, value }, tag);
+    }
+    decodeTlvInternalValue(_reader, typeLength) {
+        if (typeLength.type !== 8 /* TlvType.Boolean */)
+            throw new Error(`Unexpected type ${typeLength.type}.`);
+        return typeLength.value;
+    }
+}
+/** Boolean TLV schema. */
+export const TlvBoolean = new BooleanSchema();

package/dist/tlv/TlvCodec.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * Copyright 2022 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ByteArray, Endian } from "../util/ByteArray.js";
+import { DataReader } from "../util/DataReader.js";
+import { DataWriter } from "../util/DataWriter.js";
+/**
+ * TLV element types.
+ *
+ * @see {@link MatterCoreSpecificationV1_0} § A.7.1
+ */
+export declare const enum TlvType {
+    SignedInt = 0,
+    UnsignedInt = 4,
+    Boolean = 8,
+    Float = 10,
+    Utf8String = 12,
+    ByteString = 16,
+    Null = 20,
+    Structure = 21,
+    Array = 22,
+    List = 23,
+    EndOfContainer = 24
+}
+/** Byte length of the encoded value or length. */
+export declare const enum TlvLength {
+    OneByte = 0,
+    TwoBytes = 1,
+    FourBytes = 2,
+    EightBytes = 3
+}
+/** Type and length or value, when applicable. */
+export type TlvTypeLength = {
+    type: TlvType.SignedInt;
+    length: TlvLength;
+} | {
+    type: TlvType.UnsignedInt;
+    length: TlvLength;
+} | {
+    type: TlvType.Boolean;
+    value: boolean;
+} | {
+    type: TlvType.Float;
+    length: TlvLength.FourBytes | TlvLength.EightBytes;
+} | {
+    type: TlvType.Utf8String;
+    length: TlvLength;
+} | {
+    type: TlvType.ByteString;
+    length: TlvLength;
+} | {
+    type: TlvType.Null;
+} | {
+    type: TlvType.Structure;
+} | {
+    type: TlvType.Array;
+} | {
+    type: TlvType.List;
+} | {
+    type: TlvType.EndOfContainer;
+};
+/** Converts {@link TlvType} to the js primitive type.  */
+export type TlvToPrimitive = {
+    [TlvType.SignedInt]: bigint | number;
+    [TlvType.UnsignedInt]: bigint | number;
+    [TlvType.Boolean]: never;
+    [TlvType.Float]: number;
+    [TlvType.Utf8String]: string;
+    [TlvType.ByteString]: ByteArray;
+    [TlvType.Null]: null;
+    [TlvType.Structure]: never;
+    [TlvType.Array]: never;
+    [TlvType.List]: never;
+    [TlvType.EndOfContainer]: never;
+};
+/** {@link MatterCoreSpecificationV1_0} § A.2 */
+export type TlvTag = {
+    profile?: number;
+    id?: number;
+};
+export declare class TlvCodec {
+    static getUIntTlvLength(value: number | bigint): TlvLength;
+    static getIntTlvLength(value: number | bigint): TlvLength;
+    /** @see {@link MatterCoreSpecificationV1_0} § A.7 */
+    static readTagType(reader: DataReader<Endian.Little>): {
+        tag?: TlvTag;
+        typeLength: TlvTypeLength;
+    };
+    private static readTag;
+    private static parseTypeLength;
+    static readPrimitive<T extends TlvTypeLength, V = TlvToPrimitive[T["type"]]>(reader: DataReader<Endian.Little>, typeLength: T): V;
+    /** @see {@link MatterCoreSpecificationV1_0} § A.7 & A.8 */
+    static writeTag(writer: DataWriter<Endian.Little>, typeLengthValue: TlvTypeLength, { profile, id }?: TlvTag): void;
+    static writePrimitive<T extends TlvTypeLength>(writer: DataWriter<Endian.Little>, typeLength: T, value: TlvToPrimitive[T["type"]]): void;
+    private static writeUInt;
+}