0
# Runtime API
1

2
The runtime API provides client-side functions for managing offline functionality, handling cache updates, and responding to connectivity changes.
3

4
## Core Functions
5

6
### install
7

8
```javascript { .api }
9
function install(options?: InstallOptions): void;
10
```
11

12
Installs and initializes the ServiceWorker or AppCache for offline functionality. This function must be called each time your application loads - it's safe to call repeatedly.
13

14
**Parameters:**
15
- `options` (optional): Configuration object with event handlers
16

17
**Usage:**
18
```javascript
19
// Basic installation
20
require('offline-plugin/runtime').install();
21

22
// ES6/TypeScript
23
import * as OfflinePluginRuntime from 'offline-plugin/runtime';
24
OfflinePluginRuntime.install();
25
```
26

27
### applyUpdate
28

29
```javascript { .api }
30
function applyUpdate(): void;
31
```
32

33
Applies a pending cache update. Typically called from the `onUpdateReady` event handler to activate new cached content.
34

35
**Usage:**
36
```javascript
37
require('offline-plugin/runtime').install({
38
  onUpdateReady: () => {
39
    require('offline-plugin/runtime').applyUpdate();
40
  }
41
});
42
```
43

44
### update
45

46
```javascript { .api }
47
function update(): void;
48
```
49

50
Manually triggers a check for cache updates. The update process will fire appropriate events based on the result.
51

52
**Usage:**
53
```javascript
54
// Check for updates on user action
55
document.getElementById('update-btn').addEventListener('click', () => {
56
  require('offline-plugin/runtime').update();
57
});
58
```
59

60
## Event Handling
61

62
### InstallOptions Interface
63

64
```javascript { .api }
65
interface InstallOptions {
66
  onInstalled?: () => void;
67
  onUpdating?: () => void;
68
  onUpdateReady?: () => void;
69
  onUpdateFailed?: () => void;
70
  onUpdated?: () => void;
71
}
72
```
73

74
Event handlers for managing the offline functionality lifecycle.
75

76
### onInstalled
77

78
```javascript { .api }
79
onInstalled?: () => void;
80
```
81

82
Called exactly once when the ServiceWorker or AppCache is successfully installed and ready. Ideal for displaying "App ready for offline use" messages.
83

84
**Usage:**
85
```javascript
86
install({
87
  onInstalled: () => {
88
    console.log('App is ready for offline usage');
89
    showNotification('Ready for offline use!');
90
  }
91
});
92
```
93

94
### onUpdating
95

96
```javascript { .api }
97
onUpdating?: () => void;
98
```
99

100
Called when an update is found and the download process begins. Not supported for AppCache. Use this to show loading indicators.
101

102
**Usage:**
103
```javascript
104
install({
105
  onUpdating: () => {
106
    console.log('Downloading updates...');
107
    showSpinner('Updating app...');
108
  }
109
});
110
```
111

112
### onUpdateReady
113

114
```javascript { .api }
115
onUpdateReady?: () => void;
116
```
117

118
Called when the update download is complete and ready to be applied. All new assets are downloaded and cached. Call `applyUpdate()` to activate the new version.
119

120
**Usage:**
121
```javascript
122
install({
123
  onUpdateReady: () => {
124
    console.log('Update ready - applying...');
125
    // Immediately apply the update
126
    require('offline-plugin/runtime').applyUpdate();
127
  }
128
});
129
```
130

131
### onUpdateFailed
132

133
```javascript { .api }
134
onUpdateFailed?: () => void;
135
```
136

137
Called when the update process fails. No new content was downloaded. The current cached version remains active.
138

139
**Usage:**
140
```javascript
141
install({
142
  onUpdateFailed: () => {
143
    console.warn('Update failed - continuing with current version');
144
    hideSpinner();
145
  }
146
});
147
```
148

149
### onUpdated
150

151
```javascript { .api }
152
onUpdated?: () => void;
153
```
154

