0
# Utilities
1

2
Additional utility functions and event emitters for API deprecation management and platform-specific event handling.
3

4
## Capabilities
5

6
### deprecate Function
7

8
Utility function for deprecating APIs with version-based error throwing and comprehensive warning management.
9

10
```typescript { .api }
11
/**
12
 * Used for deprecating values and throwing an error if a given version of Expo has passed
13
 * @param library - Library name for error prefixing
14
 * @param deprecatedAPI - Name of the deprecated API
15
 * @param options - Deprecation configuration options
16
 */
17
function deprecate(
18
  library: string,
19
  deprecatedAPI: string,
20
  options?: {
21
    replacement?: string;
22
    currentVersion?: string;
23
    versionToRemove?: string;
24
  }
25
): void;
26
```
27

28
**Usage Examples:**
29

30
```typescript
31
import { deprecate } from "@unimodules/core";
32

33
// Basic deprecation warning
34
function oldFunction() {
35
  deprecate('MyLibrary', 'oldFunction', {
36
    replacement: 'newFunction'
37
  });
38
  
39
  // Original implementation
40
  return 'old result';
41
}
42

43
// Version-based deprecation with removal
44
function deprecatedAPI() {
45
  deprecate('ExpoCamera', 'takePicture', {
46
    replacement: 'takePictureAsync',
47
    currentVersion: '10.0.0',
48
    versionToRemove: '11.0.0'
49
  });
50
  
51
  // This will throw an error if current version >= version to remove
52
}
53

54
// Deprecation without replacement
55
function removedAPI() {
56
  deprecate('ExpoSensors', 'DeviceMotion.addListener', {
57
    currentVersion: '12.0.0',
58
    versionToRemove: '12.0.0'
59
  });
60
  // This will throw a CodedError with code 'ERR_DEPRECATED_API'
61
}
62
```
63

64
### Advanced Deprecation Patterns
65

66
```typescript
67
import { deprecate, CodedError } from "@unimodules/core";
68

69
class APIManager {
70
  static warnDeprecated(apiName: string, replacement?: string) {
71
    try {
72
      deprecate('APIManager', apiName, {
73
        replacement,
74
        currentVersion: '1.0.0',
75
        versionToRemove: '2.0.0'
76
      });
77
    } catch (error) {
78
      if (error instanceof CodedError && error.code === 'ERR_DEPRECATED_API') {
79
        console.error(`API removed: ${error.message}`);
80
        throw error;
81
      }
82
    }
83
  }
84
  
85
  static conditionalDeprecate(condition: boolean, apiName: string) {
86
    if (condition) {
87
      deprecate('APIManager', apiName, {
88
        replacement: `${apiName}Async`,
89
        currentVersion: '3.0.0'
90
      });
91
    }
92
  }
93
}
94
```
95

96
### SyntheticPlatformEmitter Object
97

98
Platform-specific event emitter for synthetic events that don't originate from native modules.
99

100
```typescript { .api }
101
/**
102
 * Event emitter for platform-specific synthetic events
103
 */
104
const SyntheticPlatformEmitter: EventEmitter;
105
```
106

107
**Usage Examples:**
108

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

112
// Listen to synthetic platform events
113
const subscription = SyntheticPlatformEmitter.addListener('customEvent', (data) => {
114
  console.log('Received synthetic event:', data);
115
});
116

117
// Emit synthetic events
118
SyntheticPlatformEmitter.emit('customEvent', { 
119
  message: 'Hello from synthetic emitter' 
120
});
121

122
// Clean up
123
subscription.remove();
124
```
125

126
### DeviceEventEmitter (Re-exported)
127

128
React Native's device event emitter, re-exported for convenience and compatibility.
129

130
```typescript { .api }
131
/**
132
 * React Native's device event emitter for system-level events
133
 * Re-exported from react-native for convenience
134
 */
135
const DeviceEventEmitter: DeviceEventEmitterStatic;
136

137
/**
138
 * @deprecated Use DeviceEventEmitter instead
139
 * Legacy alias maintained for backward compatibility
140
 */
