@design.estate/dees-comms 1.0.31 → 1.1.0

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@design.estate/dees-comms',
-    version: '1.0.31',
+    version: '1.1.0',
     description: 'A communications module for enabling DOM-based messaging and synchronization across browser tabs and workers.'
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSwyQkFBMkI7SUFDakMsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLCtHQUErRztDQUM3SCxDQUFBIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSwyQkFBMkI7SUFDakMsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLCtHQUErRztDQUM3SCxDQUFBIn0=

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

@@ -1,12 +1,42 @@
 import * as plugins from './dees-comms.plugins.js';
+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;
+}
 /**
  * a comm class for client side communication between workers and tabs.
  */
 export declare class DeesComms {
-    private broadcastChannel;
+    /**
+     * 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.
+     */
+    static readonly defaultChannelName = "dees-comms";
+    readonly channelName: string;
+    private readonly channel;
+    private readonly eventHandlers;
+    private closed;
+    private closing;
     typedrouter: plugins.typedrequest.TypedRouter<plugins.typedrequestInterfaces.ITypedRequest>;
     typedtarget: plugins.typedrequest.TypedTarget;
-    constructor();
+    constructor(optionsArg?: IDeesCommsOptions);
     /**
      * creates a typedrequest with this classes postMessage as postMethod
      */
@@ -19,4 +49,27 @@ export declare class DeesComms {
      * subscribe to messages
      */
     createTypedHandler<T extends plugins.typedrequestInterfaces.ITypedRequest>(methodArg: T['method'], handlerFunction: plugins.typedrequest.THandlerFunction<T>): Promise<void>;
+    /**
+     * 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.
+     */
+    broadcast<T extends plugins.typedrequestInterfaces.ITypedEvent<unknown>>(nameArg: T['name'], payloadArg: T['payload']): Promise<void>;
+    /**
+     * 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.
+     */
+    subscribe<T extends plugins.typedrequestInterfaces.ITypedEvent<unknown>>(nameArg: T['name'], handlerArg: TDeesCommsEventHandler<T>): IDeesCommsSubscription;
+    /**
+     * 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.
+     */
+    close(): Promise<void>;
+    private assertOpen;
+    private receive;
+    private dispatch;
 }

package/dist_ts/dees-comms.classes.deescomms.js

@@ -1,34 +1,84 @@
 import * as plugins from './dees-comms.plugins.js';
-let BroadcastChannel = globalThis.BroadcastChannel;
-if (!BroadcastChannel) {
-    BroadcastChannel = plugins.BroadCastChannelPolyfill;
-}
+/**
+ * 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, receiveArg) => {
+    if (typeof globalThis.BroadcastChannel === 'function') {
+        const channel = new globalThis.BroadcastChannel(nameArg);
+        channel.onmessage = (eventArg) => {
+            receiveArg(eventArg.data);
+        };
+        return {
+            post: async (messageArg) => {
+                channel.postMessage(messageArg);
+            },
+            close: async () => {
+                channel.close();
+            },
+        };
+    }
+    const channel = new plugins.BroadCastChannelPolyfill(nameArg);
+    channel.onmessage = (messageArg) => {
+        receiveArg(messageArg);
+    };
+    return {
+        post: (messageArg) => channel.postMessage(messageArg),
+        close: () => channel.close(),
+    };
+};
+const isObject = (valueArg) => typeof valueArg === 'object' && valueArg !== null;
+// `Object.hasOwn` is younger than some of the browsers the polyfill serves
+const hasOwn = (objectArg, keyArg) => 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) => {
+    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 = () => {
+    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 {
+    /**
+     * 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.
+     */
+    static { this.defaultChannelName = 'dees-comms'; }
     // receiving messages
-    constructor() {
-        this.broadcastChannel = new BroadcastChannel('dees-comms');
+    constructor(optionsArg = {}) {
+        this.eventHandlers = new Map();
+        this.closed = false;
+        this.closing = null;
         // sending messages
         this.typedrouter = new plugins.typedrequest.TypedRouter();
         this.typedtarget = new plugins.typedrequest.TypedTarget({
             postMethodWithTypedRouter: async (messageArg) => {
-                this.postMessage(messageArg);
+                await this.postMessage(messageArg);
             },
             typedRouterRef: this.typedrouter,
         });
-        this.broadcastChannel.onmessage = async (eventArg) => {
-            const message = eventArg.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);
-            }
-        };
+        this.channelName = optionsArg.channelName ?? DeesComms.defaultChannelName;
+        this.channel = openChannel(this.channelName, (messageArg) => {
+            void this.receive(messageArg);
+        });
     }
     /**
      * creates a typedrequest with this classes postMessage as postMethod
@@ -41,7 +91,8 @@ export class DeesComms {
      * posts a typedrequestmessage
      */
     async postMessage(messageArg) {
-        this.broadcastChannel.postMessage(messageArg);
+        this.assertOpen();
+        await this.channel.post(messageArg);
     }
     /**
      * subscribe to messages
@@ -49,5 +100,110 @@ export class DeesComms {
     async createTypedHandler(methodArg, handlerFunction) {
         this.typedrouter.addTypedHandler(new plugins.typedrequest.TypedHandler(methodArg, handlerFunction));
     }
+    /**
+     * 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.
+     */
+    async broadcast(nameArg, payloadArg) {
+        const message = {
+            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.
+     */
+    subscribe(nameArg, handlerArg) {
+        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 = (payloadArg, eventArg) => handlerArg(payloadArg, eventArg);
+        let handlers = this.eventHandlers.get(nameArg);
+        if (!handlers) {
+            handlers = new Set();
+            this.eventHandlers.set(nameArg, handlers);
+        }
+        handlers.add(handler);
+        return {
+            unsubscribe: () => {
+                const current = this.eventHandlers.get(nameArg);
+                if (!current) {
+                    return;
+                }
+                current.delete(handler);
+                if (current.size === 0) {
+                    this.eventHandlers.delete(nameArg);
+                }
+            },
+        };
+    }
+    /**
+     * 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.
+     */
+    async close() {
+        if (!this.closing) {
+            this.closed = true;
+            this.eventHandlers.clear();
+            this.closing = this.channel.close();
+        }
+        await this.closing;
+    }
+    assertOpen() {
+        if (this.closed) {
+            throw new Error(`DeesComms channel "${this.channelName}" is closed`);
+        }
+    }
+    async receive(messageArg) {
+        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, { skipHooks: true });
+        if (response && !response.error && !this.closed) {
+            await this.postMessage(response);
+        }
+    }
+    dispatch(eventArg) {
+        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) => {
+                // the event's name and the failure, never its payload
+                console.error(`DeesComms: a handler of the event "${eventArg.name}" failed`, errorArg);
+            });
+        }
+    }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVlcy1jb21tcy5jbGFzc2VzLmRlZXNjb21tcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL2RlZXMtY29tbXMuY2xhc3Nlcy5kZWVzY29tbXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSx5QkFBeUIsQ0FBQztBQUVuRCxJQUFJLGdCQUFnQixHQUFHLFVBQVUsQ0FBQyxnQkFBZ0IsQ0FBQztBQUNuRCxJQUFJLENBQUMsZ0JBQWdCLEVBQUUsQ0FBQztJQUN0QixnQkFBZ0IsR0FBRyxPQUFPLENBQUMsd0JBQStCLENBQUM7QUFDN0QsQ0FBQztBQUVEOztHQUVHO0FBQ0gsTUFBTSxPQUFPLFNBQVM7SUFZcEIscUJBQXFCO0lBQ3JCO1FBWlEscUJBQWdCLEdBQUcsSUFBSSxnQkFBZ0IsQ0FBQyxZQUFZLENBQUMsQ0FBQztRQUU5RCxtQkFBbUI7UUFDWixnQkFBVyxHQUFHLElBQUksT0FBTyxDQUFDLFlBQVksQ0FBQyxXQUFXLEVBQUUsQ0FBQztRQUNyRCxnQkFBVyxHQUFHLElBQUksT0FBTyxDQUFDLFlBQVksQ0FBQyxXQUFXLENBQUM7WUFDeEQseUJBQXlCLEVBQUUsS0FBSyxFQUFFLFVBQVUsRUFBRSxFQUFFO2dCQUM5QyxJQUFJLENBQUMsV0FBVyxDQUFDLFVBQVUsQ0FBQyxDQUFDO1lBQy9CLENBQUM7WUFDRCxjQUFjLEVBQUUsSUFBSSxDQUFDLFdBQVc7U0FDakMsQ0FBQyxDQUFDO1FBSUQsSUFBSSxDQUFDLGdCQUFnQixDQUFDLFNBQVMsR0FBRyxLQUFLLEVBQUUsUUFBUSxFQUFFLEVBQUU7WUFDbkQsTUFBTSxPQUFPLEdBQUksUUFBZ0IsQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUMsUUFBUSxDQUFDLElBQUksQ0FBQztZQUNwRSx1RUFBdUU7WUFDdkUsaURBQWlEO1lBQ2pELE1BQU0sUUFBUSxHQUFHLE1BQU0sSUFBSSxDQUFDLFdBQVcsQ0FBQyxtQkFBbUIsQ0FBQyxPQUFPLEVBQUU7Z0JBQ25FLFNBQVMsRUFBRSxJQUFJO2FBQ2hCLENBQUMsQ0FBQztZQUNILElBQUksUUFBUSxJQUFJLENBQUMsUUFBUSxDQUFDLEtBQUssRUFBRSxDQUFDO2dCQUNoQyxJQUFJLENBQUMsV0FBVyxDQUFDLFFBQVEsQ0FBQyxDQUFDO1lBQzdCLENBQUM7UUFDSCxDQUFDLENBQUM7SUFDSixDQUFDO0lBRUQ7O09BRUc7SUFDSSxrQkFBa0IsQ0FDdkIsVUFBdUI7UUFFdkIsTUFBTSxZQUFZLEdBQUcsSUFBSSxPQUFPLENBQUMsWUFBWSxDQUFDLFlBQVksQ0FBQyxJQUFJLENBQUMsV0FBVyxFQUFFLFVBQVUsQ0FBQyxDQUFDO1FBQ3pGLE9BQU8sWUFBWSxDQUFDO0lBQ3RCLENBQUM7SUFFRDs7T0FFRztJQUNJLEtBQUssQ0FBQyxXQUFXLENBQ3RCLFVBQWE7UUFFYixJQUFJLENBQUMsZ0JBQWdCLENBQUMsV0FBVyxDQUFDLFVBQVUsQ0FBQyxDQUFDO0lBQ2hELENBQUM7SUFFRDs7T0FFRztJQUNJLEtBQUssQ0FBQyxrQkFBa0IsQ0FDN0IsU0FBc0IsRUFDdEIsZUFBeUQ7UUFFekQsSUFBSSxDQUFDLFdBQVcsQ0FBQyxlQUFlLENBQzlCLElBQUksT0FBTyxDQUFDLFlBQVksQ0FBQyxZQUFZLENBQUksU0FBUyxFQUFFLGVBQWUsQ0FBQyxDQUNyRSxDQUFDO0lBQ0osQ0FBQztDQUNGIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVlcy1jb21tcy5jbGFzc2VzLmRlZXNjb21tcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL2RlZXMtY29tbXMuY2xhc3Nlcy5kZWVzY29tbXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSx5QkFBeUIsQ0FBQztBQWtEbkQ7Ozs7R0FJRztBQUNILE1BQU0sV0FBVyxHQUFHLENBQ2xCLE9BQWUsRUFDZixVQUF5QyxFQUN0QixFQUFFO0lBQ3JCLElBQUksT0FBTyxVQUFVLENBQUMsZ0JBQWdCLEtBQUssVUFBVSxFQUFFLENBQUM7UUFDdEQsTUFBTSxPQUFPLEdBQUcsSUFBSSxVQUFVLENBQUMsZ0JBQWdCLENBQUMsT0FBTyxDQUFDLENBQUM7UUFDekQsT0FBTyxDQUFDLFNBQVMsR0FBRyxDQUFDLFFBQStCLEVBQUUsRUFBRTtZQUN0RCxVQUFVLENBQUMsUUFBUSxDQUFDLElBQUksQ0FBQyxDQUFDO1FBQzVCLENBQUMsQ0FBQztRQUNGLE9BQU87WUFDTCxJQUFJLEVBQUUsS0FBSyxFQUFFLFVBQVUsRUFBRSxFQUFFO2dCQUN6QixPQUFPLENBQUMsV0FBVyxDQUFDLFVBQVUsQ0FBQyxDQUFDO1lBQ2xDLENBQUM7WUFDRCxLQUFLLEVBQUUsS0FBSyxJQUFJLEVBQUU7Z0JBQ2hCLE9BQU8sQ0FBQyxLQUFLLEVBQUUsQ0FBQztZQUNsQixDQUFDO1NBQ0YsQ0FBQztJQUNKLENBQUM7SUFDRCxNQUFNLE9BQU8sR0FBRyxJQUFJLE9BQU8sQ0FBQyx3QkFBd0IsQ0FBVSxPQUFPLENBQUMsQ0FBQztJQUN2RSxPQUFPLENBQUMsU0FBUyxHQUFHLENBQUMsVUFBbUIsRUFBRSxFQUFFO1FBQzFDLFVBQVUsQ0FBQyxVQUFVLENBQUMsQ0FBQztJQUN6QixDQUFDLENBQUM7SUFDRixPQUFPO1FBQ0wsSUFBSSxFQUFFLENBQUMsVUFBVSxFQUFFLEVBQUUsQ0FBQyxPQUFPLENBQUMsV0FBVyxDQUFDLFVBQVUsQ0FBQztRQUNyRCxLQUFLLEVBQUUsR0FBRyxFQUFFLENBQUMsT0FBTyxDQUFDLEtBQUssRUFBRTtLQUM3QixDQUFDO0FBQ0osQ0FBQyxDQUFDO0FBRUYsTUFBTSxRQUFRLEdBQUcsQ0FBQyxRQUFpQixFQUF1QyxFQUFFLENBQzFFLE9BQU8sUUFBUSxLQUFLLFFBQVEsSUFBSSxRQUFRLEtBQUssSUFBSSxDQUFDO0FBRXBELDJFQUEyRTtBQUMzRSxNQUFNLE1BQU0sR0FBRyxDQUFDLFNBQWtDLEVBQUUsTUFBYyxFQUFXLEVBQUUsQ0FDN0UsTUFBTSxDQUFDLFNBQVMsQ0FBQyxjQUFjLENBQUMsSUFBSSxDQUFDLFNBQVMsRUFBRSxNQUFNLENBQUMsQ0FBQztBQUUxRDs7O0dBR0c7QUFDSCxNQUFNLE9BQU8sR0FBRyxDQUNkLFVBQW1CLEVBQ3VELEVBQUU7SUFDNUUsSUFBSSxDQUFDLFFBQVEsQ0FBQyxVQUFVLENBQUMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxVQUFVLEVBQUUsZ0JBQWdCLENBQUMsRUFBRSxDQUFDO1FBQ25FLE9BQU8sSUFBSSxDQUFDO0lBQ2QsQ0FBQztJQUNELE1BQU0sS0FBSyxHQUFHLFVBQVUsQ0FBQyxjQUFjLENBQUM7SUFDeEMsSUFDRSxDQUFDLFFBQVEsQ0FBQyxLQUFLLENBQUM7UUFDaEIsT0FBTyxLQUFLLENBQUMsSUFBSSxLQUFLLFFBQVE7UUFDOUIsT0FBTyxLQUFLLENBQUMsYUFBYSxLQUFLLFFBQVE7UUFDdkMsQ0FBQyxNQUFNLENBQUMsS0FBSyxFQUFFLFNBQVMsQ0FBQyxFQUN6QixDQUFDO1FBQ0QsT0FBTyxXQUFXLENBQUM7SUFDckIsQ0FBQztJQUNELE9BQU8sRUFBRSxJQUFJLEVBQUUsS0FBSyxDQUFDLElBQUksRUFBRSxhQUFhLEVBQUUsS0FBSyxDQUFDLGFBQWEsRUFBRSxPQUFPLEVBQUUsS0FBSyxDQUFDLE9BQU8sRUFBRSxDQUFDO0FBQzFGLENBQUMsQ0FBQztBQUVGLE1BQU0sYUFBYSxHQUFHLEdBQVcsRUFBRTtJQUNqQyxNQUFNLEtBQUssR0FBRyxVQUFVLENBQUMsTUFBTSxDQUFDLGVBQWUsQ0FBQyxJQUFJLFVBQVUsQ0FBQyxFQUFFLENBQUMsQ0FBQyxDQUFDO0lBQ3BFLE9BQU8sS0FBSyxDQUFDLElBQUksQ0FBQyxLQUFLLEVBQUUsQ0FBQyxPQUFPLEVBQUUsRUFBRSxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUMsRUFBRSxDQUFDLENBQUMsUUFBUSxDQUFDLENBQUMsRUFBRSxHQUFHLENBQUMsQ0FBQyxDQUFDLElBQUksQ0FBQyxFQUFFLENBQUMsQ0FBQztBQUN4RixDQUFDLENBQUM7QUFFRjs7R0FFRztBQUNILE1BQU0sT0FBTyxTQUFTO0lBQ3BCOzs7O09BSUc7YUFDb0IsdUJBQWtCLEdBQUcsWUFBWSxBQUFmLENBQWdCO0lBaUJ6RCxxQkFBcUI7SUFDckIsWUFBWSxhQUFnQyxFQUFFO1FBZDdCLGtCQUFhLEdBQUcsSUFBSSxHQUFHLEVBQW9DLENBQUM7UUFDckUsV0FBTSxHQUFHLEtBQUssQ0FBQztRQUNmLFlBQU8sR0FBeUIsSUFBSSxDQUFDO1FBRTdDLG1CQUFtQjtRQUNaLGdCQUFXLEdBQUcsSUFBSSxPQUFPLENBQUMsWUFBWSxDQUFDLFdBQVcsRUFBRSxDQUFDO1FBQ3JELGdCQUFXLEdBQUcsSUFBSSxPQUFPLENBQUMsWUFBWSxDQUFDLFdBQVcsQ0FBQztZQUN4RCx5QkFBeUIsRUFBRSxLQUFLLEVBQUUsVUFBVSxFQUFFLEVBQUU7Z0JBQzlDLE1BQU0sSUFBSSxDQUFDLFdBQVcsQ0FBQyxVQUFVLENBQUMsQ0FBQztZQUNyQyxDQUFDO1lBQ0QsY0FBYyxFQUFFLElBQUksQ0FBQyxXQUFXO1NBQ2pDLENBQUMsQ0FBQztRQUlELElBQUksQ0FBQyxXQUFXLEdBQUcsVUFBVSxDQUFDLFdBQVcsSUFBSSxTQUFTLENBQUMsa0JBQWtCLENBQUM7UUFDMUUsSUFBSSxDQUFDLE9BQU8sR0FBRyxXQUFXLENBQUMsSUFBSSxDQUFDLFdBQVcsRUFBRSxDQUFDLFVBQVUsRUFBRSxFQUFFO1lBQzFELEtBQUssSUFBSSxDQUFDLE9BQU8sQ0FBQyxVQUFVLENBQUMsQ0FBQztRQUNoQyxDQUFDLENBQUMsQ0FBQztJQUNMLENBQUM7SUFFRDs7T0FFRztJQUNJLGtCQUFrQixDQUN2QixVQUF1QjtRQUV2QixNQUFNLFlBQVksR0FBRyxJQUFJLE9BQU8sQ0FBQyxZQUFZLENBQUMsWUFBWSxDQUFDLElBQUksQ0FBQyxXQUFXLEVBQUUsVUFBVSxDQUFDLENBQUM7UUFDekYsT0FBTyxZQUFZLENBQUM7SUFDdEIsQ0FBQztJQUVEOztPQUVHO0lBQ0ksS0FBSyxDQUFDLFdBQVcsQ0FDdEIsVUFBYTtRQUViLElBQUksQ0FBQyxVQUFVLEVBQUUsQ0FBQztRQUNsQixNQUFNLElBQUksQ0FBQyxPQUFPLENBQUMsSUFBSSxDQUFDLFVBQVUsQ0FBQyxDQUFDO0lBQ3RDLENBQUM7SUFFRDs7T0FFRztJQUNJLEtBQUssQ0FBQyxrQkFBa0IsQ0FDN0IsU0FBc0IsRUFDdEIsZUFBeUQ7UUFFekQsSUFBSSxDQUFDLFdBQVcsQ0FBQyxlQUFlLENBQzlCLElBQUksT0FBTyxDQUFDLFlBQVksQ0FBQyxZQUFZLENBQUksU0FBUyxFQUFFLGVBQWUsQ0FBQyxDQUNyRSxDQUFDO0lBQ0osQ0FBQztJQUVEOzs7O09BSUc7SUFDSSxLQUFLLENBQUMsU0FBUyxDQUNwQixPQUFrQixFQUNsQixVQUF3QjtRQUV4QixNQUFNLE9BQU8sR0FBMkI7WUFDdEMsY0FBYyxFQUFFO2dCQUNkLElBQUksRUFBRSxPQUFPO2dCQUNiLGFBQWEsRUFBRSxhQUFhLEVBQUU7Z0JBQzlCLE9BQU8sRUFBRSxVQUFVO2FBQ3BCO1NBQ0YsQ0FBQztRQUNGLE1BQU0sSUFBSSxDQUFDLFdBQVcsQ0FBQyxPQUFPLENBQUMsQ0FBQztJQUNsQyxDQUFDO0lBRUQ7Ozs7O09BS0c7SUFDSSxTQUFTLENBQ2QsT0FBa0IsRUFDbEIsVUFBcUM7UUFFckMsSUFBSSxDQUFDLFVBQVUsRUFBRSxDQUFDO1FBQ2xCLHdFQUF3RTtRQUN4RSxxREFBcUQ7UUFDckQsTUFBTSxPQUFPLEdBQXdCLENBQUMsVUFBVSxFQUFFLFFBQVEsRUFBRSxFQUFFLENBQzVELFVBQVUsQ0FBQyxVQUEwQixFQUFFLFFBQWEsQ0FBQyxDQUFDO1FBQ3hELElBQUksUUFBUSxHQUFHLElBQUksQ0FBQyxhQUFhLENBQUMsR0FBRyxDQUFDLE9BQU8sQ0FBQyxDQUFDO1FBQy9DLElBQUksQ0FBQyxRQUFRLEVBQUUsQ0FBQztZQUNkLFFBQVEsR0FBRyxJQUFJLEdBQUcsRUFBRSxDQUFDO1lBQ3JCLElBQUksQ0FBQyxhQUFhLENBQUMsR0FBRyxDQUFDLE9BQU8sRUFBRSxRQUFRLENBQUMsQ0FBQztRQUM1QyxDQUFDO1FBQ0QsUUFBUSxDQUFDLEdBQUcsQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUN0QixPQUFPO1lBQ0wsV0FBVyxFQUFFLEdBQUcsRUFBRTtnQkFDaEIsTUFBTSxPQUFPLEdBQUcsSUFBSSxDQUFDLGFBQWEsQ0FBQyxHQUFHLENBQUMsT0FBTyxDQUFDLENBQUM7Z0JBQ2hELElBQUksQ0FBQyxPQUFPLEVBQUUsQ0FBQztvQkFDYixPQUFPO2dCQUNULENBQUM7Z0JBQ0QsT0FBTyxDQUFDLE1BQU0sQ0FBQyxPQUFPLENBQUMsQ0FBQztnQkFDeEIsSUFBSSxPQUFPLENBQUMsSUFBSSxLQUFLLENBQUMsRUFBRSxDQUFDO29CQUN2QixJQUFJLENBQUMsYUFBYSxDQUFDLE1BQU0sQ0FBQyxPQUFPLENBQUMsQ0FBQztnQkFDckMsQ0FBQztZQUNILENBQUM7U0FDRixDQUFDO0lBQ0osQ0FBQztJQUVEOzs7OztPQUtHO0lBQ0ksS0FBSyxDQUFDLEtBQUs7UUFDaEIsSUFBSSxDQUFDLElBQUksQ0FBQyxPQUFPLEVBQUUsQ0FBQztZQUNsQixJQUFJLENBQUMsTUFBTSxHQUFHLElBQUksQ0FBQztZQUNuQixJQUFJLENBQUMsYUFBYSxDQUFDLEtBQUssRUFBRSxDQUFDO1lBQzNCLElBQUksQ0FBQyxPQUFPLEdBQUcsSUFBSSxDQUFDLE9BQU8sQ0FBQyxLQUFLLEVBQUUsQ0FBQztRQUN0QyxDQUFDO1FBQ0QsTUFBTSxJQUFJLENBQUMsT0FBTyxDQUFDO0lBQ3JCLENBQUM7SUFFTyxVQUFVO1FBQ2hCLElBQUksSUFBSSxDQUFDLE1BQU0sRUFBRSxDQUFDO1lBQ2hCLE1BQU0sSUFBSSxLQUFLLENBQUMsc0JBQXNCLElBQUksQ0FBQyxXQUFXLGFBQWEsQ0FBQyxDQUFDO1FBQ3ZFLENBQUM7SUFDSCxDQUFDO0lBRU8sS0FBSyxDQUFDLE9BQU8sQ0FBQyxVQUFtQjtRQUN2QyxJQUFJLElBQUksQ0FBQyxNQUFNLEVBQUUsQ0FBQztZQUNoQixPQUFPO1FBQ1QsQ0FBQztRQUNELE1BQU0sS0FBSyxHQUFHLE9BQU8sQ0FBQyxVQUFVLENBQUMsQ0FBQztRQUNsQyxJQUFJLEtBQUssS0FBSyxXQUFXLEVBQUUsQ0FBQztZQUMxQixPQUFPLENBQUMsR0FBRyxDQUFDLHNDQUFzQyxDQUFDLENBQUM7WUFDcEQsT0FBTztRQUNULENBQUM7UUFDRCxJQUFJLEtBQUssRUFBRSxDQUFDO1lBQ1YsSUFBSSxDQUFDLFFBQVEsQ0FBQyxLQUFLLENBQUMsQ0FBQztZQUNyQixPQUFPO1FBQ1QsQ0FBQztRQUNELHVFQUF1RTtRQUN2RSx1RUFBdUU7UUFDdkUsaUNBQWlDO1FBQ2pDLE1BQU0sUUFBUSxHQUFHLE1BQU0sSUFBSSxDQUFDLFdBQVcsQ0FBQyxtQkFBbUIsQ0FDekQsVUFBMEQsRUFDMUQsRUFBRSxTQUFTLEVBQUUsSUFBSSxFQUFFLENBQ3BCLENBQUM7UUFDRixJQUFJLFFBQVEsSUFBSSxDQUFDLFFBQVEsQ0FBQyxLQUFLLElBQUksQ0FBQyxJQUFJLENBQUMsTUFBTSxFQUFFLENBQUM7WUFDaEQsTUFBTSxJQUFJLENBQUMsV0FBVyxDQUFDLFFBQVEsQ0FBQyxDQUFDO1FBQ25DLENBQUM7SUFDSCxDQUFDO0lBRU8sUUFBUSxDQUFDLFFBQTZEO1FBQzVFLE1BQU0sUUFBUSxHQUFHLElBQUksQ0FBQyxhQUFhLENBQUMsR0FBRyxDQUFDLFFBQVEsQ0FBQyxJQUFJLENBQUMsQ0FBQztRQUN2RCxJQUFJLENBQUMsUUFBUSxFQUFFLENBQUM7WUFDZCxPQUFPO1FBQ1QsQ0FBQztRQUNELEtBQUssTUFBTSxPQUFPLElBQUksQ0FBQyxHQUFHLFFBQVEsQ0FBQyxFQUFFLENBQUM7WUFDcEMsa0VBQWtFO1lBQ2xFLHNEQUFzRDtZQUN0RCxJQUFJLElBQUksQ0FBQyxNQUFNLEVBQUUsQ0FBQztnQkFDaEIsT0FBTztZQUNULENBQUM7WUFDRCxJQUFJLENBQUMsUUFBUSxDQUFDLEdBQUcsQ0FBQyxPQUFPLENBQUMsRUFBRSxDQUFDO2dCQUMzQixTQUFTO1lBQ1gsQ0FBQztZQUNELEtBQUssQ0FBQyxLQUFLLElBQUksRUFBRSxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUMsT0FBTyxFQUFFLFFBQVEsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxLQUFLLENBQUMsQ0FBQyxRQUFpQixFQUFFLEVBQUU7Z0JBQ25GLHNEQUFzRDtnQkFDdEQsT0FBTyxDQUFDLEtBQUssQ0FBQyxzQ0FBc0MsUUFBUSxDQUFDLElBQUksVUFBVSxFQUFFLFFBQVEsQ0FBQyxDQUFDO1lBQ3pGLENBQUMsQ0FBQyxDQUFDO1FBQ0wsQ0FBQztJQUNILENBQUMifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design.estate/dees-comms",
-  "version": "1.0.31",
+  "version": "1.1.0",
   "private": false,
   "description": "A communications module for enabling DOM-based messaging and synchronization across browser tabs and workers.",
   "main": "dist_ts/index.js",
