fix: generate types from JSDoc

Author: wkillerud

package.json

@@ -5,7 +5,7 @@
   "main": "./dist/src/index.js",
   "types": "./types/index.d.ts",
   "exports": {
-    "types": "./types/index.js",
+    "types": "./types/index.d.ts",
     "require": "./dist/src/index.js",
     "import": "./src/index.js"
   },

src/Event.js

@@ -1,6 +1,15 @@
 import { toKey } from './utils.js';
 
+/**
+ * @template [T=unknown] payload
+ */
 export default class Event {
+    /**
+     * @constructor
+     * @param {string} channel
+     * @param {string} topic
+     * @param {T} [payload]
+     */
     constructor(channel, topic, payload) {
         this.channel = channel;
         this.topic = topic;

src/MessageBus.js

@@ -13,6 +13,9 @@ function getGlobalThis() {
     throw new Error('unable to locate global object');
 }
 
+/**
+ * @returns {{ ee: EventEmitter; sink: Sink; }}
+ */
 function getGlobalObjects() {
     let objs = getGlobalThis()['@podium'];
     if (!objs) {
@@ -25,6 +28,11 @@ function getGlobalObjects() {
     return objs;
 }
 
+/**
+ * @template [T=unknown]
+ * @typedef {(message: Event<T>) => void} MessageHandler
+ */
+
 export default class MessageBus {
     constructor() {
         const { ee, sink } = getGlobalObjects();
@@ -33,30 +41,86 @@ export default class MessageBus {
     }
 
     /**
-     * Get the latest events, newest first
+     * Returns an array of the 10 latest events for a channel and topic combination.
+     * The array is ordered such that the the latest/newest events is at the front of the array.
+     *
+     * @template [T=unknown]
+     * @param {string} channel
+     * @param {string} topic
+     * @returns {Event<T>[]}
      */
     log(channel, topic) {
         return this.sink.log(channel, topic);
     }
 
     /**
-     * Get the latest event
+     * Get the latest event for a channel and topic.
+     *
+     * @template [T=unknown]
+     * @param {string} channel
+     * @param {string} topic
+     * @returns {Event<T>}
      */
     peek(channel, topic) {
         return this.sink.peek(channel, topic);
     }
 
+    /**
+     * Publish a message for a channel and topic.
+     *
+     * @template [T=unknown]
+     * @param {string} channel
+     * @param {string} topic
+     * @param {T} [payload]
+     * @returns {Event<T>} Returns the {@link Event} object passed to subscribers.
+     */
     publish(channel, topic, payload) {
         const event = new Event(channel, topic, payload);
         this.ee.emit(event.toKey(), event);
         this.sink.push(event);
         return event;
     }
 
+    /**
+     * Subscribe to messages for a channel and topic.
+     *
+     * @template [T=unknown]
+     * @param {string} channel
+     * @param {string} topic
+     * @param {MessageHandler<T>} listener
+     *
+     * @example
+     *
+     * ```js
+     * messageBus.subscribe('channel', 'topic', (event) => {
+     *   console.log(event.payload);
+     * });
+     * ```
+     */
     subscribe(channel, topic, listener) {
         this.ee.on(toKey(channel, topic), listener);
     }
 
+    /**
+     * Remove a message listener.
+     *
+     * @template [T=unknown]
+     * @param {string} channel
+     * @param {string} topic
+     * @param {MessageHandler<T>} listener
+     *
+     * @example
+     * ```js
+     * // Declare the listener so it can be passed both to `subscribe` and `unsubscribe`.
+     * function listener(event) {
+     *   console.log(event.payload);
+     * }
+     *
+     * messageBus.subscribe('channel', 'topic', listener);
+     *
+     * messageBus.unsubscribe('channel', 'topic', listener);
+     * ```
+     */
     unsubscribe(channel, topic, listener) {
         this.ee.off(toKey(channel, topic), listener);
     }

src/Queue.js

@@ -4,6 +4,10 @@ export default class Queue {
         this.array = [];
     }
 
+    /**
+     * @template T
+     * @param {T} item
+     */
     push(item) {
         // If we are out of room, get rid of the oldest element
         if (this.array.length >= this.maxSize) {
@@ -12,10 +16,18 @@ export default class Queue {
         this.array.unshift(item);
     }
 
+    /**
+     * @template T
+     * @returns {T}
+     */
     peek() {
         return this.array[0];
     }
 
+    /**
+     * @template T
+     * @returns {T[]}
+     */
     toArray() {
         return this.array.slice();
     }

src/Sink.js

@@ -3,23 +3,47 @@ import Queue from './Queue.js';
 
 export default class Sink {
     constructor() {
+        /**
+         * @type {Map<string, Queue>}
+         */
         this.map = new Map();
     }
 
+    /**
+     * @param {string} channel
+     * @param {string} topic
+     * @returns {Queue}
+     */
     getQueue(channel, topic) {
         return this.map.get(toKey(channel, topic)) || new Queue();
     }
 
+    /**
+     * @param {import('./Event.js').default} event
+     * @returns {void}
+     */
     push(event) {
         const queue = this.getQueue(event.channel, event.topic);
         queue.push(event);
         this.map.set(event.toKey(), queue);
     }
 
+    /**
+     * @template [T=unknown]
+     * @param {string} channel
+     * @param {string} topic
+     * @returns {import('./Event.js').default<T>}
+     */
     peek(channel, topic) {
         return this.getQueue(channel, topic).peek();
     }
 
+    /**
+     * @template [T=unknown]
+     * @param {string} channel
+     * @param {string} topic
+     * @returns {import('./Event.js').default<T>[]}
+     */
     log(channel, topic) {
         return this.getQueue(channel, topic).toArray();
     }

src/index.js

@@ -1 +1,9 @@
+/**
+ * @typedef {import('./Event.js').default} Event
+ */
+/**
+ * @template [T=unknown]
+ * @typedef {import('./MessageBus.js').MessageHandler<T>} MessageHandler
+ */
+
 export { default as MessageBus } from './MessageBus.js';

src/utils.js

@@ -1,3 +1,10 @@
+/**
+ * Creates a key of `channel:topic`.
+ *
+ * @param {string} channel
+ * @param {string} topic
+ * @returns {string}
+ */
 export function toKey(channel, topic) {
     return `${channel}:${topic}`;
 }

test/Event.test.js

@@ -9,3 +9,18 @@ tap.test('toKey() - should return key format', (t) => {
     t.ok(event.toKey() === toKey(channel, topic));
     t.end();
 });
+
+tap.test('payload infers the expected type', (t) => {
+    const event = new Event('foo', 'bar', { value: 'baz' });
+    t.ok(event.payload?.value);
+    t.end();
+});
+
+tap.test('payload catches type error', (t) => {
+    /**
+     * @type {Event<{ value: string; }>}
+     */
+    // @ts-expect-error We want this to raise an error since { wrong: string } is not the expected type.
+    const event = new Event('foo', 'bar', { wrong: 'baz' }); // eslint-disable-line no-unused-vars
+    t.end();
+});