site

PAN v1.0 API Reference

Complete reference documentation for the Page Area Network (PAN) v1.0 API.

Quick Links:

PanClient API
PanMessage Format
Topic Patterns
Request/Reply Pattern
Retained Messages
Error Handling

Getting Started

Installation

<!-- Include PAN bus and autoloader -->
<pan-bus></pan-bus>
<script type="module" src="./pan/core/pan-autoload.mjs"></script>

Basic Usage

import { PanClient } from './pan/core/pan-client.mjs';

// Create client
const client = new PanClient();
await client.ready();

// Publish a message
client.publish({
  topic: 'users.updated',
  data: { id: 123, name: 'Alice' }
});

// Subscribe to messages
client.subscribe('users.*', (msg) => {
  console.log('Received:', msg.topic, msg.data);
});

PanClient API

Constructor

Creates a new PAN client instance.

new PanClient(host?, busSelector?)

Parameters

Parameter	Type	Default	Description
`host`	`HTMLElement \\| Document`	`document`	Element to dispatch/receive events from
`busSelector`	`string`	`'pan-bus'`	CSS selector for bus element

Returns

New PanClient instance

Examples

// Default: use document as host
const client = new PanClient();

// Use specific element as host
const myComponent = document.querySelector('my-component');
const client = new PanClient(myComponent);

// Custom bus selector
const client = new PanClient(document, 'custom-bus');

Use Cases

Document-level client (most common):

// All components can communicate through document
const client = new PanClient();

Component-scoped client:

// Isolate communication to specific component subtree
class MyComponent extends HTMLElement {
  connectedCallback() {
    this.client = new PanClient(this);
  }
}

ready()

Returns a promise that resolves when the PAN bus is ready.

client.ready(): Promise<void>

Returns

Promise<void> - Resolves when bus emits pan:sys.ready

Examples

// Wait for bus before publishing
const client = new PanClient();
await client.ready();
client.publish({ topic: 'app.started', data: {} });

// Use .then() syntax
client.ready().then(() => {
  console.log('Bus is ready!');
});

// Safe to call multiple times (returns same promise)
await client.ready();
await client.ready(); // No-op, already ready

Best Practices

✅ DO: Always wait for ready() before publishing

await client.ready();
client.publish({ topic: 'app.init', data: {} });

❌ DON’T: Publish before bus is ready

// May be lost if bus not ready yet
client.publish({ topic: 'app.init', data: {} });

publish()

Publishes a message to the PAN bus.

client.publish(message: PanMessage): void

Parameters

Parameter	Type	Required	Description
`message`	`PanMessage`	Yes	Message object to publish
`message.topic`	`string`	Yes	Topic name
`message.data`	`any`	Yes	Message payload
`message.retain`	`boolean`	No	Retain message for late subscribers
`message.replyTo`	`string`	No	Topic to send reply to
`message.correlationId`	`string`	No	Correlation ID for request/reply
`message.headers`	`object`	No	Optional metadata

Returns

void - Fire and forget

Examples

Simple publish:

client.publish({
  topic: 'users.updated',
  data: { id: 123, name: 'Alice' }
});

Retained message:

// Last message stored and replayed to new subscribers
client.publish({
  topic: 'app.theme',
  data: { mode: 'dark' },
  retain: true
});

With metadata headers:

client.publish({
  topic: 'analytics.event',
  data: { action: 'click', target: 'button' },
  headers: {
    userId: '123',
    sessionId: 'abc',
    timestamp: Date.now().toString()
  }
});

Common Patterns

State updates:

// Publish retained state for late joiners
function updateUserList(users) {
  client.publish({
    topic: 'users.list.state',
    data: { users },
    retain: true
  });
}

Commands:

// Fire-and-forget command
function navigateTo(route) {
  client.publish({
    topic: 'nav.goto',
    data: { route }
  });
}

Events:

// Notify about user actions
button.addEventListener('click', () => {
  client.publish({
    topic: 'ui.button.clicked',
    data: { buttonId: button.id }
  });
});

Subscribes to one or more topic patterns.

client.subscribe(
  topics: string | string[],
  handler: (message: PanMessage) => void,
  options?: SubscribeOptions
): UnsubscribeFunction

Parameters

Parameter	Type	Required	Description
`topics`	`string \\| string[]`	Yes	Topic pattern(s) to subscribe to
`handler`	`function`	Yes	Callback receiving PanMessage
`options`	`SubscribeOptions`	No	Subscription options
`options.retained`	`boolean`	No	Receive retained messages immediately
`options.signal`	`AbortSignal`	No	AbortSignal for automatic cleanup

