0
# Event System
1

2
Type-safe event emitter implementation with support for wildcard listeners and strongly-typed event payloads. Forked from the mitt library with TypeScript enhancements.
3

4
## Capabilities
5

6
### Event Emitter Creation
7

8
Create a new event emitter instance with type-safe event handling.
9

10
```typescript { .api }
11
/**
12
 * Create a type-safe event emitter
13
 * @returns Event emitter instance with on/off/emit methods
14
 */
15
function createEmitter<Events extends Record<EventType, unknown>>(): Emittable<Events>;
16
```
17

18
**Usage Example:**
19

20
```typescript
21
import { createEmitter, type Emittable } from "@intlify/shared";
22

23
// Define event types
24
interface MyEvents {
25
  userLogin: { userId: string; timestamp: number };
26
  userLogout: { userId: string };
27
  dataUpdate: { data: any[] };
28
}
29

30
// Create typed emitter
31
const emitter = createEmitter<MyEvents>();
32

33
// Type-safe event handling
34
emitter.on("userLogin", (payload) => {
35
  // payload is automatically typed as { userId: string; timestamp: number }
36
  console.log(`User ${payload?.userId} logged in at ${payload?.timestamp}`);
37
});
38

39
emitter.emit("userLogin", { userId: "123", timestamp: Date.now() });
40
```
41

42
### Event Registration
43

44
Register event handlers for specific events or all events using wildcard.
45

46
```typescript { .api }
47
/**
48
 * Register an event handler for specific event type
49
 * @param event - Event name or "*" for wildcard
50
 * @param handler - Event handler function
51
 */
52
on<Key extends keyof Events>(
53
  event: Key | '*',
54
  handler: EventHandler<Events[Key]> | WildcardEventHandler<Events>
55
): void;
56
```
57

58
**Usage Examples:**
59

60
```typescript
61
import { createEmitter } from "@intlify/shared";
62

63
interface AppEvents {
64
  error: { message: string; code: number };
65
  success: { message: string };
66
}
67

68
const emitter = createEmitter<AppEvents>();
69

70
// Register specific event handler
71
emitter.on("error", (payload) => {
72
  console.error(`Error ${payload?.code}: ${payload?.message}`);
73
});
74

75
// Register wildcard handler for all events
76
emitter.on("*", (eventName, payload) => {
77
  console.log(`Event ${String(eventName)} fired:`, payload);
78
});
79
```
80

81
### Event Deregistration
82

83
Remove event handlers for specific events or wildcard handlers.
84

85
```typescript { .api }
86
/**
87
 * Remove an event handler for specific event type
88
 * @param event - Event name or "*" for wildcard
89
 * @param handler - Event handler function to remove
90
 */
91
off<Key extends keyof Events>(
92
  event: Key | '*',
93
  handler: EventHandler<Events[Key]> | WildcardEventHandler<Events>
94
): void;
95
```
96

97
**Usage Example:**
98

99
```typescript
100
import { createEmitter } from "@intlify/shared";
101

102
const emitter = createEmitter<{ test: string }>();
103

104
const handler = (payload?: string) => {
105
  console.log("Received:", payload);
106
};
107

108
// Register handler
109
emitter.on("test", handler);
110

111
// Later, remove the same handler
112
emitter.off("test", handler);
113
```
114

115
### Event Emission
116

117
Emit events to trigger all registered handlers.
118

119
```typescript { .api }
120
/**
121
 * Emit an event to trigger all registered handlers
122
 * @param event - Event name to emit
123
 * @param payload - Optional event payload
124
 */
125
emit<Key extends keyof Events>(
126
  event: Key,
127
  payload?: Events[Key]
128
): void;
129
```
130

131
**Usage Example:**
132

133
```typescript
134
import { createEmitter } from "@intlify/shared";
135

136
interface NotificationEvents {
137
  notification: { 
138
    title: string; 
139
    body: string; 
140
    type: "info" | "warning" | "error" 
141
  };
142
}
143

144
const emitter = createEmitter<NotificationEvents>();
145

146
emitter.on("notification", (payload) => {
147
  if (payload) {
148
    showNotification(payload.title, payload.body, payload.type);
149
  }
150
});
151

152
// Emit notification event
153
emitter.emit("notification", {
154
  title: "Update Available",
155
  body: "A new version is available for download",
156
  type: "info"
157
});
158
```
159

