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
```