@seriousme/opifex 1.6.0 → 1.6.2

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ### Changed
 
+## [v1.6.2] 19-01-2025
+
+### Changed
+
+- fix: added more JSdoc comments
+
+## [v1.6.1] 18-01-2025
+
+### Changed
+
+- fix: fixed Deno lint type errors
+
 ## [v1.6.0] 18-01-2025
 
 ### Changed

package/bin/conformanceServer.ts

@@ -3,8 +3,7 @@
 
 import { AuthenticationResult } from "../server/mod.ts";
 import type { Context, TAuthenticationResult, Topic } from "../server/mod.ts";
-import { logger, LogLevel } from "../utils/mod.ts";
-import { getArgs, parseArgs } from "../utils/mod.ts";
+import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.ts";
 import { TcpServer } from "../node/tcpServer.ts";
 
 const utf8Decoder = new TextDecoder();

package/bin/mqtt.ts

@@ -1,9 +1,8 @@
 #!/usr/bin/env -S node --experimental-strip-types
 import { DEFAULT_URL } from "../client/mod.ts";
-import { logger, LogLevel } from "../utils/mod.ts";
-import { getArgs, parseArgs } from "../utils/mod.ts";
 import { getFileData, TcpClient } from "../node/tcpClient.ts";
-import type { Args } from "../utils/args.ts";
+import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.ts";
+import type { Args } from "../utils/mod.ts";
 
 const client = new TcpClient();
 const encoder = new TextEncoder();

package/deno/tcpClient.ts

@@ -1,10 +1,24 @@
-// 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";
 
