postMessage
Made Simple

/**
 * Parent Window Example
 * 
 * Demonstrates embedding an iframe and establishing secure two-way
 * communication. Parley-js handles the complexity of postMessage:
 * origin validation, response correlation, timeouts, and reconnection.
 */
import { Parley, SYSTEM_EVENTS } from 'parley-js';

// Create instance with origin validation
const parley = Parley.create({
    targetType: 'iframe',
    allowedOrigins: ['https://child.example.com'],
    timeout: 5000,
});

// Handle incoming notifications from child
parley.on('notification', (payload, respond, metadata) => {
    console.log(`Child says: ${payload.message}`);
});

// Connect to iframe and assign target ID
const iframe = document.querySelector('#child-iframe');
await parley.connect(iframe, 'child');

// Send message and get typed response
const response = await parley.send('hello', { name: 'World' }, {
    targetId: 'child'
});
console.log(response.greeting); // "Hello, World!"

// Broadcast to all connected targets
await parley.broadcast('announcement', { message: 'Update available!' });

/**
 * Child Iframe Example
 * 
 * Shows the iframe side of parent-child communication. Each context
 * runs its own Parley instance. The library provides a clean API for
 * responding to requests, handling broadcasts, and sending notifications.
 */
import { Parley, SYSTEM_EVENTS } from 'parley-js';

// Child iframe creates its own instance
const parley = Parley.create({
    targetType: 'iframe',
    allowedOrigins: ['https://parent.example.com'],
});

// Handle messages from parent with typed response
parley.on('hello', (payload, respond, metadata) => {
    console.log(`Parent sent: ${payload.name}`);
    respond({ greeting: `Hello, ${payload.name}!`, receivedAt: Date.now() });
});

// Handle broadcasts
parley.on('announcement', (payload, respond, metadata) => {
    console.log(`Announcement: ${payload.message}`);
    respond({ received: true });
});

// Connect to parent window
await parley.connect(window.parent, 'parent');

// Send notification to parent (fire-and-forget)
await parley.send('notification', { message: 'Child ready!' }, {
    targetId: 'parent',
    expectsResponse: false
});

/**
 * Window-to-Popup Example
 * 
 * Pop-up windows are notoriously tricky—they can be blocked, closed,
 * or navigated away. Parley-js manages window.opener references,
 * detects when popups close, and provides the same clean API as iframes.
 */
import { Parley } from 'parley-js';

// ═══ MAIN WINDOW ═══
const parley = Parley.create({
    targetType: 'window',
    allowedOrigins: [window.location.origin],
});

// Handle messages from popup
parley.on('popup:notification', (payload, respond, metadata) => {
    console.log(`Popup says: ${payload.message}`);
    respond({ received: true });
});

// Open popup and connect
const popup = window.open('popup.html', 'popup', 'width=600,height=400');
await parley.connect(popup, 'popup');

// Request data from popup
const time = await parley.send('get-time', { format: 'full' }, { targetId: 'popup' });

// ═══ POPUP WINDOW ═══
parley.on('get-time', (payload, respond, metadata) => {
    respond({ time: new Date().toLocaleString(), timezone: 'UTC' });
});

// Connect back to opener
await parley.connect(window.opener, 'opener');

// Send notification to main window
await parley.send('popup:notification', { message: 'Ready!' }, {
    targetId: 'opener', expectsResponse: false
});

/**
 * Heartbeat Monitoring Example
 * 
 * postMessage has no built-in way to detect if an iframe crashes,
 * a popup closes, or a connection becomes unresponsive. Parley-js
 * solves this with automatic heartbeat monitoring and reconnection.
 */
import { Parley, SYSTEM_EVENTS } from 'parley-js';

// Create instance with heartbeat enabled
const parley = Parley.create({
    targetType: 'iframe',
    allowedOrigins: ['https://child.example.com'],
    heartbeat: {
        enabled: true,
        interval: 5000,   // Ping every 5 seconds
        timeout: 2000,    // Wait 2s for response
        maxMissed: 3      // Disconnect after 3 misses
    }
});

// ═══ MONITOR CONNECTION HEALTH ═══

// Early warning: heartbeat missed
parley.onSystem(SYSTEM_EVENTS.HEARTBEAT_MISSED, (event) => {
    console.warn(`Heartbeat missed: ${event.consecutiveMissed}/3`);
    showWarning('Connection unstable...');
});

// Connection lost - iframe crashed, closed, or unresponsive
parley.onSystem(SYSTEM_EVENTS.CONNECTION_LOST, (event) => {
    console.error(`Lost connection: ${event.reason}`);
    
    if (event.reason === 'heartbeat_failure') {
        // Auto-reconnect after 3 seconds
        setTimeout(() => reconnect(), 3000);
    }
});

// Connection restored
parley.onSystem(SYSTEM_EVENTS.CONNECTED, (event) => {
    console.log(`Connected to ${event.targetId}`);
    hideWarning();
});

// ═══ POPUP CLOSE DETECTION ═══
// Detect when user closes a popup window
const popup = window.open('popup.html', '_blank');
await parley.connect(popup, 'popup');

parley.onSystem(SYSTEM_EVENTS.CONNECTION_LOST, (event) => {
    if (event.targetId === 'popup') {
        console.log('Popup was closed by user');
    }
});

/**
 * Schema Validation Example
 * 
 * Cross-window messaging can be a security risk if payloads aren't
 * validated. Parley-js supports JSON Schema validation out of the box,
 * catching malformed data before your handlers ever see it.
 */
import { Parley } from 'parley-js';

const parley = Parley.create({ targetType: 'iframe' });

// Register message type with JSON Schema validation
parley.register('user:create', {
    schema: {
        type: 'object',
        required: ['email', 'name'],
        properties: {
            email: { type: 'string', pattern: '^[^@]+@[^@]+$' },
            name: { type: 'string', minLength: 1 },
            age: { type: 'integer', minimum: 0 }
        }
    },
    timeout: 10000  // Custom timeout per message type
});

// Valid payload - passes validation
await parley.send('user:create', {
    email: 'alice@example.com',
    name: 'Alice',
    age: 28
});

// Invalid payload - throws ValidationError
await parley.send('user:create', {
    email: 'invalid-email',  // ✗ fails pattern
    name: ''                  // ✗ fails minLength
}); // Error: Validation failed