LARC API Reference

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

// Bus is ready, safe to publish/subscribe
client.publish({
  topic: 'app.started',
  data: { timestamp: Date.now() }
});

• Always call this before using the client
• Safe to call multiple times
• Waits for pan:sys.ready event if bus not ready
• Automatically announces client presence to bus

#### publish(message): void

Publishes a message to the bus.

{
  topic: string;              // Required
  data: any;                  // Required
  retain?: boolean;           // Optional
  replyTo?: string;           // Optional
  correlationId?: string;     // Optional
  headers?: Record<string, string>; // Optional
}

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

// Retained message
client.publish({
  topic: 'users.list.state',
  data: { users: [...] },
  retain: true
});

// With headers
client.publish({
  topic: 'analytics.event',
  data: { action: 'click' },
  headers: { 'x-source': 'mobile-app' }
});

#### subscribe(topics, handler, options): UnsubscribeFunction

Subscribes to one or more topic patterns.

• topics (string | string[]) - Topic pattern(s) to subscribe to
• handler (function) - Callback function(msg)
• options (object) - Subscription options

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

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

// Get retained messages immediately
client.subscribe('app.state', (msg) => {
  console.log('Current state:', msg.data);
}, { retained: true });

// Automatic cleanup with AbortController
const controller = new AbortController();
client.subscribe('events.*', handler, {
  signal: controller.signal
});

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

// Manual unsubscribe
const unsubscribe = client.subscribe('users.*', handler);
// Later: unsubscribe();

function handler(msg) {
  // msg.topic - Topic name
  // msg.data - Message payload
  // msg.id - Unique message ID
  // msg.ts - Timestamp
  // msg.retain - Whether message was retained
  // msg.correlationId - For request/reply correlation
}

#### request(topic, data, options): Promise

Sends a request and waits for a reply (request/reply pattern).

• topic (string) - Request topic
• data (any) - Request payload
• options (object) - Request options

// 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',
  { param: 'value' },
  { timeoutMs: 10000 }  // 10 second timeout
);

// Request with error handling
async function fetchUser(id) {
  try {
    const response = await client.request('users.get', { id });
    return response.data;
  } catch (err) {
    if (err.message === 'PAN request timeout') {
      console.error('Request timed out');
    } else {
      console.error('Request failed:', err);
    }
    return null;
  }
}

// Server component listens for requests
client.subscribe('users.get', (msg) => {
  const { id } = msg.data;
  const user = getUserById(id);

  // Reply to the request
  client.publish({
    topic: msg.replyTo,
    data: user,
    correlationId: msg.correlationId
  });
});

Static Method

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

Checks if a topic matches a pattern.

• topic (string) - Topic to test
• pattern (string) - Pattern to match against

PanClient.matches('users.list.state', 'users.*');  // true
PanClient.matches('users.list.state', 'users.list.state');  // true
PanClient.matches('users.list.state', '*');  // true
PanClient.matches('users.list.state', 'posts.*');  // false
PanClient.matches('users.item.123', 'users.item.*');  // true

Complete Example

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

class UserListComponent extends HTMLElement {
  constructor() {
    super();
    this.client = new PanClient(this);
    this.users = [];
  }

  async connectedCallback() {
    // Wait for bus to be ready
    await this.client.ready();

    // Subscribe to user events
    this.unsubscribe = this.client.subscribe(
      ['users.*'],
      (msg) => this.handleUserEvent(msg),
      { retained: true }  // Get current state immediately
    );

    this.render();
  }

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

  handleUserEvent(msg) {
    switch (msg.topic) {
      case 'users.list.state':
        this.users = msg.data.users;
        this.render();
        break;

      case 'users.created':
        this.users.push(msg.data);
        this.render();
        break;

      case 'users.updated':
        const index = this.users.findIndex(u => u.id === msg.data.id);
        if (index !== -1) {
          this.users[index] = msg.data;
          this.render();
        }
        break;

      case 'users.deleted':
        this.users = this.users.filter(u => u.id !== msg.data.id);
        this.render();
        break;
    }
  }

  async deleteUser(id) {
    try {
      // Request/reply pattern
      await this.client.request('users.delete', { id });
      console.log('User deleted successfully');
    } catch (err) {
      console.error('Delete failed:', err);
    }
  }

  render() {
    this.innerHTML = `
      <ul>
        ${this.users.map(user => `
          <li>
            ${user.name}
            <button onclick="this.closest('user-list-component').deleteUser(${user.id})">
              Delete
            </button>
          </li>
        `).join('')}
      </ul>
    `;
  }
}

customElements.define('user-list-component', UserListComponent);

Configuration

