0
# Decorators
1

2
Ionic Native Core provides a comprehensive decorator system that transforms standard TypeScript methods into Promise/Observable patterns with automatic error handling, platform checking, and Cordova integration.
3

4
## Capabilities
5

6
### Plugin Class Decorator
7

8
```typescript { .api }
9
/**
10
 * Class decorator that configures plugin metadata
11
 * @param config - Plugin configuration object
12
 * @returns ClassDecorator
13
 */
14
function Plugin(config: PluginConfig): ClassDecorator;
15

16
interface PluginConfig {
17
  /** Plugin name, should match the class name */
18
  pluginName: string;
19
  /** Plugin NPM package name */
20
  plugin: string;
21
  /** Plugin object reference path (optional) */
22
  pluginRef?: string;
23
  /** GitHub repository URL (optional) */
24
  repo?: string;
25
  /** Custom install command (optional) */
26
  install?: string;
27
  /** Available installation variables (optional) */
28
  installVariables?: string[];
29
  /** Supported platforms (optional) */
30
  platforms?: string[];
31
  /** Additional configuration properties */
32
  [key: string]: any;
33
}
34
```
35

36
**Usage Example:**
37

38
```typescript
39
@Plugin({
40
  pluginName: "Camera",
41
  plugin: "cordova-plugin-camera",
42
  pluginRef: "navigator.camera",
43
  repo: "https://github.com/apache/cordova-plugin-camera",
44
  platforms: ["Android", "iOS", "Windows"],
45
  install: "ionic cordova plugin add cordova-plugin-camera"
46
})
47
export class Camera extends IonicNativePlugin {
48
  // Methods here
49
}
50
```
51

52
### Cordova Method Decorator
53

54
```typescript { .api }
55
/**
56
 * Method decorator for wrapping Cordova plugin methods
57
 * Automatically handles Promise/Observable conversion and error checking
58
 * @param config - Optional configuration for the method wrapper
59
 * @returns MethodDecorator
60
 */
61
function Cordova(config?: CordovaOptions): MethodDecorator;
62

63
interface CordovaOptions {
64
  /** Destructure callback arguments into an array */
65
  destruct?: boolean;
66
  /** Override the native method name if different from TypeScript method */
67
  methodName?: string;
68
  /** Mark the method as synchronous (no Promise wrapping) */
69
  sync?: boolean;
70
  /** Callback parameter order - set to "reverse" if success/error are first */
71
  callbackOrder?: "reverse";
72
  /** Callback style for different callback patterns */
73
  callbackStyle?: "node" | "object";
74
  /** Custom index for success callback */
75
  successIndex?: number;
76
  /** Custom index for error callback */
77
  errorIndex?: number;
78
  /** Success property name for object-style callbacks */
79
  successName?: string;
80
  /** Error property name for object-style callbacks */
81
  errorName?: string;
82
  /** Return an Observable instead of Promise */
83
  observable?: boolean;
84
  /** Method name to call for clearing/stopping Observable */
85
  clearFunction?: string;
86
  /** Call clear function with same arguments as original */
87
  clearWithArgs?: boolean;
88
  /** Create Observable from global event instead of plugin method */
89
  eventObservable?: boolean;
90
  /** Event name for event-based Observables */
91
  event?: string;
92
  /** Element to attach event listener to (defaults to window) */
93
  element?: any;
94
  /** Method returns a promise natively */
95
  otherPromise?: boolean;
96
  /** Platform restrictions for this method */
97
  platforms?: string[];
98
}
99
```
100

101
**Usage Examples:**
102

103
```typescript
104
export class Camera extends IonicNativePlugin {
105
  // Basic Promise method
106
  @Cordova()
107
  getPicture(options?: CameraOptions): Promise<string> {
108
    return;
109
  }
110
  
111
  // Observable method
112
  @Cordova({ observable: true })
113
  watchHeading(): Observable<CompassHeading> {
114
    return;
115
  }
116
  
117
  // Synchronous method
118
  @Cordova({ sync: true })
119
  getVersion(): string {
120
    return;
121
  }
122
  
123
  // Custom callback configuration
124
  @Cordova({
125
    callbackStyle: "object",
126
    successName: "onSuccess",
127
    errorName: "onError"
128
  })
129
  customMethod(options: any): Promise<any> {
130
    return;
131
  }
132
}
133
```
134

135
### Cordova Property Decorator
136

137
```typescript { .api }
138
/**
139
 * Property decorator for Cordova plugin properties
140
 * Provides getter/setter access to native plugin properties
141
 * @returns PropertyDecorator
142
 */
143
function CordovaProperty(): PropertyDecorator;
144
```
145

146
**Usage Example:**
147

148
```typescript
149
export class StatusBar extends IonicNativePlugin {
150
  @CordovaProperty()
151
  isVisible: boolean;
152
  
153
  // Usage: StatusBar.isVisible will get/set the native property
154
}
155
```
156

157
### Cordova Instance Decorator
158

159
```typescript { .api }
160
/**
161
 * Method decorator for plugin instance methods
162
 * Similar to @Cordova but operates on plugin object instances
163
 * @param config - Optional configuration for the instance method wrapper
164
 * @returns MethodDecorator
165
 */
166
function CordovaInstance(config?: CordovaOptions): MethodDecorator;
167
```
168

169
**Usage Example:**
170

