0
# Availability Checking
1

2
Ionic Native Core provides comprehensive runtime checking utilities to verify plugin and Cordova availability, ensuring graceful error handling when plugins are missing or misconfigured.
3

4
## Capabilities
5

6
### Plugin Availability Checking
7

8
```typescript { .api }
9
/**
10
 * Checks if plugin/cordova is available and optionally if a specific method exists
11
 * @param plugin - Plugin instance, class, or plugin reference string
12
 * @param methodName - Optional method name to check
13
 * @param pluginName - Optional plugin name for error messages
14
 * @returns True if available, or error object describing the issue
15
 */
16
function checkAvailability(
17
  plugin: any | string,
18
  methodName?: string,
19
  pluginName?: string
20
): boolean | { error: string };
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { checkAvailability } from "@ionic-native/core";
27

28
// Check plugin availability by reference string
29
const cameraAvailable = checkAvailability("navigator.camera");
30
if (cameraAvailable === true) {
31
  // Plugin is available
32
} else {
33
  console.log("Camera not available:", cameraAvailable.error);
34
}
35

36
// Check specific method availability
37
const methodAvailable = checkAvailability("navigator.camera", "getPicture");
38
if (methodAvailable === true) {
39
  // Method is available
40
}
41

42
// Check using plugin instance
43
import { Camera } from "@ionic-native/camera";
44
const camera = new Camera();
45
const instanceAvailable = checkAvailability(camera, "getPicture", "Camera");
46
```
47

48
### Instance Availability Checking
49

50
```typescript { .api }
51
/**
52
 * Checks if _objectInstance exists and optionally has a specific method/property
53
 * Used for plugins that create object instances rather than static methods
54
 * @param pluginObj - Plugin object instance
55
 * @param methodName - Optional method name to check on the instance
56
 * @returns True if instance and method are available
57
 */
58
function instanceAvailability(
59
  pluginObj: any,
60
  methodName?: string
61
): boolean;
62
```
63

64
**Usage Example:**
65

66
```typescript
67
import { instanceAvailability } from "@ionic-native/core";
68

69
class FileObject {
70
  private _objectInstance: any;
71
  
72
  someMethod() {
73
    if (instanceAvailability(this, "readAsText")) {
74
      // Instance method is available
75
      return this._objectInstance.readAsText();
76
    } else {
77
      throw new Error("Instance not available");
78
    }
79
  }
80
}
81
```
82

83
### Lower-level Plugin Access
84

85
```typescript { .api }
86
/**
87
 * Retrieves plugin object from global scope using dot notation
88
 * @param pluginRef - Plugin reference path (e.g., "cordova.plugins.Example")
89
 * @returns Plugin object or null if not found
90
 */
91
function getPlugin(pluginRef: string): any;
92

93
/**
94
 * Gets nested property from object using dot notation path
95
 * @param element - Root element (typically window)
96
 * @param path - Dot notation path to the property
97
 * @returns Property value or null if path doesn't exist
98
 */
99
function get(element: Element | Window, path: string): any;
100
```
101

102
**Usage Examples:**
103

104
```typescript
105
import { getPlugin, get } from "@ionic-native/core";
106

107
// Get plugin object directly
108
const cameraPlugin = getPlugin("navigator.camera");
109
if (cameraPlugin) {
110
  cameraPlugin.getPicture(/* ... */);
111
}
112

113
// Get nested property from window
114
const cordova = get(window, "cordova.plugins.Example");
115
```
116

117
## Error Constants
118

119
```typescript { .api }
120
/** Error returned when Cordova framework is not available */
121
const ERR_CORDOVA_NOT_AVAILABLE: { error: "cordova_not_available" };
122

123
/** Error returned when specific plugin is not installed */
124
const ERR_PLUGIN_NOT_INSTALLED: { error: "plugin_not_installed" };
125
```
126

127
**Usage Example:**
128

129
```typescript
130
import { 
131
  checkAvailability, 
132
  ERR_CORDOVA_NOT_AVAILABLE, 
133
  ERR_PLUGIN_NOT_INSTALLED 
134
} from "@ionic-native/core";
135

136
const result = checkAvailability("navigator.camera");
137
if (result === ERR_CORDOVA_NOT_AVAILABLE) {
138
  console.log("Cordova not available - running in browser?");
139
} else if (result === ERR_PLUGIN_NOT_INSTALLED) {
140
  console.log("Camera plugin not installed");
141
} else if (result === true) {
142
  console.log("Camera plugin is available");
143
}
144
```
145

146
## Warning Functions
147

148
Internal functions used by the framework to provide helpful console warnings:
149

150
```typescript { .api }
151
/**
152
 * Logs warning when plugin is not installed
153
 * @param pluginName - Display name of the plugin
154
 * @param plugin - NPM package name for installation
155
 * @param method - Optional method name that was called
156
 */
157
function pluginWarn(pluginName: string, plugin?: string, method?: string): void;
158

159
/**
160
 * Logs warning when Cordova is not available
161
 * @param pluginName - Display name of the plugin
162
 * @param method - Optional method name that was called
163
 */
164
function cordovaWarn(pluginName: string, method?: string): void;
165
```
166

167
These functions are automatically called by the decorator system to provide helpful console messages when plugins are unavailable.
168

169
## Integration with Decorators
170

171
The availability checking system is automatically integrated with the decorator system. When you use `@Cordova()` or other decorators, they automatically call `checkAvailability()` before executing plugin methods:
172

173
```typescript
174
export class Camera extends IonicNativePlugin {
175
  @Cordova()
176
  getPicture(): Promise<string> {
177
    return; // checkAvailability is called automatically
178
  }
179
}
180

181
// When called:
182
const camera = new Camera();
183
camera.getPicture().catch(error => {
184
  // Will receive appropriate error if plugin/cordova unavailable
185
});
186
```
187

188
## Manual Availability Checking
189

190
For manual checking before using plugins:
191

192
```typescript
193
import { Camera } from "@ionic-native/camera";
194
import { checkAvailability } from "@ionic-native/core";
195

196
const camera = new Camera();
197
const available = checkAvailability(camera);
198

199
if (available === true) {
200
  // Safe to use camera methods
201
  camera.getPicture().then(/* ... */);
202
} else {
203
  // Handle unavailable plugin
204
  this.showFallbackUI();
205
}
206
```