@@ -9,15 +9,15 @@
   "author": "Lossless GmbH",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tsbundle": "^2.11.3",
-    "@git.zone/tsrun": "^2.0.6",
-    "@git.zone/tstest": "^3.6.7",
-    "@types/node": "^26.1.1"
+    "@git.zone/tsbuild": "^4.5.2",
+    "@git.zone/tsbundle": "^2.14.0",
+    "@git.zone/tsrun": "^3.0.0",
+    "@git.zone/tstest": "^6.2.0",
+    "@types/node": "^26.6.1"
   },
   "dependencies": {
-    "@api.global/typedrequest": "^3.8.0",
-    "@api.global/typedrequest-interfaces": "^4.0.0",
+    "@api.global/typedrequest": "^8.0.3",
+    "@api.global/typedrequest-interfaces": "^7.1.0",
     "@push.rocks/smartdelay": "^3.0.5",
     "broadcast-channel": "^7.2.0"
   },

package/readme.md

@@ -1,6 +1,6 @@
 # @design.estate/dees-comms
 
-a comms module for communicating within the DOM
+Typed messaging between the tabs, frames and workers of one origin over a BroadcastChannel: typed requests that expect an answer, and typed events that do not.
 
 ## Issue Reporting and Security
 
@@ -8,113 +8,112 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 
 ## Install
 