Using larc-config.mjs

LARC supports a centralized configuration file for path resolution across your application.

<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
</head>
<body>
  <!-- Step 1: Load config -->
  <script type="module" src="/larc-config.mjs"></script>

  <!-- Step 2: Load autoloader -->
  <script type="module" src="/core/pan.mjs"></script>

  <!-- Step 3: Use components -->
  <pan-card>Hello World</pan-card>
</body>
</html>

// larc-config.mjs
export const aliases = {
  '@larc/core': '/core/src',
  '@larc/components': '/components',
  '@larc/examples': '/examples'
};

export const componentPaths = {
  'pan-bus': '@larc/core/pan-bus.mjs',
  'pan-client': '@larc/core/pan-client.mjs',
  'pan-card': '@larc/components/pan-card.mjs'
};

export const paths = {
  resolve(aliasOrPath, subpath = '') {
    // Resolve aliases to absolute paths
    // ...
  },

  component(componentName) {
    // Resolve component paths
    // ...
  }
};

export const autoloadConfig = {
  baseUrl: null,
  componentsPath: '/ui/',
  extension: '.mjs',
  rootMargin: 600,

  // Custom component resolver
  resolveComponent(tagName) {
    return paths.component(tagName);
  }
};

// Apply to window.panAutoload
if (typeof window !== 'undefined') {
  window.panAutoload = Object.assign(
    window.panAutoload || {},
    autoloadConfig,
    { paths, aliases, componentPaths }
  );

  window.larcResolve = paths.resolve.bind(paths);
}

import { paths } from '/larc-config.mjs';

// Resolve any alias
const clientPath = paths.resolve('@larc/core', 'components/pan-client.mjs');

// Import dynamically
const { PanClient } = await import(clientPath);

// Or use the global helper
const resolved = window.larcResolve('@larc/core', 'components/pan-bus.mjs');

Events Reference

Event Flow

Component                    Bus                      Component
    |                        |                           |
    |-- pan:publish -------->|                           |
    |                        |-- pan:deliver ----------->|
    |                        |                           |
    |-- pan:subscribe ------>|                           |
    |                        |-- pan:deliver (retained)->|
    |                        |                           |
    |-- pan:request -------->|                           |
    |                        |-- pan:deliver ----------->|
    |                        |<- pan:reply --------------|
    |<- pan:deliver ---------|                           |

Event Summary

| Event | Direction | Purpose | |-------|-----------|---------| | pan:publish | Component → Bus | Publish a message | | pan:subscribe | Component → Bus | Subscribe to topics | | pan:unsubscribe | Component → Bus | Unsubscribe from topics | | pan:deliver | Bus → Component | Deliver message to subscriber | | pan:request | Component → Bus | Send request (signals reply expected) | | pan:reply | Component → Bus | Send reply to request | | pan:hello | Component → Bus | Announce presence | | pan:sys.ready | Bus → Document | Bus is ready | | pan:sys.stats | Component → Bus | Request statistics | | pan:sys.clear-retained | Component → Bus | Clear retained messages | | pan:sys.error | Bus → Document | Error occurred |

TypeScript Support

LARC includes comprehensive TypeScript definitions for all APIs.

Importing Types

import {
  PanClient,
  PanMessage,
  SubscribeOptions,
  RequestOptions
} from '/core/pan-client.mjs';

import {
  PanAutoloadConfig,
  maybeLoadFor,
  observeTree
} from '/core/pan.mjs';

import { PanBusEnhanced } from '/core/pan-bus.mjs';

Type Definitions

interface PanMessage<T = unknown> {
  topic: string;
  data: T;
  id?: string;
  ts?: number;
  retain?: boolean;
  replyTo?: string;
  correlationId?: string;
  headers?: Record<string, string>;
}

interface SubscribeOptions {
  retained?: boolean;
  signal?: AbortSignal;
}

interface RequestOptions {
  timeoutMs?: number;
}

interface PanAutoloadConfig {
  baseUrl?: string | null;
  componentsPath?: string;
  extension?: string;
  rootMargin?: number;
  resolvedComponentsPath?: string;
}

Generic Type Parameters

// Typed message data
interface User {
  id: number;
  name: string;
}

// Publish with type
client.publish<User>({
  topic: 'users.created',
  data: { id: 123, name: 'Alice' }
});

// Subscribe with type
client.subscribe<User>('users.*', (msg) => {
  // msg.data is typed as User
  console.log(msg.data.name);
});

// Request with types
interface UserRequest {
  id: number;
}

interface UserResponse {
  id: number;
  name: string;
  email: string;
}