Returns

UnsubscribeFunction - Call to unsubscribe: () => void

Examples

Simple subscription:

const unsub = client.subscribe('users.updated', (msg) => {
  console.log('User updated:', msg.data);
});

// Later: unsubscribe
unsub();

Multiple topics:

client.subscribe(['users.*', 'posts.*'], (msg) => {
  console.log('Received:', msg.topic, msg.data);
});

Wildcard patterns:

// Match all user-related topics
client.subscribe('users.*', (msg) => {
  console.log('User event:', msg.topic);
});

// Match everything
client.subscribe('*', (msg) => {
  console.log('Any message:', msg.topic);
});

Retained messages:

// Receive current state immediately
client.subscribe('app.theme', (msg) => {
  applyTheme(msg.data.mode);
}, { retained: true });

With AbortSignal:

const controller = new AbortController();

client.subscribe('events.*', (msg) => {
  console.log('Event:', msg.topic);
}, { signal: controller.signal });

// Later: unsubscribe automatically
controller.abort();

Common Patterns

State synchronization:

// Keep UI in sync with state
client.subscribe('users.list.state', (msg) => {
  renderUserList(msg.data.users);
}, { retained: true });

Event handling:

// Handle navigation events
client.subscribe('nav.goto', (msg) => {
  router.navigateTo(msg.data.route);
});

Component cleanup:

class MyComponent extends HTMLElement {
  connectedCallback() {
    this.client = new PanClient(this);

    // Store unsubscribe function
    this.unsub = this.client.subscribe('data.*', (msg) => {
      this.handleData(msg.data);
    });
  }

  disconnectedCallback() {
    // Clean up subscription
    this.unsub();
  }
}

Automatic cleanup:

class MyComponent extends HTMLElement {
  connectedCallback() {
    this.abortController = new AbortController();

    // Will auto-cleanup on abort
    this.client.subscribe('data.*', (msg) => {
      this.handleData(msg.data);
    }, { signal: this.abortController.signal });
  }

  disconnectedCallback() {
    // Unsubscribe all at once
    this.abortController.abort();
  }
}

request()

Sends a request and waits for a reply.

client.request(
  topic: string,
  data: any,
  options?: RequestOptions
): Promise<PanMessage>

Parameters

Parameter	Type	Required	Description
`topic`	`string`	Yes	Request topic name
`data`	`any`	Yes	Request payload
`options`	`RequestOptions`	No	Request options
`options.timeoutMs`	`number`	No	Timeout in ms (default: 5000)

Returns

Promise<PanMessage> - Resolves with reply message

Throws

Error - If request times out

Examples

Simple request:

try {
  const response = await client.request('users.get', { id: 123 });
  console.log('User:', response.data);
} catch (err) {
  console.error('Request failed:', err);
}

Custom timeout:

const response = await client.request('slow.operation', { ... }, {
  timeoutMs: 10000  // 10 second timeout
});

CRUD operations:

// Create
const created = await client.request('users.item.save', {
  item: { name: 'Alice', email: 'alice@example.com' }
});

// Read
const user = await client.request('users.item.get', { id: 123 });

// Update
const updated = await client.request('users.item.save', {
  item: { id: 123, name: 'Alice Updated' }
});

// Delete
const deleted = await client.request('users.item.delete', { id: 123 });

Error handling:

async function loadUser(id) {
  try {
    const response = await client.request('users.item.get', { id });

    if (!response.data.ok) {
      throw new Error(response.data.error);
    }

    return response.data.item;
  } catch (err) {
    if (err.message.includes('timeout')) {
      console.error('Request timed out');
    } else {
      console.error('Failed to load user:', err);
    }
    return null;
  }
}

Implementing a Responder

// Listen for requests
client.subscribe('users.item.get', async (msg) => {
  // Only respond to requests (have replyTo)
  if (!msg.replyTo) return;

  // Process request
  const user = await db.getUser(msg.data.id);

  // Send reply
  client.publish({
    topic: msg.replyTo,
    data: { ok: true, item: user },
    correlationId: msg.correlationId
  });
});

matches() (static)

Tests if a topic matches a pattern.

PanClient.matches(topic: string, pattern: string): boolean

Parameters

Parameter	Type	Required	Description
`topic`	`string`	Yes	Topic to test
`pattern`	`string`	Yes	Pattern to match

Returns

boolean - true if topic matches pattern

Pattern Rules

