@seriousme/opifex 2.0.3 → 2.2.0

package/mqttPacket/subscribe.ts

@@ -1,13 +1,7 @@
-import type {
-  CodecOpts,
-  PacketId,
-  QoS,
-  TopicFilter,
-  TPacketType,
-  TRetainHandling,
-} from "./types.ts";
+import type { CodecOpts, PacketId, QoS, TopicFilter } from "./types.ts";
 import type { ProtocolLevelNoV5 } from "./protocolLevels.ts";
 import type { SubscribeProperties } from "./Properties.ts";
+import type { RetainHandling } from "./RetainHandling.ts";
 import { PacketType } from "./PacketType.ts";
 import { BitMask } from "./BitMask.ts";
 import { Encoder } from "./encoder.ts";
@@ -18,7 +12,7 @@ import { booleanFlag, Decoder, DecoderError } from "./decoder.ts";
  */
 export type SubscribePacketV4 = {
   /** The type of the MQTT control packet. */
-  type: TPacketType;
+  type: PacketType;
   /** The protocol version level, restricted to non-v5 variants. */
   protocolLevel: ProtocolLevelNoV5;
   /** The unique 16-bit packet identifier. */
@@ -32,7 +26,7 @@ export type SubscribePacketV4 = {
  */
 export type SubscribePacketV5 = {
   /** The type of the MQTT control packet. */
-  type: TPacketType;
+  type: PacketType;
   /** The protocol version level, strictly set to 5. */
   protocolLevel: 5;
   /** The unique 16-bit packet identifier. */
@@ -71,7 +65,7 @@ export type SubscriptionV5 = {
   /** Optional flag indicating whether messages forwarded under this subscription keep their original retain flag. */
   retainAsPublished?: boolean;
   /** Optional setting declaring how retained messages are handled when the subscription is created. */
-  retainHandling?: TRetainHandling;
+  retainHandling?: RetainHandling;
 };
 
 /** * Represents a generic union of MQTT subscription configurations (v4 or v5).
@@ -126,7 +120,7 @@ export function decode(
   buffer: Uint8Array,
   flags: number,
   codecOpts: CodecOpts,
-  packetType: TPacketType,
+  packetType: PacketType,
 ): SubscribePacket {
   // 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/mqttPacket/types.ts

@@ -1,29 +1,10 @@
 import type { BitMask } from "./BitMask.ts";
-import type { PacketType } from "./PacketType.ts";
-import type { RetainHandling } from "./RetainHandling.ts";
-import type { AuthenticationResult } from "./AuthenticationResult.ts";
-import type { ReasonCode } from "./ReasonCode.ts";
 import type { ProtocolLevel } from "./protocolLevels.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];
-
-/**
- * Type to limit reason code to valid values
- */
-export type TReasonCode = typeof ReasonCode[keyof typeof ReasonCode];
+export type BitMask = typeof BitMask[keyof typeof BitMask];
 
 /**
  * Quality of Service level
@@ -65,12 +46,6 @@ export type ReturnCodes = number[];
  */
 export type ClientId = string;
 
-/**
- * helper type to limit retain handling values
- */
-export type TRetainHandling =
-  typeof RetainHandling[keyof typeof RetainHandling];
-
 /**
  * UTF8 string pair (for v5)
  */

package/mqttPacket/unsuback.ts

@@ -1,22 +1,23 @@
-import type { CodecOpts, PacketId, TPacketType, TReasonCode } from "./types.ts";
+import type { CodecOpts, PacketId } from "./types.ts";
 import type { ProtocolLevelNoV5 } from "./protocolLevels.ts";
 import type { UnsubackProperties } from "./Properties.ts";
+import type { ReasonCode } from "./ReasonCode.ts";
 import { PacketType } from "./PacketType.ts";
 import { Decoder, hasEmptyFlags } from "./decoder.ts";
 import { Encoder } from "./encoder.ts";
 
 export type UnsubackPacketV4 = {
-  type: TPacketType;
+  type: PacketType;
   protocolLevel: ProtocolLevelNoV5;
   id: PacketId;
 };
 
 export type UnsubackPacketV5 = {
-  type: TPacketType;
+  type: PacketType;
   protocolLevel: 5;
   id: PacketId;
   properties: UnsubackProperties;
-  reasonCodes: Array<TReasonCode>;
+  reasonCodes: Array<ReasonCode>;
 };
 
 /**
@@ -49,7 +50,7 @@ export function decode(
   buffer: Uint8Array,
   flags: number,
   codecOpts: CodecOpts,
-  packetType: TPacketType,
+  packetType: PacketType,
 ): UnsubackPacket {
   hasEmptyFlags(flags);
   const decoder = new Decoder(packetType, buffer);
@@ -58,7 +59,7 @@ export function decode(
     const properties = decoder.getProperties(PacketType.unsuback);
     const reasonCodes = [];
     while (!decoder.atEnd()) {
-      const reasonCode = decoder.getReasonCode();
+      const reasonCode = decoder.geReasonCode();
       reasonCodes.push(reasonCode);
     }
     return {
@@ -66,7 +67,7 @@ export function decode(
       protocolLevel: 5,
       id,
       properties,
-      reasonCodes: reasonCodes as Array<TReasonCode>,
+      reasonCodes: reasonCodes as Array<ReasonCode>,
     };
   }
   decoder.done();

package/mqttPacket/unsubscribe.ts

@@ -1,10 +1,4 @@
-import type {
-  CodecOpts,
-  PacketId,
-  Topic,
-  TopicFilter,
-  TPacketType,
-} from "./types.ts";
+import type { CodecOpts, PacketId, Topic, TopicFilter } from "./types.ts";
 import type { ProtocolLevelNoV5 } from "./protocolLevels.ts";
 import type { UnsubscribeProperties } from "./Properties.ts";
 import { PacketType } from "./PacketType.ts";
@@ -16,7 +10,7 @@ import { Decoder, DecoderError } from "./decoder.ts";
  */
 export type UnsubscribePacketV4 = {
   /** The type of the MQTT control packet. */
-  type: TPacketType;
+  type: PacketType;
   /** The protocol version level, restricted to non-v5 variants. */
   protocolLevel: ProtocolLevelNoV5;
   /** The unique 16-bit packet identifier. */
@@ -30,7 +24,7 @@ export type UnsubscribePacketV4 = {
  */
 export type UnsubscribePacketV5 = {
   /** The type of the MQTT control packet. */
-  type: TPacketType;
+  type: PacketType;
   /** The protocol version level, strictly set to 5. */
   protocolLevel: 5;
   /** The unique 16-bit packet identifier. */
@@ -77,7 +71,7 @@ export function decode(
   buffer: Uint8Array,
   flags: number,
   codecOpts: CodecOpts,
-  packetType: TPacketType,
+  packetType: PacketType,
 ): UnsubscribePacket {
   if (flags !== 0b0010) {
     throw new DecoderError("Invalid header");

package/node/mod.ts

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

package/node/tcpClient.ts

@@ -12,7 +12,8 @@ import type { SockConn } from "../socket/socket.ts";
 import { wrapNodeSocket } from "./wrapNodeSocket.ts";
 
 /**
- * @function getFileData
+ * Fetches data from a file and returns it as a string
+ *
  * @param filename
  * @returns Promise
  *
@@ -20,7 +21,9 @@ import { wrapNodeSocket } from "./wrapNodeSocket.ts";
  * @example
  * const data = await getFileData("data.txt");
  */
-export async function getFileData(filename: string | undefined) {
+export async function getFileData(
+  filename: string | undefined,
+): Promise<string | undefined> {
   if (!filename) {
     return;
   }
@@ -31,13 +34,16 @@ export async function getFileData(filename: string | undefined) {
   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 connectMQTT(hostname: string, port = 1883): Promise<SockConn> {
     logger.debug({ hostname, port });
     return new Promise((resolve, reject) => {
@@ -55,6 +61,15 @@ export class TcpClient extends Client {
     });
   }
 
+  /**
+   * 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 SockConn object
+   */
   protected connectMQTTS(
     hostname: string,
     port = 8883,
@@ -83,7 +98,7 @@ export class TcpClient extends Client {
     });
   }
 
-  // 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/node/tcpServer.ts

@@ -14,19 +14,26 @@ type ServerOptions = {
   port?: number;
 };
 
-/*
- * 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 mqttServer: MqttServer;
   private server?: Server;
   private serverOptions;
+
+  /**
+   * Create a new TCP server
+   */
   constructor(serverOptions: ServerOptions, mqttOptions: MqttServerOptions) {
     this.mqttServer = new MqttServer(mqttOptions);
     this.serverOptions = serverOptions;
   }
 
-  async start() {
+  /**
+   * Start listening
+   */
+  async start(): Promise<void> {
     this.server = createServer((sock) =>
       this.mqttServer.serve(wrapNodeSocket(sock))
     );
@@ -39,12 +46,19 @@ export class TcpServer {
     await isListening;
     return;
   }
-  stop() {
+
+  /**
+   * Stop listening
+   */
+  stop(): void {
     this.mqttServer.close();
     this.server?.close();
   }
 
-  get port() {
+  /**
+   * The port number the server is listening on
+   */
+  get port(): number | undefined {
     const address = this.server?.address();
     // deno-coverage-ignore-start
     if (typeof address === "object" && address !== null) {
@@ -54,7 +68,10 @@ export class TcpServer {
     // deno-coverage-ignore-stop
   }
 
-  get address() {
+  /**
+   * The address the server is listening on
+   */
+  get address(): string | undefined {
     const addressResult = this.server?.address();
     // deno-coverage-ignore-start
     if (typeof addressResult === "object") {

package/node/tlsServer.ts

@@ -1,5 +1,5 @@
 /*
- * This module provides a NodeJS specific implementation of a tls socket listener
+ * This module provides a NodeJS specific implementation of a TLS socket listener
  * it uses the platform agnostic MqttServer class
  *  @module
  */
@@ -16,20 +16,26 @@ type ServerOptions = {
   cert: string;
 };
 
-/*
- * 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 mqttServer: MqttServer;
   private server?: Server;
   private serverOptions;
 
+  /**
+   * Create a new TLS server
+   */
   constructor(serverOptions: ServerOptions, mqttOptions: MqttServerOptions) {
     this.mqttServer = new MqttServer(mqttOptions);
     this.serverOptions = serverOptions;
   }
 
-  async start() {
+  /**
+   * Start listening
+   */
+  async start(): Promise<void> {
     const tlsOptions = {
       minVersion: "TLSv1.3" as const,
       key: this.serverOptions.key,
@@ -49,12 +55,19 @@ export class TlsServer {
     await isListening;
     return;
   }
-  stop() {
+
+  /**
+   * Stop listening
+   */
+  stop(): void {
     this.mqttServer.close();
     this.server?.close();
   }
 
-  get port() {
+  /**
+   * The port number the server is listening on
+   */
+  get port(): number | undefined {
     const address = this.server?.address();
     if (typeof address === "object" && address !== null) {
       return address?.port;
@@ -62,7 +75,10 @@ export class TlsServer {
     return this.serverOptions?.port;
   }
 
-  get address() {
+  /**
+   * The address the server is listening on
+   */
+  get address(): string | undefined {
     const addressResult = this.server?.address();
     // deno-coverage-ignore-start
     if (typeof addressResult === "object") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seriousme/opifex",
-  "version": "2.0.3",
+  "version": "2.2.0",
   "description": "MQTT client & server for Deno & NodeJS and Bun",
   "author": "Hans Klunder",
   "license": "MIT",
@@ -43,6 +43,11 @@
     "dist/**/*.d.ts.map"
   ],
   "exports": {
+    ".": {
+      "deno": "./deno/mod.ts",
+      "node": "./dist/node/mod.js",
+      "default": null
+    },
     "./tcpClient": {
       "deno": "./deno/tcpClient.ts",
       "default": "./dist/node/tcpClient.js"

package/persistence/basicPersistence.ts

@@ -4,10 +4,10 @@ import type {
   ClientSubscription,
   ExtPublishPacket,
   Handler,
-  IPersistence,
+  Persistence,
   ShareName,
 } from "./persistence.ts";
-import type { IStorageProvider } from "./storage.ts";
+import type { StorageProvider } from "./storage.ts";
 import { PacketDirection } from "./storage.ts";
 import { assert, getOrInsert, logger, Trie } from "./deps.ts";
 import { MAX_PACKET_ID } from "./persistence.ts";
@@ -60,14 +60,14 @@ function clonePacket(packet: ExtPublishPacket): ExtPublishPacket {
   return newPacket;
 }
 
-export class MqttPersistence implements IPersistence {
+export class MqttPersistence implements Persistence {
   private clientHandlerList = new Map<ClientId, Handler>();
   private trie = new Trie<TrieSub>();
   private packetIdCounters = new Map<ClientId, number>();
-  private storage: IStorageProvider;
+  private storage: StorageProvider;
   private sharedGroupCounters = new Map<string, number>();
 
-  constructor(storage: IStorageProvider) {
+  constructor(storage: StorageProvider) {
     this.storage = storage;
   }
 

package/persistence/deps.ts

@@ -4,10 +4,10 @@ export type {
   PublishPacket,
   PublishPacketV5,
   QoS,
+  RetainHandling,
   Subscription,
   Topic,
   TopicFilter,
-  TRetainHandling,
 } from "../mqttPacket/mod.ts";
 export { MQTTLevel, PacketType } from "../mqttPacket/mod.ts";
 export { Trie } from "../trie/trie.ts";

package/persistence/memory/memoryStorage.ts

@@ -1,6 +1,6 @@
 /**
  * @module
- * Volatile in-memory implementation of IStorageProvider.
+ * Volatile in-memory implementation of StorageProvider.
  * Completely decoupled from MQTT protocol logic.
  */
 import type { ClientId, PacketId, Topic, TopicFilter } from "../deps.ts";
@@ -10,7 +10,7 @@ import type {
   ExtPublishPacket,
   ShareName,
 } from "../persistence.ts";
-import type { IStorageProvider, StoredSubscription } from "../storage.ts";
+import type { StorageProvider, StoredSubscription } from "../storage.ts";
 import { PacketDirection } from "../storage.ts";
 import { getOrInsert, joinTopicFilter, topicFilterToRegExp } from "../deps.ts";
 
@@ -20,7 +20,7 @@ type pendingTableEntry = {
   createdAtMs: number;
 };
 
-export class MemoryStorage implements IStorageProvider {
+export class MemoryStorage implements StorageProvider {
   private seqId = 1;
   private sessionTable = new Map<ClientId, ClientRegistrationResult>();
 

package/persistence/mod.ts

@@ -14,7 +14,7 @@ export type {
 export type {
   ClientRegistrationResult,
   Handler,
-  IPersistence,
+  Persistence,
 } from "./persistence.ts";
 export { MAX_PACKET_ID } from "./persistence.ts";
 export { SqlitePersistence } from "./sqlite/sqlitePersistence.ts";

package/persistence/persistence.testing.ts

@@ -1,5 +1,5 @@
 /**
- * Shared test suite for IPersistence implementations.
+ * Shared test suite for Persistence implementations.
  * Ensures behavioral parity between MemoryPersistence and SqlitePersistence.
  */
 
@@ -10,7 +10,7 @@ import type { QoS } from "./deps.ts";
 import type {
   ClientSubscription,
   ExtPublishPacket,
-  IPersistence,
+  Persistence,
 } from "./persistence.ts";
 import type { PublishPacketV5 } from "../mqttPacket/publish.ts";
 
@@ -33,7 +33,7 @@ function createPacket(
 }
 
 async function createReceiver(
-  persistence: IPersistence,
+  persistence: Persistence,
   clientId: string,
   clean = false,
 ): Promise<{ received: ExtPublishPacket[] }> {
@@ -54,7 +54,7 @@ async function createReceiver(
 export type PersistenceFactoryOptions = {
   name: string;
   factory: () => {
-    persistence: IPersistence;
+    persistence: Persistence;
     cleanup: () => void | Promise<void>;
   };
 };

package/persistence/persistence.ts

@@ -7,8 +7,8 @@ import type {
   PacketId,
   PublishPacketV5,
   QoS,
+  RetainHandling,
   TopicFilter,
-  TRetainHandling,
 } from "./deps.ts";
 
 /**
@@ -29,7 +29,7 @@ export type ClientSubscription = {
   qos: QoS;
   noLocal?: boolean;
   retainAsPublished?: boolean;
-  retainHandling?: TRetainHandling;
+  retainHandling?: RetainHandling;
   subscriptionIdentifier?: number;
 };
 
@@ -49,7 +49,7 @@ export type ClientRegistrationResult = {
 /**
  * Interface for persistence implementations to store messages and subscriptions
  */
-export interface IPersistence {
+export interface Persistence {
   // initialize the persistence
   // e.g. setting up the data store
   initialize(): Promise<void>;

package/persistence/sqlite/sqliteStorage.ts

@@ -7,7 +7,7 @@ import type {
   ShareName,
 } from "../persistence.ts";
 import { PacketDirection } from "../storage.ts";
-import type { IStorageProvider, StoredSubscription } from "../storage.ts";
+import type { StorageProvider, StoredSubscription } from "../storage.ts";
 import { topicFilterToRegExp } from "../deps.ts";
 import {
   deleteClientState,
@@ -37,7 +37,7 @@ function deserializePacket(
   return packet;
 }
 
-export class SqliteStorage implements IStorageProvider {
+export class SqliteStorage implements StorageProvider {
   private db: sqlite.DatabaseSync;
 
   private statements: AllStatements;

package/persistence/storage.ts

@@ -15,7 +15,7 @@ export const PacketDirection = {
 export type PacketDirection =
   typeof PacketDirection[keyof typeof PacketDirection];
 
-export interface IStorageProvider {
+export interface StorageProvider {
   initialize(): Promise<void>;
   close?(): Promise<void>;
 

package/server/context.ts

@@ -11,15 +11,15 @@ import type {
   AnyPacket,
   ConnectPacket,
   ExtPublishPacket,
-  IPersistence,
   PacketId,
+  Persistence,
   ProtocolLevel,
   PublishPacket,
   PubrelPacket,
+  ReasonCode,
   ShareName,
   SockConn,
   Topic,
-  TReasonCode,
 } from "./deps.ts";
 
 import { QueueMode } from "./config.ts";
@@ -36,7 +36,7 @@ export const utf8Encoder = new TextEncoder();
 
 /** Possible results from isAuthenticated and processAuth handler */
 export type AuthenticatedResult = {
-  reasonCode: TReasonCode;
+  reasonCode: ReasonCode;
   reasonString?: string;
   authData?: Uint8Array;
 };
@@ -168,7 +168,7 @@ export class Context {
   mqttConn: MqttConn;
 
   /** The persistence layer instance used by the server. */
-  persistence: IPersistence;
+  persistence: Persistence;
 
   /** The configured authentication and authorization lifecycle hooks. */
   handlers: Handlers;
@@ -233,7 +233,7 @@ export class Context {
    */
   constructor(
     configuration: Configuration, // all settings
-    persistence: IPersistence, // The server persistence layer implementation.
+    persistence: Persistence, // The server persistence layer implementation.
     conn: SockConn, // The underlying socket connection.
     handlers: Handlers, // The validation handlers
   ) {

package/server/deps.ts

@@ -3,7 +3,7 @@ export { MqttConn } from "../mqttConn/mqttConn.ts";
 export type {
   ClientSubscription,
   ExtPublishPacket,
-  IPersistence,
+  Persistence,
   ShareName,
 } from "../persistence/persistence.ts";
 export { MemoryPersistence } from "../persistence/memory/memoryPersistence.ts";
@@ -32,7 +32,6 @@ export type {
   SubscriptionV5,
   Topic,
   TopicFilter,
-  TReasonCode,
   UnsubackPacket,
   UnsubscribePacket,
 } from "../mqttPacket/mod.ts";

package/server/handlers/completeConnect.ts

@@ -1,5 +1,5 @@
 import { AuthenticationResult, PacketType, ReasonCode } from "../deps.ts";
-import type { ProtocolLevel, TReasonCode } from "../deps.ts";
+import type { ProtocolLevel } from "../deps.ts";
 import type { Context } from "../context.ts";
 
 /**
@@ -29,7 +29,7 @@ export function reasonToReturnCode(reasonCode: number): number {
 export async function completeConnect(
   ctx: Context,
   protocolLevel: ProtocolLevel,
-  reasonCode: TReasonCode,
+  reasonCode: ReasonCode,
   reasonString: string | undefined,
 ) {
   const cfg = ctx.config.context;