@seriousme/opifex 1.6.1 → 1.6.2

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 ### Changed
 
+## [v1.6.2] 19-01-2025
+
+### Changed
+
+- fix: added more JSdoc comments
+
 ## [v1.6.1] 18-01-2025
 
 ### Changed

package/deno/tcpClient.ts

@@ -1,9 +1,21 @@
-// This a Deno specific implementation of TCP client sockets
-// it extends the platform agnostic Client class
+/**
+ * This a Deno 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 type { SockConn } from "../client/deps.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,
 ): Promise<string | undefined> {
@@ -17,6 +29,11 @@ export async function getFileData(
   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 async connectMQTT(
     hostname: string,

package/deno/tcpServer.ts

@@ -1,8 +1,15 @@
-// This a Deno specific implementation of a TCP socket listener
-// it uses the platform agnostic MqttServer class
+/**
+ * This module provides a Deno specific implementation of a TCP socket listener
+ * it uses the platform agnostic MqttServer class
+ *  @module
+ */
+
 import { MqttServer } from "../server/mod.ts";
 import type { MqttServerOptions } from "../server/mod.ts";
 
+/*
+ * TCP server that wraps a MqttServer, see demoServer.ts in the /bin folder
+ */
 export class TcpServer {
   private listener: Deno.Listener<Deno.Conn>;
   private mqttServer: MqttServer;

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@seriousme/opifex",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "exports": {
     "./server": "./server/mod.ts",
     "./client": "./client/mod.ts",

package/dist/mqttPacket/AuthenticationResult.js

@@ -9,5 +9,8 @@ export const AuthenticationResult = {
     badUsernameOrPassword: 4,
     notAuthorized: 5,
 };
+/**
+ * Reverse lookup for AuthenticationResult
+ */
 export const AuthenticationResultByNumber = Object
     .fromEntries(Object.entries(AuthenticationResult).map(([k, v]) => [v, k]));

package/dist/mqttPacket/mod.js

@@ -1,3 +1,8 @@
+/**
+ *  This module provides the encoding and decoding of MQTT packets
+ * it is used by the server and client modules
+ *  @module
+ */
 import { PacketNameByType, PacketType } from "./PacketType.js";
 import { invalidTopic, invalidTopicFilter, invalidUTF8 } from "./validators.js";
 import { decodeLength, encodeLength } from "./length.js";

package/dist/node/tcpClient.js

@@ -1,11 +1,23 @@
-// 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.js";
 import { logger } from "../client/deps.js";
 import { readFile } from "node:fs/promises";
 import { createConnection } from "node:net";
 import * as tls from "node:tls";
 import { wrapNodeSocket } from "./wrapNodeSocket.js";
+/**
+ * @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) {
     if (!filename) {
         return;
@@ -16,6 +28,11 @@ export async function getFileData(filename) {
     }
     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 {
     connectMQTT(hostname, port = 1883) {
         logger.debug({ hostname, port });

package/dist/node/tcpServer.js

@@ -1,6 +1,9 @@
 import { createServer } from "node:net";
 import { MqttServer } from "../server/mod.js";
 import { wrapNodeSocket } from "./wrapNodeSocket.js";
+/*
+ * TCP server that wraps a MqttServer, see demoServer.ts in the /bin folder
+ */
 export class TcpServer {
     mqttServer;
     server;

package/dist/utils/args.js

@@ -32,6 +32,20 @@ function parseKeyValue(arg, alias) {
     }
     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, opts = {}) {
     const { alias = {}, boolean = [], string = [], default: defaults = {} } = opts;
     const result = { ...defaults };

package/dist/utils/assert.js

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

package/dist/utils/asyncQueue.js

@@ -1,4 +1,15 @@
 import { nextTick } from "./nextTick.js";
+/**
+ * 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 {
     queue = [];
     maxQueueLength = Infinity;

package/dist/utils/deferred.js

@@ -1,3 +1,6 @@
+/**
+ * Create a promise that can be resolved/rejected later
+ */
 export class Deferred {
     promise;
     resolve;

package/dist/utils/logger.js

@@ -1,3 +1,6 @@
+/**
+ * The available log levels
+ */
 export const LogLevel = {
     error: 0,
     warn: 1,
@@ -5,6 +8,19 @@ export const LogLevel = {
     verbose: 3,
     debug: 4,
 };
+/**
+ * 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 {
     defaultError = console.error;
     defaultWarn = console.warn;
@@ -26,4 +42,17 @@ export class Logger {
         this.debug = logLevel > 3 ? this.defaultDebug : this.noop;
     }
 }
+/**
+ * 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 = new Logger();

package/dist/utils/mod.js

@@ -1,3 +1,7 @@
+/**
+ *  This module provides various utilities
+ *  @module
+ */
 export { assert } from "./assert.js";
 export { Deferred } from "./deferred.js";
 export { Logger, logger, LogLevel } from "./logger.js";

package/dist/utils/nextTick.js

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

package/dist/utils/platform.js

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

package/mqttPacket/AuthenticationResult.ts

@@ -1,7 +1,6 @@
 /**
  *  Possible MQTT authentication results
  */
-
 export const AuthenticationResult = {
   ok: 0,
   unacceptableProtocol: 1,
@@ -11,6 +10,9 @@ export const AuthenticationResult = {
   notAuthorized: 5,
 } as const;
 
+/**
+ * Reverse lookup for AuthenticationResult
+ */
 export const AuthenticationResultByNumber: Record<number, string> = Object
   .fromEntries(
     Object.entries(AuthenticationResult).map(([k, v]) => [v, k]),

package/mqttPacket/connack.ts

@@ -4,6 +4,10 @@ import { BitMask } from "./BitMask.ts";
 import { booleanFlag, Decoder, DecoderError } from "./decoder.ts";
 import { AuthenticationResultByNumber } from "./AuthenticationResult.ts";
 
+/**
+ * ConnackPacket is sent from the server to the client in response to a connect packet.
+ * It indicates that the connect is accepted.
+ */
 export type ConnackPacket = {
   type: TPacketType;
   sessionPresent: boolean;

package/mqttPacket/connect.ts

@@ -9,6 +9,9 @@ import {
   hasEmptyFlags,
 } from "./decoder.ts";
 
+/**
+ * ConnectPacket is sent from the client to the server to initiate a connection.
+ */
 export type ConnectPacket = {
   type: TPacketType;
   protocolName?: string;

package/mqttPacket/disconnect.ts

@@ -2,6 +2,10 @@ import { PacketType } from "./PacketType.ts";
 import { isEmptyBuf } from "./decoder.ts";
 import type { TPacketType } from "./types.ts";
 
+/**
+ * DisconnectPacket is the final control packet sent from the client to the server.
+ * It indicates that the client is disconnecting cleanly.
+ */
 export type DisconnectPacket = {
   type: TPacketType;
 };

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,
@@ -33,6 +39,9 @@ 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

package/mqttPacket/pingreq.ts

@@ -2,6 +2,9 @@ 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;
 };

package/mqttPacket/pingres.ts

@@ -2,6 +2,10 @@ 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;
 };

package/mqttPacket/puback.ts

@@ -3,6 +3,9 @@ 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;

package/mqttPacket/pubcomp.ts

@@ -3,6 +3,10 @@ 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;

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;

package/mqttPacket/pubrec.ts

@@ -3,6 +3,10 @@ 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;

package/mqttPacket/pubrel.ts

@@ -3,6 +3,10 @@ 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;

package/mqttPacket/suback.ts

@@ -3,6 +3,10 @@ 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;

package/mqttPacket/subscribe.ts

@@ -4,12 +4,18 @@ 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;

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,6 +3,10 @@ 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;

package/mqttPacket/unsubscribe.ts

@@ -4,6 +4,9 @@ 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;

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.1",
+  "version": "1.6.2",
   "description": "MQTT client & server for Deno & NodeJS",
   "type": "module",
   "scripts": {

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,3 +1,7 @@
+/**
+ *  This module provides various utilities
+ *  @module
+ */
 export { assert } from "./assert.ts";
 export { Deferred } from "./deferred.ts";
 export { Logger, logger, LogLevel } from "./logger.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";
+
+/**
+ * @returns an array of command line arguments
+ */
 export function getArgs(): string[] {
   return argv.slice(2);
 }