Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/knowledgecode/messenger

Type-safe Request/Reply and Pub/Sub messaging library for browser applications
https://github.com/knowledgecode/messenger

browser communication components iframe message-channel messaging pub-sub pubsub request-reply type-safe typescript worker

Last synced: about 1 month ago
JSON representation

Type-safe Request/Reply and Pub/Sub messaging library for browser applications

Awesome Lists containing this project

README 

          
# Messenger



A type-safe Request/Reply and Pub/Sub messaging library for cross-context communication in browsers, enabling seamless message exchange between the main window, iframes, and web workers.



## Features



- **Request/Reply Pattern**: Send requests and receive responses asynchronously

- **Pub/Sub Pattern**: Publish messages to multiple subscribers

- **Cross-Context Communication**: Works seamlessly between:

  - Main window ↔ iframes

  - Main window ↔ web workers

  - iframe ↔ iframe

  - Components within the same context

- **Type-Safe**: Built with TypeScript for excellent type inference

- **Promise-Based**: Modern async/await API

- **Secure**: Uses MessageChannel API for isolated communication



## Installation



```shell

npm i @knowledgecode/messenger

```



## Usage



### Node.js / Bundlers (Recommended)



```typescript

import { MessengerClient, MessengerServer } from '@knowledgecode/messenger';

```



### Browser (UMD - Legacy)



For legacy environments without ES module support:



```html



  const { MessengerClient, MessengerServer } = self.messenger;



```



For workers in legacy environments:



```typescript

// worker.ts (legacy)

importScripts('./node_modules/@knowledgecode/messenger/dist/messenger.js');

const { MessengerServer } = self.messenger;

```



## Quick Start



> **Note**: The examples below are written in TypeScript. Build them to JavaScript files using TypeScript compiler or a bundler before running in the browser.



### Example: Main Window ↔ Worker



#### main.ts (build to main.js)



```typescript

import { MessengerClient } from '@knowledgecode/messenger';



const messenger = new MessengerClient();

const worker = new Worker('./worker.js', { type: 'module' });



(async () => {

  // Connect to the worker's server named 'calculator'

  await messenger.connect('calculator', worker);



  // Request/Reply: Send a request and wait for response

  const result = await messenger.req('add', { x: 2, y: 3 });

  console.log(result); // => 5



  // Send: Fire and forget

  messenger.send('close');

  messenger.disconnect();

})();

```



#### worker.ts (build to worker.js)



```typescript

import { MessengerServer } from '@knowledgecode/messenger';



interface AddRequest {

  x: number;

  y: number;

}



const messenger = new MessengerServer('calculator', self);



// Bind handler for 'add' topic

messenger.bind('add', (data) => {

  if (!data) {

    return 0;

  }

  return data.x + data.y;

});



// Bind handler for 'close' topic

messenger.bind('close', () => {

  messenger.close();

  self.close();

});

```



### Example: Main Window ↔ iframe



#### main.ts (build to main.js)



```typescript

import { MessengerClient } from '@knowledgecode/messenger';



interface StatusUpdate {

  status: string;

  timestamp: number;

}



interface User {

  id: number;

  name: string;

  email: string;

}



const messenger = new MessengerClient();

const iframe = document.querySelector('iframe');



(async () => {

  // Connect to iframe's server with targetOrigin for security

  await messenger.connect('iframe-app', iframe!.contentWindow!, {

    targetOrigin: 'https://example.com', // Use '*' only for development

    timeout: 5000

  });



  // Subscribe to messages published from the iframe

  messenger.subscribe('status-update', (data) => {

    if (data) {

      console.log('Status:', data.status);

    }

  });



  // Send request to iframe

  const userData = await messenger.req('get-user', { id: 123 });

  console.log(userData);

})();

```



#### iframe.ts (build to iframe.js)



```typescript

import { MessengerServer } from '@knowledgecode/messenger';



interface GetUserRequest {

  id: number;

}



interface User {

  id: number;

  name: string;

  email: string;

}



const messenger = new MessengerServer('iframe-app', self);



messenger.bind('get-user', async (data) => {

  if (!data) {

    throw new Error('User ID is required');

  }

  const response = await fetch(`/api/users/${data.id}`);

  return await response.json() as User;

});



// Publish status updates to subscribers

setInterval(() => {

  messenger.publish('status-update', { status: 'running', timestamp: Date.now() });

}, 1000);

```



### Example: Same-Context Communication (Component to Component)



You can use Messenger for communication between components within the same window or worker context.



#### data-service.ts (build to data-service.js)



```typescript

import { MessengerServer } from '@knowledgecode/messenger';



interface DataItem {

  id: number;

  value: string;

}



const messenger = new MessengerServer('data-service', self);



messenger.bind('get-data', (): DataItem[] => {

  return [

    { id: 1, value: 'Item 1' },

    { id: 2, value: 'Item 2' },

    { id: 3, value: 'Item 3' }

  ];

});

```