Exact match: users.list.state matches users.list.state
Single wildcard: users.* matches users.list but NOT users.list.state
Global wildcard: * matches any topic
Wildcard position: Can be anywhere (*.updated, users.*.state)

Examples

// Exact match
PanClient.matches('users.list.state', 'users.list.state')  // true

// Single segment wildcard
PanClient.matches('users.list', 'users.*')         // true
PanClient.matches('users.list.state', 'users.*')  // false (2 segments)

// Global wildcard
PanClient.matches('users.list.state', '*')         // true
PanClient.matches('any.topic.here', '*')           // true

// Wildcard positions
PanClient.matches('users.item.updated', '*.item.updated')  // true
PanClient.matches('users.item.123', 'users.item.*')        // true

// No match
PanClient.matches('users.list', 'posts.*')         // false

Use Cases

Manual filtering:

client.subscribe('*', (msg) => {
  if (PanClient.matches(msg.topic, 'users.*')) {
    handleUserEvent(msg);
  } else if (PanClient.matches(msg.topic, 'posts.*')) {
    handlePostEvent(msg);
  }
});

Testing patterns:

const pattern = 'users.*';
const topics = ['users.list', 'users.item', 'posts.list'];

const matching = topics.filter(t => PanClient.matches(t, pattern));
console.log(matching); // ['users.list', 'users.item']

PanMessage Format

All messages follow this structure:

interface PanMessage {
  // Required fields
  topic: string;      // Topic name (e.g., "users.list.state")
  data: any;          // Message payload (any JSON-serializable value)

  // Optional fields (auto-generated by bus if not provided)
  id?: string;        // Unique message ID (UUID)
  ts?: number;        // Timestamp in milliseconds (epoch)

  // Optional fields (features)
  retain?: boolean;           // If true, message is retained by bus
  replyTo?: string;           // Topic to send reply to
  correlationId?: string;     // Correlation ID for request/reply
  headers?: Record<string, string>;  // Optional metadata
}

Field Descriptions

topic (required)

Topic name using dotted notation.

Format: resource.action.qualifier

Examples:

users.list.state - User list state
users.item.get - Get user request
nav.goto - Navigation command
ui.modal.opened - UI event

Best Practices:

Use lowercase
Use dots to separate segments
Be specific but concise
Follow conventions (see Topic Patterns)

data (required)

Message payload - any JSON-serializable value.

Supported types:

Object: { id: 123, name: 'Alice' }
Array: [1, 2, 3]
String: "hello"
Number: 42
Boolean: true / false
Null: null

Not supported:

Functions
undefined (use null instead)
Circular references (will throw)
DOM nodes (serialize to plain objects)

Examples:

// Object payload
{ topic: 'users.updated', data: { id: 123, name: 'Alice' } }

// Array payload
{ topic: 'users.list.state', data: [user1, user2, user3] }

// Simple value
{ topic: 'counter.value', data: 42 }

// Null
{ topic: 'users.selected', data: null }  // No selection

id (optional)

Unique message identifier (UUID).

Auto-generated: Bus creates UUID if not provided Format: "550e8400-e29b-41d4-a716-446655440000"

Use cases:

Message deduplication
Tracking specific messages
Debugging

// Let bus generate ID (recommended)
client.publish({ topic: 'users.updated', data: { ... } });

// Provide custom ID
client.publish({
  topic: 'users.updated',
  data: { ... },
  id: 'custom-id-123'
});

ts (optional)

Timestamp in milliseconds since epoch.

Auto-generated: Bus adds timestamp if not provided Format: Number (e.g., 1699564800000)

Use cases:

Message ordering
Time-based filtering
Analytics

// Let bus generate timestamp (recommended)
client.publish({ topic: 'event', data: { ... } });

// Provide custom timestamp
client.publish({
  topic: 'event',
  data: { ... },
  ts: Date.now()
});

retain (optional)

If true, bus stores this message and replays it to new subscribers.

Default: false Type: boolean

Use cases:

Application state
Configuration
Last known value

// Retained state message
client.publish({
  topic: 'app.theme',
  data: { mode: 'dark' },
  retain: true
});

// New subscribers get current theme
client.subscribe('app.theme', (msg) => {
  console.log('Current theme:', msg.data.mode);
}, { retained: true });

See: Retained Messages

replyTo (optional)

Topic to send reply to (for request/reply pattern).

Type: string Auto-generated: By client.request()

Use cases:

Request/reply pattern
Async responses

