@design.estate/dees-comms 1.0.32 → 1.1.1

package/ts/dees-comms.classes.deescomms.ts

@@ -1,38 +1,186 @@
 import * as plugins from './dees-comms.plugins.js';
 
-let BroadcastChannel = globalThis.BroadcastChannel;
-if (!BroadcastChannel) {
-  BroadcastChannel = plugins.BroadCastChannelPolyfill as any;
+export interface IDeesCommsOptions {
+  /**
+   * The channel this instance talks on. Instances hear each other only when
+   * they use the same name, in any tab, frame or worker of the same origin.
+   * Defaults to `DeesComms.defaultChannelName`, the channel every instance
+   * used before names existed.
+   */
+  channelName?: string;
+}
+
+/**
+ * Receives the payload of one typed event, and the event itself.
+ */
+export type TDeesCommsEventHandler<T extends plugins.typedrequestInterfaces.ITypedEvent<unknown>> = (
+  payloadArg: T['payload'],
+  eventArg: T
+) => void | Promise<void>;
+
+export interface IDeesCommsSubscription {
+  /**
+   * Stops this subscription. An event that is being delivered right now does
+   * not reach it any more; calling it again does nothing.
+   */
+  unsubscribe(): void;
+}
+
+/**
+ * How a typed event travels on the channel. The envelope keeps it apart from
+ * typed requests and their responses, which are routed by the typedrouter.
+ */
+interface IDeesCommsEventMessage {
+  deesCommsEvent: plugins.typedrequestInterfaces.ITypedEvent<unknown>;
+}
+
+type TStoredEventHandler = (
+  payloadArg: unknown,
+  eventArg: plugins.typedrequestInterfaces.ITypedEvent<unknown>
+) => void | Promise<void>;
+
+/**
+ * The part of a BroadcastChannel that DeesComms uses: the platform's own, or
+ * the polyfill where the platform has none.
+ */
+interface IDeesCommsChannel {
+  post(messageArg: unknown): Promise<void>;
+  close(): Promise<void>;
+  /**
+   * Whether the open channel keeps its process alive. Only Node.js's channel
+   * can hold a process; elsewhere this does nothing.
+   */
+  holdProcess(holdArg: boolean): void;
+}
+
+/**
+ * A channel that decides whether it keeps its process alive, as Node.js's
+ * BroadcastChannel does. A browser's channel has neither method.
+ */
+interface IProcessHoldingChannel {
+  ref(): void;
+  unref(): void;
 }
 
+const isProcessHolding = (channelArg: object): channelArg is IProcessHoldingChannel =>
+  'ref' in channelArg &&
+  typeof channelArg.ref === 'function' &&
+  'unref' in channelArg &&
+  typeof channelArg.unref === 'function';
+
+/**
+ * Opens a channel that hands every message it receives to `receiveArg` as the
+ * message itself: the platform's BroadcastChannel delivers a MessageEvent, the
+ * polyfill delivers the message.
+ */
+const openChannel = (
+  nameArg: string,
+  receiveArg: (messageArg: unknown) => void
+): IDeesCommsChannel => {
+  if (typeof globalThis.BroadcastChannel === 'function') {
+    const channel = new globalThis.BroadcastChannel(nameArg);
+    channel.onmessage = (eventArg: MessageEvent<unknown>) => {
+      receiveArg(eventArg.data);
+    };
+    const processHolding = isProcessHolding(channel) ? channel : null;
+    // an open channel alone does not keep a Node.js process running
+    processHolding?.unref();
+    return {
+      post: async (messageArg) => {
+        channel.postMessage(messageArg);
+      },
+      close: async () => {
+        channel.close();
+      },
+      holdProcess: (holdArg) => {
+        if (holdArg) {
+          processHolding?.ref();
+        } else {
+          processHolding?.unref();
+        }
+      },
+    };
+  }
+  const channel = new plugins.BroadCastChannelPolyfill<unknown>(nameArg);
+  channel.onmessage = (messageArg: unknown) => {
+    receiveArg(messageArg);
+  };
+  return {
+    post: (messageArg) => channel.postMessage(messageArg),
+    close: () => channel.close(),
+    // the polyfill stands in only where the platform has no channel, which
+    // Node.js always has
+    holdProcess: () => undefined,
+  };
+};
+
+const isObject = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null;
+
+// `Object.hasOwn` is younger than some of the browsers the polyfill serves
+const hasOwn = (objectArg: Record<string, unknown>, keyArg: string): boolean =>
+  Object.prototype.hasOwnProperty.call(objectArg, keyArg);
+
+/**
+ * The event a received message carries: `null` for a message that is no
+ * event, `'malformed'` for an envelope without a well-formed event in it.
+ */
+const eventOf = (
+  messageArg: unknown
+): plugins.typedrequestInterfaces.ITypedEvent<unknown> | 'malformed' | null => {
+  if (!isObject(messageArg) || !hasOwn(messageArg, 'deesCommsEvent')) {
+    return null;
+  }
+  const event = messageArg.deesCommsEvent;
+  if (
+    !isObject(event) ||
+    typeof event.name !== 'string' ||
+    typeof event.uniqueEventId !== 'string' ||
+    !hasOwn(event, 'payload')
+  ) {
+    return 'malformed';
+  }
+  return { name: event.name, uniqueEventId: event.uniqueEventId, payload: event.payload };
+};
+
+const createEventId = (): string => {
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+  return Array.from(bytes, (byteArg) => byteArg.toString(16).padStart(2, '0')).join('');
+};
+
 /**
  * a comm class for client side communication between workers and tabs.
  */
 export class DeesComms {
-  private broadcastChannel = new BroadcastChannel('dees-comms');
-  
+  /**
+   * The channel of every instance that is not given a name. Code that talks
+   * to other code on it, like a service worker and its pages, keeps working
+   * unchanged; an application gives its own messages a name of its own.
+   */
+  public static readonly defaultChannelName = 'dees-comms';
+
+  public readonly channelName: string;
+  private readonly channel: IDeesCommsChannel;
+  private readonly eventHandlers = new Map<string, Set<TStoredEventHandler>>();
+  private hasTypedHandlers = false;
+  private closed = false;
+  private closing: Promise<void> | null = null;
+
   // sending messages
   public typedrouter = new plugins.typedrequest.TypedRouter();
   public typedtarget = new plugins.typedrequest.TypedTarget({
     postMethodWithTypedRouter: async (messageArg) => {
-      this.postMessage(messageArg);
+      await this.postMessage(messageArg);
     },
     typedRouterRef: this.typedrouter,
   });
 
   // receiving messages
-  constructor() {
-    this.broadcastChannel.onmessage = async (eventArg) => {
-      const message = (eventArg as any).method ? eventArg : eventArg.data;
-      // Skip hooks for broadcast-received messages to prevent infinite loops
-      // when traffic logging hooks are set up globally
-      const response = await this.typedrouter.routeAndAddResponse(message, {
-        skipHooks: true,
-      });
-      if (response && !response.error) {
-        this.postMessage(response);
-      }
-    };
+  constructor(optionsArg: IDeesCommsOptions = {}) {
+    this.channelName = optionsArg.channelName ?? DeesComms.defaultChannelName;
+    this.channel = openChannel(this.channelName, (messageArg) => {
+      void this.receive(messageArg);
+    });
   }
 
   /**
@@ -51,7 +199,8 @@ export class DeesComms {
   public async postMessage<T = plugins.typedrequestInterfaces.ITypedRequest>(
     messageArg: T
   ): Promise<void> {
-    this.broadcastChannel.postMessage(messageArg);
+    this.assertOpen();
+    await this.channel.post(messageArg);
   }
 
   /**
@@ -64,5 +213,142 @@ export class DeesComms {
     this.typedrouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<T>(methodArg, handlerFunction)
     );
+    this.hasTypedHandlers = true;
+    this.holdProcessWhileListened();
+  }
+
+  /**
+   * Sends a typed event to every other instance on this channel and expects
+   * no answer. The instance that sends it does not receive it; any other
+   * instance on the same channel does, in this context or another one.
+   */
+  public async broadcast<T extends plugins.typedrequestInterfaces.ITypedEvent<unknown>>(
+    nameArg: T['name'],
+    payloadArg: T['payload']
+  ): Promise<void> {
+    const message: IDeesCommsEventMessage = {
+      deesCommsEvent: {
+        name: nameArg,
+        uniqueEventId: createEventId(),
+        payload: payloadArg,
+      },
+    };
+    await this.postMessage(message);
+  }
+
+  /**
+   * Calls the handler for every typed event of that name another instance
+   * broadcasts on this channel. Handlers run in the order they subscribed; one
+   * that throws or rejects is reported and does not keep the others from
+   * running.
+   */
+  public subscribe<T extends plugins.typedrequestInterfaces.ITypedEvent<unknown>>(
+    nameArg: T['name'],
+    handlerArg: TDeesCommsEventHandler<T>
+  ): IDeesCommsSubscription {
+    this.assertOpen();
+    // the name is the contract: what arrives under it is taken as its type,
+    // as a typed handler takes the request of its method
+    const handler: TStoredEventHandler = (payloadArg, eventArg) =>
+      handlerArg(payloadArg as T['payload'], eventArg as T);
+    let handlers = this.eventHandlers.get(nameArg);
+    if (!handlers) {
+      handlers = new Set();
+      this.eventHandlers.set(nameArg, handlers);
+    }
+    handlers.add(handler);
+    this.holdProcessWhileListened();
+    return {
+      unsubscribe: () => {
+        const current = this.eventHandlers.get(nameArg);
+        if (!current) {
+          return;
+        }
+        current.delete(handler);
+        if (current.size === 0) {
+          this.eventHandlers.delete(nameArg);
+          this.holdProcessWhileListened();
+        }
+      },
+    };
+  }
+
+  /**
+   * Closes the channel. Nothing is received from then on, every subscription
+   * ends, and sending, broadcasting or subscribing throws. A typed request
+   * still waiting for its response when the channel closes cannot receive it
+   * and ends with its own timeout. Closing again does nothing.
+   */
+  public async close(): Promise<void> {
+    if (!this.closing) {
+      this.closed = true;
+      this.eventHandlers.clear();
+      this.closing = this.channel.close();
+    }
+    await this.closing;
+  }
+
+  /**
+   * In Node.js an instance keeps its process alive while something listens on
+   * it, as a MessagePort with a message listener does: a subscription, or a
+   * typed handler it created. One nobody listens on lets the process end.
+   */
+  private holdProcessWhileListened(): void {
+    if (this.closed) {
+      return;
+    }
+    this.channel.holdProcess(this.hasTypedHandlers || this.eventHandlers.size > 0);
+  }
+
+  private assertOpen(): void {
+    if (this.closed) {
+      throw new Error(`DeesComms channel "${this.channelName}" is closed`);
+    }
+  }
+
+  private async receive(messageArg: unknown): Promise<void> {
+    if (this.closed) {
+      return;
+    }
+    const event = eventOf(messageArg);
+    if (event === 'malformed') {
+      console.log('DeesComms received a malformed event');
+      return;
+    }
+    if (event) {
+      this.dispatch(event);
+      return;
+    }
+    // Skip hooks for broadcast-received messages to prevent infinite loops
+    // when traffic logging hooks are set up globally. The router validates
+    // the shape of what it is given.
+    const response = await this.typedrouter.routeAndAddResponse(
+      messageArg as plugins.typedrequestInterfaces.ITypedRequest,
+      { skipHooks: true }
+    );
+    if (response && !response.error && !this.closed) {
+      await this.postMessage(response);
+    }
+  }
+
+  private dispatch(eventArg: plugins.typedrequestInterfaces.ITypedEvent<unknown>): void {
+    const handlers = this.eventHandlers.get(eventArg.name);
+    if (!handlers) {
+      return;
+    }
+    for (const handler of [...handlers]) {
+      // a handler that closed the channel ends the delivery, and one an
+      // earlier handler unsubscribed is not called any more
+      if (this.closed) {
+        return;
+      }
+      if (!handlers.has(handler)) {
+        continue;
+      }
+      void (async () => handler(eventArg.payload, eventArg))().catch((errorArg: unknown) => {
+        // the event's name and the failure, never its payload
+        console.error(`DeesComms: a handler of the event "${eventArg.name}" failed`, errorArg);
+      });
+    }
   }
 }

package/readme.hints.md

@@ -1 +0,0 @@
-