iframe.io 1.0.4 → 1.0.6

package/README.md

@@ -1,2 +1,459 @@
 # iframe.io
-Easy and friendly API to connect and interact between content window and its containing iframe
+
+Easy and friendly API to connect and interact between content window and its containing iframe with enhanced features like heartbeat monitoring, automatic reconnection, message queuing, and rate limiting.
+
+## Features
+
+- 🔄 **Bi-directional Communication** - Seamless messaging between parent window and iframe
+- 💓 **Heartbeat Monitoring** - Automatic connection health checking
+- 🔌 **Auto Reconnection** - Automatic reconnection with exponential backoff
+- 📦 **Message Queuing** - Queue messages when connection is lost
+- 🛡️ **Security** - Origin validation and message sanitization
+- ⚡ **Rate Limiting** - Prevent message flooding
+- 🎯 **Event System** - Robust event-driven architecture
+- ✨ **Promise Support** - Async/await compatible methods
+- 📊 **Connection Stats** - Real-time connection statistics
+
+## Installation
+
+```bash
+npm install iframe.io
+```
+
+## Quick Start
+
+### Parent Window (WINDOW type)
+
+```javascript
+import IOF from 'iframe.io'
+
+// Create iframe and get reference
+const iframe = document.createElement('iframe')
+iframe.src = 'https://example.com/iframe-content'
+document.body.appendChild(iframe)
+
+// Initialize connection
+const iof = new IOF({ type: 'WINDOW', debug: true })
+
+iframe.onload = () => {
+  // Initiate connection with iframe
+  iof.initiate(iframe.contentWindow, 'https://example.com')
+  
+  // Listen for connection
+  iof.on('connect', () => {
+    console.log('Connected to iframe!')
+    
+    // Send message
+    iof.emit('hello', { message: 'Hello from parent!' })
+  })
+  
+  // Listen for messages
+  iof.on('response', (data) => {
+    console.log('Received:', data)
+  })
+}
+```
+
+### Iframe Content (IFRAME type)
+
+```javascript
+import IOF from 'iframe.io'
+
+// Create connection listener
+const iof = new IOF({ type: 'IFRAME', debug: true })
+
+// Listen for parent connection
+iof.listen('https://parent-domain.com')
+
+// Handle connection
+iof.on('connect', () => {
+  console.log('Connected to parent!')
+})
+
+// Listen for messages
+iof.on('hello', (data, ack) => {
+  console.log('Received from parent:', data)
+  
+  // Send response
+  iof.emit('response', { message: 'Hello from iframe!' })
+  
+  // Acknowledge receipt (optional)
+  if (ack) ack(false, 'Message received')
+})
+```
+
+## API Reference
+
+### Constructor
+
+```javascript
+new IOF(options?)
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `type` | `'WINDOW' \| 'IFRAME'` | `'IFRAME'` | Connection type |
+| `debug` | `boolean` | `false` | Enable debug logging |
+| `heartbeatInterval` | `number` | `30000` | Heartbeat interval in ms |
+| `connectionTimeout` | `number` | `10000` | Connection timeout in ms |
+| `maxMessageSize` | `number` | `1048576` | Max message size (1MB) |
+| `maxMessagesPerSecond` | `number` | `100` | Rate limit for messages |
+| `autoReconnect` | `boolean` | `true` | Enable auto reconnection |
+| `messageQueueSize` | `number` | `50` | Max queued messages |
+
+### Connection Methods
+
+#### `initiate(contentWindow, iframeOrigin)`
+
+Establish connection with an iframe (WINDOW type only).
+
+```javascript
+iof.initiate(iframe.contentWindow, 'https://iframe-origin.com')
+```
+
+**Parameters:**
+- `contentWindow` - The iframe's contentWindow
+- `iframeOrigin` - The iframe's origin URL
+
+#### `listen(hostOrigin?)`
+
+Listen for connection from parent window (IFRAME type).
+
+```javascript
+iof.listen('https://parent-origin.com') // Optional origin restriction
+```
+
+**Parameters:**
+- `hostOrigin` (optional) - Restrict connections to specific origin
+
+#### `disconnect(callback?)`
+
+Disconnect and clean up all resources.
+
+```javascript
+iof.disconnect(() => {
+  console.log('Disconnected!')
+})
+```
+
+### Messaging Methods
+
+#### `emit(event, payload?, callback?)`
+
+Send a message to the peer.
+
+```javascript
+// Simple message
+iof.emit('myEvent', { data: 'hello' })
+
+// With acknowledgment
+iof.emit('myEvent', { data: 'hello' }, (error, response) => {
+  if (error) {
+    console.error('Error:', error)
+  } else {
+    console.log('Response:', response)
+  }
+})
+
+// Callback as second parameter
+iof.emit('myEvent', (error, response) => {
+  console.log('Response:', response)
+})
+```
+
+#### `on(event, listener)`
+
+Add event listener.
+
+```javascript
+iof.on('myEvent', (data, ack) => {
+  console.log('Received:', data)
+  
+  // Send acknowledgment (optional)
+  if (ack) ack(false, 'Success response')
+})
+```
+
+#### `once(event, listener)`
+
+Add one-time event listener.
+
+```javascript
+iof.once('myEvent', (data) => {
+  console.log('This will only fire once:', data)
+})
+```
+
+#### `off(event, listener?)`
+
+Remove event listener(s).
+
+```javascript
+// Remove specific listener
+iof.off('myEvent', myListener)
+
+// Remove all listeners for event
+iof.off('myEvent')
+```
+
+#### `removeListeners(callback?)`
+
+Remove all event listeners.
+
+```javascript
+iof.removeListeners(() => {
+  console.log('All listeners removed')
+})
+```
+
+### Async Methods
+
+#### `emitAsync(event, payload?)`
+
+Send message and return Promise.
+
+```javascript
+try {
+  const response = await iof.emitAsync('getData', { id: 123 })
+  console.log('Response:', response)
+} catch (error) {
+  console.error('Error:', error)
+}
+```
+
+#### `onceAsync(event)`
+
+Wait for single event occurrence.
+
+```javascript
+const data = await iof.onceAsync('dataReady')
+console.log('Data received:', data)
+```
+
+#### `connectAsync(timeout?)`
+
+Wait for connection to be established.
+
+```javascript
+try {
+  await iof.connectAsync(5000) // 5 second timeout
+  console.log('Connected!')
+} catch (error) {
+  console.error('Connection timeout')
+}
+```
+
+### Utility Methods
+
+#### `isConnected()`
+
+Check if connection is active.
+
+```javascript
+if (iof.isConnected()) {
+  console.log('Connection is active')
+}
+```
+
+#### `getStats()`
+
+Get connection statistics.
+
+```javascript
+const stats = iof.getStats()
+console.log('Stats:', stats)
+/*
+{
+  connected: true,
+  peerType: 'WINDOW',
+  origin: 'https://example.com',
+  lastHeartbeat: 1640995200000,
+  queuedMessages: 0,
+  reconnectAttempts: 0,
+  activeListeners: 5,
+  messageRate: 10
+}
+*/
+```
+
+#### `clearQueue()`
+
+Clear queued messages.
+
+```javascript
+iof.clearQueue()
+```
+
+## Events
+
+### Built-in Events
+
+| Event | Description | Data |
+|-------|-------------|------|
+| `connect` | Connection established | - |
+| `disconnect` | Connection lost | `{ reason: string }` |
+| `reconnecting` | Reconnection attempt | `{ attempt: number, delay: number }` |
+| `reconnection_failed` | All reconnection attempts failed | `{ attempts: number }` |
+| `error` | Error occurred | `{ type: string, ...details }` |
+
+### Error Types
+
+- `RATE_LIMIT_EXCEEDED` - Message rate limit exceeded
+- `MESSAGE_HANDLING_ERROR` - Error processing received message
+- `EMIT_ERROR` - Error sending message
+- `LISTENER_ERROR` - Error in event listener
+- `INVALID_ORIGIN` - Message from unauthorized origin
+- `ORIGIN_MISMATCH` - Origin doesn't match established connection
+- `NO_CONNECTION` - Attempted to send without connection
+
+## Advanced Usage
+
+### Message Acknowledgments
+
+```javascript
+// Sender
+iof.emit('processData', { data: [...] }, (error, result) => {
+  if (error) {
+    console.error('Processing failed:', error)
+  } else {
+    console.log('Processing result:', result)
+  }
+})
+
+// Receiver
+iof.on('processData', async (data, ack) => {
+  try {
+    const result = await processData(data.data)
+    ack(false, result) // Success: ack(error, ...args)
+  } catch (error) {
+    ack(error.message) // Error: ack(errorMessage)
+  }
+})
+```
+
+### Connection Monitoring
+
+```javascript
+const iof = new IOF({
+  heartbeatInterval: 10000, // 10 seconds
+  connectionTimeout: 5000,  // 5 seconds
+  autoReconnect: true
+})
+
+iof.on('disconnect', ({ reason }) => {
+  console.log('Connection lost:', reason)
+})
+
+iof.on('reconnecting', ({ attempt, delay }) => {
+  console.log(`Reconnecting (${attempt}/5) in ${delay}ms`)
+})
+
+iof.on('reconnection_failed', ({ attempts }) => {
+  console.log(`Failed to reconnect after ${attempts} attempts`)
+})
+```
+
+### Message Queuing
+
+```javascript
+const iof = new IOF({
+  messageQueueSize: 100,
+  autoReconnect: true
+})
+
+// Messages sent while disconnected are automatically queued
+iof.emit('queuedMessage', { data: 'This will be queued if disconnected' })
+
+// Check queue status
+const stats = iof.getStats()
+console.log(`Queued messages: ${stats.queuedMessages}`)
+```
+
+### Rate Limiting
+
+```javascript
+const iof = new IOF({
+  maxMessagesPerSecond: 50,
+  maxMessageSize: 512 * 1024 // 512KB
+})
+
+iof.on('error', ({ type, limit, current }) => {
+  if (type === 'RATE_LIMIT_EXCEEDED') {
+    console.log(`Rate limit exceeded: ${current}/${limit} messages per second`)
+  }
+})
+```
+
+### Security Best Practices
+
+```javascript
+// Always specify allowed origins
+iof.listen('https://trusted-parent.com')
+
+// Handle security errors
+iof.on('error', ({ type, expected, received }) => {
+  if (type === 'INVALID_ORIGIN') {
+    console.warn(`Rejected message from ${received}, expected ${expected}`)
+  }
+})
+
+// Validate message content
+iof.on('userData', (data, ack) => {
+  if (!isValidUserData(data)) {
+    return ack('Invalid data format')
+  }
+  // Process valid data...
+})
+```
+
+## Browser Support
+
+- Modern browsers with postMessage API support
+- Chrome 2+
+- Firefox 3+
+- Safari 4+
+- IE 8+
+- Edge (all versions)
+
+## TypeScript Support
+
+The library is written in TypeScript and includes full type definitions:
+
+```typescript
+import IOF, { Options, PeerType, AckFunction, Listener } from 'iframe.io'
+
+const options: Options = {
+  type: 'WINDOW',
+  debug: true,
+  heartbeatInterval: 15000
+}
+
+const iof = new IOF(options)
+
+// Type-safe event handling
+iof.on('myEvent', (data: { message: string }, ack?: AckFunction) => {
+  console.log(data.message)
+  ack?.(false, 'success')
+})
+
+// Type-safe async emissions
+const response = await iof.emitAsync<{ query: string }, { result: any }>('search', { 
+  query: 'typescript' 
+})
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.
+
+## Support
+
+- Create an issue on GitHub for bug reports
+- Check existing issues for common problems
+- Review the documentation for usage examples

