@seriousme/opifex 1.6.0 → 1.6.2

package/mqttPacket/mod.ts

@@ -1,3 +1,9 @@
+/**
+ *  This module provides the encoding and decoding of MQTT packets
+ * it is used by the server and client modules
+ *  @module
+ */
+
 import type {
   ClientId,
   Dup,
@@ -13,26 +19,29 @@ import type {
 import { PacketNameByType, PacketType } from "./PacketType.ts";
 import { invalidTopic, invalidTopicFilter, invalidUTF8 } from "./validators.ts";
 import { decodeLength, encodeLength } from "./length.ts";
-import connect, { type ConnectPacket } from "./connect.ts";
-import connack, { type ConnackPacket } from "./connack.ts";
+import { connect, type ConnectPacket } from "./connect.ts";
+import { connack, type ConnackPacket } from "./connack.ts";
 import {
   AuthenticationResult,
   AuthenticationResultByNumber,
 } from "./AuthenticationResult.ts";
-import publish, { type PublishPacket } from "./publish.ts";
-import puback, { type PubackPacket } from "./puback.ts";
-import pubrec, { type PubrecPacket } from "./pubrec.ts";
-import pubrel, { type PubrelPacket } from "./pubrel.ts";
-import pubcomp, { type PubcompPacket } from "./pubcomp.ts";
-import subscribe, { type SubscribePacket } from "./subscribe.ts";
-import suback, { type SubackPacket } from "./suback.ts";
-import unsubscribe, { type UnsubscribePacket } from "./unsubscribe.ts";
-import unsuback, { type UnsubackPacket } from "./unsuback.ts";
-import pingreq, { type PingreqPacket } from "./pingreq.ts";
-import pingres, { type PingresPacket } from "./pingres.ts";
-import disconnect, { type DisconnectPacket } from "./disconnect.ts";
+import { publish, type PublishPacket } from "./publish.ts";
+import { puback, type PubackPacket } from "./puback.ts";
+import { pubrec, type PubrecPacket } from "./pubrec.ts";
+import { pubrel, type PubrelPacket } from "./pubrel.ts";
+import { pubcomp, type PubcompPacket } from "./pubcomp.ts";
+import { subscribe, type SubscribePacket } from "./subscribe.ts";
+import { suback, type SubackPacket } from "./suback.ts";
+import { unsubscribe, type UnsubscribePacket } from "./unsubscribe.ts";
+import { unsuback, type UnsubackPacket } from "./unsuback.ts";
+import { pingreq, type PingreqPacket } from "./pingreq.ts";
+import { pingres, type PingresPacket } from "./pingres.ts";
+import { disconnect, type DisconnectPacket } from "./disconnect.ts";
 import { DecoderError } from "./decoder.ts";
 
+/**
+ * this can be any possible MQTT packet
+ */
 export type AnyPacket =
   | ConnectPacket
   | ConnackPacket
@@ -108,7 +117,7 @@ export const packetsByType = [
   disconnect, // 14
 ] as const;
 
-export function encode(packet: AnyPacket) {
+export function encode(packet: AnyPacket): Uint8Array {
   const packetType: number = packet.type;
   // deno-lint-ignore no-explicit-any
   const pkt: any = packet;

package/mqttPacket/pingreq.ts

@@ -2,12 +2,18 @@ import { PacketType } from "./PacketType.ts";
 import { hasEmptyFlags, isEmptyBuf } from "./decoder.ts";
 import type { TPacketType } from "./types.ts";
 
+/**
+ * PingreqPacket is a packet that is sent to the server to keep the connection alive
+ */
 export type PingreqPacket = {
   type: TPacketType;
 };
 
-export default {
-  encode(_packet: PingreqPacket) {
+export const pingreq: {
+  encode(_packet: PingreqPacket): { flags: number; bytes: number[] };
+  decode(buffer: Uint8Array, flags: number): PingreqPacket;
+} = {
+  encode(_packet: PingreqPacket): { flags: number; bytes: number[] } {
     const flags = 0;
     return { flags, bytes: [] };
   },

package/mqttPacket/pingres.ts

@@ -2,12 +2,19 @@ import { PacketType } from "./PacketType.ts";
 import { isEmptyBuf } from "./decoder.ts";
 import type { TPacketType } from "./types.ts";
 
+/**
+ * PingresPacket is  an empty packet that is sent by the server in response to a PingreqPacket.
+ * It is used to indicate that the client is still connected to the server.
+ */
 export type PingresPacket = {
   type: TPacketType;
 };
 
-export default {
-  encode(_packet: PingresPacket) {
+export const pingres: {
+  encode(_packet: PingresPacket): { flags: number; bytes: number[] };
+  decode(buffer: Uint8Array): PingresPacket;
+} = {
+  encode(_packet: PingresPacket): { flags: number; bytes: number[] } {
     const flags = 0;
     return { flags, bytes: [] };
   },

package/mqttPacket/puback.ts

@@ -3,13 +3,19 @@ import { PacketType } from "./PacketType.ts";
 import { Decoder } from "./decoder.ts";
 import { Encoder } from "./encoder.ts";
 
+/**
+ * PubackPacket is sent to indicate publish complete (QoS 1)
+ */
 export type PubackPacket = {
   type: TPacketType;
   id: PacketId;
 };
 
-export default {
-  encode(packet: PubackPacket) {
+export const puback: {
+  encode(packet: PubackPacket): { flags: number; bytes: number[] };
+  decode(buffer: Uint8Array): PubackPacket;
+} = {
+  encode(packet: PubackPacket): { flags: number; bytes: number[] } {
     const flags = 0;
     const encoder = new Encoder();
     encoder.setInt16(packet.id);

package/mqttPacket/pubcomp.ts

@@ -3,13 +3,20 @@ import { PacketType } from "./PacketType.ts";
 import { Decoder } from "./decoder.ts";
 import { Encoder } from "./encoder.ts";
 
+/**
+ * PubcompPacket is sent to indicate publish complete
+ * It is the fourth packet of the QoS 2 protocol exchange.
+ */
 export type PubcompPacket = {
   type: TPacketType;
   id: PacketId;
 };
 
-export default {
-  encode(packet: PubcompPacket) {
+export const pubcomp: {
+  encode(packet: PubcompPacket): { flags: number; bytes: number[] };
+  decode(buffer: Uint8Array): PubcompPacket;
+} = {
+  encode(packet: PubcompPacket): { flags: number; bytes: number[] } {
     const flags = 0;
     const encoder = new Encoder();
     encoder.setInt16(packet.id);

package/mqttPacket/publish.ts

@@ -4,6 +4,10 @@ import { BitMask } from "./BitMask.ts";
 import { Encoder, EncoderError } from "./encoder.ts";
 import { booleanFlag, Decoder, DecoderError } from "./decoder.ts";
 
+/**
+ * PublishPacket is used to send data from client to server and
+ * from server to subscribers
+ */
 export type PublishPacket = {
   type: TPacketType;
   topic: Topic;
@@ -14,8 +18,11 @@ export type PublishPacket = {
   id?: number;
 };
 
-export default {
-  encode(packet: PublishPacket) {
+export const publish: {
+  encode(packet: PublishPacket): { flags: number; bytes: number[] };
+  decode(buffer: Uint8Array, flags: number): PublishPacket;
+} = {
+  encode(packet: PublishPacket): { flags: number; bytes: number[] } {
     const qos = packet.qos || 0;
 
     const flags = (packet.dup ? BitMask.bit3 : 0) +

package/mqttPacket/pubrec.ts

@@ -3,13 +3,20 @@ import { PacketType } from "./PacketType.ts";
 import { Decoder } from "./decoder.ts";
 import { Encoder } from "./encoder.ts";
 
+/**
+ * PubrecPacket indicates publish received
+ * It is the second packet of the QoS 2 protocol exchange.
+ */
 export type PubrecPacket = {
   type: TPacketType;
   id: PacketId;
 };
 
-export default {
-  encode(packet: PubrecPacket) {
+export const pubrec: {
+  encode(packet: PubrecPacket): { flags: number; bytes: number[] };
+  decode(buffer: Uint8Array): PubrecPacket;
+} = {
+  encode(packet: PubrecPacket): { flags: number; bytes: number[] } {
     const flags = 0;
     const encoder = new Encoder();
     encoder.setInt16(packet.id);

package/mqttPacket/pubrel.ts

@@ -3,13 +3,20 @@ import { PacketType } from "./PacketType.ts";
 import { Decoder } from "./decoder.ts";
 import { Encoder } from "./encoder.ts";
 
+/**
+ * PubrelPacket is the packet sent by the Server to the Client in response to a
+ * PubrecPacket. It is the third packet of the QoS 2 protocol exchange.
+ */
 export type PubrelPacket = {
   type: TPacketType;
   id: PacketId;
 };
 
-export default {
-  encode(packet: PubrelPacket) {
+export const pubrel: {
+  encode(packet: PubrelPacket): { flags: number; bytes: number[] };
+  decode(buffer: Uint8Array): PubrelPacket;
+} = {
+  encode(packet: PubrelPacket): { flags: number; bytes: number[] } {
     const flags = 0;
     const encoder = new Encoder();
     encoder.setInt16(packet.id);

package/mqttPacket/suback.ts

@@ -3,14 +3,21 @@ import { PacketType } from "./PacketType.ts";
 import { Encoder } from "./encoder.ts";
 import { Decoder } from "./decoder.ts";
 
+/**
+ * SubackPacket is sent by the server to the client to confirm receipt and
+ * processing of a SubscribePacket.
+ */
 export type SubackPacket = {
   type: TPacketType;
   id: PacketId;
   returnCodes: ReturnCodes;
 };
 
-export default {
-  encode(packet: SubackPacket) {
+export const suback: {
+  encode(packet: SubackPacket): { flags: number; bytes: number[] };
+  decode(buffer: Uint8Array): SubackPacket;
+} = {
+  encode(packet: SubackPacket): { flags: number; bytes: number[] } {
     const flags = 0;
     const encoder = new Encoder();
     encoder.setInt16(packet.id);

package/mqttPacket/subscribe.ts

@@ -4,19 +4,28 @@ import { BitMask } from "./BitMask.ts";
 import { Encoder } from "./encoder.ts";
 import { booleanFlag, Decoder, DecoderError } from "./decoder.ts";
 
+/**
+ * SubscribePacket is sent from client to server to subscribe to topics
+ */
 export type SubscribePacket = {
   type: TPacketType;
   id: PacketId;
   subscriptions: Subscription[];
 };
 
+/**
+ * The topic to subscribe to and the associated QoS
+ */
 export type Subscription = {
   topicFilter: TopicFilter;
   qos: QoS;
 };
 
-export default {
-  encode(packet: SubscribePacket) {
+export const subscribe: {
+  encode(packet: SubscribePacket): { flags: number; bytes: number[] };
+  decode(buffer: Uint8Array, flags: number): SubscribePacket;
+} = {
+  encode(packet: SubscribePacket): { flags: number; bytes: number[] } {
     // Bits 3,2,1 and 0 of the fixed header of the SUBSCRIBE Control Packet are reserved and
     // MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other value as
     // malformed and close the Network Connection [MQTT-3.8.1-1].

package/mqttPacket/types.ts

@@ -2,26 +2,57 @@ import type { BitMask } from "./BitMask.ts";
 import type { PacketType } from "./PacketType.ts";
 import type { AuthenticationResult } from "./AuthenticationResult.ts";
 
+/**
+ * Type to limit bit mask to valid values
+ */
 export type TBitMask = typeof BitMask[keyof typeof BitMask];
+/**
+ * Type to limit packet type to valid values
+ */
 export type TPacketType = typeof PacketType[keyof typeof PacketType];
+
+/**
+ * Type to limit authentication result to valid values
+ */
 export type TAuthenticationResult =
   typeof AuthenticationResult[keyof typeof AuthenticationResult];
 
+/**
+ * Quality of Service level
+ */
 export type QoS = 0 | 1 | 2;
 
+/**
+ * Packet payload
+ */
 export type Payload = Uint8Array;
 
 /**
- * The MQTT topic to publish or subscribe to
+ * The MQTT topic to publish to
  */
 export type Topic = string;
 
+/**
+ * The MQTT topic to subscribe/unsubscribe to
+ */
 export type TopicFilter = string;
 
+/**
+ * Duplicate delivery flag
+ */
 export type Dup = boolean;
 
+/**
+ * Packet identifier, unique per client session
+ */
 export type PacketId = number;
 
+/**
+ * Return codes on to describe result of subscribe operation
+ */
 export type ReturnCodes = number[];
 
+/**
+ * Client identifier that uniquely identifies a client
+ */
 export type ClientId = string;

package/mqttPacket/unsuback.ts

@@ -3,13 +3,20 @@ import { PacketType } from "./PacketType.ts";
 import { Decoder } from "./decoder.ts";
 import { Encoder } from "./encoder.ts";
 
+/**
+ * UnsubackPacket is sent by the server to the client to confirm receipt
+ * of an UnsubscribePacket.
+ */
 export type UnsubackPacket = {
   type: TPacketType;
   id: PacketId;
 };
 
-export default {
-  encode(packet: UnsubackPacket) {
+export const unsuback: {
+  encode(packet: UnsubackPacket): { flags: number; bytes: number[] };
+  decode(buffer: Uint8Array): UnsubackPacket;
+} = {
+  encode(packet: UnsubackPacket): { flags: number; bytes: number[] } {
     const flags = 0;
     const encoder = new Encoder();
     encoder.setInt16(packet.id);

package/mqttPacket/unsubscribe.ts

@@ -4,14 +4,20 @@ import { BitMask } from "./BitMask.ts";
 import { Encoder } from "./encoder.ts";
 import { booleanFlag, Decoder, DecoderError } from "./decoder.ts";
 
+/**
+ * UnsubscribePacket is sent from client to server to unsubscribe from topics
+ */
 export type UnsubscribePacket = {
   type: TPacketType;
   id: PacketId;
   topicFilters: TopicFilter[];
 };
 
-export default {
-  encode(packet: UnsubscribePacket) {
+export const unsubscribe: {
+  encode(packet: UnsubscribePacket): { flags: number; bytes: number[] };
+  decode(buffer: Uint8Array, flags: number): UnsubscribePacket;
+} = {
+  encode(packet: UnsubscribePacket): { flags: number; bytes: number[] } {
     // Bits 3,2,1 and 0 of the fixed header of the UNSUBSCRIBE Control Packet are reserved and
     // MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other value as
     // malformed and close the Network Connection [MQTT-3.10.1-1].

package/node/tcpClient.ts

@@ -1,5 +1,8 @@
-// this a NodeJS specific implementation of TCP client sockets
-// it extends the platform agnostic Client class
+/*
+ * this a NodeJS specific implementation of TCP client sockets
+ * it extends the platform agnostic Client class
+ *  @module
+ */
 import { Client } from "../client/client.ts";
 import { logger } from "../client/deps.ts";
 import { readFile } from "node:fs/promises";
@@ -8,6 +11,15 @@ import * as tls from "node:tls";
 import type { SockConn } from "../socket/socket.ts";
 import { wrapNodeSocket } from "./wrapNodeSocket.ts";
 
+/**
+ * @function getFileData
+ * @param filename
+ * @returns Promise
+ *
+ * Fetches data from a file and returns it as a string
+ * @example
+ * const data = await getFileData("data.txt");
+ */
 export async function getFileData(filename: string | undefined) {
   if (!filename) {
     return;
@@ -19,6 +31,12 @@ export async function getFileData(filename: string | undefined) {
   return data;
 }
 
+/*
+ * TCPclient extends the Client class to provide TCP based clients
+ * it is used by the MQTTclient to connect to the broker
+ * see mqtt.ts in the /bin folder as an example
+ */
+
 export class TcpClient extends Client {
   protected connectMQTT(hostname: string, port = 1883): Promise<SockConn> {
     logger.debug({ hostname, port });

package/node/tcpServer.ts

@@ -1,5 +1,8 @@
-// This a NodeJS specific implementation of a TCP socket listener
-// it uses the platform agnostic MqttServer class
+/*
+ * This module provides a NodeJS specific implementation of a TCP socket listener
+ * it uses the platform agnostic MqttServer class
+ *  @module
+ */
 import type { Server } from "node:net";
 import { createServer } from "node:net";
 import type { MqttServerOptions } from "../server/mod.ts";
@@ -11,6 +14,9 @@ type ServerOptions = {
   port?: number;
 };
 
+/*
+ * TCP server that wraps a MqttServer, see demoServer.ts in the /bin folder
+ */
 export class TcpServer {
   private mqttServer: MqttServer;
   private server?: Server;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seriousme/opifex",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "MQTT client & server for Deno & NodeJS",
   "type": "module",
   "scripts": {
@@ -25,7 +25,7 @@
     "./server": "./dist/server/mod.js",
     "./client": "./dist/client/mod.js",
     "./mqttPacket": "./dist/mqttPacket/mod.js",
-    "./utils": "./dist/utils/mod.js,",
+    "./utils": "./dist/utils/mod.js",
     "./tcpClient": "./dist/node/tcpClient.js",
     "./tcpServer": "./dist/node/tcpServer.js"
   },
@@ -34,7 +34,7 @@
       "./server": "./server/mod.ts",
       "./client": "./client/mod.ts",
       "./mqttPacket": "./mqttPacket/mod.ts",
-      "./utils": "./utils/mod.ts,",
+      "./utils": "./utils/mod.ts",
       "./tcpClient": "./deno/tcpClient.ts",
       "./tcpServer": "./deno/tcpServer.ts"
     },

package/utils/args.ts

@@ -1,3 +1,6 @@
+/**
+ * Parsed arguments as key value
+ */
 // deno-lint-ignore no-explicit-any
 export type Args = Record<string, any>;
 export type ArgsValue = string | number | boolean;
@@ -54,6 +57,20 @@ function parseKeyValue(
   return ["_", arg];
 }
 
+/**
+ *  a parser for command line arguments
+ * @param args the arguments to parse
+ * @param opts the options for the parser
+ * @returns the parsed arguments
+ *
+ * @example
+ * const args = parseArgs(args, {
+ *  alias: { h: "help" },
+ *  boolean: ["help"],
+ *  string: ["port"],
+ *  default: { port: 3000 },
+ * });
+ */
 export function parseArgs(args: string[], opts: ArgOpts = {}): Args {
   const { alias = {}, boolean = [], string = [], default: defaults = {} } =
     opts;

package/utils/assert.ts

@@ -6,6 +6,7 @@ export class AssertionError extends Error {
   }
 }
 
+/** assert(expr, msg) throws AssertionError if expr is falsy. */
 export function assert(expr: unknown, msg = ""): asserts expr {
   if (!expr) {
     throw new AssertionError(msg);

package/utils/asyncQueue.ts

@@ -1,5 +1,16 @@
 import { nextTick } from "./nextTick.ts";
 
+/**
+ * An Async Queue is a queue that can be used to push items to it and then wait
+ * for them to be consumed.
+ *
+ * @example
+ * const queue = new AsyncQueue<string>();
+ * queue.push("hello");
+ * for await (const item of queue) {
+ *   console.log(item); // "hello"
+ * }
+ */
 export class AsyncQueue<T> {
   private queue: T[] = [];
   private maxQueueLength = Infinity;

package/utils/deferred.ts

@@ -1,3 +1,7 @@
+/**
+ * Create a promise that can be resolved/rejected later
+ */
+
 export class Deferred<T> {
   promise: Promise<T>;
   resolve!: (val: T) => void;

package/utils/logger.ts

@@ -1,3 +1,6 @@
+/**
+ * The available log levels
+ */
 export const LogLevel = {
   error: 0,
   warn: 1,
@@ -8,6 +11,19 @@ export const LogLevel = {
 
 export type TLogLevel = typeof LogLevel[keyof typeof LogLevel];
 
+/**
+ * Simple logger class
+ * @example
+ * ```ts
+ * const logger = new Logger();
+ * logger.level(LogLevel.debug);
+ * logger.debug("debug message");
+ * logger.verbose("verbose message");
+ * logger.info("info message");
+ * logger.warn("warn message");
+ * logger.error("error message");
+ * ```
+ */
 export class Logger {
   private defaultError = console.error;
   private defaultWarn = console.warn;
@@ -32,4 +48,17 @@ export class Logger {
   }
 }
 
+/**
+ * logger provides a singleton logger instance
+ * @example
+ * ```ts
+ * import { logger } from "./utils/logger.ts";
+ * logger.level(LogLevel.debug);
+ * logger.debug("debug message");
+ * logger.verbose("verbose message");
+ * logger.info("info message");
+ * logger.warn("warn message");
+ * logger.error("error message");
+ * ```
+ */
 export const logger: Logger = new Logger();

package/utils/mod.ts

@@ -1,7 +1,12 @@
+/**
+ *  This module provides various utilities
+ *  @module
+ */
 export { assert } from "./assert.ts";
 export { Deferred } from "./deferred.ts";
 export { Logger, logger, LogLevel } from "./logger.ts";
 export { AsyncQueue } from "./asyncQueue.ts";
 export { nextTick } from "./nextTick.ts";
 export { parseArgs } from "./args.ts";
+export type { Args } from "./args.ts";
 export { getArgs } from "./platform.ts";

package/utils/nextTick.ts

@@ -1,3 +1,6 @@
+/**
+ * @returns a promise that resolves on the nextTick of the event loop
+ */
 export function nextTick(): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, 0));
 }

package/utils/platform.ts

@@ -1,4 +1,8 @@
 import { argv } from "node:process";
-export function getArgs() {
+
+/**
+ * @returns an array of command line arguments
+ */
+export function getArgs(): string[] {
   return argv.slice(2);
 }