@matter/main

@matter/main

Implementation of Matter protocol in typescript with no native dependencies (and very limited dependencies).

This is a convenient single-dependency for applications build on matter.js and have automatic registrations for Node.js and react-native as platforms.

This package supports all Node.js LTS versions starting with 18.x (when Node.js is used).

The following features are abstracted away to allow to be implemented environment specific:

• Network (UDP/MDNS)
• Crypto
• Storage
• Date/Timer
• Logger (Default uses "console")
• Environment (Process and Configuration handling)

Exported functionality

[!IMPORTANT] All exports here are for the current API. Legacy Cluster implementations are only exported via @project-chip/matter.js!

This library exports the Matter protocol functionality as well as some helper functions as named exports:

Export	Description
@matter/main	Re-Exports all functionality from @matter/general, @matter/node, Environment class, Matter model class and the datatypes from @matter/types
@matter/main/behaviors	Exports Behavior classes as framework to implement all relevant Logic for clusters and internal logic. Contains auto-generated class structures and also Cluster default implementations.
@matter/main/behaviors/*	Exports Behavior classes as framework to implement all relevant Logic for clusters and internal logic. Contains auto-generated class structures and also Cluster default implementations as cluster-name export
@matter/main/clusters	Exports all Matter Cluster definitions
@matter/main/clusters/*	Exports Matter Cluster definitions as cluster-name export
@matter/main/devices	Exports Matter Device type classes
@matter/main/devices/*	Exports Matter Device type classes as cluster-name export
@matter/main/endpoints	Exports Matter Endpoint structure classes
@matter/main/endpoints/*	Exports Matter Endpoint structure classes as cluster-name export
@matter/main/model	Exports a JavaScript version of the Matter data model. Re-exports @matter/model package.
@matter/main/node	Exports the matter node specific classes. Re-exports @matter/node package.
@matter/main/protocol	Exports Basic Matter protocol functionality. Re-exports @matter/protocol package.
@matter/main/types	Exports all Types (includes Clusters and Matter datatypes and matter.js own datatypes. Re-exports @matter/types package.

Both exports and the typings are exported as CommonJS and ES6 modules.

For more details please refer to the API Documentation.

Typescript note

To have Typescript and your IDE know all the relevant exported functionality you need to use the following in your tsconfig.json:

{
    compilerOptions: {
        "target": "es2022", // Matter.js most likely won't work with older versions of ES
        moduleResolution: "node16", // Required to support package.json exports
        module: "node16", // Required to make sure all imports are js
    },
}

Additionally, we recommend using "strictNullChecks": true or better for code quality "strict": true to make sure that all types are correctly determined.

Building

• npm run build: Build all code and create CommonJS and ES6 variants in dist directory. This will built incrementally and only build the changed files.
• npm run build-clean: Clean the dist directory and build all code from scratch

Tests

• npm run test-node: Run tests in node.js
• npm run test-web: Run tests in the browser
• npm run test: Run all tests

test-web will create a /coverage directory containing the test code coverage

Changelog

0.11.9 (2024-12-11)

• @matter/node

  • Enhancement: Enhances the number assertations to only allow finite numbers
  • Enhancement: WindowCovering: Adds an internal property to disable the operational state and value management by the default implementation to allow device to handle this themselves
  • BREAKING: WindowCovering: supportsCalibration is moved from state property to an internal property
  • Fix: ColorControl: Do not try to convert color mode details if they are not defined
  • Fix: ColorControl: colorMode attribute needs to be defined if HS feature is not used because the default value 0 is else invalid

• @matter/protocol

  • Fix: Also retry next discovered address when a Channel establishment error for PASE occurs
  • Fix: Optimizes MDNS cache handling to prevent too early cache invalidation

• @matter/types

  • Enhancement: Deprecated fields are now also usable and just flagged as deprecated on generated code
  • Enhancement: Removes default value from attribute ColorMode of ColorControl cluster because feature specific enum value was used

• @project-chip/matter.js

  • Feature: Introduces PairedNode#triggerReconnect() method to trigger a reconnection
  • Enhancement: Considers a node in reconnection state that should be decommissioned as already factory reset
  • Enhancement: Optimizes reconnection handling in Controller API
  • Fix: Do not try to convert color mode details if they are not defined
  • Fix: Clusters generated for extensions of base clusters such as Alarm Base and Mode Base now include full details of extended types; in particular extended enums such as Mode Tag were previously insufficiently defined
  • BREAKING: In ContentLauncher cluster ParameterEnum is renamed to Parameter and Parameter is renamed to ParameterStruct

• @matter/model

  • Feature: New Scope component analyzes scope of a model, caches analysis results, and implements algorithms that require analysis to perform efficiently
  • Enhancement: Models that define datatypes now inherit from common ScopeModel base class
  • Fix: Extended enums and other types now report the full set of members via Scope#membersOf
  • BREAKING: ClusterModel and ValueModel properties members, activeMembers and conformantMembers are removed; use Scope#membersOf instead