@seriousme/opifex 2.0.3 → 2.2.0

package/client/ConnectionState.ts

@@ -20,5 +20,5 @@ export const ConnectionState = {
 /**
  * @description Type representing the possible values of ConnectionState
  */
-export type TConnectionState =
+export type ConnectionState =
   (typeof ConnectionState)[keyof typeof ConnectionState];

package/client/client.ts

@@ -8,19 +8,20 @@ import {
 } from "./deps.ts";
 
 import type {
+  AuthenticationResult,
   ConnectPacket,
-  IStore,
+  ProtocolLevel,
   PublishPacket,
   SockConn,
+  Store,
   SubscribePacket,
-  TAuthenticationResult,
 } from "./deps.ts";
 
 import { noop } from "../utils/mod.ts";
 
 import { Context } from "./context.ts";
 import type { AuthenticatedResult } from "./context.ts";
-import type { TConnectionState } from "./ConnectionState.ts";
+import type { ConnectionState } from "./ConnectionState.ts";
 import { BufferedAsyncIterable } from "./deps.ts";
 
 /**
@@ -32,18 +33,25 @@ function generateClientId(prefix: string): string {
   return `${prefix}-${Math.random().toString().slice(-10)}`;
 }
 
-type ConnectOptions = Omit<
+/** All properties of a connect packet, except for type and protocol name */
+export type ConnectOptions = Omit<
   ConnectPacket,
   "type" | "protocolName"
 >;
 
 /** ConnectParameters define how to connect */
 export type ConnectParameters = {
+  /** the URL to connect to */
   url?: URL | undefined;
+  /** any CA Certs to trust */
   caCerts?: string[] | undefined;
+  /** the clients certificate */
   cert?: string | undefined;
+  /** the clients private key*/
   key?: string | undefined;
+  /** number of retries before stopping connection attempts */
   numberOfRetries?: number | undefined;
+  /** connect options */
   options?: ConnectOptions | undefined;
 };
 
@@ -80,7 +88,7 @@ function backOffSleep(random: boolean, attempt: number): Promise<void> {
 /** the default MQTT URL to connect to */
 export const DEFAULT_URL = "mqtt://localhost:1883/";
 /** the default protocol level to connect with*/
-export const DEFAULT_PROTOCOLLEVEL = MQTTLevel.v4;
+export const DEFAULT_PROTOCOLLEVEL = MQTTLevel.v4 as ProtocolLevel;
 /** the default keepalive time */
 export const DEFAULT_KEEPALIVE = 60; // 60 seconds
 const DEFAULT_RETRIES = 3; // on first connect
@@ -110,6 +118,7 @@ function normalizeError(err: unknown): Error {
  * connection type that is supported by the subclass.
  */
 export class Client {
+  /** callback to handle v5 extended authentication, see /examples folder */
   public onAuth: (
     authMethod: string,
     authData: Uint8Array,
@@ -119,21 +128,36 @@ export class Client {
       reasonString: "No authentication method configured",
     };
   };
+  /** callback for errors */
   public onError: (err: Error) => void = noop;
+  /** callback for publish packets */
   public onPacket: (pkt: PublishPacket) => void | Promise<void> = noop;
+  /** callback once connected */
   public onConnected: () => void = noop;
+  /** callback once disconnected */
   public onDisconnected: () => void = noop;
+  /** callback when reconnecting */
   public onReconnecting: () => void = noop;
 
+  /** clientId prefix used when automatically generating a client Id */
   protected clientIdPrefix = CLIENTID_PREFIX;
+  /** number of times to retry connect */
   protected numberOfRetries = DEFAULT_RETRIES;
+  /** the URL to connect to */
   protected connectUrl: URL = new URL(DEFAULT_URL);
+  /** the keepAlive value in number of seconds */
   protected keepAlive = DEFAULT_KEEPALIVE;
+  /** the requested protocol level */
   protected protocolLevel = DEFAULT_PROTOCOLLEVEL;
+  /** try auto reconnect if connection is lost */
   protected autoReconnect = true;
+  /** any CA Certs to trust */
   protected caCerts?: string[] | undefined;
+  /** the clients certificate */
   protected cert?: string | undefined;
+  /** the clients private key*/
   protected key?: string | undefined;
+  /** the MQTT clientId */
   protected clientId: string;
   private ctx: Context;
   private connectPacket?: ConnectPacket;
@@ -141,17 +165,25 @@ export class Client {
   /**
    * Creates a new MQTT client instance
    */
-  constructor(store?: IStore) {
+  constructor(store?: Store) {
     const cStore = store ? store : new MemoryStore();
     this.ctx = new Context(cStore, this);
     this.clientId = generateClientId(this.clientIdPrefix);
     this.numberOfRetries = DEFAULT_RETRIES;
   }
 
-  public get connectionState(): TConnectionState {
+  /**
+   * Current connection state
+   * @returns connectionState as ConnectionState
+   */
+  public get connectionState(): ConnectionState {
     return this.ctx.connectionState;
   }
 
+  /**
+   * Current configured connection URL
+   * @returns URL object
+   */
   public get url(): URL {
     return this.connectUrl;
   }
@@ -222,7 +254,7 @@ export class Client {
    * @param params - Connection parameters
    * @returns Promise resolving to authentication result
    */
-  connect(params: ConnectParameters = {}): Promise<TAuthenticationResult> {
+  connect(params: ConnectParameters = {}): Promise<AuthenticationResult> {
     this.connectUrl = params?.url || this.connectUrl;
     this.numberOfRetries = params.numberOfRetries || this.numberOfRetries;
     this.caCerts = params?.caCerts;
@@ -240,7 +272,7 @@ export class Client {
       type: PacketType.connect,
       ...options,
     };
-    const deferred = new Deferred<TAuthenticationResult>();
+    const deferred = new Deferred<AuthenticationResult>();
     this.ctx.unresolvedConnect = deferred;
     this.doConnect();
     return deferred.promise;

package/client/context.ts

@@ -8,22 +8,20 @@ import {
 } from "./deps.ts";
 import type {
   AnyPacket,
+  AuthenticationResult,
   ConnectPacket,
-  IStore,
   PacketId,
   ProtocolLevel,
   PublishPacket,
+  ReasonCode,
   ReturnCodes,
   SockConn,
+  Store,
   SubscribePacket,
-  TAuthenticationResult,
-  TPacketType,
-  TReasonCode,
   UnsubscribePacket,
 } from "./deps.ts";
 
 import { handlePacket } from "./handlers/handlePacket.ts";
-import type { TConnectionState } from "./ConnectionState.ts";
 import { ConnectionState } from "./ConnectionState.ts";
 import type { Client } from "./client.ts";
 import { assert } from "../utils/assert.ts";
@@ -31,7 +29,7 @@ import { assert } from "../utils/assert.ts";
 /**
  * packets not allowed during authentication
  */
-function blockedDuringAuthentication(pktType: TPacketType) {
+function blockedDuringAuthentication(pktType: PacketType) {
   return (
     pktType === PacketType.publish ||
     pktType === PacketType.subscribe ||
@@ -41,24 +39,24 @@ function blockedDuringAuthentication(pktType: TPacketType) {
 
 /** Possible results from authHandler */
 export type AuthenticatedResult = {
-  reasonCode: TReasonCode;
+  reasonCode: ReasonCode;
   reasonString?: string;
   authData?: Uint8Array;
 };
 
 export class Context {
   mqttConn?: MqttConn;
-  #connectionState: TConnectionState;
+  #connectionState: ConnectionState;
   protocolLevel: ProtocolLevel;
   pingTimer?: Timer;
-  unresolvedConnect?: Deferred<TAuthenticationResult>;
+  unresolvedConnect?: Deferred<AuthenticationResult>;
   unresolvedPublish: Map<PacketId, Deferred<void>>;
   unresolvedSubscribe: Map<PacketId, Deferred<ReturnCodes>>;
   unresolvedUnSubscribe: Map<PacketId, Deferred<void>>;
-  store: IStore;
+  store: Store;
   #client: Client;
 
-  constructor(store: IStore, client: Client) {
+  constructor(store: Store, client: Client) {
     this.#client = client;
     this.store = store;
     this.#connectionState = ConnectionState.offline;
@@ -68,11 +66,11 @@ export class Context {
     this.unresolvedUnSubscribe = new Map();
   }
 
-  get connectionState(): TConnectionState {
+  get connectionState(): ConnectionState {
     return this.#connectionState;
   }
 
-  set connectionState(state: TConnectionState) {
+  set connectionState(state: ConnectionState) {
     this.#connectionState = state;
     switch (state) {
       case "connected":

package/client/deps.ts

@@ -17,10 +17,7 @@ export type {
   ReturnCodes,
   SubackPacket,
   SubscribePacket,
-  TAuthenticationResult,
   Topic,
-  TPacketType,
-  TReasonCode,
   UnsubackPacket,
   UnsubscribePacket,
 } from "../mqttPacket/mod.ts";
@@ -38,8 +35,14 @@ export {
 } from "../mqttPacket/mod.ts";
 
 export { MqttConn } from "../mqttConn/mqttConn.ts";
-export type { SockConn } from "../socket/socket.ts";
+export type {
+  NetAddr,
+  SockAddr,
+  SockConn,
+  UnixAddr,
+  VsockAddr,
+} from "../socket/socket.ts";
 export { Timer } from "../timer/timer.ts";
 export { BufferedAsyncIterable, Deferred, logger } from "../utils/mod.ts";
 export { MemoryStore } from "./store/memoryStore.ts";
-export type { IStore } from "./store/store.ts";
+export type { Store } from "./store/store.ts";

package/client/handlers/handleConnack.ts

@@ -1,7 +1,7 @@
 import type { Context } from "../context.ts";
 import { ConnectionState } from "../ConnectionState.ts";
 import { AuthenticationResultByNumber, ReasonCodeByNumber } from "../deps.ts";
-import type { ConnackPacket, TReasonCode } from "../deps.ts";
+import type { ConnackPacket, ReasonCode } from "../deps.ts";
 
 /**
  * Handles the CONNACK packet received from the MQTT broker
@@ -38,7 +38,7 @@ export async function handleConnack(ctx: Context, packet: ConnackPacket) {
   }
 
   const errMsg = packet.protocolLevel === 5
-    ? ReasonCodeByNumber[result as TReasonCode]
+    ? ReasonCodeByNumber[result as ReasonCode]
     : AuthenticationResultByNumber[result];
 
   const err = new Error(

package/client/mod.ts

@@ -8,10 +8,21 @@ export {
   DEFAULT_PROTOCOLLEVEL,
   DEFAULT_URL,
 } from "./client.ts";
-export { MQTTLevel, ReasonCode } from "./deps.ts";
-export type { ProtocolLevel, QoS } from "./deps.ts";
+export { logger, MQTTLevel, ReasonCode } from "./deps.ts";
+export type {
+  AuthenticationResult,
+  NetAddr,
+  ProtocolLevel,
+  QoS,
+  SockAddr,
+  SockConn,
+  UnixAddr,
+  VsockAddr,
+} from "./deps.ts";
 export type {
   ConnectParameters,
   PublishParameters,
   SubscribeParameters,
 } from "./client.ts";
+
+export type { ConnectionState } from "./ConnectionState.ts";

package/client/store/memoryStore.ts

@@ -5,20 +5,21 @@
 import { assert } from "./deps.ts";
 import type { PacketId } from "./deps.ts";
 
-import {
-  type IStore,
-  MAX_PACKET_ID,
-  type PacketStore,
-  type PendingAckOutgoing,
-  type pendingIncoming,
-  type PendingOutgoing,
-  type PendingOutgoingPackets,
+import { MAX_PACKET_ID } from "./store.ts";
+
+import type {
+  PacketStore,
+  PendingAckOutgoing,
+  pendingIncoming,
+  PendingOutgoing,
+  PendingOutgoingPackets,
+  Store,
 } from "./store.ts";
 
 /**
- * In-memory implementation of the IStore interface for managing MQTT packet storage
+ * In-memory implementation of the Store interface for managing MQTT packet storage
  */
-export class MemoryStore implements IStore {
+export class MemoryStore implements Store {
   /** Current packet ID counter */
   private packetId: PacketId;
 

package/client/store/store.ts

@@ -46,7 +46,7 @@ export type PendingOutgoingPackets = PendingAckOutgoing | PendingOutgoing;
 /**
  * Interface defining the storage requirements for MQTT packet state management
  */
-export interface IStore {
+export interface Store {
   /** Store for incoming packets pending processing */
   pendingIncoming: PacketStore<pendingIncoming>;
 

package/deno/mod.ts

@@ -0,0 +1,7 @@
+/**
+ * Opifex default exports for Deno
+ * @module
+ */
+
+export * from "../client/mod.ts";
+export * from "../server/mod.ts";

package/deno/tcpClient.ts

@@ -3,16 +3,16 @@
  * 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";
+
+import { Client, logger } from "../client/mod.ts";
+import type { SockConn } from "../client/mod.ts";
 
 /**
- * @function getFileData
+ * Fetches data from a file and returns it as a string
+ *
  * @param filename
  * @returns Promise
  *
- * Fetches data from a file and returns it as a string
  * @example
  * const data = await getFileData("data.txt");
  */
@@ -29,12 +29,16 @@ export async function getFileData(
   return data;
 }
 
-/*
- * TCPclient extends the Client class to provide TCP based clients
+/**
+ * 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 {
+  /** Connect using MQTT over TCP
+   * @param hostname the name of the host to connect to
+   * @param port the port number
+   */
   protected async connectMQTT(
     hostname: string,
     port = 1883,
@@ -43,6 +47,15 @@ export class TcpClient extends Client {
     return await Deno.connect({ hostname, port });
   }
 
+  /**
+   * Connect using MQTT over TLS
+   * @param hostname the name of the host to connect to
+   * @param port the port number
+   * @param caCerts the CA certificates to trust
+   * @param cert the clients certificate
+   * @param key the clients private key
+   * @returns a Deno.TlsConn object
+   */
   protected async connectMQTTS(
     hostname: string,
     port = 8883,
@@ -61,7 +74,7 @@ export class TcpClient extends Client {
     return await Deno.connectTls(connectOpts);
   }
 
-  // overload createConn from the base client class
+  /** createConn is used by the base client class */
   protected override createConn(): Promise<SockConn> {
     const { protocol, hostname, port: portStr } = this.connectUrl;
     const port = Number(portStr);

package/deno/tcpServer.ts

@@ -7,12 +7,16 @@
 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
+/**
+ * TCP server that wraps a MqttServer, see the /examples folder
  */
 export class TcpServer {
   private listener: Deno.Listener<Deno.Conn>;
   private mqttServer: MqttServer;
+
+  /**
+   * Create a new TCP server
+   */
   constructor(
     serverOptions: Deno.TcpListenOptions,
     mqttOptions: MqttServerOptions,
@@ -21,16 +25,26 @@ export class TcpServer {
     this.mqttServer = new MqttServer(mqttOptions);
   }
 
-  async start() {
+  /**
+   * Start listening
+   */
+  async start(): Promise<void> {
     for await (const conn of this.listener) {
       this.mqttServer.serve(conn);
     }
   }
-  stop() {
+
+  /**
+   * Stop listening
+   */
+  stop(): void {
     this.mqttServer.close(true);
     this.listener.close();
   }
 
+  /**
+   * The port number the server is listening on
+   */
   get port(): number | undefined {
     // deno-coverage-ignore-start
     if (this.listener.addr.transport === "tcp") {
@@ -40,6 +54,9 @@ export class TcpServer {
     // deno-coverage-ignore-stop
   }
 
+  /**
+   * The address the server is listening on
+   */
   get address(): string | undefined {
     // deno-coverage-ignore-start
     if (this.listener.addr.transport === "tcp") {

package/deno/tlsServer.ts

@@ -7,12 +7,15 @@
 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
+/**
+ * TLS server that wraps a MqttServer, see the /examples folder
  */
 export class TlsServer {
   private listener: Deno.TlsListener;
   private mqttServer: MqttServer;
+  /**
+   * Create a new TLS server
+   */
   constructor(
     serverOptions: Deno.ListenTlsOptions & Deno.TlsCertifiedKeyPem,
     mqttOptions: MqttServerOptions,
@@ -21,20 +24,33 @@ export class TlsServer {
     this.mqttServer = new MqttServer(mqttOptions);
   }
 
-  async start() {
+  /**
+   * Start listening
+   */
+  async start(): Promise<void> {
     for await (const conn of this.listener) {
       this.mqttServer.serve(conn);
     }
   }
-  stop() {
+
+  /**
+   * Stop listening
+   */
+  stop(): void {
     this.mqttServer.close();
     this.listener.close();
   }
+  /**
+   * The port number the server is listening on
+   */
   // deno-coverage-ignore-start
   get port(): number | undefined {
     return this.listener.addr.port;
   }
 
+  /**
+   * The address the server is listening on
+   */
   get address(): string | undefined {
     return this.listener.addr.hostname;
   }

package/deno/wsServer.ts

@@ -1,9 +1,16 @@
+/**
+ * This a Deno specific implementation of a WebSocket server
+ * @module
+ */
 import { MqttServer } from "../server/mod.ts";
 import type { MqttServerOptions } from "../server/mod.ts";
 import { logger } from "../utils/logger.ts";
 import { wrapWebSocket } from "../web/wrapWebSocket.ts";
 import type { HostnamePort } from "../web/wrapWebSocket.ts";
 
+/**
+ * WebSocket server that wraps a MqttServer, see the /examples folder
+ */
 export class WsServer {
   private server?: Deno.HttpServer;
   private mqttServer: MqttServer;
@@ -12,6 +19,9 @@ export class WsServer {
     hostname?: string;
   };
 
+  /**
+   * Create a new WebSocket server
+   */
   constructor(
     serverOptions: Deno.ServeOptions & { port: number; hostname?: string },
     mqttOptions: MqttServerOptions,
@@ -19,6 +29,7 @@ export class WsServer {
     this.listenOptions = serverOptions;
     this.mqttServer = new MqttServer(mqttOptions);
   }
+
   private async handleWsClient(socket: WebSocket, remoteAddr: HostnamePort) {
     const conn = await wrapWebSocket(socket, remoteAddr);
     logger.debug("created conn");
@@ -26,6 +37,9 @@ export class WsServer {
     logger.debug("serving mqtt");
   }
 
+  /**
+   * Start listening
+   */
   async start(): Promise<void> {
     this.server = Deno.serve(this.listenOptions, (req, info) => {
       const { hostname, port } = info.remoteAddr;
@@ -46,6 +60,9 @@ export class WsServer {
     await this.server.finished;
   }
 
+  /**
+   * Stop listening
+   */
   stop(): void {
     this.mqttServer.close(true);
     if (this.server) {
@@ -53,6 +70,9 @@ export class WsServer {
     }
   }
 
+  /**
+   * The port number the server is listening on
+   */
   get port(): number | undefined {
     // deno-coverage-ignore-start
     if (this.server?.addr.transport === "tcp") {
@@ -62,6 +82,9 @@ export class WsServer {
     // deno-coverage-ignore-stop
   }
 
+  /**
+   * The address the server is listening on
+   */
   get address(): string | undefined {
     // deno-coverage-ignore-start
     if (this.server?.addr.transport === "tcp") {

package/dist/client/ConnectionState.d.ts

@@ -19,5 +19,5 @@ export declare const ConnectionState: {
 /**
  * @description Type representing the possible values of ConnectionState
  */
-export type TConnectionState = (typeof ConnectionState)[keyof typeof ConnectionState];
+export type ConnectionState = (typeof ConnectionState)[keyof typeof ConnectionState];
 //# sourceMappingURL=ConnectionState.d.ts.map

package/dist/client/ConnectionState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConnectionState.d.ts","sourceRoot":"","sources":["../../client/ConnectionState.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,eAAe;IAC1B,sDAAsD;aACtD,OAAO,EAAE,SAAS;IAClB,4DAA4D;aAC5D,UAAU,EAAE,YAAY;IACxB,sCAAsC;aACtC,SAAS,EAAE,WAAW;IACtB,gDAAgD;aAChD,aAAa,EAAE,eAAe;IAC9B,mCAAmC;aACnC,YAAY,EAAE,cAAc;IAC5B,2CAA2C;aAC3C,cAAc,EAAE,gBAAgB;CACxB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAC1B,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC"}
+{"version":3,"file":"ConnectionState.d.ts","sourceRoot":"","sources":["../../client/ConnectionState.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,eAAe;IAC1B,sDAAsD;aACtD,OAAO,EAAE,SAAS;IAClB,4DAA4D;aAC5D,UAAU,EAAE,YAAY;IACxB,sCAAsC;aACtC,SAAS,EAAE,WAAW;IACtB,gDAAgD;aAChD,aAAa,EAAE,eAAe;IAC9B,mCAAmC;aACnC,YAAY,EAAE,cAAc;IAC5B,2CAA2C;aAC3C,cAAc,EAAE,gBAAgB;CACxB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,eAAe,GACzB,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC"}