141
const RCTDeviceEventEmitter: DeviceEventEmitterStatic;
142
```
143

144
**Usage Examples:**
145

146
```typescript
147
import { DeviceEventEmitter, RCTDeviceEventEmitter } from "@unimodules/core";
148

149
// Modern usage
150
const keyboardSubscription = DeviceEventEmitter.addListener('keyboardDidShow', (event) => {
151
  console.log('Keyboard height:', event.endCoordinates.height);
152
});
153

154
// Legacy usage (deprecated but still works)
155
const oldSubscription = RCTDeviceEventEmitter.addListener('keyboardDidHide', () => {
156
  console.log('Keyboard hidden');
157
});
158

159
// Clean up
160
keyboardSubscription.remove();
161
oldSubscription.remove();
162
```
163

164
## Advanced Usage
165

166
### Custom Event Emitter Patterns
167

168
```typescript
169
import { SyntheticPlatformEmitter, EventEmitter } from "@unimodules/core";
170

171
class CustomEventManager {
172
  private static eventQueue: Array<{ name: string; data: any }> = [];
173
  private static isReady = false;
174
  
175
  static emit(eventName: string, data: any) {
176
    if (this.isReady) {
177
      SyntheticPlatformEmitter.emit(eventName, data);
178
    } else {
179
      // Queue events until ready
180
      this.eventQueue.push({ name: eventName, data });
181
    }
182
  }
183
  
184
  static setReady() {
185
    this.isReady = true;
186
    // Flush queued events
187
    this.eventQueue.forEach(({ name, data }) => {
188
      SyntheticPlatformEmitter.emit(name, data);
189
    });
190
    this.eventQueue = [];
191
  }
192
  
193
  static listen(eventName: string, callback: (data: any) => void) {
194
    return SyntheticPlatformEmitter.addListener(eventName, callback);
195
  }
196
}
197
```
198

199
### Deprecation Warning Management
200

201
```typescript
202
import { deprecate } from "@unimodules/core";
203

204
class DeprecationManager {
205
  private static warnedAPIs = new Set<string>();
206
  
207
  static warnOnce(library: string, api: string, options: any = {}) {
208
    const key = `${library}.${api}`;
209
    if (!this.warnedAPIs.has(key)) {
210
      this.warnedAPIs.add(key);
211
      deprecate(library, api, options);
212
    }
213
  }
214
  
215
  static resetWarnings() {
216
    this.warnedAPIs.clear();
217
  }
218
  
219
  static getWarnedAPIs() {
220
    return Array.from(this.warnedAPIs);
221
  }
222
}
223

224
// Usage
225
DeprecationManager.warnOnce('MyModule', 'oldMethod', {
226
  replacement: 'newMethod'
227
});
228
```
229

230
### Event Emitter Factory
231

232
```typescript
233
import { EventEmitter, SyntheticPlatformEmitter } from "@unimodules/core";
234

235
function createEventEmitter(namespace: string) {
236
  return {
237
    emit: (eventName: string, data: any) => {
238
      SyntheticPlatformEmitter.emit(`${namespace}:${eventName}`, data);
239
    },
240
    
241
    addListener: (eventName: string, listener: (data: any) => void) => {
242
      return SyntheticPlatformEmitter.addListener(`${namespace}:${eventName}`, listener);
243
    },
244
    
245
    removeAllListeners: (eventName: string) => {
246
      SyntheticPlatformEmitter.removeAllListeners(`${namespace}:${eventName}`);
247
    }
248
  };
249
}
250

251
// Usage
252
const myEmitter = createEventEmitter('MyModule');
253
const subscription = myEmitter.addListener('dataUpdate', (data) => {
254
  console.log('Module data:', data);
255
});
256

257
myEmitter.emit('dataUpdate', { value: 42 });
258
```
259

260
## Types
261

262
```typescript { .api }
263
interface DeprecateOptions {
264
  replacement?: string;
265
  currentVersion?: string;
266
  versionToRemove?: string;
267
}
268

269
interface DeviceEventEmitterStatic {
270
  addListener: (eventType: string, listener: (data: any) => void) => { remove: () => void };
271
  emit: (eventType: string, ...args: any[]) => void;
272
  removeAllListeners: (eventType: string) => void;
273
}
274
```