// Manually set replyTo
client.publish({
  topic: 'users.item.get',
  data: { id: 123 },
  replyTo: 'users.item.get.reply.abc123',
  correlationId: 'req-001'
});

// Or use client.request() (recommended)
const response = await client.request('users.item.get', { id: 123 });

See: Request/Reply Pattern

correlationId (optional)

Correlation identifier for matching requests and replies.

Type: string Auto-generated: By client.request()

Use cases:

Match request with reply
Track conversation

// Auto-generated by client.request()
const response = await client.request('users.item.get', { id: 123 });
// correlationId is automatically created and matched

// Manual correlation
const corrId = crypto.randomUUID();
client.publish({
  topic: 'task.start',
  data: { task: 'process' },
  correlationId: corrId
});

client.subscribe('task.complete', (msg) => {
  if (msg.correlationId === corrId) {
    console.log('Our task completed!');
  }
});

headers (optional)

Free-form metadata as string key-value pairs.

Type: Record<string, string> Default: undefined

Use cases:

User context (userId, sessionId)
Tracing (traceId, spanId)
Metadata (source, version)

client.publish({
  topic: 'analytics.event',
  data: { action: 'click', target: 'button' },
  headers: {
    userId: '123',
    sessionId: 'abc',
    timestamp: Date.now().toString(),
    source: 'mobile-app'
  }
});

Topic Patterns

Naming Conventions

Standard format: resource.action.qualifier

Examples:

users.list.state        # Resource: users, Action: list, Qualifier: state
users.item.get          # Resource: users, Action: item (single), Qualifier: get
users.item.save         # Resource: users, Action: item, Qualifier: save
nav.goto                # Resource: nav, Action: goto
ui.modal.opened         # Resource: ui (modal), Action: opened

Wildcard Matching

Single segment: * matches exactly one segment

'users.*'              # Matches: users.list, users.item
                       # Does NOT match: users.list.state, users.item.get

'*.updated'            # Matches: users.updated, posts.updated
                       # Does NOT match: users.item.updated

'users.*.state'        # Matches: users.list.state, users.item.state
                       # Does NOT match: users.state, users.list.item.state

Global wildcard: * alone matches any topic

'*'                    # Matches: ALL topics

Reserved Namespaces

pan:* - Reserved for PAN internals

pan:sys.ready          # System ready event
pan:publish            # Internal publish event
pan:subscribe          # Internal subscribe event
pan:deliver            # Internal deliver event

❌ DO NOT use pan:* topics in application code

pan:$reply:* - Auto-generated reply topics

pan:$reply:client-id:correlation-id

❌ DO NOT manually create pan:$reply:* topics

Request/Reply Pattern

Overview

Request/reply enables async request-response communication between components.

How it works:

Requester calls client.request(topic, data)
Request is published with auto-generated replyTo and correlationId
Responder listens for request topic
Responder publishes reply to replyTo topic with same correlationId
Requester receives reply (promise resolves)

Basic Example

Requester:

try {
  const response = await client.request('users.item.get', { id: 123 });
  console.log('User:', response.data.item);
} catch (err) {
  console.error('Request failed:', err);
}

Responder:

client.subscribe('users.item.get', async (msg) => {
  if (!msg.replyTo) return;  // Not a request

  const user = await database.getUser(msg.data.id);

  client.publish({
    topic: msg.replyTo,
    data: { ok: true, item: user },
    correlationId: msg.correlationId
  });
});

Response Format

Recommended format:

{
  ok: boolean,         // Success flag
  item?: any,          // Result data (on success)
  error?: string,      // Error message (on failure)
  code?: string        // Error code (on failure)
}

Example responses:

// Success
{ ok: true, item: { id: 123, name: 'Alice' } }

// Error
{ ok: false, error: 'User not found', code: 'NOT_FOUND' }

// List result
{ ok: true, items: [user1, user2, user3], total: 50 }

Complete CRUD Example

// CREATE
async function createUser(userData) {
  const response = await client.request('users.item.save', {
    item: userData
  });

  if (!response.data.ok) {
    throw new Error(response.data.error);
  }

  return response.data.item;
}

// READ (single)
async function getUser(id) {
  const response = await client.request('users.item.get', { id });
  return response.data.ok ? response.data.item : null;
}

// READ (list)
async function listUsers() {
  const response = await client.request('users.list.get', {});
  return response.data.items || [];
}

// UPDATE
async function updateUser(id, changes) {
  const response = await client.request('users.item.save', {
    item: { id, ...changes }
  });
  return response.data.item;
}

// DELETE
async function deleteUser(id) {
  const response = await client.request('users.item.delete', { id });
  return response.data.ok;
}