const response = await client.request<UserRequest, UserResponse>(
  'users.get',
  { id: 123 }
);

// response.data is typed as UserResponse
console.log(response.data.email);

Component with TypeScript

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

interface TodoItem {
  id: number;
  text: string;
  completed: boolean;
}

interface TodoState {
  todos: TodoItem[];
}

class TodoListElement extends HTMLElement {
  private client: PanClient;
  private unsubscribe?: () => void;
  private todos: TodoItem[] = [];

  constructor() {
    super();
    this.client = new PanClient(this);
  }

  async connectedCallback(): Promise<void> {
    await this.client.ready();

    this.unsubscribe = this.client.subscribe<TodoState>(
      'todos.state',
      (msg) => this.handleState(msg),
      { retained: true }
    );

    this.render();
  }

  disconnectedCallback(): void {
    this.unsubscribe?.();
  }

  private handleState(msg: PanMessage<TodoState>): void {
    this.todos = msg.data.todos;
    this.render();
  }

  private addTodo(text: string): void {
    this.client.publish<Partial<TodoItem>>({
      topic: 'todos.add',
      data: { text, completed: false }
    });
  }

  private render(): void {
    // Render implementation
  }
}

customElements.define('todo-list', TodoListElement);

Best Practices

1. Always Wait for Bus Ready

// Good
async connectedCallback() {
  await this.client.ready();
  this.client.subscribe('topic', handler);
}

// Bad - may miss messages or fail
connectedCallback() {
  this.client.subscribe('topic', handler); // Bus might not be ready
}

2. Clean Up Subscriptions

// Good - cleanup in disconnectedCallback
class MyComponent extends HTMLElement {
  async connectedCallback() {
    await this.client.ready();
    this.unsubscribe = this.client.subscribe('topic', handler);
  }

  disconnectedCallback() {
    this.unsubscribe?.();
  }
}

// Or use AbortSignal for automatic cleanup
async connectedCallback() {
  const controller = new AbortController();
  this.client.subscribe('topic', handler, {
    signal: controller.signal
  });

  // Store controller to abort later
  this.abortController = controller;
}

disconnectedCallback() {
  this.abortController?.abort();
}

3. Use Retained Messages for State

// Good - use retained messages for state
client.publish({
  topic: 'users.list.state',
  data: { users: [...] },
  retain: true  // New subscribers get current state
});

// Subscribe with retained option to get current state
client.subscribe('users.list.state', handler, { retained: true });

4. Namespace Your Topics

// Good - clear hierarchy
'app.users.list.state'
'app.users.created'
'app.posts.updated'

// Bad - flat structure
'userList'
'newUser'
'updatePost'

5. Use Request/Reply for RPC

// Good - request/reply for RPC-style operations
const result = await client.request('users.get', { id: 123 });

// Bad - publish and hope for response
client.publish({ topic: 'users.get', data: { id: 123 } });
// No way to correlate response

6. Validate Message Data

// Good - validate incoming data
client.subscribe('users.*', (msg) => {
  if (!msg.data || typeof msg.data !== 'object') {
    console.error('Invalid message data');
    return;
  }

  const { id, name } = msg.data;
  if (!id || !name) {
    console.error('Missing required fields');
    return;
  }

  // Process valid data
  handleUser(msg.data);
});

7. Use Wildcards Wisely

// Good - specific wildcards
client.subscribe('users.*', handler);
client.subscribe('users.*.admin', handler);

// Careful - global wildcard receives ALL messages
client.subscribe('*', handler); // Only for debugging/monitoring

8. Handle Request Timeouts

// Good - handle timeouts gracefully
async function fetchUser(id) {
  try {
    const response = await client.request('users.get', { id }, {
      timeoutMs: 5000
    });
    return response.data;
  } catch (err) {
    if (err.message === 'PAN request timeout') {
      console.warn('Request timed out, using cached data');
      return getCachedUser(id);
    }
    throw err;
  }
}

9. Use Debug Mode During Development

<!-- Enable debug logging -->
<pan-bus debug="true"></pan-bus>

// Check bus statistics
document.dispatchEvent(new CustomEvent('pan:sys.stats', {
  bubbles: true,
  composed: true
}));

10. Organize Components by Feature

components/
  users/
    user-list.mjs
    user-detail.mjs
    user-form.mjs
  posts/
    post-list.mjs
    post-detail.mjs
  shared/
    loading-spinner.mjs
    error-message.mjs

Common Pitfalls

1. Forgetting to Wait for Bus Ready

// Wrong - bus might not be ready
class MyComponent extends HTMLElement {
  connectedCallback() {
    this.client.publish({ topic: 'test', data: {} }); // Might fail
  }
}