171
```typescript
172
export class File extends IonicNativePlugin {
173
  private _objectInstance: any;
174
  
175
  @CordovaInstance()
176
  readAsText(path: string): Promise<string> {
177
    return;
178
  }
179
}
180
```
181

182
### Instance Property Decorator
183

184
```typescript { .api }
185
/**
186
 * Property decorator for plugin instance properties
187
 * Provides access to properties on the _objectInstance
188
 * @returns PropertyDecorator
189
 */
190
function InstanceProperty(): PropertyDecorator;
191
```
192

193
**Usage Example:**
194

195
```typescript
196
export class MediaObject extends IonicNativePlugin {
197
  private _objectInstance: any;
198
  
199
  @InstanceProperty()
200
  duration: number;
201
}
202
```
203

204
### Cordova Function Override Decorator
205

206
```typescript { .api }
207
/**
208
 * Method decorator that overrides a native function with an Observable
209
 * Useful for callback functions that need to be overridden
210
 * @returns MethodDecorator
211
 */
212
function CordovaFunctionOverride(): MethodDecorator;
213
```
214

215
**Usage Example:**
216

217
```typescript
218
export class BackgroundMode extends IonicNativePlugin {
219
  @CordovaFunctionOverride()
220
  onactivate(): Observable<any> {
221
    return;
222
  }
223
}
224
```
225

226
### Additional Decorators
227

228
```typescript { .api }
229
/**
230
 * Method decorator for checking availability before method execution
231
 * @param config - Optional configuration for availability checking
232
 * @returns MethodDecorator
233
 */
234
function CordovaCheck(config?: CordovaOptions): MethodDecorator;
235

236
/**
237
 * Method decorator for checking instance availability before method execution
238
 * @param config - Optional configuration for instance availability checking
239
 * @returns MethodDecorator
240
 */
241
function InstanceCheck(config?: CordovaOptions): MethodDecorator;
242
```
243

244
## Configuration Patterns
245

246
### Observable with Clear Function
247

248
For plugins that need cleanup when Observable is unsubscribed:
249

250
```typescript
251
@Cordova({
252
  observable: true,
253
  clearFunction: "clearWatch",
254
  clearWithArgs: true
255
})
256
watchPosition(): Observable<Geoposition> {
257
  return;
258
}
259
```
260

261
### Event-based Observable
262

263
For creating Observables from global events:
264

265
```typescript
266
@Cordova({
267
  eventObservable: true,
268
  event: "deviceready"
269
})
270
onDeviceReady(): Observable<any> {
271
  return;
272
}
273
```
274

275
### Platform-specific Methods
276

277
Restrict methods to specific platforms:
278

279
```typescript
280
@Cordova({
281
  platforms: ["iOS"]
282
})
283
iOSOnlyMethod(): Promise<any> {
284
  return;
285
}
286
```
287

288
## Low-level Decorator Functions
289

290
These functions are typically used internally by the decorator system but are also exported for advanced use cases:
291

292
```typescript { .api }
293
/**
294
 * Internal function used by @Cordova decorator
295
 * @param pluginObj - Plugin instance
296
 * @param methodName - Method name to call
297
 * @param config - Cordova configuration options
298
 * @param args - Method arguments
299
 * @returns Result from plugin method call
300
 */
301
function cordova(
302
  pluginObj: any, 
303
  methodName: string, 
304
  config: CordovaOptions, 
305
  args: IArguments | any[]
306
): any;
307

308
/**
309
 * Internal function used by @CordovaInstance decorator
310
 * @param pluginObj - Plugin object with _objectInstance
311
 * @param methodName - Method name to call on instance
312
 * @param config - Cordova configuration options
313
 * @param args - Method arguments
314
 * @returns Result from instance method call
315
 */
316
function cordovaInstance(
317
  pluginObj: any, 
318
  methodName: string, 
319
  config: CordovaOptions, 
320
  args: IArguments | any[]
321
): any;
322

323
/**
324
 * Internal function used by @CordovaFunctionOverride decorator
325
 * @param pluginObj - Plugin instance
326
 * @param methodName - Method name to override
327
 * @param args - Method arguments
328
 * @returns Observable for function override
329
 */
330
function cordovaFunctionOverride(
331
  pluginObj: any, 
332
  methodName: string, 
333
  args?: IArguments | any[]
334
): Observable<any>;
335
```
336

337
### Property Access Functions
338

339
```typescript { .api }
340
/**
341
 * Gets property value from Cordova plugin with availability checking
342
 * @param pluginObj - Plugin instance
343
 * @param key - Property name
344
 * @returns Property value or null if plugin/property unavailable
345
 */
346
function cordovaPropertyGet(pluginObj: any, key: string): any;
347

348
/**
349
 * Sets property value on Cordova plugin with availability checking
350
 * @param pluginObj - Plugin instance
351
 * @param key - Property name
352
 * @param value - Value to set
353
 */
354
function cordovaPropertySet(pluginObj: any, key: string, value: any): void;
355

356
/**
357
 * Gets property value from plugin instance object
358
 * @param pluginObj - Plugin object with _objectInstance
359
 * @param key - Property name
360
 * @returns Property value or null if instance/property unavailable
361
 */
362
function instancePropertyGet(pluginObj: any, key: string): any;
363

364
/**
365
 * Sets property value on plugin instance object
366
 * @param pluginObj - Plugin object with _objectInstance
367
 * @param key - Property name
368
 * @param value - Value to set
369
 */
370
function instancePropertySet(pluginObj: any, key: string, value: any): void;
371
```