@telperion/messenger 7.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Thalesrc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,600 @@
+# @telperion/messenger
+
+[![npm](https://img.shields.io/npm/v/@telperion/messenger.svg)](https://www.npmjs.com/package/@telperion/messenger)
+[![npm](https://img.shields.io/npm/dw/@telperion/messenger.svg)](https://www.npmjs.com/package/@telperion/messenger)
+[![codecov](https://codecov.io/gh/telperiontech/telperion/graph/badge.svg?token=dz46LY3onk&flag=messenger)](https://codecov.io/gh/telperiontech/telperion?flag=messenger)
+[![TypeScript](https://badges.frapsoft.com/typescript/version/typescript-next.svg?v=101)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Javascript messaging library for cross-context communication
+
+**Part of the [Telperion](https://github.com/telperiontech/telperion) monorepo**
+
+## Installation
+
+```bash
+npm install @telperion/messenger
+# or
+yarn add @telperion/messenger
+# or
+pnpm add @telperion/messenger
+```
+
+## Overview
+
+Messenger provides a unified, decorator-based API for cross-context messaging in JavaScript applications. Built on RxJS, it supports:
+
+- 🖼️ **Iframe Communication** - Parent-child window messaging
+- 🧩 **Chrome Extensions** - Background scripts, content scripts, and popups
+- 👷 **Web Workers** - Main thread and worker communication
+- 📡 **Broadcast Channel** - Tab-to-tab messaging
+
+## Core Concepts
+
+### MessageClient & MessageHost
+
+The library uses two main abstractions:
+
+- **`MessageClient`**: Sends requests and receives responses (uses `@Request` decorator)
+- **`MessageHost`**: Listens for requests and sends responses (uses `@Listen` decorator)
+- **`MessageService`**: Combines both client and host (bidirectional communication)
+
+![Core Architecture](docs/images/core-architecture.svg)
+
+### Decorators
+
+- **`@Request(path)`**: Marks a method as a message sender
+- **`@Listen(path)`**: Marks a method as a message listener
+
+## Usage
+
+### Iframe Communication
+
+Send and receive messages between iframes and parent windows.
+
+![Iframe Communication](docs/images/iframe-communication.svg)
+
+#### Client-Only (Iframe)
+
+```typescript
+import { IframeMessageClient, Request } from '@telperion/messenger/iframe';
+import { Observable } from 'rxjs';
+
+class IframeClient extends IframeMessageClient {
+  @Request('greeting')
+  sayHello(name: string): Observable<string> {
+    return null!; // Implementation handled by decorator
+  }
+}
+
+// Default: sends messages to parent window
+const client = new IframeClient();
+
+// Optional: specify channel name
+const clientWithChannel = new IframeClient('my-channel');
+
+// Optional: target specific iframe (from parent window)
+const iframe = document.querySelector('iframe');
+const clientToIframe = new IframeClient('my-channel', iframe);
+
+// Optional: use a function to get iframe dynamically
+const clientWithDynamicIframe = new IframeClient('my-channel', () => 
+  document.querySelector('iframe#dynamic')
+);
+
+client.sayHello('John').subscribe(response => {
+  console.log(response); // 'Hello John!'
+});
+```
+
+#### Host-Only (Parent Window)
+
+```typescript
+import { IframeMessageHost, Listen, UpcomingMessage } from '@telperion/messenger/iframe';
+import { of } from 'rxjs';
+
+class ParentHost extends IframeMessageHost {
+  @Listen('greeting')
+  handleGreeting({ data }: UpcomingMessage<string>): Observable<string> {
+    return of(`Hello ${data}!`);
+  }
+}
+
+// Default: listens to all iframes
+const host = new ParentHost();
+
+// Optional: specify channel name
+const hostWithChannel = new ParentHost('my-channel');
+
+// Optional: listen only to specific iframe
+const iframe = document.querySelector('iframe');
+const hostForSpecificIframe = new ParentHost('my-channel', iframe);
+
+// Optional: use a function to get iframe dynamically
+const hostWithDynamicIframe = new ParentHost('my-channel', () => 
+  document.querySelector('iframe#dynamic')
+);
+```
+
+#### Bidirectional Communication (MessageService)
+
+```typescript
+import { IframeMessageService, Request, Listen } from '@telperion/messenger/iframe';
+import { of, Observable } from 'rxjs';
+
+class IframeBidirectional extends IframeMessageService {
+  // Send messages
+  @Request('getData')
+  requestData(): Observable<any> {
+    return null!;
+  }
+
+  // Receive messages
+  @Listen('update')
+  handleUpdate(data: any): Observable<string> {
+    console.log('Received update:', data);
+    return of('Update processed');
+  }
+}
+
+// Default: communicates with parent window
+const service = new IframeBidirectional();
+
+// Optional: specify channel name and target frame
+const iframe = document.querySelector('iframe');
+const serviceWithTarget = new IframeBidirectional('my-channel', iframe);
+
+// From within iframe (communicates with parent)
+const iframeService = new IframeBidirectional('my-channel');
+```
+
+---
+
+### Chrome Extensions
+
+Communicate across extension contexts (background, content scripts, popups).
+
+![Chrome Extension Communication](docs/images/chrome-extension-communication.svg)
+
+#### Content Script
+
+```typescript
+import { ChromeMessageClient, Request } from '@telperion/messenger/chrome';
+import { Observable } from 'rxjs';
+
+class ContentScript extends ChromeMessageClient {
+  @Request('fetchData')
+  getData(query: string): Observable<any> {
+    return null!;
+  }
+
+  @Request('saveSettings')
+  saveSettings(settings: object): Observable<boolean> {
+    return null!;
+  }
+}
+
+const contentScript = new ContentScript();
+
+contentScript.getData('user').subscribe(data => {
+  console.log('Received:', data);
+});
+```
+
+#### Background Script
+
+```typescript
+import { ChromeMessageHost, Listen } from '@telperion/messenger/chrome';
+import { of, Observable } from 'rxjs';
+
+class BackgroundScript extends ChromeMessageHost {
+  @Listen('fetchData')
+  handleFetchData(query: string): Observable<any> {
+    // Fetch from API or storage
+    return of({ name: 'John', age: 30 });
+  }
+
+  @Listen('saveSettings')
+  handleSaveSettings(settings: object): Observable<boolean> {
+    // Save to chrome.storage
+    return of(true);
+  }
+}
+
+const background = new BackgroundScript();
+```
+
+---
+
+### Web Workers
+
+Communicate between main thread and web workers.
+
+![Web Worker Communication](docs/images/worker-communication.svg)
+
+#### Main Thread
+
+```typescript
+import { WorkerMessageService, Request, Listen } from '@telperion/messenger/worker';
+import { of, Observable } from 'rxjs';
+
+class MainThread extends WorkerMessageService {
+  @Request('processData')
+  sendDataToWorker(data: number[]): Observable<number> {
+    return null!;
+  }
+
+  @Listen('progress')
+  handleProgress(percent: number): Observable<void> {
+    console.log(`Progress: ${percent}%`);
+    return of(void 0);
+  }
+}
+
+// Must provide Worker instance in main thread
+const worker = new Worker('./worker.js');
+const mainService = new MainThread(worker);
+
+mainService.sendDataToWorker([1, 2, 3, 4, 5]).subscribe(result => {
+  console.log('Worker result:', result);
+});
+```
+
+##### Flexible Worker Initialization
+
+The worker parameter supports multiple initialization patterns for different use cases:
+
+```typescript
+// Direct Worker instance
+const service1 = new MainThread(new Worker('./worker.js'));
+
+// Promise that resolves to a Worker (for async initialization)
+const workerPromise = import('./worker.js').then(m => new Worker(m.default));
+const service2 = new MainThread(workerPromise);
+
+// Function that returns a Worker (for lazy initialization)
+const service3 = new MainThread(() => new Worker('./worker.js'));
+
+// Function that returns a Promise<Worker> (for async lazy initialization)
+const service4 = new MainThread(async () => {
+  const module = await import('./worker.js');
+  return new Worker(module.default);
+});
+```
+
+##### Dynamic Worker Management with `initialize()`
+
+The `initialize()` method allows you to switch workers at runtime or re-establish connections:
+
+```typescript
+class MainThread extends WorkerMessageService {
+  // ... decorators and methods
+}
+
+// Start without a worker
+const service = new MainThread();
+
+// Later, connect to a worker dynamically
+service.initialize(new Worker('./worker.js'));
+
+// Switch to a different worker
+service.initialize(new Worker('./different-worker.js'));
+
+// Re-establish connection after worker error
+const worker = new Worker('./worker.js');
+worker.onerror = (error) => {
+  console.error('Worker error, reinitializing...', error);
+  service.initialize(new Worker('./worker.js'));
+};
+service.initialize(worker);
+
+// Conditional worker initialization
+function getWorker() {
+  return navigator.hardwareConcurrency > 2 
+    ? new Worker('./heavy-worker.js')
+    : new Worker('./light-worker.js');
+}
+service.initialize(getWorker);
+```
+
+#### Worker Thread
+
+```typescript
+import { WorkerMessageService, Request, Listen } from '@telperion/messenger/worker';
+import { of, Observable } from 'rxjs';
+
+class WorkerThread extends WorkerMessageService {
+  @Listen('processData')
+  handleProcessData(data: number[]): Observable<number> {
+    // Heavy computation
+    const result = data.reduce((sum, n) => sum + n, 0);
+    return of(result);
+  }
+
+  @Request('progress')
+  reportProgress(percent: number): Observable<void> {
+    return null!;
+  }
+}
+
+// Inside worker: no argument needed (uses self)
+const workerService = new WorkerThread();
+```
+
+---
+
+### Broadcast Channel
+
+Communicate between different tabs/windows of the same origin.
+
+![Broadcast Channel Communication](docs/images/broadcast-communication.svg)
+
+#### Tab 1
+
+```typescript
+import { BroadcastMessageService, Request, Listen } from '@telperion/messenger/broadcast';
+import { of, Observable } from 'rxjs';
+
+class Tab1 extends BroadcastMessageService {
+  @Request('sync')
+  requestSync(data: any): Observable<string> {
+    return null!;
+  }
+
+  @Listen('notification')
+  handleNotification(message: string): Observable<void> {
+    console.log('Notification:', message);
+    return of(void 0);
+  }
+}
+
+const tab1 = new Tab1('my-app-channel');
+
+tab1.requestSync({ user: 'John' }).subscribe(response => {
+  console.log(response); // 'Sync completed'
+});
+```
+
+#### Tab 2
+
+```typescript
+import { BroadcastMessageService, Request, Listen } from '@telperion/messenger/broadcast';
+import { of, Observable } from 'rxjs';
+
+class Tab2 extends BroadcastMessageService {
+  @Listen('sync')
+  handleSync(data: any): Observable<string> {
+    console.log('Syncing data:', data);
+    return of('Sync completed');
+  }
+
+  @Request('notification')
+  sendNotification(message: string): Observable<void> {
+    return null!;
+  }
+}
+
+const tab2 = new Tab2('my-app-channel');
+```
+
+---
+
+## Advanced Features
+
+### Streaming Responses
+
+Return multiple values over time using RxJS operators:
+
+```typescript
+import { Listen } from '@telperion/messenger/iframe';
+import { interval } from 'rxjs';
+import { map, take } from 'rxjs/operators';
+
+class StreamingHost extends IframeMessageHost {
+  @Listen('countdown')
+  handleCountdown(start: number): Observable<number> {
+    return interval(1000).pipe(
+      map(i => start - i),
+      take(start + 1)
+    );
+  }
+}
+```
+
+The client receives each value as it's emitted:
+
+```typescript
+client.countdown(5).subscribe(
+  value => console.log(value), // 5, 4, 3, 2, 1, 0
+  error => console.error(error),
+  () => console.log('Complete!')
+);
+```
+
+### Error Handling
+
+```typescript
+import { Listen } from '@telperion/messenger/iframe';
+import { throwError } from 'rxjs';
+
+class ErrorHost extends IframeMessageHost {
+  @Listen('riskyOperation')
+  handleRiskyOperation(data: any): Observable<any> {
+    if (!data.valid) {
+      return throwError(() => new Error('Invalid data'));
+    }
+    return of({ success: true });
+  }
+}
+```
+
+### Constructor Parameters
+
+#### Iframe
+
+**`IframeMessageClient` / `IframeMessageHost` / `IframeMessageService`**
+
+```typescript
+constructor(channelName?: string, targetFrame?: HTMLIFrameElement | (() => HTMLIFrameElement))
+```
+
+- **`channelName`** (optional): Channel identifier for namespacing messages. Default: `'messenger-iframe-message'`
+- **`targetFrame`** (optional): Specific iframe to communicate with. Can be:
+  - `HTMLIFrameElement`: Direct reference to iframe element
+  - `() => HTMLIFrameElement`: Function returning iframe (useful for dynamic iframes)
+  - Omit to communicate with parent window (from iframe) or all iframes (from parent)
+
+**Examples:**
+```typescript
+// From iframe: communicate with parent
+const client = new IframeMessageClient();
+
+// From parent: communicate with specific iframe
+const iframe = document.querySelector('iframe');
+const host = new IframeMessageHost('my-channel', iframe);
+
+// Dynamic iframe reference
+const service = new IframeMessageService('my-channel', () => 
+  document.querySelector('iframe[data-active="true"]')
+);
+```
+
+#### Worker
+
+**`WorkerMessageClient` / `WorkerMessageHost` / `WorkerMessageService`**
+
+```typescript
+constructor(worker?: Worker)
+```
+
+- **`worker`** (optional): Worker instance for main thread communication
+  - **In main thread**: Must provide `Worker` instance
+  - **In worker thread**: Omit parameter (uses `self` automatically)
+
+**Examples:**
+```typescript
+// Main thread: must provide worker
+const worker = new Worker('./worker.js');
+const service = new WorkerMessageService(worker);
+
+// Inside worker: no parameter needed
+const service = new WorkerMessageService();
+```
+
+#### Broadcast
+
+**`BroadcastMessageClient` / `BroadcastMessageHost` / `BroadcastMessageService`**
+
+```typescript
+constructor(channelName?: string)
+```
+
+- **`channelName`** (optional): Broadcast channel name. Default: `'messenger-broadcast-message'`
+
+**Example:**
+```typescript
+const service = new BroadcastMessageService('app-sync-channel');
+```
+
+#### Chrome
+
+**`ChromeMessageClient` / `ChromeMessageHost`**
+
+```typescript
+constructor(connectionName?: string)
+```
+
+- **`connectionName`** (optional): Connection identifier. Default: `'messenger-chrome-message'`
+
+**Example:**
+```typescript
+const client = new ChromeMessageClient('extension-port');
+```
+
+## API Reference
+
+### Classes
+
+- **`MessageClient`** - Base class for message senders
+- **`MessageHost`** - Base class for message receivers
+- **`IframeMessageClient`** - Iframe client implementation
+- **`IframeMessageHost`** - Iframe host implementation
+- **`IframeMessageService`** - Bidirectional iframe communication
+- **`ChromeMessageClient`** - Chrome extension client
+- **`ChromeMessageHost`** - Chrome extension host
+- **`WorkerMessageService`** - Bidirectional worker communication
+- **`BroadcastMessageClient`** - Broadcast channel client
+- **`BroadcastMessageHost`** - Broadcast channel host
+- **`BroadcastMessageService`** - Bidirectional broadcast communication
+
+### Decorators
+
+- **`@Request(path: string)`** - Decorator for sending messages
+- **`@Listen(path: string)`** - Decorator for receiving messages
+
+### Types
+
+- **`Message`** - Message payload structure
+- **`MessageResponse`** - Response payload structure
+- **`UpcomingMessage<T>`** - Incoming message with sender info (iframe)
+
+## Requirements
+
+- RxJS 7.x or higher
+- TypeScript 4.x or higher (for decorator support)
+- Modern browser with ES2015+ support
+
+## Development
+
+### Testing
+
+Messenger uses a modular testing structure with separate configurations for each submodule:
+
+```bash
+# Run all tests (all submodules in parallel)
+pnpm nx run messenger:test
+
+# Run specific submodule tests
+pnpm nx run messenger:test/core          # Core functionality (Node.js)
+pnpm nx run messenger:test/worker        # Web Worker tests (Browser)
+pnpm nx run messenger:test/chrome        # Chrome extension tests (Browser)
+pnpm nx run messenger:test/broadcast     # Broadcast Channel tests (Browser)
+pnpm nx run messenger:test/iframe        # Iframe communication tests (Browser)
+
+# Run all tests with coverage and merge reports
+pnpm nx run messenger:test/coverage
+
+# Debug browser tests (visible browser)
+pnpm nx run messenger:test/headed
+```
+
+For detailed testing documentation, see:
+- [TESTING-GUIDE.md](./docs/TESTING-GUIDE.md) - Complete testing guide
+- [TEST-COMMANDS.md](./docs/TEST-COMMANDS.md) - Quick command reference
+- [TESTING-SETUP-SUMMARY.md](./docs/TESTING-SETUP-SUMMARY.md) - Setup overview
+
+### Building
+
+```bash
+# Build the library
+pnpm nx build messenger
+
+# Build and watch for changes
+pnpm nx build messenger --watch
+```
+
+### Contributing
+
+When adding new submodule support:
+
+1. Create submodule directory in `src/`
+2. Add test files alongside code: `*.spec.ts`
+3. Create submodule's `vitest.config.ts` in the submodule directory
+4. Add test target in `project.json`
+5. Update main `test` target to include new submodule
+
+See [TESTING-GUIDE.md](./docs/TESTING-GUIDE.md) for details on adding new submodules.
+
+## License
+
+MIT © [Telperion](https://github.com/telperiontech)

package/broadcast/default-channel-name.cjs

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CHANNEL_NAME = void 0;
+exports.DEFAULT_CHANNEL_NAME = 'MESSENGER_DEFAULT_CHANNEL';

package/broadcast/default-channel-name.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_CHANNEL_NAME = "MESSENGER_DEFAULT_CHANNEL";

package/broadcast/default-channel-name.js

@@ -0,0 +1,3 @@
+export const DEFAULT_CHANNEL_NAME = 'MESSENGER_DEFAULT_CHANNEL';
+
+//# sourceMappingURL=default-channel-name.js.map

package/broadcast/default-channel-name.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../libs/messenger/src/broadcast/default-channel-name.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG,2BAA2B,CAAC","file":"default-channel-name.js","sourcesContent":["export const DEFAULT_CHANNEL_NAME = 'MESSENGER_DEFAULT_CHANNEL';\n"]}

package/broadcast/index.cjs

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Listen = exports.Request = exports.BroadcastMessageService = exports.BroadcastMessageHost = exports.BroadcastMessageClient = void 0;
+var message_client_1 = require("./message-client");
+Object.defineProperty(exports, "BroadcastMessageClient", { enumerable: true, get: function () { return message_client_1.BroadcastMessageClient; } });
+var message_host_1 = require("./message-host");
+Object.defineProperty(exports, "BroadcastMessageHost", { enumerable: true, get: function () { return message_host_1.BroadcastMessageHost; } });
+var message_service_1 = require("./message-service");
+Object.defineProperty(exports, "BroadcastMessageService", { enumerable: true, get: function () { return message_service_1.BroadcastMessageService; } });
+var request_decorator_1 = require("../request.decorator");
+Object.defineProperty(exports, "Request", { enumerable: true, get: function () { return request_decorator_1.Request; } });
+var listen_decorator_1 = require("../listen.decorator");
+Object.defineProperty(exports, "Listen", { enumerable: true, get: function () { return listen_decorator_1.Listen; } });

package/broadcast/index.d.ts

@@ -0,0 +1,5 @@
+export { BroadcastMessageClient } from './message-client';
+export { BroadcastMessageHost } from './message-host';
+export { BroadcastMessageService } from './message-service';
+export { Request } from '../request.decorator';
+export { Listen } from '../listen.decorator';

package/broadcast/index.js

@@ -0,0 +1,7 @@
+export { BroadcastMessageClient } from './message-client';
+export { BroadcastMessageHost } from './message-host';
+export { BroadcastMessageService } from './message-service';
+export { Request } from '../request.decorator';
+export { Listen } from '../listen.decorator';
+
+//# sourceMappingURL=index.js.map

package/broadcast/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../libs/messenger/src/broadcast/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC","file":"index.js","sourcesContent":["export { BroadcastMessageClient } from './message-client';\nexport { BroadcastMessageHost } from './message-host';\nexport { BroadcastMessageService } from './message-service';\nexport { Request } from '../request.decorator';\nexport { Listen } from '../listen.decorator';\n"]}

package/broadcast/message-client.cjs

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BroadcastMessageClient = void 0;
+const rxjs_1 = require("rxjs");
+const message_client_1 = require("../message-client");
+const selectors_1 = require("../selectors");
+const default_channel_name_1 = require("./default-channel-name");
+class BroadcastMessageClient extends message_client_1.MessageClient {
+    [selectors_1.RESPONSES$] = new rxjs_1.Subject();
+    #channel;
+    constructor(channelName = default_channel_name_1.DEFAULT_CHANNEL_NAME) {
+        super();
+        this.#channel = new BroadcastChannel(channelName);
+        this.#channel.addEventListener('message', this.#handler);
+    }
+    [selectors_1.SEND](message) {
+        this.#channel.postMessage(message);
+    }
+    #handler = (event) => {
+        this[selectors_1.RESPONSES$].next(event.data);
+    };
+    [selectors_1.GET_NEW_ID]() {
+        return crypto.randomUUID();
+    }
+}
+exports.BroadcastMessageClient = BroadcastMessageClient;