@matter/general 0.16.0-alpha.0-20250814-484abe647 → 0.16.0-alpha.0-20250815-ac9fd6eb0

package/src/net/NetInterface.ts

@@ -6,6 +6,7 @@
 
 import { Environment } from "#environment/Environment.js";
 import { Environmental } from "#environment/Environmental.js";
+import { Bytes } from "#util/Bytes.js";
 import { Channel } from "./Channel.js";
 import { ServerAddress } from "./ServerAddress.js";
 import { TransportInterface, TransportInterfaceSet } from "./TransportInterface.js";
@@ -14,7 +15,7 @@ import { TransportInterface, TransportInterfaceSet } from "./TransportInterface.
  * A Network interface enhances a TransportInterface with the ability to open a channel to a remote server.
  */
 export interface NetInterface extends TransportInterface {
-    openChannel(address: ServerAddress): Promise<Channel<Uint8Array>>;
+    openChannel(address: ServerAddress): Promise<Channel<Bytes>>;
 }
 
 export function isNetworkInterface(obj: TransportInterface | NetInterface): obj is NetInterface {

package/src/net/TransportInterface.ts

@@ -6,6 +6,7 @@
 
 import { Environment } from "#environment/Environment.js";
 import { Environmental } from "#environment/Environmental.js";
+import { Bytes } from "#util/Bytes.js";
 import { BasicSet } from "#util/Set.js";
 import { Channel, ChannelType } from "./Channel.js";
 
@@ -14,7 +15,7 @@ import { Channel, ChannelType } from "./Channel.js";
  * It cannot open new connections.
  */
 export interface TransportInterface {
-    onData(listener: (socket: Channel<Uint8Array>, data: Uint8Array) => void): TransportInterface.Listener;
+    onData(listener: (socket: Channel<Bytes>, data: Bytes) => void): TransportInterface.Listener;
     close(): Promise<void>;
     supports(type: ChannelType, address?: string): boolean;
 }

package/src/net/UdpChannel.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { MaybePromise } from "#util/index.js";
+import { Bytes, MaybePromise } from "#util/index.js";
 import { ChannelType } from "./Channel.js";
 import { TransportInterface } from "./TransportInterface.js";
 
@@ -25,7 +25,7 @@ export interface UdpChannel {
     addMembership(address: string): MaybePromise<void>;
     dropMembership(address: string): MaybePromise<void>;
     onData(listener: UdpChannel.Callback): TransportInterface.Listener;
-    send(host: string, port: number, data: Uint8Array): Promise<void>;
+    send(host: string, port: number, data: Bytes): Promise<void>;
     close(): Promise<void>;
     get port(): number;
     supports(type: ChannelType, address?: string): boolean;
@@ -33,6 +33,6 @@ export interface UdpChannel {
 
 export namespace UdpChannel {
     export interface Callback {
-        (netInterface: string | undefined, peerAddress: string, peerPort: number, data: Uint8Array): void;
+        (netInterface: string | undefined, peerAddress: string, peerPort: number, data: Bytes): void;
     }
 }

package/src/net/UdpInterface.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Bytes } from "#util/Bytes.js";
 import { Channel, ChannelType, IpNetworkChannel } from "./Channel.js";
 import { NetInterface } from "./NetInterface.js";
 import { Network, NetworkError } from "./Network.js";
@@ -40,7 +41,7 @@ export class UdpInterface implements NetInterface {
         return Promise.resolve(new UdpConnection(this.#server, ip, port));
     }
 
-    onData(listener: (channel: Channel<Uint8Array>, messageBytes: Uint8Array) => void): TransportInterface.Listener {
+    onData(listener: (channel: Channel<Bytes>, messageBytes: Bytes) => void): TransportInterface.Listener {
         return this.#server.onData((_netInterface, peerHost, peerPort, data) =>
             listener(new UdpConnection(this.#server, peerHost, peerPort), data),
         );
@@ -63,7 +64,7 @@ export class UdpInterface implements NetInterface {
     }
 }
 
-export class UdpConnection implements IpNetworkChannel<Uint8Array> {
+export class UdpConnection implements IpNetworkChannel<Bytes> {
     readonly isReliable = false;
     readonly type = ChannelType.UDP;
     readonly #server: UdpChannel;
@@ -80,7 +81,7 @@ export class UdpConnection implements IpNetworkChannel<Uint8Array> {
         return this.#server.maxPayloadSize;
     }
 
-    send(data: Uint8Array) {
+    send(data: Bytes) {
         return this.#server.send(this.#peerAddress, this.#peerPort, data);
     }
 

package/src/net/UdpMulticastServer.ts

@@ -5,6 +5,7 @@
  */
 
 import { MatterAggregateError } from "#MatterError.js";
+import { Bytes } from "#util/Bytes.js";
 import { Logger } from "../log/Logger.js";
 import { Cache } from "../util/Cache.js";
 import { asError } from "../util/Error.js";
@@ -89,7 +90,7 @@ export class UdpMulticastServer {
         return this.serverIpv4 !== undefined;
     }
 
-    onMessage(listener: (message: Uint8Array, peerAddress: string, netInterface: string) => void) {
+    onMessage(listener: (message: Bytes, peerAddress: string, netInterface: string) => void) {
         this.serverIpv4?.onData((netInterface, peerAddress, _port, message) => {
             if (netInterface === undefined) {
                 // Ignore Network packages not coming over any known interface
@@ -106,7 +107,7 @@ export class UdpMulticastServer {
         });
     }
 
-    async send(message: Uint8Array, netInterface?: string, uniCastTarget?: string) {
+    async send(message: Bytes, netInterface?: string, uniCastTarget?: string) {
         netInterface = netInterface ?? this.netInterface;
 
         // When we know the network interface and the unicast target, we can send unicast

package/src/net/mock/MockRouter.ts

@@ -39,7 +39,7 @@ export namespace MockRouter {
         sourcePort: number;
         destAddress: string;
         destPort: number;
-        payload: Uint8Array;
+        payload: BufferSource;
     }
 
     export interface Route {

package/src/net/mock/MockUdpChannel.ts

@@ -62,7 +62,7 @@ export class MockUdpChannel implements UdpChannel {
         };
     }
 
-    async send(host: string, port: number, payload: Uint8Array) {
+    async send(host: string, port: number, payload: BufferSource) {
         this.#host.simulator.router({
             kind: "udp",
             sourceAddress: this.#sendFrom,

package/src/net/mock/NetworkSimulator.ts

@@ -20,5 +20,5 @@ export class NetworkSimulator {
 }
 
 export namespace NetworkSimulator {
-    export type Listener = (netInterface: string, peerAddress: string, peerPort: number, data: Uint8Array) => void;
+    export type Listener = (netInterface: string, peerAddress: string, peerPort: number, data: BufferSource) => void;
 }

package/src/storage/Storage.ts

@@ -42,7 +42,7 @@ export abstract class Storage {
     abstract writeBlobFromStream(
         contexts: string[],
         key: string,
-        stream: ReadableStream<Uint8Array>,
+        stream: ReadableStream<BufferSource>,
     ): MaybePromise<void>;
 }
 

package/src/storage/StorageBackendMemory.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Bytes } from "#util/Bytes.js";
 import { deepCopy } from "#util/DeepCopy.js";
 import { CloneableStorage, Storage, StorageError } from "./Storage.js";
 import { SupportedStorageTypes } from "./StringifyTools.js";
@@ -68,13 +69,13 @@ export class StorageBackendMemory extends Storage implements CloneableStorage {
         if (value === undefined) {
             return new Blob([]);
         }
-        if (!(value instanceof Uint8Array)) {
-            throw new StorageError("Value must be an Uint8Array to read as blob stream.");
+        if (!Bytes.isBytes(value)) {
+            throw new StorageError("Value must be a BufferSource to read as blob stream.");
         }
-        return new Blob([value]);
+        return new Blob([Bytes.exclusive(value)]);
     }
 
-    async writeBlobFromStream(contexts: string[], key: string, stream: ReadableStream<Uint8Array>): Promise<void> {
+    async writeBlobFromStream(contexts: string[], key: string, stream: ReadableStream<BufferSource>): Promise<void> {
         this.#assertInitialized();
         const reader = stream.getReader();
         const chunks: Uint8Array[] = [];
@@ -84,8 +85,9 @@ export class StorageBackendMemory extends Storage implements CloneableStorage {
             while (true) {
                 const { done, value } = await reader.read();
                 if (done) break;
-                chunks.push(value);
-                length += value.length;
+                const data = Bytes.of(value);
+                chunks.push(data);
+                length += data.length;
             }
             const combined = new Uint8Array(length);
             let offset = 0;

package/src/storage/StorageContext.ts

@@ -111,7 +111,7 @@ export class StorageContext implements StorageContextFactory {
         return this.storage.openBlob(this.thisContexts, key);
     }
 
-    writeBlobFromStream(key: string, stream: ReadableStream<Uint8Array>) {
+    writeBlobFromStream(key: string, stream: ReadableStream<BufferSource>) {
         return this.storage.writeBlobFromStream(this.thisContexts, key, stream);
     }
 }

package/src/storage/StringifyTools.ts

@@ -9,7 +9,7 @@ import { Bytes } from "../util/Bytes.js";
 import { isObject } from "../util/Type.js";
 
 /** Supported base types to stringify the data for the storage that can be used as keys and also values. */
-type SupportedStorageBaseTypes = string | number | boolean | bigint | Uint8Array;
+type SupportedStorageBaseTypes = string | number | boolean | bigint | Bytes;
 
 /** Supported combined types to stringify the data for the storage that can be used as values. */
 type SupportedComplexStorageTypes =
@@ -38,7 +38,7 @@ export function toJson(object: SupportedStorageTypes, spaces?: number): string {
             if (typeof value === "bigint") {
                 return `{"${JSON_SPECIAL_KEY_TYPE}":"BigInt","${JSON_SPECIAL_KEY_VALUE}":"${value.toString()}"}`;
             }
-            if (value instanceof Uint8Array) {
+            if (Bytes.isBytes(value)) {
                 return `{"${JSON_SPECIAL_KEY_TYPE}":"Uint8Array","${JSON_SPECIAL_KEY_VALUE}":"${Bytes.toHex(value)}"}`;
             }
             //Node.js can sometimes pass in a native Buffer object in place of a Uint8Array, of which it is a subclass of, the Buffer class implements its own toJSON method which breaks our serialization.

package/src/transaction/Tx.ts

@@ -291,7 +291,11 @@ class Tx implements Transaction, Transaction.Finalization {
 
     reject(cause: unknown): MaybePromise<never> {
         if (this.#status === Status.Shared) {
-            this.#reset("released");
+            try {
+                this.#reset("released");
+            } finally {
+                this[Symbol.dispose]();
+            }
             throw cause;
         }
 

package/src/util/Bytes.ts

@@ -4,13 +4,20 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { UnexpectedDataError } from "../MatterError.js";
+import { ImplementationError, UnexpectedDataError } from "../MatterError.js";
 
 export enum Endian {
     Little,
     Big,
 }
 
+/**
+ * A standard JS source of bytes.
+ *
+ * This alias mainly exists because "AllowedSharedBufferSource" is an annoying name.
+ */
+export type Bytes = AllowSharedBufferSource;
+
 /**
  * A string tag for hex literals.
  *
@@ -34,29 +41,37 @@ export function b$(strings: TemplateStringsArray, ...values: unknown[]) {
  * Utility functions for manipulating Uint8Array.
  */
 export namespace Bytes {
-    export function toHex(array: Uint8Array) {
+    export function toHex(array: Bytes) {
         const hexArray = new Array<string>();
-        hexArray.length = array.length;
-        array.forEach(byte => hexArray.push(byte.toString(16).padStart(2, "0")));
+        const data = Bytes.of(array);
+        hexArray.length = data.length;
+        data.forEach(byte => hexArray.push(byte.toString(16).padStart(2, "0")));
         return hexArray.join("");
     }
 
-    export function toBase64(array: Uint8Array) {
+    export function toBase64(array: Bytes) {
         let result = "";
-        array.forEach(byte => (result += String.fromCharCode(byte)));
+        const data = Bytes.of(array);
+        data.forEach(byte => (result += String.fromCharCode(byte)));
         return btoa(result);
     }
 
-    export function dataViewOf(array: Uint8Array) {
-        return new DataView(array.buffer, array.byteOffset, array.byteLength);
+    export function dataViewOf(array: Bytes) {
+        const data = Bytes.of(array);
+        return new DataView(data.buffer, data.byteOffset, data.byteLength);
     }
 
-    export function areEqual(array1: Uint8Array, array2: Uint8Array) {
-        if (array1.length !== array2.length) return false;
-        return array1.every((value, index) => array2[index] === value);
+    export function areEqual(array1: Bytes, array2: Bytes) {
+        if (array1.byteLength !== array2.byteLength) return false;
+        const data1 = Bytes.of(array1);
+        const data2 = Bytes.of(array2);
+        return data1.every((value, index) => data2[index] === value);
     }
 
-    export function of(source: BufferSource) {
+    /**
+     * Obtain a {@link Uint8Array} for {@link Bytes}.
+     */
+    export function of(source: Bytes) {
         if (source instanceof Uint8Array) {
             return source;
         }
@@ -68,7 +83,28 @@ export namespace Bytes {
         return new Uint8Array(source);
     }
 
-    export function fromHex(hexString: string) {
+    /**
+     * Like {@link of} for the few places where JS differentiates between {@link BufferSource} and
+     * {@link SharedBufferSource}.
+     *
+     * We generally do not deal with shared buffers and this is mostly relevant for security APIs.  So we throw if for
+     * some reason the input sourde is not exclusive.
+     */
+    export function exclusive(source: Bytes) {
+        const buffer = "buffer" in source ? source.buffer : source;
+
+        if (buffer[Symbol.toStringTag] !== "ArrayBuffer") {
+            throw new ImplementationError("A shared buffer source is not allowed here");
+        }
+
+        return source as BufferSource;
+    }
+
+    export function isBytes(source: unknown): source is Bytes {
+        return source instanceof ArrayBuffer || ArrayBuffer.isView(source);
+    }
+
+    export function fromHex(hexString: string): Bytes {
         if (hexString.length === 0) return new Uint8Array(0);
         if (hexString.length % 2 !== 0) throw new UnexpectedDataError("Hex string should have an even length.");
         const bytes = hexString.match(/.{1,2}/g)?.map(byteHex => parseInt(byteHex, 16));
@@ -86,27 +122,29 @@ export namespace Bytes {
         return fromHex(result);
     }
 
-    export function fromString(string: string) {
+    export function fromString(string: string): Bytes {
         return new TextEncoder().encode(string);
     }
 
-    export function concat(...arrays: Uint8Array[]): Uint8Array {
+    export function concat(...arrays: Bytes[]): Bytes {
         let length = 0;
-        arrays.forEach(array => (length += array.length));
+        const data = arrays.map(array => Bytes.of(array));
+        data.forEach(array => (length += array.length));
         const result = new Uint8Array(length);
         let offset = 0;
-        arrays.forEach(array => {
+        data.forEach(array => {
             result.set(array, offset);
             offset += array.length;
         });
         return result;
     }
 
-    export function asBigInt(bytes: Uint8Array) {
-        const view = new DataView(bytes.buffer);
+    export function asBigInt(bytes: Bytes) {
+        const view = Bytes.dataViewOf(bytes);
         let result = 0n;
-        for (let i = 0; i < bytes.length; ) {
-            const remaining = bytes.length - i;
+        const length = view.byteLength;
+        for (let i = 0; i < length; ) {
+            const remaining = length - i;
             if (remaining >= 8) {
                 result = (result << 64n) + view.getBigUint64(i);
                 i += 8;

package/src/util/DataReader.ts

@@ -13,8 +13,8 @@ export class DataReader<E extends Endian = Endian.Big> {
     readonly #buffer: Uint8Array;
     #offset = 0;
 
-    constructor(buffer: Uint8Array, endian?: E) {
-        this.#buffer = buffer;
+    constructor(buffer: Bytes, endian?: E) {
+        this.#buffer = Bytes.of(buffer);
         this.#dataView = Bytes.dataViewOf(this.#buffer);
         this.#littleEndian = endian === Endian.Little;
     }

package/src/util/DataWriter.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Endian } from "./Bytes.js";
+import { Bytes, Endian } from "./Bytes.js";
 import { toNumber } from "./Number.js";
 
 /** Writer that auto-increments its offset after each write. */
@@ -86,8 +86,8 @@ export class DataWriter<E extends Endian = Endian.Big> {
         this.length += 8;
     }
 
-    writeByteArray(value: Uint8Array) {
-        this.chunks.push(value);
+    writeByteArray(value: Bytes) {
+        this.chunks.push(Bytes.of(value));
         this.length += value.byteLength;
     }
 

package/src/util/String.ts

@@ -139,13 +139,8 @@ export function serialize(value: any) {
         if (typeof value === "boolean") {
             return value ? "true" : "false";
         }
-        if (ArrayBuffer.isView(value)) {
-            const dv = new DataView(value.buffer, value.byteOffset, value.byteLength);
-            const bytes = Array<string>();
-            for (let i = 0; i < dv.byteLength; i++) {
-                bytes.push(dv.getUint8(i).toString(16).padStart(2, "0"));
-            }
-            return bytes.join("");
+        if (Bytes.isBytes(value)) {
+            return Bytes.toHex(value);
         }
 
         // Composite objects after this
@@ -284,7 +279,7 @@ export function serializeToJs(value: unknown) {
         return `new Date(${JSON.stringify(value.toISOString)})`;
     }
 
-    if (value instanceof Uint8Array) {
+    if (Bytes.isBytes(value)) {
         return `b$\`${Bytes.toHex(value)}\``;
     }