#### app.ts (build to app.js)



```typescript

import { MessengerClient } from '@knowledgecode/messenger';



interface DataItem {

  id: number;

  value: string;

}



const messenger = new MessengerClient();



(async () => {

  // Connect to the data service in the same context

  await messenger.connect('data-service', self);



  // Request data from the service

  const items = await messenger.req('get-data');

  console.log('Received items:', items);



  messenger.disconnect();

})();

```



## API Reference



### MessengerClient



Client for connecting to a MessengerServer and sending messages.



#### `constructor()`



Creates a new MessengerClient instance.



```typescript

const messenger = new MessengerClient();

```



#### `connect(name, endpoint, options)`



Establishes a connection to a MessengerServer.



**Parameters:**



- `name` (**string**): Unique name of the MessengerServer to connect to

- `endpoint` (**Window | Worker**, optional): Target context that has `postMessage()` method. Defaults to `self`

- `options` (**object**, optional): Connection options

  - `targetOrigin` (**string**, optional): Target origin for security (iframe only). Defaults to `'*'`. For production, always specify the exact origin

  - `timeout` (**number**, optional): Connection timeout in milliseconds. If omitted, waits indefinitely



**Returns:** `Promise` - Resolves when connection is established



**Throws:**



- `Error` if endpoint doesn't have `postMessage()` method

- `Error` if connection times out



**Examples:**



```typescript

// Connect to iframe with security and timeout

const iframe = document.querySelector('iframe');

await messenger.connect('my-iframe', iframe!.contentWindow!, {

  targetOrigin: 'https://trusted-domain.com',

  timeout: 5000

});

```



```typescript

// Connect to worker

const worker = new Worker('./worker.js', { type: 'module' });

await messenger.connect('my-worker', worker, { timeout: 3000 });

```



```typescript

// Connect from within a worker to parent

await messenger.connect('main', self);

```



#### `disconnect()`



Disconnects from the server, clears all subscriptions, and cleans up resources.



```typescript

messenger.disconnect();

```



#### `send(topic, data)`



Sends a one-way message to a topic. Does not wait for a response.



**Parameters:**



- `topic` (**string**): Topic name

- `data` (**unknown**): Data to send



**Throws:** `Error` if not connected



```typescript

messenger.send('log', { level: 'info', message: 'Task completed' });

```



#### `req(topic, data, timeout)`



Sends a request to a topic and waits for a response.



**Type Parameters:**



- `T` (optional): The expected response type. Defaults to `unknown`



**Parameters:**



- `topic` (**string**): Topic name

- `data` (**unknown**, optional): Data to send

- `timeout` (**number**, optional): Request timeout in milliseconds. If omitted, waits indefinitely



**Returns:** `Promise` - Resolves with the response data of type `T`



**Throws:**



- `Error` if not connected

- `Error` if request times out

- `Error` if the topic is not bound on the server



**Examples:**



```typescript

// Simple request with type inference

const result = await messenger.req('calculate', { operation: 'add', values: [1, 2, 3] });

```



```typescript

// Request with timeout and type safety

interface DataResponse {

  id: number;

  value: string;

}



try {

  const data = await messenger.req('fetch-data', { id: 123 }, 5000);

  console.log(data.value); // TypeScript knows about the 'value' property

} catch (error) {

  console.error('Request failed:', (error as Error).message);

}

```



#### `subscribe(topic, listener)`



Subscribes to messages published on a topic.



**Type Parameters:**



- `T` (optional): The expected message data type. Defaults to `unknown`



**Parameters:**



- `topic` (**string**): Topic name

- `listener` (**function**): Callback function invoked when messages are published

  - Signature: `(data?: T) => void`



**Throws:** `Error` if not connected



```typescript

interface Notification {

  title: string;

  message: string;

  timestamp: number;

}



messenger.subscribe('notifications', (data) => {

  if (data) {

    console.log('Notification received:', data.title);

  }

});

```



#### `unsubscribe(topic, listener)`



Unsubscribes from a topic.



**Parameters:**



- `topic` (**string**, optional): Topic name. If omitted, clears all subscriptions

- `listener` (**function**, optional): Specific listener to remove. If omitted, removes all listeners for the topic



```typescript

// Remove specific listener

interface UpdateData {

  version: string;

}



const listener = (data?: UpdateData) => {

  if (data) {

    console.log(data.version);

  }

};

messenger.subscribe('updates', listener);

messenger.unsubscribe('updates', listener);



// Remove all listeners for a topic

messenger.unsubscribe('updates');



// Remove all subscriptions

messenger.unsubscribe();

```



---



### MessengerServer



Server for accepting client connections and handling messages.



#### `constructor(name, endpoint)`



Creates a new MessengerServer instance.



**Parameters:**



- `name` (**string**): Unique name for this server. Clients use this name to connect

- `endpoint` (**Window | Worker**, optional): Context to listen on. Defaults to `self`



