Channel API

/**
 * Main channel class implementing EventEmitter-like interface
 * Supports single or multiple transports for flexible communication
 */
class Channel {
  /** Create a channel with single transport */
  constructor(input: ChannelArgsSingle);
  /** Create a channel with multiple transports */
  constructor(input: ChannelArgsMulti);
  
  /** Whether channel operates asynchronously */
  readonly isAsync: boolean;
  /** Whether channel has any transports configured */
  hasTransport: boolean;
}

interface ChannelArgsSingle {
  /** Single transport for communication */
  transport?: ChannelTransport;
  /** Whether to operate asynchronously */
  async?: boolean;
}

interface ChannelArgsMulti {
  /** Array of transports for communication */
  transports: ChannelTransport[];
  /** Whether to operate asynchronously */
  async?: boolean;
}

import { Channel, PostMessageTransport } from "@storybook/channels";

// Single transport channel
const singleTransportChannel = new Channel({
  transport: new PostMessageTransport({ page: 'manager' }),
  async: true
});

// Multiple transport channel
const multiTransportChannel = new Channel({
  transports: [
    new PostMessageTransport({ page: 'manager' }),
    new WebsocketTransport({ url: 'ws://localhost:9001' })
  ]
});

/**
 * Add event listener for the specified event name
 * @param eventName - Name of the event to listen for  
 * @param listener - Function to call when event is emitted
 */
addListener(eventName: string, listener: Listener): void;

/**
 * Alias for addListener - add event listener
 * @param eventName - Name of the event to listen for
 * @param listener - Function to call when event is emitted  
 */
on(eventName: string, listener: Listener): void;

/**
 * Add one-time event listener that removes itself after first call
 * @param eventName - Name of the event to listen for
 * @param listener - Function to call when event is emitted
 */
once(eventName: string, listener: Listener): void;

/**
 * Remove specific event listener
 * @param eventName - Name of the event
 * @param listener - Specific listener function to remove
 */
removeListener(eventName: string, listener: Listener): void;

/**
 * Alias for removeListener - remove specific event listener  
 * @param eventName - Name of the event
 * @param listener - Specific listener function to remove
 */
off(eventName: string, listener: Listener): void;

/**
 * Remove all listeners for specified event, or all listeners if no event specified
 * @param eventName - Optional event name, removes all listeners if omitted
 */
removeAllListeners(eventName?: string): void;

const channel = new Channel({ transport: new PostMessageTransport({ page: 'manager' }) });

// Add listeners
const storyListener = (data) => console.log('Story changed:', data);
channel.addListener('story-changed', storyListener);
channel.on('story-selected', (data) => console.log('Selected:', data));

// One-time listener
channel.once('app-ready', () => console.log('App is ready!'));

// Remove listeners
channel.removeListener('story-changed', storyListener);
channel.removeAllListeners('story-selected');
channel.removeAllListeners(); // Remove all listeners

/**
 * Emit event to all listeners and transports
 * @param eventName - Name of the event to emit
 * @param args - Arguments to pass to event listeners
 */
emit(eventName: string, ...args: any): void;

/**
 * Get last emitted data for the specified event
 * @param eventName - Name of the event
 * @returns Last emitted data or undefined if no data
 */
last(eventName: string): any;

// Emit events with data
channel.emit('story-changed', { storyId: 'example-story', parameters: {} });
channel.emit('error-occurred', { message: 'Something went wrong', code: 500 });

// Get last emitted data
const lastStoryData = channel.last('story-changed');
if (lastStoryData) {
  console.log('Last story:', lastStoryData.storyId);
}

/**
 * Get array of event names that have listeners
 * @returns Array of event names with registered listeners
 */
eventNames(): string[];

/**
 * Count the number of listeners for specified event
 * @param eventName - Name of the event
 * @returns Number of listeners registered for the event
 */
listenerCount(eventName: string): number;

/**
 * Get array of listeners for specified event
 * @param eventName - Name of the event
 * @returns Array of listener functions or undefined if no listeners
 */
listeners(eventName: string): Listener[] | undefined;

// Inspect event state
const eventNames = channel.eventNames(); // ['story-changed', 'story-selected']
const storyListenerCount = channel.listenerCount('story-changed'); // 2
const storyListeners = channel.listeners('story-changed'); // [function, function]

// Check if event has listeners
if (channel.listenerCount('custom-event') > 0) {
  channel.emit('custom-event', data);
}

/**
 * Interface for event listener functions
 * @param args - Variable arguments passed from emit calls
 */
interface Listener {
  (...args: any[]): void;
}

/**
 * Map of event names to arrays of listener functions
 */
interface EventsKeyValue {
  [key: string]: Listener[];
}