-To integrate `@design.estate/dees-comms` into your project, run the following command in your terminal:
-
 ```bash
 pnpm add @design.estate/dees-comms
 ```
 
-This will add the package to your project dependencies. 
-
 ## Usage
 
-`@design.estate/dees-comms` facilitates communication within the DOM, especially between various workers and tabs in client-side JavaScript. Using TypeScript and the provided ESM syntax will enhance your development experience with better intellisense support and type safety.
-
-### Setting Up
+### Channels
 
-First, make sure to import the module in your TypeScript file:
+Every `DeesComms` instance talks on one BroadcastChannel. Instances hear each other only when they use the same channel name, in any tab, frame or worker of the same origin.
 
 ```typescript
 import { DeesComms } from '@design.estate/dees-comms';
 
-interface IMyMessage {
-  method: 'myMethod';
-  request: {
-    someData: string;
-  };
-  response: {
-    reply: string;
-  };
-}
-```
-
-### Initializing the Communication Module
+// the default channel, 'dees-comms'
+const comms = new DeesComms();
 
-Create an instance of the `DeesComms` class to start using the module. This instance will act as the central communication hub in your application.
+// a channel of this application's own
+const appComms = new DeesComms({ channelName: 'my-app' });
 
-```typescript
-const myDeesComms = new DeesComms();
+console.log(DeesComms.defaultChannelName); // 'dees-comms'
+console.log(appComms.channelName); // 'my-app'
 ```
 
