0
# Ionic Native Core
1

2
Ionic Native Core provides the foundational infrastructure for TypeScript wrappers for Cordova and Capacitor plugins. It offers a comprehensive decorator system, base classes, and utilities that transform callback-based plugin interfaces into Promise and Observable patterns compatible with modern JavaScript frameworks.
3

4
## Package Information
5

6
- **Package Name**: @ionic-native/core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @ionic-native/core`
10

11
## Core Imports
12

13
```typescript
14
import { IonicNativePlugin } from "@ionic-native/core";
15
```
16

17
For decorators:
18

19
```typescript
20
import { 
21
  Cordova, 
22
  CordovaProperty, 
23
  CordovaInstance, 
24
  Plugin 
25
} from "@ionic-native/core";
26
```
27

28
For utilities:
29

30
```typescript
31
import { 
32
  checkAvailability, 
33
  wrap, 
34
  getPromise 
35
} from "@ionic-native/core";
36
```
37

38
For Observable support (requires RxJS):
39

40
```typescript
41
import { Observable } from "rxjs";
42
```
43

44
## Basic Usage
45

46
Create a plugin wrapper by extending IonicNativePlugin and using decorators:
47

48
```typescript
49
import { IonicNativePlugin, Plugin, Cordova } from "@ionic-native/core";
50

51
@Plugin({
52
  pluginName: "ExamplePlugin",
53
  plugin: "cordova-plugin-example",
54
  pluginRef: "cordova.plugins.Example",
55
  repo: "https://github.com/example/cordova-plugin-example",
56
  platforms: ["Android", "iOS"]
57
})
58
export class ExamplePlugin extends IonicNativePlugin {
59
  
60
  @Cordova()
61
  getData(): Promise<any> {
62
    return; // Promise return type is handled by decorator
63
  }
64
  
65
  @Cordova({ observable: true })
66
  watchData(): Observable<any> {
67
    return; // Observable return type is handled by decorator
68
  }
69
}
70
```
71

72
## Architecture
73

74
Ionic Native Core is built around several key components:
75

76
- **Base Plugin Class**: `IonicNativePlugin` provides common functionality for all plugin wrappers
77
- **Decorator System**: Transforms method calls to handle Promise/Observable patterns and error checking
78
- **Availability Checking**: Runtime verification of plugin and Cordova availability
79
- **Promise/Observable Wrapping**: Automatic conversion of callback-based APIs to modern async patterns
80
- **Error Handling**: Comprehensive error reporting for missing plugins and Cordova
81
- **Framework Integration**: Native support for Angular 1 dependency injection
82

83
## Capabilities
84

85
### Base Plugin Class
86

87
Foundation class that all Ionic Native plugin wrappers extend, providing standardized plugin metadata and availability checking.
88

89
```typescript { .api }
90
class IonicNativePlugin {
91
  static pluginName: string;
92
  static pluginRef: string;
93
  static plugin: string;
94
  static repo: string;
95
  static platforms: string[];
96
  static install: string;
97
  
98
  static installed(): boolean;
99
  static getPlugin(): any;
100
  static getPluginName(): string;
101
  static getPluginRef(): string;
102
  static getPluginInstallName(): string;
103
  static getSupportedPlatforms(): string[];
104
}
105
```
106

107
[Base Plugin Class](./base-plugin.md)
108

109
### Decorator System
110

111
Comprehensive decorator system for transforming plugin methods into Promise/Observable patterns with automatic error handling and platform checking.
112

113
```typescript { .api }
114
function Plugin(config: PluginConfig): ClassDecorator;
115
function Cordova(config?: CordovaOptions): MethodDecorator;
116
function CordovaProperty(): PropertyDecorator;
117
function CordovaInstance(config?: CordovaOptions): MethodDecorator;
118
function InstanceProperty(): PropertyDecorator;
119
function CordovaFunctionOverride(): MethodDecorator;
120
```
121

122
[Decorators](./decorators.md)
123

124
### Availability and Error Checking
125

126
Runtime checking utilities for plugin and Cordova availability with comprehensive error reporting.
127

128
```typescript { .api }
129
function checkAvailability(
130
  plugin: any | string, 
131
  methodName?: string, 
132
  pluginName?: string
133
): boolean | { error: string };
134

135
function instanceAvailability(
136
  pluginObj: any, 
137
  methodName?: string
138
): boolean;
139
```
140

141
[Availability Checking](./availability.md)
142

143
### Promise and Observable Utilities
144

145
Core utilities for creating promises and wrapping plugin methods with Promise/Observable patterns.
146

147
```typescript { .api }
148
function getPromise<T>(
149
  callback: (resolve: Function, reject?: Function) => any
150
): Promise<T>;
151

152
function wrap(
153
  pluginObj: any, 
154
  methodName: string, 
155
  opts?: CordovaOptions
156
): (...args: any[]) => any;
157

158
function wrapInstance(
159
  pluginObj: any, 
160
  methodName: string, 
161
  opts?: any
162
): Function;
163
```
164

165
[Promise and Observable Utilities](./promise-observable.md)
166

167
## Core Types
168

169
### Configuration Interfaces
170

171
```typescript { .api }
172
interface PluginConfig {
173
  pluginName: string;
174
  plugin: string;
175
  pluginRef?: string;
176
  repo?: string;
177
  install?: string;
178
  installVariables?: string[];
179
  platforms?: string[];
180
  [key: string]: any;
181
}
182

183
interface CordovaOptions {
184
  destruct?: boolean;
185
  methodName?: string;
186
  sync?: boolean;
187
  callbackOrder?: "reverse";
188
  callbackStyle?: "node" | "object";
189
  successIndex?: number;
190
  errorIndex?: number;
191
  successName?: string;
192
  errorName?: string;
193
  observable?: boolean;
194
  clearFunction?: string;
195
  clearWithArgs?: boolean;
196
  eventObservable?: boolean;
197
  event?: string;
198
  element?: any;
199
  otherPromise?: boolean;
200
  platforms?: string[];
201
}
202
```
203

204
### Error Constants
205

206
```typescript { .api }
207
const ERR_CORDOVA_NOT_AVAILABLE: { error: "cordova_not_available" };
208
const ERR_PLUGIN_NOT_INSTALLED: { error: "plugin_not_installed" };
209
```
210

211
### Utility Types
212

213
```typescript { .api }
214
type WrapFn = (...args: any[]) => any;
215
```