Timeout Handling

async function getUserWithRetry(id, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.request('users.item.get', { id }, {
        timeoutMs: 5000
      });
    } catch (err) {
      if (err.message.includes('timeout') && i < maxRetries - 1) {
        console.log(`Timeout, retrying (${i + 1}/${maxRetries})...`);
        continue;
      }
      throw err;
    }
  }
}

Retained Messages

Overview

Retained messages are the last message published to a topic, stored by the bus and replayed to new subscribers who opt-in.

Use cases:

Application state
Configuration
Last known value
Avoid “no data” state on load

Publishing Retained Messages

// Publish retained state
client.publish({
  topic: 'app.theme',
  data: { mode: 'dark' },
  retain: true
});

// Later: publish new state (replaces previous)
client.publish({
  topic: 'app.theme',
  data: { mode: 'light' },
  retain: true
});

Subscribing to Retained Messages

// Receive current state immediately
client.subscribe('app.theme', (msg) => {
  applyTheme(msg.data.mode);
}, { retained: true });

// Without retained option (only new messages)
client.subscribe('app.theme', (msg) => {
  applyTheme(msg.data.mode);
});  // Won't receive current state

Complete State Example

// State manager
class UserListManager {
  constructor(client) {
    this.client = client;
    this.users = [];
  }

  // Publish state
  updateState(users) {
    this.users = users;
    this.client.publish({
      topic: 'users.list.state',
      data: { users: this.users },
      retain: true
    });
  }

  // Add user
  addUser(user) {
    this.users.push(user);
    this.updateState(this.users);
  }

  // Remove user
  removeUser(id) {
    this.users = this.users.filter(u => u.id !== id);
    this.updateState(this.users);
  }
}

// UI component
class UserListComponent extends HTMLElement {
  connectedCallback() {
    this.client = new PanClient(this);

    // Get current state + future updates
    this.client.subscribe('users.list.state', (msg) => {
      this.render(msg.data.users);
    }, { retained: true });
  }

  render(users) {
    this.innerHTML = users.map(u => `<li>${u.name}</li>`).join('');
  }
}

Best Practices

✅ DO:

Use retained messages for state
One retained message per topic (last value)
Keep retained data reasonably sized

❌ DON’T:

Use retained for events (use normal publish)
Rely on retained for history (only last value stored)
Retain huge datasets (consider pagination)

Error Handling

Request Timeouts

async function safeRequest(topic, data) {
  try {
    return await client.request(topic, data, { timeoutMs: 5000 });
  } catch (err) {
    if (err.message.includes('timeout')) {
      console.error('Request timed out');
      return { data: { ok: false, error: 'Timeout' } };
    }
    throw err;
  }
}

Invalid Data

try {
  client.publish({
    topic: 'users.updated',
    data: { circular: selfReference }  // Will throw
  });
} catch (err) {
  console.error('Failed to publish:', err);
}

Missing Responders

// Set reasonable timeout for potentially missing responders
const response = await client.request('optional.service', data, {
  timeoutMs: 1000  // Fail fast
}).catch(err => {
  // Handle gracefully
  return { data: { ok: false, error: 'Service unavailable' } };
});

Next Steps

Topic Conventions: See TOPICS.md for detailed conventions
Code Examples: See examples/ for complete working examples
API Stability: See API_STABILITY.md for guarantees

Last Updated: November 2024

This site is open source. Improve this page.

site

PAN v1.0 API Reference

Getting Started

Installation

Basic Usage

PanClient API

Constructor

Parameters

Returns

Examples

Use Cases

ready()

Returns

Examples

Best Practices

publish()

Parameters

Returns

Examples

Common Patterns

subscribe()

Parameters

Returns

Examples

Common Patterns

request()

Parameters

Returns

Throws

Examples

Implementing a Responder

matches() (static)

Parameters

Returns

Pattern Rules

Examples

Use Cases

PanMessage Format

Field Descriptions

topic (required)

data (required)

id (optional)

ts (optional)

retain (optional)

replyTo (optional)

correlationId (optional)

headers (optional)

Topic Patterns

Naming Conventions

Wildcard Matching

Reserved Namespaces

Request/Reply Pattern

Overview

Basic Example

Response Format

Complete CRUD Example

Timeout Handling

Retained Messages

Overview

Publishing Retained Messages

Subscribing to Retained Messages

Complete State Example

Best Practices

Error Handling

Request Timeouts

Invalid Data

Missing Responders

Next Steps