0
# Event Management
1

2
Core event handling system for native module events with automatic listener lifecycle management and cross-platform compatibility.
3

4
## Capabilities
5

6
### EventEmitter Class
7

8
Provides event emitter functionality for native modules with automatic listener management and native module lifecycle handling.
9

10
```typescript { .api }
11
/**
12
 * Event emitter for native module events with automatic listener management
13
 */
14
class EventEmitter {
15
  /**
16
   * Create an event emitter for a native module
17
   * @param nativeModule - The native module to create events for
18
   */
19
  constructor(nativeModule: NativeModule);
20
  
21
  /**
22
   * Add a listener for the specified event
23
   * @param eventName - Name of the event to listen for
24
   * @param listener - Function to call when event is emitted
25
   * @returns Subscription object with remove method
26
   */
27
  addListener<T>(eventName: string, listener: (event: T) => void): Subscription;
28
  
29
  /**
30
   * Remove all listeners for the specified event
31
   * @param eventName - Name of the event to remove listeners for
32
   */
33
  removeAllListeners(eventName: string): void;
34
  
35
  /**
36
   * Remove a specific subscription
37
   * @param subscription - The subscription to remove
38
   */
39
  removeSubscription(subscription: Subscription): void;
40
  
41
  /**
42
   * Emit an event to all listeners
43
   * @param eventName - Name of the event to emit
44
   * @param params - Parameters to pass to listeners
45
   */
46
  emit(eventName: string, ...params: any[]): void;
47
}
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
import { EventEmitter } from "@unimodules/core";
54

55
// Create event emitter for a native module
56
const myModule = NativeModulesProxy.MyModule;
57
const eventEmitter = new EventEmitter(myModule);
58

59
// Add event listener
60
const subscription = eventEmitter.addListener('dataReceived', (data) => {
61
  console.log('Received data:', data);
62
});
63

64
// Add typed event listener
65
interface LocationData { latitude: number; longitude: number; }
66
const locationSubscription = eventEmitter.addListener<LocationData>('locationUpdate', (location) => {
67
  console.log(`Location: ${location.latitude}, ${location.longitude}`);
68
});
69

70
// Remove specific listener
71
subscription.remove();
72

73
// Remove all listeners for an event
74
eventEmitter.removeAllListeners('dataReceived');
75

76
// Emit custom events
77
eventEmitter.emit('customEvent', { message: 'Hello world' });
78
```
79

80
### Subscription Interface
81

82
Represents an active event listener subscription with cleanup functionality.
83

84
```typescript { .api }
85
/**
86
 * Represents an active event listener subscription
87
 */
88
interface Subscription {
89
  /**
90
   * Remove this subscription and stop receiving events
91
   */
92
  remove: () => void;
93
}
94
```
95

96
### DeviceEventEmitter (Re-exported)
97

98
React Native's device event emitter, re-exported for convenience.
99

100
```typescript { .api }
101
/**
102
 * React Native's device event emitter for system-level events
103
 */
104
const DeviceEventEmitter: DeviceEventEmitterStatic;
105
```
106

107
**Usage Examples:**
108

109
```typescript
110
import { DeviceEventEmitter } from "@unimodules/core";
111

112
// Listen to system events
113
const keyboardSubscription = DeviceEventEmitter.addListener('keyboardDidShow', (event) => {
114
  console.log('Keyboard height:', event.endCoordinates.height);
115
});
116

117
// Clean up
118
keyboardSubscription.remove();
119
```
120

121
### Legacy Compatibility
122

123
For backward compatibility with older code.
124

125
```typescript { .api }
126
/**
127
 * @deprecated Use DeviceEventEmitter instead
128
 */
129
const RCTDeviceEventEmitter: DeviceEventEmitterStatic;
130
```
131

132
## Advanced Usage
133

134
### Automatic Native Module Lifecycle
135

136
The EventEmitter automatically manages native module observation lifecycle:
137

138
```typescript
139
import { EventEmitter } from "@unimodules/core";
140

141
const sensorModule = NativeModulesProxy.Accelerometer;
142
const eventEmitter = new EventEmitter(sensorModule);
143

144
// First listener automatically calls startObserving() on Android
145
const subscription1 = eventEmitter.addListener('accelerometerData', handleData);
146

147
// Additional listeners don't trigger additional startObserving calls
148
const subscription2 = eventEmitter.addListener('accelerometerData', handleOtherData);
149

150
// Removing last listener automatically calls stopObserving() on Android
151
subscription1.remove();
152
subscription2.remove(); // This triggers stopObserving()
153
```
154

155
### Error Handling
156

157
```typescript
158
import { EventEmitter, CodedError } from "@unimodules/core";
159

160
const eventEmitter = new EventEmitter(someModule);
161

162
try {
163
  const subscription = eventEmitter.addListener('eventName', (data) => {
164
    if (data.error) {
165
      throw new CodedError('EVENT_ERROR', `Event processing failed: ${data.error}`);
166
    }
167
    // Process data
168
  });
169
} catch (error) {
170
  if (error instanceof CodedError) {
171
    console.error(`Error ${error.code}: ${error.message}`);
172
  }
173
}
174
```
175

176
## Types
177

178
```typescript { .api }
179
interface NativeModule {
180
  startObserving?: () => void;
181
  stopObserving?: () => void;
182
  addListener: (eventName: string) => void;
183
  removeListeners: (count: number) => void;
184
}
185

186
type EventListener<T> = (event: T) => void;
187
```