0
# Channel API
1

2
The Channel class provides the core event management functionality with support for multiple transport mechanisms. It implements an EventEmitter-like interface optimized for communication between different parts of the Storybook ecosystem.
3

4
## Capabilities
5

6
### Channel Class
7

8
The main class for managing events and transport communication.
9

10
```typescript { .api }
11
/**
12
 * Main channel class implementing EventEmitter-like interface
13
 * Supports single or multiple transports for flexible communication
14
 */
15
class Channel {
16
  /** Create a channel with single transport */
17
  constructor(input: ChannelArgsSingle);
18
  /** Create a channel with multiple transports */
19
  constructor(input: ChannelArgsMulti);
20
  
21
  /** Whether channel operates asynchronously */
22
  readonly isAsync: boolean;
23
  /** Whether channel has any transports configured */
24
  hasTransport: boolean;
25
}
26

27
interface ChannelArgsSingle {
28
  /** Single transport for communication */
29
  transport?: ChannelTransport;
30
  /** Whether to operate asynchronously */
31
  async?: boolean;
32
}
33

34
interface ChannelArgsMulti {
35
  /** Array of transports for communication */
36
  transports: ChannelTransport[];
37
  /** Whether to operate asynchronously */
38
  async?: boolean;
39
}
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import { Channel, PostMessageTransport } from "@storybook/channels";
46

47
// Single transport channel
48
const singleTransportChannel = new Channel({
49
  transport: new PostMessageTransport({ page: 'manager' }),
50
  async: true
51
});
52

53
// Multiple transport channel
54
const multiTransportChannel = new Channel({
55
  transports: [
56
    new PostMessageTransport({ page: 'manager' }),
57
    new WebsocketTransport({ url: 'ws://localhost:9001' })
58
  ]
59
});
60
```
61

62
### Event Listener Management
63

64
Methods for adding and removing event listeners.
65

66
```typescript { .api }
67
/**
68
 * Add event listener for the specified event name
69
 * @param eventName - Name of the event to listen for  
70
 * @param listener - Function to call when event is emitted
71
 */
72
addListener(eventName: string, listener: Listener): void;
73

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

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

88
/**
89
 * Remove specific event listener
90
 * @param eventName - Name of the event
91
 * @param listener - Specific listener function to remove
92
 */
93
removeListener(eventName: string, listener: Listener): void;
94

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

102
/**
103
 * Remove all listeners for specified event, or all listeners if no event specified
104
 * @param eventName - Optional event name, removes all listeners if omitted
105
 */
106
removeAllListeners(eventName?: string): void;
107
```
108

109
**Usage Examples:**
110

111
```typescript
112
const channel = new Channel({ transport: new PostMessageTransport({ page: 'manager' }) });
113

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

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

122
// Remove listeners
123
channel.removeListener('story-changed', storyListener);
124
channel.removeAllListeners('story-selected');
125
channel.removeAllListeners(); // Remove all listeners
126
```
127

128
### Event Emission
129

130
Methods for emitting events to listeners and transports.
131

132
```typescript { .api }
133
/**
134
 * Emit event to all listeners and transports
135
 * @param eventName - Name of the event to emit
136
 * @param args - Arguments to pass to event listeners
137
 */
138
emit(eventName: string, ...args: any): void;
139

140
/**
141
 * Get last emitted data for the specified event
142
 * @param eventName - Name of the event
143
 * @returns Last emitted data or undefined if no data
144
 */
145
last(eventName: string): any;
146
```
147

148
**Usage Examples:**
149

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

155
// Get last emitted data
156
const lastStoryData = channel.last('story-changed');
157
if (lastStoryData) {
158
  console.log('Last story:', lastStoryData.storyId);
159
}
160
```
161

162
### Event Introspection
163

164
Methods for inspecting the current state of event listeners.
165

166
```typescript { .api }
167
/**
168
 * Get array of event names that have listeners
169
 * @returns Array of event names with registered listeners
170
 */
171
eventNames(): string[];
172

173
/**
174
 * Count the number of listeners for specified event
175
 * @param eventName - Name of the event
176
 * @returns Number of listeners registered for the event
177
 */
178
listenerCount(eventName: string): number;
179

180
/**
181
 * Get array of listeners for specified event
182
 * @param eventName - Name of the event
183
 * @returns Array of listener functions or undefined if no listeners
184
 */
185
listeners(eventName: string): Listener[] | undefined;
186
```
187

188
**Usage Examples:**
189

190
```typescript
191
// Inspect event state
192
const eventNames = channel.eventNames(); // ['story-changed', 'story-selected']
193
const storyListenerCount = channel.listenerCount('story-changed'); // 2
194
const storyListeners = channel.listeners('story-changed'); // [function, function]
195

196
// Check if event has listeners
197
if (channel.listenerCount('custom-event') > 0) {
198
  channel.emit('custom-event', data);
199
}
200
```
201

202
## Type Definitions
203

204
```typescript { .api }
205
/**
206
 * Interface for event listener functions
207
 * @param args - Variable arguments passed from emit calls
208
 */
209
interface Listener {
210
  (...args: any[]): void;
211
}
212

213
/**
214
 * Map of event names to arrays of listener functions
215
 */
216
interface EventsKeyValue {
217
  [key: string]: Listener[];
218
}
219
```