-export async function getFileData(filename: string | undefined) {
+/**
+ * @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> {
   if (!filename) {
     return;
   }
@@ -15,8 +29,16 @@ 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 async connectMQTT(hostname: string, port = 1883) {
+  protected async connectMQTT(
+    hostname: string,
+    port = 1883,
+  ): Promise<Deno.TcpConn> {
     logger.debug({ hostname, port });
     return await Deno.connect({ hostname, port });
   }
@@ -27,7 +49,7 @@ export class TcpClient extends Client {
     caCerts?: string[],
     cert?: string,
     key?: string,
-  ) {
+  ): Promise<Deno.TlsConn> {
     logger.debug({ hostname, port, caCerts, cert });
     return await Deno.connectTls({ hostname, port, caCerts, cert, key });
   }

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;
@@ -23,14 +30,14 @@ export class TcpServer {
     this.listener.close();
   }
 
-  get port() {
+  get port(): number | undefined {
     if (this.listener.addr.transport === "tcp") {
       return this.listener.addr.port;
     }
     return undefined;
   }
 
-  get address() {
+  get address(): string | undefined {
     if (this.listener.addr.transport === "tcp") {
       return this.listener.addr.hostname;
     }

package/deno.json

@@ -1,11 +1,11 @@
 {
   "name": "@seriousme/opifex",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "exports": {
     "./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/dist/bin/conformanceServer.js

@@ -1,8 +1,7 @@
 #!/usr/bin/env -S node --experimental-strip-types
 // this server is intended to be used with https://github.com/eclipse/iottestware
 import { AuthenticationResult } from "../server/mod.js";
-import { logger, LogLevel } from "../utils/mod.js";
-import { getArgs, parseArgs } from "../utils/mod.js";
+import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.js";
 import { TcpServer } from "../node/tcpServer.js";
 const utf8Decoder = new TextDecoder();
 const userTable = new Map();

package/dist/bin/mqtt.js

@@ -1,8 +1,7 @@
 #!/usr/bin/env -S node --experimental-strip-types
 import { DEFAULT_URL } from "../client/mod.js";
-import { logger, LogLevel } from "../utils/mod.js";
-import { getArgs, parseArgs } from "../utils/mod.js";
 import { getFileData, TcpClient } from "../node/tcpClient.js";
+import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.js";
 const client = new TcpClient();
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();

package/dist/mqttPacket/AuthenticationResult.js

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

package/dist/mqttPacket/connack.js

@@ -2,7 +2,7 @@ import { PacketType } from "./PacketType.js";
 import { BitMask } from "./BitMask.js";
 import { booleanFlag, Decoder, DecoderError } from "./decoder.js";
 import { AuthenticationResultByNumber } from "./AuthenticationResult.js";
-export default {
+export const connack = {
     encode(packet) {
         const flags = 0;
         return {

package/dist/mqttPacket/connect.js

@@ -8,7 +8,7 @@ function invalidProtocolName(version, name) {
     }
     return false;
 }
-export default {
+export const connect = {
     encode(packet) {
         const flags = 0;
         const protocolLevel = 4;

package/dist/mqttPacket/disconnect.js

@@ -1,6 +1,6 @@
 import { PacketType } from "./PacketType.js";
 import { isEmptyBuf } from "./decoder.js";
-export default {
+export const disconnect = {
     encode(_packet) {
         const flags = 0;
         return { flags, bytes: [] };

package/dist/mqttPacket/mod.js

@@ -1,21 +1,26 @@
+/**
+ *  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";
-import connect from "./connect.js";
-import connack from "./connack.js";
+import { connect } from "./connect.js";
+import { connack } from "./connack.js";
 import { AuthenticationResult, AuthenticationResultByNumber, } from "./AuthenticationResult.js";
-import publish from "./publish.js";
-import puback from "./puback.js";
-import pubrec from "./pubrec.js";
-import pubrel from "./pubrel.js";
-import pubcomp from "./pubcomp.js";
-import subscribe from "./subscribe.js";
-import suback from "./suback.js";
-import unsubscribe from "./unsubscribe.js";
-import unsuback from "./unsuback.js";
-import pingreq from "./pingreq.js";
-import pingres from "./pingres.js";
-import disconnect from "./disconnect.js";
+import { publish } from "./publish.js";
+import { puback } from "./puback.js";
+import { pubrec } from "./pubrec.js";
+import { pubrel } from "./pubrel.js";
+import { pubcomp } from "./pubcomp.js";
+import { subscribe } from "./subscribe.js";
+import { suback } from "./suback.js";
+import { unsubscribe } from "./unsubscribe.js";
+import { unsuback } from "./unsuback.js";
+import { pingreq } from "./pingreq.js";
+import { pingres } from "./pingres.js";
+import { disconnect } from "./disconnect.js";
 import { DecoderError } from "./decoder.js";
 export { AuthenticationResult, AuthenticationResultByNumber, decodeLength, encodeLength, invalidTopic, invalidTopicFilter, invalidUTF8, PacketNameByType, PacketType, };
 export const packetsByType = [

package/dist/mqttPacket/pingreq.js

@@ -1,6 +1,6 @@
 import { PacketType } from "./PacketType.js";
 import { hasEmptyFlags, isEmptyBuf } from "./decoder.js";
-export default {
+export const pingreq = {
     encode(_packet) {
         const flags = 0;
         return { flags, bytes: [] };

package/dist/mqttPacket/pingres.js

@@ -1,6 +1,6 @@
 import { PacketType } from "./PacketType.js";
 import { isEmptyBuf } from "./decoder.js";
-export default {
+export const pingres = {
     encode(_packet) {
         const flags = 0;
         return { flags, bytes: [] };

package/dist/mqttPacket/puback.js

@@ -1,7 +1,7 @@
 import { PacketType } from "./PacketType.js";
 import { Decoder } from "./decoder.js";
 import { Encoder } from "./encoder.js";
-export default {
+export const puback = {
     encode(packet) {
         const flags = 0;
         const encoder = new Encoder();

package/dist/mqttPacket/pubcomp.js

@@ -1,7 +1,7 @@
 import { PacketType } from "./PacketType.js";
 import { Decoder } from "./decoder.js";
 import { Encoder } from "./encoder.js";
-export default {
+export const pubcomp = {
     encode(packet) {
         const flags = 0;
         const encoder = new Encoder();

package/dist/mqttPacket/publish.js

@@ -2,7 +2,7 @@ import { PacketType } from "./PacketType.js";
 import { BitMask } from "./BitMask.js";
 import { Encoder, EncoderError } from "./encoder.js";
 import { booleanFlag, Decoder, DecoderError } from "./decoder.js";
-export default {
+export const publish = {
     encode(packet) {
         const qos = packet.qos || 0;
         const flags = (packet.dup ? BitMask.bit3 : 0) +

package/dist/mqttPacket/pubrec.js

@@ -1,7 +1,7 @@
 import { PacketType } from "./PacketType.js";
 import { Decoder } from "./decoder.js";
 import { Encoder } from "./encoder.js";
-export default {
+export const pubrec = {
     encode(packet) {
         const flags = 0;
         const encoder = new Encoder();

package/dist/mqttPacket/pubrel.js

@@ -1,7 +1,7 @@
 import { PacketType } from "./PacketType.js";
 import { Decoder } from "./decoder.js";
 import { Encoder } from "./encoder.js";
-export default {
+export const pubrel = {
     encode(packet) {
         const flags = 0;
         const encoder = new Encoder();

package/dist/mqttPacket/suback.js

@@ -1,7 +1,7 @@
 import { PacketType } from "./PacketType.js";
 import { Encoder } from "./encoder.js";
 import { Decoder } from "./decoder.js";
-export default {
+export const suback = {
     encode(packet) {
         const flags = 0;
         const encoder = new Encoder();

package/dist/mqttPacket/subscribe.js

@@ -2,7 +2,7 @@ import { PacketType } from "./PacketType.js";
 import { BitMask } from "./BitMask.js";
 import { Encoder } from "./encoder.js";
 import { booleanFlag, Decoder, DecoderError } from "./decoder.js";
-export default {
+export const subscribe = {
     encode(packet) {
         // 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

package/dist/mqttPacket/unsuback.js

@@ -1,7 +1,7 @@
 import { PacketType } from "./PacketType.js";
 import { Decoder } from "./decoder.js";
 import { Encoder } from "./encoder.js";
-export default {
+export const unsuback = {
     encode(packet) {
         const flags = 0;
         const encoder = new Encoder();

package/dist/mqttPacket/unsubscribe.js

@@ -2,7 +2,7 @@ import { PacketType } from "./PacketType.js";
 import { BitMask } from "./BitMask.js";
 import { Encoder } from "./encoder.js";
 import { booleanFlag, Decoder, DecoderError } from "./decoder.js";
-export default {
+export const unsubscribe = {
     encode(packet) {
         // 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

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,10 @@ export const AuthenticationResult = {
   notAuthorized: 5,
 } as const;
 
-export const AuthenticationResultByNumber = Object.fromEntries(
-  Object.entries(AuthenticationResult).map(([k, v]) => [v, k]),
-);
+/**
+ * Reverse lookup for AuthenticationResult
+ */
+export const AuthenticationResultByNumber: Record<number, string> = Object
+  .fromEntries(
+    Object.entries(AuthenticationResult).map(([k, v]) => [v, k]),
+  );

package/mqttPacket/PacketType.ts

@@ -16,6 +16,6 @@ export const PacketType = {
   disconnect: 14,
 } as const;
 
-export const PacketNameByType = Object.fromEntries(
+export const PacketNameByType: Record<number, string> = Object.fromEntries(
   Object.entries(PacketType).map(([k, v]) => [v, k]),
 );

package/mqttPacket/connack.ts

@@ -4,13 +4,20 @@ 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;
   returnCode: TAuthenticationResult;
 };
 
-export default {
+export const connack: {
+  encode(packet: ConnackPacket): { flags: number; bytes: number[] };
+  decode(buffer: Uint8Array, _flags: number): ConnackPacket | undefined;
+} = {
   encode(packet: ConnackPacket): { flags: number; bytes: number[] } {
     const flags = 0;
     return {

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;
@@ -33,8 +36,11 @@ function invalidProtocolName(version: number, name: string): boolean {
   return false;
 }
 
-export default {
-  encode(packet: ConnectPacket) {
+export const connect: {
+  encode(packet: ConnectPacket): { flags: number; bytes: number[] };
+  decode(buffer: Uint8Array, flags: number): ConnectPacket;
+} = {
+  encode(packet: ConnectPacket): { flags: number; bytes: number[] } {
     const flags = 0;
 
     const protocolLevel = 4;

package/mqttPacket/disconnect.ts

@@ -2,12 +2,19 @@ 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;
 };
 
-export default {
-  encode(_packet: DisconnectPacket) {
+export const disconnect: {
+  encode(_packet: DisconnectPacket): { flags: number; bytes: number[] };
+  decode(buffer: Uint8Array, _flags: number): DisconnectPacket;
+} = {
+  encode(_packet: DisconnectPacket): { flags: number; bytes: number[] } {
     const flags = 0;
     return { flags, bytes: [] };
   },