-### Sending Messages
+An instance created without a name uses `DeesComms.defaultChannelName`, the channel every instance used before names existed. Other packages talk on it: `DomTools` of `@design.estate/dees-domtools` opens an instance on it, and the service worker of `@api.global/typedserver` exchanges its messages with its pages there. Give your application's messages a channel of their own, so that they neither reach nor disturb that traffic.
 
-To send messages, you'll need to create a typed request. Let's assume we are sending a message that requires a response:
+The platform's `BroadcastChannel` is used wherever there is one (browsers, workers, Node.js); elsewhere the [`broadcast-channel`](https://www.npmjs.com/package/broadcast-channel) package stands in for it.
 
-```typescript
-// Creating a typed request
-const myTypedRequest = myDeesComms.createTypedRequest<IMyMessage>('myMethod');
-
-// Firing the request
-const response = await myTypedRequest.fire({
-  someData: 'Hello, World!',
-});
-console.log('Received response:', response.reply);
-```
-
-### Receiving and Handling Messages
+### Typed requests
 
-To handle incoming messages, you need to define handlers for the types of messages you expect to receive. 
+A typed request goes to every other instance on the channel; an instance with a handler for its method answers it.
 
 ```typescript
-// Define the handler for the 'myMethod' message
-myDeesComms.createTypedHandler<IMyMessage>('myMethod', async (request) => {
-  console.log('Message received:', request.someData);
-  
-  // Process the incoming message...
-  
-  // Return a response (if needed)
-  return {
-    reply: 'Message received loud and clear!'
+import { DeesComms } from '@design.estate/dees-comms';
+import type { ITypedRequest } from '@api.global/typedrequest-interfaces';
+
+interface IGreetRequest extends ITypedRequest {
+  method: 'greet';
+  request: {
+    name: string;
+  };
+  response: {
+    reply: string;
   };
+}
+
+// in one tab or worker
+const answering = new DeesComms({ channelName: 'my-app' });
+answering.createTypedHandler<IGreetRequest>('greet', async (request) => {
+  return { reply: `Hello ${request.name}, nice to meet you!` };
 });
-```
 
