@seriousme/opifex 1.8.1 → 1.9.0

package/mqttPacket/encoder.ts

@@ -2,6 +2,9 @@ const utf8Encoder = new TextEncoder();
 import type { Topic, TopicFilter } from "./types.ts";
 import { invalidTopic, invalidTopicFilter } from "./validators.ts";
 
+/**
+ * Custom error class for encoding operations
+ */
 export class EncoderError extends Error {
   constructor(message: string) {
     super(message);
@@ -9,24 +12,47 @@ export class EncoderError extends Error {
   }
 }
 
+/**
+ * Encoder class for MQTT packet encoding
+ */
 export class Encoder {
+  /** Internal buffer to store encoded bytes */
   private buffer: number[];
 
+  /**
+   * Creates a new Encoder instance
+   */
   constructor() {
     this.buffer = [];
   }
 
+  /**
+   * Adds a single byte to the buffer
+   * @param value - Byte value to add (0-255)
+   * @returns The encoder instance for chaining
+   */
   setByte(value: number): this {
     this.buffer.push(value);
     return this;
   }
 
+  /**
+   * Adds a 16-bit integer to the buffer in big-endian format
+   * @param value - 16-bit integer value to add
+   * @returns The encoder instance for chaining
+   */
   setInt16(value: number): this {
     this.setByte(value >> 8);
     this.setByte(value & 0xff);
     return this;
   }
 
+  /**
+   * Adds a byte array to the buffer with length prefix
+   * @param value - Byte array to add
+   * @throws {EncoderError} If array length exceeds 0xffff bytes
+   * @returns The encoder instance for chaining
+   */
   setByteArray(value: Uint8Array): this {
     if (value.length > 0xffff) {
       throw new EncoderError("More than 0xffff bytes of data");
@@ -36,11 +62,22 @@ export class Encoder {
     return this;
   }
 
+  /**
+   * Adds a UTF-8 encoded string to the buffer with length prefix
+   * @param value - String to encode and add
+   * @returns The encoder instance for chaining
+   */
   setUtf8String(value: string): this {
     this.setByteArray(utf8Encoder.encode(value));
     return this;
   }
 
+  /**
+   * Adds an MQTT topic string to the buffer
+   * @param value - Topic string to add
+   * @throws {EncoderError} If topic is invalid
+   * @returns The encoder instance for chaining
+   */
   setTopic(value: Topic): this {
     if (invalidTopic(value)) {
       throw new EncoderError(
@@ -51,6 +88,12 @@ export class Encoder {
     return this;
   }
 
+  /**
+   * Adds an MQTT topic filter string to the buffer
+   * @param value - Topic filter string to add
+   * @throws {EncoderError} If topic filter is invalid
+   * @returns The encoder instance for chaining
+   */
   setTopicFilter(value: TopicFilter): this {
     if (invalidTopicFilter(value)) {
       throw new EncoderError(
@@ -61,11 +104,20 @@ export class Encoder {
     return this;
   }
 
+  /**
+   * Adds remaining bytes to the buffer without modification
+   * @param value - Array of bytes to add
+   * @returns The encoder instance for chaining
+   */
   setRemainder(value: Uint8Array | number[]): this {
     this.buffer.push(...value);
     return this;
   }
 
+  /**
+   * Returns the final encoded buffer
+   * @returns Array containing all encoded bytes
+   */
   done(): number[] {
     return this.buffer;
   }

package/mqttPacket/length.ts

@@ -1,3 +1,9 @@
+/**
+ * Encodes a number into a variable-length byte array using a modified base-128 encoding
+ * @param n The number to encode
+ * @returns Array of bytes representing the encoded number
+ * @throws Error if the encoded length is greater than 4 bytes
+ */
 export function encodeLength(n: number): number[] {
   const output = [];
   let x = n;
@@ -15,6 +21,13 @@ export function encodeLength(n: number): number[] {
   return output;
 }
 
+/**
+ * Decodes a variable-length encoded number from a byte array
+ * @param buf The byte array containing the encoded number
+ * @param start The starting position in the buffer to begin decoding
+ * @returns Object containing the decoded length and number of bytes used for encoding
+ * @throws Error if decoding fails
+ */
 export function decodeLength(
   buf: Uint8Array,
   start: number,
@@ -30,12 +43,20 @@ export function decodeLength(
   throw Error("length decoding failed");
 }
 
+/**
+ * Interface for the result returned by the length decoder
+ */
 export type LengthDecoderResult = {
   done: boolean;
   length: number;
   numLengthBytes: number;
 };
 
+/**
+ * Creates a stateful decoder function for processing variable-length encoded numbers
+ * @returns Function that processes one byte at a time and returns decoding status
+ * @throws Error if the encoded length is greater than 4 bytes
+ */
 export function getLengthDecoder(): (
   encodedByte: number,
 ) => LengthDecoderResult {

package/mqttPacket/mod.ts

@@ -1,7 +1,8 @@
 /**
- *  This module provides the encoding and decoding of MQTT packets
- * it is used by the server and client modules
- *  @module
+ * @module MQTT Packet Encoding/Decoding
+ * @description This module provides comprehensive encoding and decoding functionality for MQTT packets
+ * used in both server and client implementations. It handles all MQTT packet types and their
+ * transformations between binary and object representations.
  */
 
 import type {
@@ -99,6 +100,10 @@ export {
   PacketType,
 };
 
+/**
+ * Array mapping MQTT packet types to their corresponding encode/decode handlers
+ * Index corresponds to packet type number.
+ */
 export const packetsByType = [
   null,
   connect, // 1
@@ -117,6 +122,13 @@ export const packetsByType = [
   disconnect, // 14
 ] as const;
 
+/**
+ * @function encode
+ * @description Encodes an MQTT packet object into a binary Uint8Array format
+ * @param {AnyPacket} packet - The MQTT packet object to encode
+ * @returns {Uint8Array} The encoded packet as a binary buffer
+ * @throws {Error} If packet encoding fails
+ */
 export function encode(packet: AnyPacket): Uint8Array {
   const packetType: number = packet.type;
   // deno-lint-ignore no-explicit-any
@@ -133,6 +145,15 @@ export function encode(packet: AnyPacket): Uint8Array {
   ]);
 }
 
+/**
+ * @function decodePayload
+ * @description Decodes a packet payload from binary format into an MQTT packet object
+ * @param {number} firstByte - The first byte of the MQTT packet containing type and flags
+ * @param {Uint8Array} buffer - The binary buffer containing the packet payload
+ * @returns {AnyPacket} The decoded MQTT packet object
+ * @throws {Error} If packet decoding fails
+ */
+
 export function decodePayload(
   firstByte: number,
   buffer: Uint8Array,
@@ -146,6 +167,13 @@ export function decodePayload(
   throw new Error("packet decoding failed");
 }
 
+/**
+ * @function decode
+ * @description Decodes a complete MQTT packet from binary format into a packet object
+ * @param {Uint8Array} buffer - The binary buffer containing the complete MQTT packet
+ * @returns {AnyPacket} The decoded MQTT packet object
+ * @throws {DecoderError} If packet decoding fails due to invalid format or insufficient data
+ */
 export function decode(buffer: Uint8Array): AnyPacket {
   if (buffer.length < 2) {
     throw new DecoderError("Packet decoding failed");

package/node/wrapNodeSocket.ts

@@ -3,7 +3,7 @@
  */
 import type { Socket } from "node:net";
 import { Writable } from "node:stream";
-import type { SockConn } from "../socket/socket.ts";
+import type { NetAddr, SockConn } from "../socket/socket.ts";
 /**
  * Closes a Node.js socket if it is not already closed
  * @param sock - The Node.js socket to close
@@ -50,9 +50,10 @@ export function wrapNodeSocket(socket: Socket): SockConn {
     },
   );
   const writable = Writable.toWeb(socket);
-  const remoteAddr = {
+  const remoteAddr: NetAddr = {
     hostname: socket.remoteAddress || "",
     port: socket.remotePort || 0,
+    transport: "tcp",
   };
 
   const conn: SockConn = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seriousme/opifex",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "MQTT client & server for Deno & NodeJS",
   "type": "module",
   "scripts": {
@@ -36,7 +36,8 @@
     "./tcpServer": "./dist/node/tcpServer.js",
     "./server": "./dist/server/mod.js",
     "./client": "./dist/client/mod.js",
-    "./persistence": "./dist/persistence/persistence.js",
+    "./trie": "./dist/trie/trie.js",
+    "./persistence": "./dist/persistence/mod.js",
     "./mqttConn": "./dist/mqttConn/mqttConn.js",
     "./mqttPacket": "./dist/mqttPacket/mod.js",
     "./utils": "./dist/utils/mod.js"
@@ -47,7 +48,8 @@
       "./tcpServer": "./deno/tcpServer.ts",
       "./server": "./server/mod.ts",
       "./client": "./client/mod.ts",
-      "./persistence": "./persistence/persistence.ts",
+      "./trie": "./trie/trie.ts",
+      "./persistence": "./persistence/mod.ts",
       "./mqttConn": "./mqttConn/mqttConn.ts",
       "./mqttPacket": "./mqttPacket/mod.ts",
       "./utils": "./utils/mod.ts"

package/persistence/memory/memoryPersistence.ts

@@ -1,24 +1,23 @@
-import {
-  type ClientId,
-  type PacketId,
-  type PublishPacket,
-  type QoS,
-  type Topic,
-  type TopicFilter,
-  Trie,
-} from "../deps.ts";
-
 import type {
   Client,
+  ClientId,
   Handler,
   IPersistence,
+  IStore,
+  PacketId,
+  PacketStore,
+  PublishPacket,
+  QoS,
   RetainStore,
-} from "../persistence.ts";
-import type { IStore, PacketStore, SubscriptionStore } from "../store.ts";
-import { assert } from "../../utils/mod.ts";
+  SubscriptionStore,
+  Topic,
+  TopicFilter,
+} from "../mod.ts";
 
-const maxPacketId = 0xffff;
-// const maxQueueLength = 0xffff;
+import { maxPacketId } from "../mod.ts";
+
+import { Trie } from "../deps.ts";
+import { assert } from "../../utils/mod.ts";
 
 type ClientSubscription = {
   clientId: ClientId;
@@ -99,7 +98,7 @@ export class MemoryPersistence implements IPersistence {
   unsubscribe(store: IStore, topicFilter: TopicFilter): void {
     const clientId = store.clientId;
     const qos = store.subscriptions.get(topicFilter);
-    if (qos) {
+    if (qos !== undefined) {
       store.subscriptions.delete(topicFilter);
       this.trie.remove(topicFilter, { clientId, qos });
     }

package/persistence/mod.ts

@@ -0,0 +1,20 @@
+/**
+ * @module persistence
+ * @description Module for handling MQTT message persistence and client management
+ */
+export type { IStore, PacketStore, SubscriptionStore } from "./store.ts";
+export type {
+  ClientId,
+  PacketId,
+  PublishPacket,
+  QoS,
+  Topic,
+  TopicFilter,
+} from "./deps.ts";
+export type {
+  Client,
+  Handler,
+  IPersistence,
+  RetainStore,
+} from "./persistence.ts";
+export { maxPacketId } from "./persistence.ts";

package/persistence/persistence.ts

@@ -5,6 +5,11 @@
 import type { ClientId, PublishPacket, QoS, Topic } from "./deps.ts";
 import type { IStore } from "./store.ts";
 
+/**
+ * Maximum packet ID value for MQTT messages (0xffff/65535)
+ * @constant {number}
+ */
+export const maxPacketId = 0xffff;
 /**
  * Handler function type for processing publish packets
  * @callback Handler

package/socket/socket.ts

@@ -1,6 +1,6 @@
-export type SockAddr = NetAddr | UnixAddr | undefined;
+export type SockAddr = NetAddr | UnixAddr | VsockAddr;
 export interface NetAddr {
-  transport?: "tcp" | "udp";
+  transport: "tcp" | "udp";
   hostname: string;
   port: number;
 }
@@ -10,6 +10,12 @@ export interface UnixAddr {
   path: string;
 }
 
+export interface VsockAddr {
+  transport: "vsock";
+  cid: number;
+  port: number;
+}
+
 export type SockConn = {
   readable: ReadableStream<Uint8Array>;
   writable: WritableStream<Uint8Array>;