0
# @unimodules/core
1

2
@unimodules/core is a deprecated compatibility wrapper that provides backward compatibility for applications migrating from the legacy Unimodules infrastructure to the newer Expo Modules API. It serves as a bridge between old @unimodules/core architecture and modern expo-modules-core system, allowing existing React Native applications to continue functioning during migration.
3

4
⚠️ **Deprecation Notice**: This package is deprecated in favor of the `expo` package. Applications should migrate using the guide at https://expo.fyi/expo-modules-migration
5

6
## Package Information
7

8
- **Package Name**: @unimodules/core
9
- **Package Type**: npm
10
- **Language**: TypeScript
11
- **Installation**: `npm install @unimodules/core`
12
- **Main Dependency**: expo-modules-core ~0.4.0
13

14
## Core Imports
15

16
```typescript
17
import { 
18
  EventEmitter, 
19
  NativeModulesProxy, 
20
  Platform,
21
  requireNativeViewManager,
22
  CodedError,
23
  UnavailabilityError,
24
  DeviceEventEmitter,
25
  Subscription,
26
  SyntheticPlatformEmitter,
27
  ProxyNativeModule,
28
  deprecate,
29
  // Permission system
30
  PermissionStatus,
31
  PermissionResponse,
32
  createPermissionHook
33
} from "@unimodules/core";
34
```
35

36
For CommonJS:
37

38
```javascript
39
const { 
40
  EventEmitter, 
41
  NativeModulesProxy, 
42
  Platform,
43
  requireNativeViewManager,
44
  CodedError,
45
  UnavailabilityError,
46
  DeviceEventEmitter,
47
  Subscription,
48
  SyntheticPlatformEmitter,
49
  ProxyNativeModule,
50
  deprecate,
51
  PermissionStatus,
52
  PermissionResponse,
53
  createPermissionHook
54
} = require("@unimodules/core");
55
```
56

57
## Basic Usage
58

59
```typescript
60
import { 
61
  EventEmitter, 
62
  NativeModulesProxy, 
63
  Platform,
64
  CodedError 
65
} from "@unimodules/core";
66

67
// Platform detection
68
if (Platform.OS === 'ios') {
69
  console.log('Running on iOS');
70
}
71

72
// Access native modules
73
const MyNativeModule = NativeModulesProxy.MyModule;
74
if (MyNativeModule) {
75
  await MyNativeModule.someMethod();
76
}
77

78
// Event handling
79
const eventEmitter = new EventEmitter(MyNativeModule);
80
const subscription = eventEmitter.addListener('eventName', (data) => {
81
  console.log('Received event:', data);
82
});
83

84
// Clean up
85
subscription.remove();
86
```
87

88
## Architecture
89

90
@unimodules/core provides essential infrastructure for React Native/Expo module development:
91

92
- **Module Proxy System**: `NativeModulesProxy` provides dynamic access to native modules
93
- **Event System**: `EventEmitter` handles native-to-JavaScript event communication  
94
- **Platform Utilities**: Extended platform detection and capability checking
95
- **View Integration**: `requireNativeViewManager` for native UI components
96
- **Error Handling**: Standardized error classes with error codes
97
- **Permission System**: Complete permission management with React hooks
98

99
## Capabilities
100

101
### Event Management
102

103
Core event handling system for native module events with automatic listener lifecycle management.
104

105
```typescript { .api }
106
class EventEmitter {
107
  constructor(nativeModule: NativeModule);
108
  addListener<T>(eventName: string, listener: (event: T) => void): Subscription;
109
  removeAllListeners(eventName: string): void;
110
  removeSubscription(subscription: Subscription): void;
111
  emit(eventName: string, ...params: any[]): void;
112
}
113

114
interface Subscription {
115
  remove: () => void;
116
}
117
```
118

119
[Event Management](./event-management.md)
120

121
### Native Module Access
122

123
Proxy system providing dynamic access to native modules with automatic method binding and error handling.
124

125
```typescript { .api }
126
const NativeModulesProxy: { [moduleName: string]: ProxyNativeModule };
127

128
interface ProxyNativeModule {
129
  [propertyName: string]: any;
130
  addListener: (eventName: string) => void;
131
  removeListeners: (count: number) => void;
132
}
133
```
134