-### Communication Between Tabs or Workers
+// in another one
+const asking = new DeesComms({ channelName: 'my-app' });
+const response = await asking.createTypedRequest<IGreetRequest>('greet').fire({ name: 'Alice' });
+console.log(response.reply); // 'Hello Alice, nice to meet you!'
+```
 
-`@design.estate/dees-comms` uses the Broadcast Channel API and a polyfill for environments where it's not available, enabling seamless communication between different contexts like tabs, iframes, or web workers.
+`postMessage()` posts a typed request object as it is; `typedrouter` and `typedtarget` are the `@api.global/typedrequest` router and target the instance routes with.
 
-### Complete Example
+### Typed events
 
-Putting it all together, let's create a small application that sends a message and listens for a response:
+A typed event is sent to every other instance on the channel and expects no answer. It is declared as an `ITypedEvent` of `@api.global/typedrequest-interfaces`: its `name` is the contract, its `payload` is what travels.
 
 ```typescript
 import { DeesComms } from '@design.estate/dees-comms';
+import type { ITypedEvent } from '@api.global/typedrequest-interfaces';
 
-interface IGreetRequest {
-  method: 'greet';
-  request: {
-    name: string;
-  };
-  response: {
-    reply: string;
+interface ISettingsChangedEvent extends ITypedEvent<{ section: string }> {
+  name: 'settingsChanged';
+  uniqueEventId: string;
+  payload: {
+    section: string;
   };
 }
 
-const appDeesComms = new DeesComms();
-
-// Setting up the listener
-appDeesComms.createTypedHandler<IGreetRequest>('greet', async (request) => {
-  console.log(`Greetings received from ${request.name}`);
-  return { reply: `Hello ${request.name}, nice to meet you!` };
+// in every tab that has to follow
+const listening = new DeesComms({ channelName: 'my-app' });
+const subscription = listening.subscribe<ISettingsChangedEvent>('settingsChanged', (payload, event) => {
+  console.log(`settings changed in ${payload.section}`, event.uniqueEventId);
 });
 
-// Sending a greeting message
-const greetRequest = appDeesComms.createTypedRequest<IGreetRequest>('greet');
-const response = await greetRequest.fire({ name: 'Alice' });
-console.log(response.reply); // Expected output: "Hello Alice, nice to meet you!"
+// in the tab where it happened
+const telling = new DeesComms({ channelName: 'my-app' });
+await telling.broadcast<ISettingsChangedEvent>('settingsChanged', { section: 'profile' });
+
+// later
+subscription.unsubscribe();
 ```
 
-This module provides a powerful and flexible way to handle communications within the DOM, leveraging modern JavaScript features and patterns. The usage of TypeScript ensures type safety and enhances code understandability and maintainability.
+- The instance that broadcasts an event does not receive it; every other instance on the channel does, in the same context or another one.
+- `broadcast()` gives every event a new `uniqueEventId`.
+- Handlers of one name run in the order they subscribed. A handler that throws or rejects is reported with `console.error`, naming the event and the error but never the payload, and does not keep the others from running. A handler that an earlier one unsubscribes during the same event is not called for it.
+- Events and typed requests stay apart: an event never reaches a typed handler, and a typed request never reaches a subscription, whatever their names.
+- An instance of 1.0.32 routes every message it receives as a typed request; on the platform's own BroadcastChannel, `@api.global/typedrequest` 8 then logs `TypedRouter received a malformed request DTO` for every event. That is one more reason to broadcast on a channel of your application's own.
+
+### Closing
+
+```typescript
+await comms.close();
+```
+
+A closed instance receives nothing: its subscriptions end and its typed handlers are no longer asked. `postMessage()`, `broadcast()` and the typed requests it fires reject, and `subscribe()` throws. A typed request that is still waiting for its response when the channel closes cannot receive it and ends with its own timeout. Closing again does nothing. An open channel keeps a Node.js process alive, so close every instance a test or a script opens.
+
+### What travels
+
+Requests, responses and events are copied with the structured clone algorithm, so they carry data, not functions or class instances. A BroadcastChannel is confined to its origin, but every script of that origin can listen on a channel whose name it knows: send no secrets, and nothing that identifies a person, on it.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-comms',
-  version: '1.0.31',
+  version: '1.1.0',
   description: 'A communications module for enabling DOM-based messaging and synchronization across browser tabs and workers.'
 }