// Correct
class MyComponent extends HTMLElement {
  async connectedCallback() {
    await this.client.ready();
    this.client.publish({ topic: 'test', data: {} }); // Safe
  }
}

2. Memory Leaks from Uncleared Subscriptions

// Wrong - subscription never cleaned up
class MyComponent extends HTMLElement {
  connectedCallback() {
    this.client.subscribe('topic', handler); // Leaks!
  }
}

// Correct
class MyComponent extends HTMLElement {
  connectedCallback() {
    this.unsubscribe = this.client.subscribe('topic', handler);
  }

  disconnectedCallback() {
    this.unsubscribe();
  }
}

3. Publishing Non-Serializable Data

// Wrong - DOM nodes, functions, circular refs not allowed
client.publish({
  topic: 'test',
  data: {
    element: document.body,        // DOM node - fails
    callback: () => {},            // Function - fails
    circular: { ref: null }        // Circular ref - fails
  }
});

// Correct - use plain objects/arrays/primitives
client.publish({
  topic: 'test',
  data: {
    elementId: 'body',
    callbackName: 'handleClick',
    values: [1, 2, 3]
  }
});

4. Exceeding Message Size Limits

// Wrong - huge payload
client.publish({
  topic: 'test',
  data: hugeArray // > 512KB - rejected
});

// Correct - paginate or chunk data
const chunks = chunkArray(hugeArray, 100);
chunks.forEach((chunk, i) => {
  client.publish({
    topic: `test.chunk.${i}`,
    data: chunk
  });
});

5. Rate Limiting Issues

// Wrong - burst of messages
for (let i = 0; i < 10000; i++) {
  client.publish({ topic: 'test', data: i }); // Rate limited!
}

// Correct - batch or throttle
const batch = [];
for (let i = 0; i < 10000; i++) {
  batch.push(i);
  if (batch.length >= 100) {
    client.publish({ topic: 'test.batch', data: batch });
    batch.length = 0;
    await new Promise(resolve => setTimeout(resolve, 10));
  }
}

6. Not Handling Request Timeouts

// Wrong - uncaught timeout
async function getData() {
  const result = await client.request('data.get', {}); // Might timeout
  return result.data;
}

// Correct
async function getData() {
  try {
    const result = await client.request('data.get', {}, {
      timeoutMs: 5000
    });
    return result.data;
  } catch (err) {
    console.error('Request failed:', err);
    return null;
  }
}

7. Circular Message Loops

// Wrong - infinite loop
client.subscribe('test', (msg) => {
  // Don't publish the same topic you're subscribed to!
  client.publish({ topic: 'test', data: msg.data }); // Infinite loop!
});

// Correct - use different topics
client.subscribe('test.request', (msg) => {
  // Respond on different topic
  client.publish({ topic: 'test.response', data: process(msg.data) });
});

8. Incorrect Topic Patterns

// Wrong - patterns don't match
client.subscribe('users.*.admin', handler);
// Won't match: 'users.created' (only one segment after users)
// Won't match: 'users.list.admin.settings' (too many segments)

// Correct understanding
client.subscribe('users.*', handler);
// Matches: 'users.created', 'users.updated', 'users.deleted'
// Doesn't match: 'users.list.state' (two segments after users)

client.subscribe('users.*.*', handler);
// Matches: 'users.list.state', 'users.item.updated'

9. Missing Error Handlers

// Wrong - errors go unhandled
document.addEventListener('pan:sys.error', (e) => {
  // No handler - errors silent
});

// Correct - log or handle errors
document.addEventListener('pan:sys.error', (e) => {
  const { code, message, details } = e.detail;
  console.error(`Bus error [${code}]:`, message, details);

  // Show to user if needed
  if (code === 'RATE_LIMIT_EXCEEDED') {
    showNotification('Too many requests, please slow down');
  }
});

10. Not Using TypeScript Types

// Wrong - no type safety
const response = await client.request('users.get', { id: '123' }); // String instead of number
console.log(response.data.email); // Might not exist

// Correct - use TypeScript
interface UserRequest {
  id: number;
}

interface UserResponse {
  id: number;
  name: string;
  email: string;
}

const response = await client.request<UserRequest, UserResponse>(
  'users.get',
  { id: 123 } // Type checked
);

console.log(response.data.email); // Type safe

Additional Resources

• Repository: https://github.com/larcjs/larc
• Examples: /examples/ directory in the repository
• Quick Start: /docs/QUICK-START-CONFIG.md
• Browser Compatibility: /docs/BROWSER-COMPATIBILITY.md

License

LARC is open source. Check the repository for license information.