135
[Native Module Access](./native-modules.md)
136

137
### Platform Utilities
138

139
Extended platform detection and capability checking beyond React Native's built-in Platform.
140

141
```typescript { .api }
142
interface PlatformInterface {
143
  OS: PlatformOSType;
144
  select: <T>(specifics: { [platform in PlatformSelectOSType]?: T }) => T;
145
  isDOMAvailable: boolean;
146
  canUseEventListeners: boolean;
147
  canUseViewport: boolean;
148
  isAsyncDebugging: boolean;
149
}
150

151
const Platform: PlatformInterface;
152
```
153

154
[Platform Utilities](./platform-utilities.md)
155

156
### Error Handling
157

158
Standardized error classes for consistent error handling across Expo modules.
159

160
```typescript { .api }
161
class CodedError extends Error {
162
  code: string;
163
  info?: any;
164
  constructor(code: string, message: string);
165
}
166

167
class UnavailabilityError extends CodedError {
168
  constructor(moduleName: string, propertyName: string);
169
}
170
```
171

172
[Error Handling](./error-handling.md)
173

174
### Permission Management
175

176
Complete permission system with React hooks for managing app permissions.
177

178
```typescript { .api }
179
enum PermissionStatus {
180
  GRANTED = 'granted',
181
  UNDETERMINED = 'undetermined',
182
  DENIED = 'denied'
183
}
184

185
interface PermissionResponse {
186
  status: PermissionStatus;
187
  expires: PermissionExpiration;
188
  granted: boolean;
189
  canAskAgain: boolean;
190
}
191

192
function createPermissionHook<Permission extends PermissionResponse, Options extends object>(
193
  methods: PermissionHookMethods<Permission, Options>
194
): (options?: PermissionHookOptions<Options>) => [Permission | null, () => Promise<Permission>, () => Promise<Permission>];
195
```
196

197
[Permission Management](./permissions.md)
198

199
### Native View Integration
200

201
Component creation utilities for integrating native UI components into React Native applications.
202

203
```typescript { .api }
204
function requireNativeViewManager<P = any>(viewName: string): React.ComponentType<P>;
205
```
206

207
[Native View Integration](./native-views.md)
208

209
### Utilities
210

211
API deprecation utilities and additional event emitters for platform-specific functionality.
212

213
```typescript { .api }
214
function deprecate(
215
  library: string, 
216
  deprecatedAPI: string, 
217
  options?: {
218
    replacement?: string;
219
    currentVersion?: string;
220
    versionToRemove?: string;
221
  }
222
): void;
223

224
const SyntheticPlatformEmitter: EventEmitter;
225
const DeviceEventEmitter: DeviceEventEmitterStatic;
226
const RCTDeviceEventEmitter: DeviceEventEmitterStatic; // @deprecated Use DeviceEventEmitter
227
```
228

229
[Utilities](./utilities.md)
230

231
## Types
232

233
```typescript { .api }
234
type PlatformOSType = 'ios' | 'android' | 'windows' | 'macos' | 'web';
235
type PlatformSelectOSType = PlatformOSType | 'native' | 'electron' | 'default';
236
type PlatformSelect = <T>(specifics: { [platform in PlatformSelectOSType]?: T }) => T;
237
type PermissionExpiration = 'never' | number;
238

239
interface NativeModule {
240
  startObserving?: () => void;
241
  stopObserving?: () => void;
242
  addListener: (eventName: string) => void;
243
  removeListeners: (count: number) => void;
244
}
245

246
interface Subscription {
247
  remove: () => void;
248
}
249

250
interface ProxyNativeModule {
251
  [propertyName: string]: any;
252
  addListener: (eventName: string) => void;
253
  removeListeners: (count: number) => void;
254
}
255

256
interface DeviceEventEmitterStatic {
257
  addListener: (eventType: string, listener: (data: any) => void) => { remove: () => void };
258
  emit: (eventType: string, ...args: any[]) => void;
259
  removeAllListeners: (eventType: string) => void;
260
}
261
```