160
## Core Types
161

162
### Event Type Definition
163

164
```typescript { .api }
165
/**
166
 * Valid event identifier types
167
 */
168
type EventType = string | symbol;
169
```
170

171
### Event Handler Types  
172

173
```typescript { .api }
174
/**
175
 * Standard event handler function
176
 */
177
type EventHandler<T = unknown> = (payload?: T) => void;
178

179
/**
180
 * Wildcard event handler that receives event name and payload
181
 */
182
type WildcardEventHandler<T = Record<string, unknown>> = (
183
  event: keyof T,
184
  payload?: T[keyof T]
185
) => void;
186
```
187

188
### Event Handler Collections
189

190
```typescript { .api }
191
/**
192
 * Array of event handlers for a specific event
193
 */
194
type EventHandlerList<T = unknown> = Array<EventHandler<T>>;
195

196
/**
197
 * Array of wildcard event handlers
198
 */
199
type WildcardEventHandlerList<T = Record<string, unknown>> = Array<
200
  WildcardEventHandler<T>
201
>;
202

203
/**
204
 * Map storing all event handlers by event name
205
 */
206
type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<
207
  keyof Events | '*',
208
  EventHandlerList<Events[keyof Events]> | WildcardEventHandlerList<Events>
209
>;
210
```
211

212
### Emittable Interface
213

214
```typescript { .api }
215
/**
216
 * Core event emitter interface with type safety
217
 */
218
interface Emittable<Events extends Record<EventType, unknown> = {}> {
219
  /**
220
   * Map of registered event handlers by event name
221
   */
222
  events: EventHandlerMap<Events>;
223

224
  /**
225
   * Register an event handler
226
   * @param event - Event name or "*" for wildcard
227
   * @param handler - Handler function
228
   */
229
  on<Key extends keyof Events>(
230
    event: Key | '*',
231
    handler: EventHandler<Events[Key]> | WildcardEventHandler<Events>
232
  ): void;
233

234
  /**
235
   * Remove an event handler
236
   * @param event - Event name or "*" for wildcard  
237
   * @param handler - Handler function to remove
238
   */
239
  off<Key extends keyof Events>(
240
    event: Key | '*',
241
    handler: EventHandler<Events[Key]> | WildcardEventHandler<Events>
242
  ): void;
243

244
  /**
245
   * Emit an event to all registered handlers
246
   * @param event - Event name to emit
247
   * @param payload - Event payload
248
   */
249
  emit<Key extends keyof Events>(
250
    event: Key,
251
    payload?: Events[Key]
252
  ): void;
253
}
254
```
255

256
## Advanced Usage
257

258
### Multiple Handlers
259

260
```typescript
261
import { createEmitter } from "@intlify/shared";
262

263
interface LogEvents {
264
  log: { level: string; message: string; timestamp: number };
265
}
266

267
const logger = createEmitter<LogEvents>();
268

269
// Multiple handlers for same event
270
logger.on("log", (payload) => {
271
  console.log(`[${payload?.level}] ${payload?.message}`);
272
});
273

274
logger.on("log", (payload) => {
275
  if (payload?.level === "error") {
276
    sendToErrorReporting(payload);
277
  }
278
});
279

280
// Wildcard logger
281
logger.on("*", (eventName, payload) => {
282
  saveToDatabase(String(eventName), payload);
283
});
284
```
285

286
### Handler Cleanup
287

288
```typescript
289
import { createEmitter } from "@intlify/shared";
290

291
const emitter = createEmitter<{ cleanup: void }>();
292

293
// Store handler reference for later cleanup
294
const cleanupHandler = () => {
295
  console.log("Cleaning up resources");
296
};
297

298
emitter.on("cleanup", cleanupHandler);
299

300
// Later, remove handler to prevent memory leaks
301
emitter.off("cleanup", cleanupHandler);
302
```