package/dist/index.d.ts

@@ -75,7 +75,7 @@ export default class IOF {
     once(_event: string, fn: Listener): this;
     off(_event: string, fn?: Listener): this;
     removeListeners(fn?: Listener): this;
-    emitAsync<T = any, R = any>(_event: string, payload?: T): Promise<R>;
+    emitAsync<T = any, R = any>(_event: string, payload?: T, timeout?: number): Promise<R>;
     onceAsync<T = any>(_event: string): Promise<T>;
     connectAsync(timeout?: number): Promise<void>;
     private cleanup;

package/dist/index.js

@@ -35,18 +35,21 @@ function sanitizePayload(payload, maxSize) {
     if (!payload)
         return payload;
     var size = getMessageSize(payload);
-    if (size > maxSize) {
+    if (size > maxSize)
         throw new Error("Message size ".concat(size, " exceeds limit ").concat(maxSize));
-    }
     // Basic sanitization - remove functions and undefined values
     return JSON.parse(JSON.stringify(payload));
 }
 var ackId = function () {
-    var rmin = 100000, rmax = 999999;
-    var timestamp = Date.now();
-    var random = Math.floor(Math.random() * (rmax - rmin + 1) + rmin);
+    var rmin = 100000, rmax = 999999, timestamp = Date.now(), random = Math.floor(Math.random() * (rmax - rmin + 1) + rmin);
     return "".concat(timestamp, "_").concat(random);
 };
+var RESERVED_EVENTS = [
+    'ping',
+    'pong',
+    '__heartbeat',
+    '__heartbeat_response'
+];
 var IOF = /** @class */ (function () {
     function IOF(options) {
         if (options === void 0) { options = {}; }
@@ -81,7 +84,8 @@ var IOF = /** @class */ (function () {
             if (_this.isConnected()) {
                 var now = Date.now();
                 // Check if peer is still responsive
-                if (_this.peer.lastHeartbeat && (now - _this.peer.lastHeartbeat) > (_this.options.heartbeatInterval * 2)) {
+                if (_this.peer.lastHeartbeat
+                    && (now - _this.peer.lastHeartbeat) > (_this.options.heartbeatInterval * 2)) {
                     _this.debug("[".concat(_this.peer.type, "] Heartbeat timeout detected"));
                     _this.handleConnectionLoss();
                     return;
@@ -132,11 +136,11 @@ var IOF = /** @class */ (function () {
             // For IFRAME type, just wait for incoming connection
             // Set timeout for this reconnection attempt
             setTimeout(function () {
-                if (!_this.peer.connected) {
-                    _this.reconnectAttempts < _this.maxReconnectAttempts
-                        ? _this.attemptReconnection()
-                        : _this.fire('reconnection_failed', { attempts: _this.reconnectAttempts });
-                }
+                if (_this.peer.connected)
+                    return;
+                _this.reconnectAttempts < _this.maxReconnectAttempts
+                    ? _this.attemptReconnection()
+                    : _this.fire('reconnection_failed', { attempts: _this.reconnectAttempts });
             }, _this.options.connectionTimeout);
         }, delay);
     };
@@ -273,7 +277,11 @@ var IOF = /** @class */ (function () {
             try {
                 // Enhanced security: check host origin where event must only come from
                 if (hostOrigin && hostOrigin !== origin) {
-                    _this.fire('error', { type: 'INVALID_ORIGIN', expected: hostOrigin, received: origin });
+                    _this.fire('error', {
+                        type: 'INVALID_ORIGIN',
+                        expected: hostOrigin,
+                        received: origin
+                    });
                     return;
                 }
                 // Enhanced security: check valid message structure
@@ -288,7 +296,11 @@ var IOF = /** @class */ (function () {
                 }
                 // Origin different from handshaked source origin
                 else if (origin !== _this.peer.origin) {
-                    _this.fire('error', { type: 'ORIGIN_MISMATCH', expected: _this.peer.origin, received: origin });
+                    _this.fire('error', {
+                        type: 'ORIGIN_MISMATCH',
+                        expected: _this.peer.origin,
+                        received: origin
+                    });
                     return;
                 }
                 var _event = data._event, payload = data.payload, cid = data.cid, timestamp = data.timestamp;
@@ -334,8 +346,7 @@ var IOF = /** @class */ (function () {
     IOF.prototype.fire = function (_event, payload, cid) {
         var _this = this;
         // Volatile event - check if any listeners exist
-        if (!this.Events[_event]
-            && !this.Events[_event + '--@once'])
+        if (!this.Events[_event] && !this.Events[_event + '--@once'])
             return this.debug("[".concat(this.peer.type, "] No <").concat(_event, "> listener defined"));
         var ackFn = cid
             ? function (error) {
@@ -376,8 +387,11 @@ var IOF = /** @class */ (function () {
         // Check rate limiting
         if (!this.checkRateLimit())
             return this;
-        // Queue message if not connected (except for connection-related events)
-        if (!this.isConnected() && !['ping', 'pong', '__heartbeat', '__heartbeat_response'].includes(_event)) {
+        /**
+         * Queue message if not connected: Except for
+         * connection-related events
+         */
+        if (!this.isConnected() && !RESERVED_EVENTS.includes(_event)) {
             this.queueMessage(_event, payload, fn);
             return this;
         }
@@ -391,7 +405,9 @@ var IOF = /** @class */ (function () {
         }
         try {
             // Enhanced security: sanitize and validate payload
-            var sanitizedPayload = payload ? sanitizePayload(payload, this.options.maxMessageSize) : payload;
+            var sanitizedPayload = payload
+                ? sanitizePayload(payload, this.options.maxMessageSize)
+                : payload;
             // Acknowledge event listener
             var cid = void 0;
             if (typeof fn === 'function') {
@@ -419,9 +435,8 @@ var IOF = /** @class */ (function () {
                 error: error instanceof Error ? error.message : String(error)
             });
             // Call acknowledgment with error if provided
-            if (typeof fn === 'function') {
-                fn(error instanceof Error ? error.message : String(error));
-            }
+            typeof fn === 'function'
+                && fn(error instanceof Error ? error.message : String(error));
         }
         return this;
     };
@@ -468,21 +483,27 @@ var IOF = /** @class */ (function () {
         this.debug("[".concat(this.peer.type, "] All listeners removed"));
         return this;
     };
-    IOF.prototype.emitAsync = function (_event, payload) {
+    IOF.prototype.emitAsync = function (_event, payload, timeout) {
         var _this = this;
+        if (timeout === void 0) { timeout = 5000; }
         return new Promise(function (resolve, reject) {
+            var timeoutId = setTimeout(function () {
+                reject(new Error("Event '".concat(_event, "' acknowledgment timeout after ").concat(timeout, "ms")));
+            }, timeout);
             try {
                 _this.emit(_event, payload, function (error) {
                     var args = [];
                     for (var _i = 1; _i < arguments.length; _i++) {
                         args[_i - 1] = arguments[_i];
                     }
+                    clearTimeout(timeoutId);
                     error
                         ? reject(new Error(typeof error === 'string' ? error : 'Ack error'))
                         : resolve(args.length === 0 ? undefined : args.length === 1 ? args[0] : args);
                 });
             }
             catch (error) {
+                clearTimeout(timeoutId);
                 reject(error);
             }
         });
@@ -493,14 +514,13 @@ var IOF = /** @class */ (function () {
     };
     IOF.prototype.connectAsync = function (timeout) {
         var _this = this;
-        if (timeout === void 0) { timeout = 5000; }
         return new Promise(function (resolve, reject) {
             if (_this.isConnected())
                 return resolve();
             var timeoutId = setTimeout(function () {
                 _this.off('connect', connectHandler);
                 reject(new Error('Connection timeout'));
-            }, timeout);
+            }, timeout || _this.options.connectionTimeout);
             var connectHandler = function () {
                 clearTimeout(timeoutId);
                 resolve();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iframe.io",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Easy and friendly API to connect and interact between content window and its containing iframe",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -34,6 +34,12 @@
   },
   "keywords": [
     "realtime",
+    "embeddable",
+    "widget",
+    "components",
+    "micro-frontend",
+    "Secure",
+    "cross-origin",
     "iframe",
     "browser",
     "events",

package/src/index.ts

@@ -36,7 +36,7 @@ export type MessageData = {
 
 export type Message = {
   origin: string
-  data: MessageData,
+  data: MessageData
   source: Window
 }
 
@@ -52,37 +52,43 @@ function newObject( data: object ){
 }
 
 function getMessageSize( data: any ): number {
-  try {
-    return JSON.stringify( data ).length
-  } catch {
-    return 0
-  }
+  try { return JSON.stringify( data ).length }
+  catch { return 0 }
 }
 
 function sanitizePayload( payload: any, maxSize: number ): any {
   if( !payload ) return payload
-  
+
   const size = getMessageSize( payload )
-  if( size > maxSize ) {
+  if( size > maxSize )
     throw new Error(`Message size ${size} exceeds limit ${maxSize}`)
-  }
-  
+
   // Basic sanitization - remove functions and undefined values
   return JSON.parse( JSON.stringify( payload ) )
 }
 
 const ackId = () => {
-  const rmin = 100000, rmax = 999999
-  const timestamp = Date.now()
-  const random = Math.floor( Math.random() * ( rmax - rmin + 1 ) + rmin )
+  const
+  rmin = 100000,
+  rmax = 999999,
+  timestamp = Date.now(),
+  random = Math.floor( Math.random() * ( rmax - rmin + 1 ) + rmin )
+
   return `${timestamp}_${random}`
 }
 
+const RESERVED_EVENTS = [
+  'ping',
+  'pong',
+  '__heartbeat',
+  '__heartbeat_response'
+]
+
 export default class IOF {
   Events: RegisteredEvents
   peer: Peer
   options: Options
-  private messageListener?: (event: MessageEvent) => void
+  private messageListener?: ( event: MessageEvent ) => void
   private heartbeatTimer?: NodeJS.Timeout
   private reconnectTimer?: NodeJS.Timeout
   private messageQueue: QueuedMessage[] = []
@@ -93,21 +99,21 @@ export default class IOF {
   constructor( options: Options = {} ){
     if( options && typeof options !== 'object' )
       throw new Error('Invalid Options')
-    
-    this.options = { 
-      debug: false, 
+
+    this.options = {
+      debug: false,
       heartbeatInterval: 30000, // 30 seconds
       connectionTimeout: 10000, // 10 seconds
       maxMessageSize: 1024 * 1024, // 1MB
       maxMessagesPerSecond: 100,
       autoReconnect: true,
       messageQueueSize: 50,
-      ...options 
+      ...options
     }
-	  this.Events = {}
+    this.Events = {}
     this.peer = { type: 'IFRAME', connected: false }
 
-    if( options.type ) 
+    if( options.type )
       this.peer.type = options.type.toUpperCase() as PeerType
   }
 
@@ -122,30 +128,33 @@ export default class IOF {
   // Enhanced connection health monitoring
   private startHeartbeat(){
     if( !this.options.heartbeatInterval ) return
-    
+
     this.heartbeatTimer = setInterval(() => {
       if( this.isConnected() ){
         const now = Date.now()
-        
+
         // Check if peer is still responsive
-        if( this.peer.lastHeartbeat && ( now - this.peer.lastHeartbeat ) > ( this.options.heartbeatInterval! * 2 ) ){
+        if( this.peer.lastHeartbeat
+            && ( now - this.peer.lastHeartbeat ) > ( this.options.heartbeatInterval! * 2 ) ){
           this.debug(`[${this.peer.type}] Heartbeat timeout detected`)
           this.handleConnectionLoss()
+
           return
         }
-        
+
         // Send heartbeat
         try { this.emit('__heartbeat', { timestamp: now }) }
         catch( error ){
-          this.debug(`[${this.peer.type}] Heartbeat send failed:`, error )
+          this.debug(`[${this.peer.type}] Heartbeat send failed:`, error)
           this.handleConnectionLoss()
         }
       }
     }, this.options.heartbeatInterval )
   }
+
   private stopHeartbeat(){
     if( !this.heartbeatTimer ) return
-    
+
     clearInterval( this.heartbeatTimer )
     this.heartbeatTimer = undefined
   }
@@ -153,112 +162,114 @@ export default class IOF {
   // Handle connection loss and potential reconnection
   private handleConnectionLoss(){
     if( !this.peer.connected ) return
-    
+
     this.peer.connected = false
     this.stopHeartbeat()
     this.fire('disconnect', { reason: 'CONNECTION_LOST' })
-    
+
     this.options.autoReconnect
     && this.reconnectAttempts < this.maxReconnectAttempts
     && this.attemptReconnection()
   }
+
   private attemptReconnection(){
     if( this.reconnectTimer ) return
-    
+
     this.reconnectAttempts++
     const delay = Math.min( 1000 * Math.pow( 2, this.reconnectAttempts - 1 ), 30000 ) // Exponential backoff, max 30s
-    
+
     this.debug(`[${this.peer.type}] Attempting reconnection ${this.reconnectAttempts}/${this.maxReconnectAttempts} in ${delay}ms`)
     this.fire('reconnecting', { attempt: this.reconnectAttempts, delay })
-    
+
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = undefined
-      
+
       // Re-initiate connection for WINDOW type
       this.peer.type === 'WINDOW'
       && this.peer.source
       && this.peer.origin
       && this.emit('ping')
-      
+
       // For IFRAME type, just wait for incoming connection
-      
+
       // Set timeout for this reconnection attempt
-      setTimeout( () => {
-        if( !this.peer.connected ){
-          this.reconnectAttempts < this.maxReconnectAttempts
-                        ? this.attemptReconnection()
-                        : this.fire('reconnection_failed', { attempts: this.reconnectAttempts })
-        }
-      }, this.options.connectionTimeout! )
-    }, delay )
+      setTimeout(() => {
+        if( this.peer.connected ) return
+
+        this.reconnectAttempts < this.maxReconnectAttempts
+            ? this.attemptReconnection()
+            : this.fire('reconnection_failed', { attempts: this.reconnectAttempts })
+      }, this.options.connectionTimeout!)
+    }, delay)
   }
 
   // Message rate limiting
   private checkRateLimit(): boolean {
     if( !this.options.maxMessagesPerSecond ) return true
-    
-    const 
+
+    const
     now = Date.now(),
     aSecondAgo = now - 1000
-    
+
     // Clean old entries
     this.messageRateTracker = this.messageRateTracker.filter( timestamp => timestamp > aSecondAgo )
-    
+
     // Check if limit exceeded
     if( this.messageRateTracker.length >= this.options.maxMessagesPerSecond ){
-      this.fire('error', { 
-        type: 'RATE_LIMIT_EXCEEDED', 
+      this.fire('error', {
+        type: 'RATE_LIMIT_EXCEEDED',
         limit: this.options.maxMessagesPerSecond,
         current: this.messageRateTracker.length
       })
 
       return false
     }
-    
+
     this.messageRateTracker.push( now )
     return true
   }
+
   // Queue messages when not connected
   private queueMessage( _event: string, payload?: any, fn?: AckFunction ){
     if( this.messageQueue.length >= this.options.messageQueueSize! ){
       // Remove oldest message
       const removed = this.messageQueue.shift()
-      this.debug(`[${this.peer.type}] Message queue full, removed oldest message:`, removed?._event )
+      this.debug(`[${this.peer.type}] Message queue full, removed oldest message:`, removed?._event)
     }
-    
+
     this.messageQueue.push({
       _event,
       payload,
       fn,
       timestamp: Date.now()
     })
-    
+
     this.debug(`[${this.peer.type}] Queued message: ${_event} (queue size: ${this.messageQueue.length})`)
   }
 
   // Process queued messages when connection is established
   private processMessageQueue(){
     if( !this.isConnected() || this.messageQueue.length === 0 ) return
-    
+
     this.debug(`[${this.peer.type}] Processing ${this.messageQueue.length} queued messages`)
-    
+
     const queue = [...this.messageQueue]
     this.messageQueue = []
-    
+
     queue.forEach( message => {
       try { this.emit( message._event, message.payload, message.fn ) }
-      catch( error ){ this.debug(`[${this.peer.type}] Failed to send queued message:`, error ) }
+      catch( error ){ this.debug(`[${this.peer.type}] Failed to send queued message:`, error) }
     })
   }
 
   /**
-   * Establish a connection with an iframe containing 
+   * Establish a connection with an iframe containing
    * in the current window
    */
   initiate( contentWindow: MessageEventSource, iframeOrigin: string ){
     if( !contentWindow || !iframeOrigin )
       throw new Error('Invalid Connection initiation arguments')
-    
+
     if( this.peer.type === 'IFRAME' )
       throw new Error('Expect IFRAME to <listen> and WINDOW to <initiate> a connection')
 
@@ -269,7 +280,7 @@ export default class IOF {
     this.peer.origin = iframeOrigin
     this.peer.connected = false
     this.reconnectAttempts = 0
-    
+
     this.messageListener = ({ origin, data, source }) => {
       try {
         // Enhanced security: check valid message structure
@@ -277,23 +288,23 @@ export default class IOF {
             || !source
             || typeof data !== 'object'
             || !data.hasOwnProperty('_event') ) return
-            
+
         const { _event, payload, cid, timestamp } = data as Message['data']
-        
+
         // Handle heartbeat responses
         if( _event === '__heartbeat_response' ){
           this.peer.lastHeartbeat = Date.now()
           return
         }
-        
+
         // Handle heartbeat requests
         if( _event === '__heartbeat' ){
           this.emit('__heartbeat_response', { timestamp: Date.now() })
           this.peer.lastHeartbeat = Date.now()
           return
         }
-        
-        this.debug( `[${this.peer.type}] Message: ${_event}`, payload || '' )
+
+        this.debug(`[${this.peer.type}] Message: ${_event}`, payload || '')
 
         // Handshake or availability check events
         if( _event == 'pong' ){
@@ -312,16 +323,16 @@ export default class IOF {
         this.fire( _event, payload, cid )
       }
       catch( error ){
-        this.debug(`[${this.peer.type}] Message handling error:`, error )
-        this.fire('error', { 
+        this.debug(`[${this.peer.type}] Message handling error:`, error)
+        this.fire('error', {
           type: 'MESSAGE_HANDLING_ERROR',
           error: error instanceof Error ? error.message : String(error),
-          origin 
+          origin
         })
       }
     }
 
-    window.addEventListener( 'message', this.messageListener, false )
+    window.addEventListener('message', this.messageListener, false)
 
     this.debug(`[${this.peer.type}] Initiate connection: IFrame origin <${iframeOrigin}>`)
     this.emit('ping')
@@ -345,10 +356,14 @@ export default class IOF {
       try {
         // Enhanced security: check host origin where event must only come from
         if( hostOrigin && hostOrigin !== origin ){
-          this.fire('error', { type: 'INVALID_ORIGIN', expected: hostOrigin, received: origin })
+          this.fire('error', {
+            type: 'INVALID_ORIGIN',
+            expected: hostOrigin,
+            received: origin
+          })
           return
         }
-          
+
         // Enhanced security: check valid message structure
         if( !source
             || typeof data !== 'object'
@@ -362,25 +377,29 @@ export default class IOF {
 
         // Origin different from handshaked source origin
         else if( origin !== this.peer.origin ){
-          this.fire('error', { type: 'ORIGIN_MISMATCH', expected: this.peer.origin, received: origin })
+          this.fire('error', {
+            type: 'ORIGIN_MISMATCH',
+            expected: this.peer.origin,
+            received: origin
+          })
           return
         }
-        
+
         const { _event, payload, cid, timestamp } = data
-        
+
         // Handle heartbeat responses
         if( _event === '__heartbeat_response' ){
           this.peer.lastHeartbeat = Date.now()
           return
         }
-        
+
         // Handle heartbeat requests
         if( _event === '__heartbeat' ){
           this.emit('__heartbeat_response', { timestamp: Date.now() })
           this.peer.lastHeartbeat = Date.now()
           return
         }
-        
+
         this.debug(`[${this.peer.type}] Message: ${_event}`, payload || '')
 
         // Handshake or availability check events
@@ -394,7 +413,7 @@ export default class IOF {
           this.startHeartbeat()
           this.fire('connect')
           this.processMessageQueue()
-          
+
           return this.debug(`[${this.peer.type}] connected`)
         }
 
@@ -402,49 +421,48 @@ export default class IOF {
         this.fire( _event, payload, cid )
       }
       catch( error ){
-        this.debug(`[${this.peer.type}] Message handling error:`, error )
-        this.fire('error', { 
+        this.debug(`[${this.peer.type}] Message handling error:`, error)
+        this.fire('error', {
           type: 'MESSAGE_HANDLING_ERROR',
           error: error instanceof Error ? error.message : String(error),
-          origin 
+          origin
         })
       }
     }
 
-    window.addEventListener( 'message', this.messageListener, false )
+    window.addEventListener('message', this.messageListener, false)
 
     return this
   }
 
   fire( _event: string, payload?: MessageData['payload'], cid?: string ){
     // Volatile event - check if any listeners exist
-    if( !this.Events[ _event ] 
-        && !this.Events[ _event +'--@once'] )
+    if( !this.Events[_event] && !this.Events[_event + '--@once'] )
       return this.debug(`[${this.peer.type}] No <${_event}> listener defined`)
 
     const ackFn = cid
-                  ? ( error: boolean | string, ...args: any[] ): void => {
-                      this.emit(`${_event}--${cid}--@ack`, { error: error || false, args } )
-                      return
-                    }
-                  : undefined
+      ? ( error: boolean | string, ...args: any[] ): void => {
+          this.emit(`${_event}--${cid}--@ack`, { error: error || false, args })
+          return
+        }
+      : undefined
     let listeners: Listener[] = []
 
-    if( this.Events[ _event +'--@once'] ){
+    if( this.Events[_event + '--@once'] ){
       // Once triggable event
       _event += '--@once'
-      listeners = this.Events[ _event ]
+      listeners = this.Events[_event]
       // Delete once event listeners after fired
-      delete this.Events[ _event ]
+      delete this.Events[_event]
     }
-    else listeners = this.Events[ _event ]
-    
+    else listeners = this.Events[_event]
+
     // Fire listeners with error handling
     listeners.forEach( fn => {
       try { payload !== undefined ? fn( payload, ackFn ) : fn( ackFn ) }
       catch( error ){
-        this.debug(`[${this.peer.type}] Listener error for ${_event}:`, error )
-        this.fire('error', { 
+        this.debug(`[${this.peer.type}] Listener error for ${_event}:`, error)
+        this.fire('error', {
           type: 'LISTENER_ERROR',
           event: _event,
           error: error instanceof Error ? error.message : String(error)
@@ -456,123 +474,137 @@ export default class IOF {
   emit<T = any>( _event: string, payload?: T | AckFunction, fn?: AckFunction ){
     // Check rate limiting
     if( !this.checkRateLimit() ) return this
-    
-    // Queue message if not connected (except for connection-related events)
-    if( !this.isConnected() && !['ping', 'pong', '__heartbeat', '__heartbeat_response'].includes(_event) ){
+
+    /**
+     * Queue message if not connected: Except for
+     * connection-related events
+     */
+    if( !this.isConnected() && !RESERVED_EVENTS.includes(_event) ){
       this.queueMessage( _event, payload, fn )
       return this
     }
-    
+
     if( !this.peer.source ){
       this.fire('error', { type: 'NO_CONNECTION', event: _event })
       return this
     }
 
-		if( typeof payload == 'function' ){
-			fn = payload as AckFunction
-			payload = undefined
-		}
+    if( typeof payload == 'function' ){
+      fn = payload as AckFunction
+      payload = undefined
+    }
 
     try {
       // Enhanced security: sanitize and validate payload
-      const sanitizedPayload = payload ? sanitizePayload( payload, this.options.maxMessageSize! ) : payload
-      
+      const sanitizedPayload = payload
+        ? sanitizePayload( payload, this.options.maxMessageSize! )
+        : payload
+
       // Acknowledge event listener
       let cid: string | undefined
       if( typeof fn === 'function' ){
         const ackFunction = fn
 
         cid = ackId()
-		    this.once(`${_event}--${cid}--@ack`, ({ error, args }) => ackFunction( error, ...args ) )
+        this.once(`${_event}--${cid}--@ack`, ({ error, args }) => ackFunction( error, ...args ))
       }
-      
-      const messageData = { 
-        _event, 
-        payload: sanitizedPayload, 
+
+      const messageData = {
+        _event,
+        payload: sanitizedPayload,
         cid,
         timestamp: Date.now(),
         size: getMessageSize( sanitizedPayload )
       }
-      
+
       this.peer.source.postMessage( newObject( messageData ), this.peer.origin as string )
     }
     catch( error ){
-      this.debug(`[${this.peer.type}] Emit error:`, error )
-      this.fire('error', { 
+      this.debug(`[${this.peer.type}] Emit error:`, error)
+      this.fire('error', {
         type: 'EMIT_ERROR',
         event: _event,
         error: error instanceof Error ? error.message : String(error)
       })
-      
+
       // Call acknowledgment with error if provided
-      if( typeof fn === 'function' ){
-        fn( error instanceof Error ? error.message : String(error) )
-      }
+      typeof fn === 'function'
+      && fn( error instanceof Error ? error.message : String(error) )
     }
 
-		return this
+    return this
   }
-  
+
   on( _event: string, fn: Listener ){
-		// Add Event listener
-		if( !this.Events[ _event ] ) this.Events[ _event ] = []
-		this.Events[ _event ].push( fn )
-    
+    // Add Event listener
+    if( !this.Events[_event] ) this.Events[_event] = []
+    this.Events[_event].push( fn )
+
     this.debug(`[${this.peer.type}] New <${_event}> listener on`)
-		return this
-	}
-  
+    return this
+  }
+
   once( _event: string, fn: Listener ){
-		// Add Once Event listener
+    // Add Once Event listener
     _event += '--@once'
 
-		if( !this.Events[ _event ] ) this.Events[ _event ] = []
-		this.Events[ _event ].push( fn )
-    
+    if( !this.Events[_event] ) this.Events[_event] = []
+    this.Events[_event].push( fn )
+
     this.debug(`[${this.peer.type}] New <${_event} once> listener on`)
-		return this
-	}
+    return this
+  }
 
-	off( _event: string, fn?: Listener ){
-		// Remove Event listener
-    if( fn && this.Events[ _event ] ){
+  off( _event: string, fn?: Listener ){
+    // Remove Event listener
+    if( fn && this.Events[_event] ){
       // Remove specific listener if provided
-      const index = this.Events[ _event ].indexOf( fn )
-      if( index > -1 ) {
-        this.Events[ _event ].splice( index, 1 )
+      const index = this.Events[_event].indexOf( fn )
+      if( index > -1 ){
+        this.Events[_event].splice( index, 1 )
+
         // Remove event array if empty
-        if( this.Events[ _event ].length === 0 )
-          delete this.Events[ _event ]
+        if( this.Events[_event].length === 0 )
+          delete this.Events[_event]
       }
     }
     // Remove all listeners for event
-    else delete this.Events[ _event ]
-    
+    else delete this.Events[_event]
+
     typeof fn == 'function' && fn()
     this.debug(`[${this.peer.type}] <${_event}> listener off`)
 
-		return this
-	}
+    return this
+  }
 
-	removeListeners( fn?: Listener ){
+  removeListeners( fn?: Listener ){
     // Clear all event listeners
-		this.Events = {}
-		typeof fn == 'function' && fn()
+    this.Events = {}
+    typeof fn == 'function' && fn()
 
     this.debug(`[${this.peer.type}] All listeners removed`)
-		return this
-	}
+    return this
+  }
 
-  emitAsync<T = any, R = any>( _event: string, payload?: T ): Promise<R> {
+  emitAsync<T = any, R = any>( _event: string, payload?: T, timeout: number = 5000 ): Promise<R> {
     return new Promise(( resolve, reject ) => {
+      const timeoutId = setTimeout(() => {
+        reject( new Error(`Event '${_event}' acknowledgment timeout after ${timeout}ms`) )
+      }, timeout)
+
       try {
         this.emit( _event, payload, ( error, ...args ) => {
+          clearTimeout( timeoutId )
+
           error
             ? reject( new Error( typeof error === 'string' ? error : 'Ack error' ) )
             : resolve( args.length === 0 ? undefined : args.length === 1 ? args[0] : args )
         })
       }
-      catch( error ){ reject( error ) }
+      catch( error ){
+        clearTimeout( timeoutId )
+        reject( error )
+      }
     })
   }
 
@@ -580,33 +612,33 @@ export default class IOF {
     return new Promise( resolve => this.once( _event, resolve ) )
   }
 
-  connectAsync( timeout: number = 5000 ): Promise<void> {
+  connectAsync( timeout?: number ): Promise<void> {
     return new Promise(( resolve, reject ) => {
       if( this.isConnected() ) return resolve()
 
       const timeoutId = setTimeout(() => {
-        this.off('connect', connectHandler )
+        this.off('connect', connectHandler)
         reject( new Error('Connection timeout') )
-      }, timeout )
+      }, timeout || this.options.connectionTimeout)
 
       const connectHandler = () => {
         clearTimeout( timeoutId )
         resolve()
       }
 
-      this.once('connect', connectHandler )
+      this.once('connect', connectHandler)
     })
   }
 
   // Clean up all resources
   private cleanup(){
     if( this.messageListener ){
-      window.removeEventListener( 'message', this.messageListener )
+      window.removeEventListener('message', this.messageListener)
       this.messageListener = undefined
     }
-    
+
     this.stopHeartbeat()
-    
+
     if( this.reconnectTimer ){
       clearTimeout( this.reconnectTimer )
       this.reconnectTimer = undefined
@@ -616,7 +648,7 @@ export default class IOF {
   disconnect( fn?: () => void ){
     // Clean disconnect method
     this.cleanup()
-    
+
     this.peer.connected = false
     this.peer.source = undefined
     this.peer.origin = undefined
@@ -625,10 +657,10 @@ export default class IOF {
     this.messageRateTracker = []
     this.reconnectAttempts = 0
     this.removeListeners()
-    
+
     typeof fn == 'function' && fn()
     this.debug(`[${this.peer.type}] Disconnected`)
-    
+
     return this
   }
 
@@ -654,4 +686,4 @@ export default class IOF {
     this.debug(`[${this.peer.type}] Cleared ${queueSize} queued messages`)
     return this
   }
-}
+}