155
Called when the update has been successfully applied, either through `applyUpdate()` or automatically by the browser. The new version is now active.
156

157
**Usage:**
158
```javascript
159
install({
160
  onUpdated: () => {
161
    console.log('App updated successfully');
162
    // Reload to use the new version
163
    window.location.reload();
164
  }
165
});
166
```
167

168
## Complete Usage Examples
169

170
### Basic Update Handling
171

172
```javascript
173
require('offline-plugin/runtime').install({
174
  onInstalled: () => {
175
    console.log('SW Event:', 'onInstalled');
176
  },
177
  
178
  onUpdateReady: () => {
179
    console.log('SW Event:', 'onUpdateReady');
180
    // Automatically apply update
181
    require('offline-plugin/runtime').applyUpdate();
182
  },
183
  
184
  onUpdated: () => {
185
    console.log('SW Event:', 'onUpdated');
186
    // Reload page to use new version
187
    window.location.reload();
188
  }
189
});
190
```
191

192
### User-Controlled Updates
193

194
```javascript
195
let updateAvailable = false;
196

197
require('offline-plugin/runtime').install({
198
  onUpdateReady: () => {
199
    updateAvailable = true;
200
    showUpdatePrompt('A new version is available. Update now?');
201
  },
202
  
203
  onUpdated: () => {
204
    window.location.reload();
205
  }
206
});
207

208
function applyPendingUpdate() {
209
  if (updateAvailable) {
210
    require('offline-plugin/runtime').applyUpdate();
211
  }
212
}
213
```
214

215
### Advanced Update Management
216

217
```javascript
218
const runtime = require('offline-plugin/runtime');
219

220
// Track update state
221
let isUpdating = false;
222

223
runtime.install({
224
  onInstalled: () => {
225
    setStatus('Ready for offline use');
226
  },
227
  
228
  onUpdating: () => {
229
    isUpdating = true;
230
    setStatus('Downloading update...', true);
231
  },
232
  
233
  onUpdateReady: () => {
234
    isUpdating = false;
235
    setStatus('Update ready');
236
    
237
    // Ask user before applying
238
    if (confirm('Update available. Apply now?')) {
239
      runtime.applyUpdate();
240
    }
241
  },
242
  
243
  onUpdateFailed: () => {
244
    isUpdating = false;
245
    setStatus('Update failed', false);
246
  },
247
  
248
  onUpdated: () => {
249
    setStatus('Updated successfully');
250
    setTimeout(() => window.location.reload(), 1000);
251
  }
252
});
253

254
// Check for updates periodically
255
setInterval(() => {
256
  if (!isUpdating) {
257
    runtime.update();
258
  }
259
}, 5 * 60 * 1000); // Every 5 minutes
260
```
261

262
### TypeScript Usage
263

264
```typescript
265
import * as OfflinePluginRuntime from 'offline-plugin/runtime';
266

267
interface UpdateState {
268
  isInstalled: boolean;
269
  isUpdating: boolean;
270
  hasUpdate: boolean;
271
}
272

273
const state: UpdateState = {
274
  isInstalled: false,
275
  isUpdating: false,
276
  hasUpdate: false
277
};
278

279
OfflinePluginRuntime.install({
280
  onInstalled: (): void => {
281
    state.isInstalled = true;
282
    console.log('ServiceWorker installed');
283
  },
284
  
285
  onUpdating: (): void => {
286
    state.isUpdating = true;
287
  },
288
  
289
  onUpdateReady: (): void => {
290
    state.isUpdating = false;
291
    state.hasUpdate = true;
292
    
293
    // Auto-apply in production, prompt in development
294
    if (process.env.NODE_ENV === 'production') {
295
      OfflinePluginRuntime.applyUpdate();
296
    } else {
297
      console.log('Update ready - call applyUpdate() to apply');
298
    }
299
  },
300
  
301
  onUpdated: (): void => {
302
    state.hasUpdate = false;
303
    window.location.reload();
304
  }
305
});
306
```