```typescript

// In a worker

const messenger = new MessengerServer('my-worker', self);



// In an iframe

const messenger = new MessengerServer('my-iframe', self);



// In main window (listening for messages from a specific worker)

const worker = new Worker('./worker.js', { type: 'module' });

const messenger = new MessengerServer('worker-listener', worker);

```



#### `bind(topic, listener)`



Binds a handler to a topic for receiving messages.



**Type Parameters:**



- `T` (optional): The expected message data type. Defaults to `unknown`



**Parameters:**



- `topic` (**string**): Topic name (must be unique per server)

- `listener` (**function**): Handler function

  - Signature: `(data?: T) => unknown`

  - For `send()` messages: return value is ignored

  - For `req()` messages: return value (or resolved Promise value) is sent back to client



**Returns:** `boolean` - `true` if bound successfully, `false` if topic already bound



**Examples:**



```typescript

// Handle one-way messages

interface LogMessage {

  level: string;

  message: string;

}



messenger.bind('log', (data) => {

  if (data) {

    console.log(`[${data.level}] ${data.message}`);

  }

});



// Handle requests (synchronous)

interface AddRequest {

  x: number;

  y: number;

}



messenger.bind('add', (data) => {

  if (!data) {

    return 0;

  }

  return data.x + data.y;

});



// Handle requests (asynchronous)

interface FetchUserRequest {

  id: number;

}



interface User {

  id: number;

  name: string;

}



messenger.bind('fetch-user', async (data) => {

  if (!data) {

    throw new Error('User ID is required');

  }

  const response = await fetch(`/api/users/${data.id}`);

  return await response.json() as User;

});



// Check binding result

if (!messenger.bind('duplicate-topic', () => {})) {

  console.error('Topic already bound');

}

```



#### `unbind(topic)`



Removes the handler for a topic.



**Parameters:**



- `topic` (**string**): Topic name



```typescript

messenger.unbind('old-topic');

```



#### `publish(topic, data)`



Publishes a message to all subscribed clients on a topic.



**Parameters:**



- `topic` (**string**): Topic name

- `data` (**unknown**, optional): Data to publish



This method does not wait for responses and succeeds even if there are no subscribers.



```typescript

// Notify all subscribers

messenger.publish('status-change', { status: 'ready', timestamp: Date.now() });



// Broadcast to all clients

setInterval(() => {

  messenger.publish('heartbeat', { timestamp: Date.now() });

}, 1000);

```



#### `close()`



Closes all client connections, removes all handlers and subscriptions, and shuts down the server.



```typescript

messenger.close();

```



## Security Considerations



When connecting to iframes from different origins, always specify the exact `targetOrigin` instead of using `'*'`:



```typescript

// ❌ Insecure - allows any origin

await messenger.connect('iframe', iframe!.contentWindow!, { targetOrigin: '*' });



// ✅ Secure - restricts to specific origin

await messenger.connect('iframe', iframe!.contentWindow!, {

  targetOrigin: 'https://trusted-domain.com'

});

```



## TypeScript



This library is written in TypeScript and provides full type safety with generic support.



### Type-safe Requests



```typescript

import { MessengerClient } from '@knowledgecode/messenger';



interface User {

  id: number;

  name: string;

}



const messenger = new MessengerClient();



// Type-safe request - result is typed as User

const user = await messenger.req('get-user', { id: 123 });

console.log(user.name); // TypeScript knows user has a name property

```



### Type-safe Subscriptions



The listener receives `data` as `T | undefined` because messages may be published without data.



```typescript

interface StatusUpdate {

  status: 'online' | 'offline';

  timestamp: number;

}



// Type-safe subscribe - data parameter is StatusUpdate | undefined

messenger.subscribe('status-change', (data) => {

  if (data) {

    console.log(`Status: ${data.status} at ${data.timestamp}`);

  }

});

```



### Type-safe Handlers



Handlers receive `data` as `T | undefined` because clients may send requests or messages without data.



```typescript

interface CalculateRequest {

  operation: 'add' | 'subtract' | 'multiply' | 'divide';

  a: number;

  b: number;

}



interface CalculateResponse {

  result: number;

}



const messenger = new MessengerServer('calculator', self);



// Type-safe handler - data parameter is CalculateRequest | undefined

messenger.bind('calculate', (data) => {

  if (!data) {

    return { result: 0 };

  }



  switch (data.operation) {

    case 'add':

      return { result: data.a + data.b };

    case 'subtract':

      return { result: data.a - data.b };

    case 'multiply':

      return { result: data.a * data.b };

    case 'divide':

      return { result: data.a / data.b };

  }

});



// Client side - response is typed as CalculateResponse

const client = new MessengerClient();

await client.connect('calculator', self);



const response = await client.req('calculate', {

  operation: 'add',

  a: 5,

  b: 3

});



console.log(response.result); // TypeScript knows about result property

```



## License



MIT