Add TSDoc info to all public classes and interfaces

Author: alesgenova

src/common.ts

@@ -3,10 +3,22 @@ export const MARKER = '@post-me';
 export type IdType = number;
 export type KeyType = string;
 
+/**
+ * The options that can be passed when calling a method on the other context with RemoteHandle.customCall()
+ *
+ * @public
+ *
+ */
 export type CallOptions = {
   transfer?: Transferable[];
 };
 
+/**
+ * The options that can be passed when emitting an event to the other context with LocalHandle.emit()
+ *
+ * @public
+ *
+ */
 export type EmitOptions = {
   transfer?: Transferable[];
 };

src/connection.ts

@@ -7,15 +7,41 @@ import {
   RemoteHandle,
 } from './handles';
 
+/**
+ * An active connection between two contexts
+ *
+ * @typeParam M0 - The methods exposed by this context
+ * @typeParam E1 - The events exposed by this context
+ * @typeParam M1 - The methods exposed by the other context
+ * @typeParam E1 - The events exposed by the other context
+ *
+ * @public
+ *
+ */
 export interface Connection<
   M0 extends MethodsType = any,
   E0 extends EventsType = any,
   M1 extends MethodsType = any,
   E1 extends EventsType = any
 > {
-  localHandle: () => LocalHandle<M0, E0>;
-  remoteHandle: () => RemoteHandle<M1, E1>;
-  close: () => void;
+  /**
+   * Get a handle to the local end of the connection
+   *
+   * @returns A {@link LocalHandle} to the local side of the Connection
+   */
+  localHandle(): LocalHandle<M0, E0>;
+
+  /**
+   * Get a handle to the other end of the connection
+   *
+   * @returns A {@link RemoteHandle} to the other side of the Connection
+   */
+  remoteHandle(): RemoteHandle<M1, E1>;
+
+  /**
+   * Stop listening to incoming message from the other side
+   */
+  close(): void;
 }
 
 export class ConcreteConnection<M0 extends MethodsType> implements Connection {

src/dispatcher.ts

@@ -1,6 +1,6 @@
 import { IdType, KeyType, createUniqueIdFn } from './common';
 import { Messenger } from './messenger';
-import { Emitter } from './emitter';
+import { ConcreteEmitter } from './emitter';
 import {
   isMessage,
   isCallMessage,
@@ -42,7 +42,7 @@ export type DispatcherEvents = {
   [MessageType.Event]: EventMessage<any>;
 };
 
-export class Dispatcher extends Emitter<DispatcherEvents> {
+export class Dispatcher extends ConcreteEmitter<DispatcherEvents> {
   private messenger: Messenger;
   private sessionId: IdType;
   private removeMessengerListener: () => void;
@@ -138,7 +138,7 @@ export type ParentHandshakeDispatcherEvents = {
   [x: number]: HandshakeResponseMessage;
 };
 
-export class ParentHandshakeDispatcher extends Emitter<ParentHandshakeDispatcherEvents> {
+export class ParentHandshakeDispatcher extends ConcreteEmitter<ParentHandshakeDispatcherEvents> {
   private messenger: Messenger;
   private sessionId: IdType;
   private removeMessengerListener: () => void;
@@ -186,7 +186,7 @@ export type ChildHandshakeDispatcherEvents = {
   [MessageType.HandshakeRequest]: HandshakeRequestMessage;
 };
 
-export class ChildHandshakeDispatcher extends Emitter<ChildHandshakeDispatcherEvents> {
+export class ChildHandshakeDispatcher extends ConcreteEmitter<ChildHandshakeDispatcherEvents> {
   private messenger: Messenger;
   private removeMessengerListener: () => void;
 

src/emitter.ts

@@ -1,24 +1,61 @@
 import { EventsType } from './common';
 
-export interface IEmitter<E extends EventsType> {
-  addEventListener: <K extends keyof E>(
+/**
+ * A simple event emitter interface used to implement the observer pattern throughout the codebase.
+ *
+ * @public
+ *
+ */
+export interface Emitter<E extends EventsType> {
+  /**
+   * Add a listener to a specific event.
+   *
+   * @param eventName - The name of the event
+   * @param listener - A listener function that takes as parameter the payload of the event
+   */
+  addEventListener<K extends keyof E>(
     eventName: K,
     listener: (data: E[K]) => void
-  ) => void;
-  removeEventListener: <K extends keyof E>(
+  ): void;
+
+  /**
+   * Remove a listener from a specific event.
+   *
+   * @param eventName - The name of the event
+   * @param listener - A listener function that had been added previously
+   */
+  removeEventListener<K extends keyof E>(
     eventName: K,
     listener: (data: E[K]) => void
-  ) => void;
-  once: <K extends keyof E>(eventName: K) => Promise<E[K]>;
+  ): void;
+
+  /**
+   * Add a listener to a specific event, that will only be invoked once
+   *
+   * @remarks
+   *
+   * After the first occurrence of the specified event, the listener will be invoked and
+   * immediately removed.
+   *
+   * @param eventName - The name of the event
+   * @param listener - A listener function that had been added previously
+   */
+  once<K extends keyof E>(eventName: K): Promise<E[K]>;
 }
 
-export class Emitter<E extends EventsType> implements IEmitter<E> {
+/**
+ * A concrete implementation of the {@link Emitter} interface
+ *
+ * @public
+ */
+export class ConcreteEmitter<E extends EventsType> implements Emitter<E> {
   private _listeners: Partial<Record<keyof E, Set<(data: any) => void>>>;
 
   constructor() {
     this._listeners = {};
   }
 
+  /** {@inheritDoc Emitter.addEventListener} */
   addEventListener<K extends keyof E>(
     eventName: K,
     listener: (data: E[K]) => void
@@ -33,6 +70,7 @@ export class Emitter<E extends EventsType> implements IEmitter<E> {
     listeners.add(listener);
   }
 
+  /** {@inheritDoc Emitter.removeEventListener} */
   removeEventListener<K extends keyof E>(
     eventName: K,
     listener: (data: E[K]) => void
@@ -46,6 +84,7 @@ export class Emitter<E extends EventsType> implements IEmitter<E> {
     listeners.delete(listener);
   }
 
+  /** {@inheritDoc Emitter.once} */
   once<K extends keyof E>(eventName: K): Promise<E[K]> {
     return new Promise((resolve) => {
       const listener = (data: E[K]) => {
@@ -57,6 +96,7 @@ export class Emitter<E extends EventsType> implements IEmitter<E> {
     });
   }
 
+  /** @internal */
   protected emit<K extends keyof E>(eventName: K, data: E[K]) {
     let listeners = this._listeners[eventName];
 
@@ -69,6 +109,7 @@ export class Emitter<E extends EventsType> implements IEmitter<E> {
     });
   }
 
+  /** @internal */
   protected removeAllListeners() {
     Object.values(this._listeners).forEach((listeners) => {
       if (listeners) {

src/handles.ts

@@ -5,7 +5,7 @@ import {
   EmitOptions,
   CallOptions,
 } from './common';
-import { Emitter, IEmitter } from './emitter';
+import { Emitter, ConcreteEmitter } from './emitter';
 import { Dispatcher } from './dispatcher';
 import {
   MessageType,
@@ -16,49 +16,149 @@ import {
 } from './messages';
 import { createCallbackProxy, isCallbackProxy } from './proxy';
 
+/**
+ * A handle to the other end of the connection
+ *
+ * @remarks
+ *
+ * Use this handle to:
+ *
+ *   - Call methods exposed by the other end
+ *
+ *   - Add listeners to custom events emitted by the other end
+ *
+ * @typeParam M - The methods exposed by the other context
+ * @typeParam E - The events exposed by the other context
+ *
+ * @public
+ *
+ */
 export interface RemoteHandle<
   M extends MethodsType = any,
   E extends EventsType = any
-> extends IEmitter<E> {
-  call: <K extends keyof M>(
+> extends Emitter<E> {
+  /**
+   * Call a method exposed by the other end.
+   *
+   * @param methodName - The name of the method
+   * @param args - The list of arguments passed to the method
+   * @returns A Promise of the value returned by the method
+   *
+   */
+  call<K extends keyof M>(
     methodName: K,
     ...args: Parameters<M[K]>
-  ) => Promise<InnerType<ReturnType<M[K]>>>;
-  customCall: <K extends keyof M>(
+  ): Promise<InnerType<ReturnType<M[K]>>>;
+
+  /**
+   * Call a method exposed by the other end.
+   *
+   * @param methodName - The name of the method
+   * @param args - The list of arguments passed to the method
+   * @param options - The {@link CallOptions} to customize this method call
+   * @returns A Promise of the value returned by the method
+   *
+   */
+  customCall<K extends keyof M>(
     methodName: K,
     args: Parameters<M[K]>,
     options?: CallOptions
-  ) => Promise<InnerType<ReturnType<M[K]>>>;
-  setCallTransfer: <K extends keyof M>(
+  ): Promise<InnerType<ReturnType<M[K]>>>;
+
+  /**
+   * Specify which parts of the arguments of a given method call should be transferred
+   * into the other context instead of cloned.
+   *
+   * @remarks
+   *
+   * You only need to call setCallTransfer once per method. After the transfer function is set,
+   * it will automatically be used by all subsequent calls to the specified method.
+   *
+   * @param methodName - The name of the method
+   * @param transfer - A function that takes as parameters the arguments of a method call, and returns a list of transferable objects.
+   *
+   */
+  setCallTransfer<K extends keyof M>(
     methodName: K,
     transfer: (...args: Parameters<M[K]>) => Transferable[]
-  ) => void;
+  ): void;
 }
 
+/**
+ * A handle to the local end of the connection
+ *
+ * @remarks
+ *
+ * Use this handle to:
+ *
+ * - Emit custom events to the other end
+ *
+ * @typeParam M - The methods exposed by this context
+ * @typeParam E - The events exposed by this context
+ *
+ * @public
+ *
+ */
 export interface LocalHandle<
   M extends MethodsType = any,
   E extends EventsType = any
 > {
-  emit: <K extends keyof E>(
+  /**
+   * Emit a custom event with a payload. The event can be captured by the other context.
+   *
+   * @param eventName - The name of the event
+   * @param data - The payload associated with the event
+   * @param options - The {@link EmitOptions} to customize this emit call
+   *
+   */
+  emit<K extends keyof E>(
     eventName: K,
     data: E[K],
     options?: EmitOptions
-  ) => void;
-  setReturnTransfer: <K extends keyof M>(
+  ): void;
+
+  /**
+   * Specify which parts of the return value of a given method call should be transferred
+   * into the other context instead of cloned.
+   *
+   * @remarks
+   *
+   * You only need to call setReturnTransfer once per method. After the transfer function is set,
+   * it will automatically be used every time a value is returned by the specified method.
+   *
+   * @param methodName - The name of the method
+   * @param transfer - A function that takes as parameter the return value of a method call, and returns a list of transferable objects.
+   *
+   */
+  setReturnTransfer<K extends keyof M>(
     methodName: K,
     transfer: (result: InnerType<ReturnType<M[K]>>) => Transferable[]
-  ) => void;
-  setEmitTransfer: <K extends keyof E>(
+  ): void;
+
+  /**
+   * Specify which parts of the payload of a given event should be transferred
+   * into the other context instead of cloned.
+   *
+   * @remarks
+   *
+   * You only need to call setEmitTransfer once per event type. After the transfer function is set,
+   * it will automatically be used every time a payload is attached to the specific event.
+   *
+   * @param eventName - The name of the method
+   * @param transfer - A function that takes as parameter the payload of an event, and returns a list of transferable objects.
+   *
+   */
+  setEmitTransfer<K extends keyof E>(
     eventName: K,
     transfer: (payload: E[K]) => Transferable[]
-  ) => void;
+  ): void;
 }
 
 export class ConcreteRemoteHandle<
     M extends MethodsType = any,
     E extends EventsType = any
   >
-  extends Emitter<E>
+  extends ConcreteEmitter<E>
   implements RemoteHandle<M, E> {
   private _dispatcher: Dispatcher;
   private _callTransfer: { [x: string]: (...args: any) => Transferable[] };