0
# localForage
1

2
localForage is a fast and simple storage library for JavaScript that improves the offline experience of web applications by using asynchronous storage (IndexedDB or WebSQL) with a simple, localStorage-like API. It automatically falls back to localStorage in browsers with no IndexedDB or WebSQL support, offering both callback and Promise-based APIs with async/await support, and can store any JavaScript type including Blobs, TypedArrays, and other objects that can be serialized to JSON.
3

4
## Package Information
5

6
- **Package Name**: localforage
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install localforage`
10

11
## Core Imports
12

13
```javascript
14
import localforage from 'localforage';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const localforage = require('localforage');
21
```
22

23
For environments without module support:
24

25
```html
26
<script src="localforage.js"></script>
27
<script>console.log('localforage is: ', localforage);</script>
28
```
29

30
## Basic Usage
31

32
```javascript
33
import localforage from 'localforage';
34

35
// Store data
36
await localforage.setItem('users', [
37
  { name: 'Alice', age: 25 },
38
  { name: 'Bob', age: 30 }
39
]);
40

41
// Retrieve data
42
const users = await localforage.getItem('users');
43
console.log(users); // [{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }]
44

45
// Remove data
46
await localforage.removeItem('users');
47

48
// Clear all data
49
await localforage.clear();
50
```
51

52
## Architecture
53

54
localForage is built around several key components:
55

56
- **Driver System**: Automatic selection and fallback between IndexedDB, WebSQL, and localStorage
57
- **Storage Interface**: Unified API that works consistently across all storage backends
58
- **Serialization**: Automatic handling of complex data types including Blobs and TypedArrays
59
- **Promise-based API**: Modern async/await support with optional callback compatibility
60
- **Multi-instance Support**: Ability to create multiple storage instances with different configurations
61

62
## Capabilities
63

64
### Core Storage Operations
65

66
Primary data storage methods that work consistently across all supported storage backends. These methods form the core localStorage-like API with full async support.
67

68
```javascript { .api }
69
function getItem<T>(key: string, callback?: (err: any, value: T | null) => void): Promise<T | null>;
70

71
function setItem<T>(key: string, value: T, callback?: (err: any, value: T) => void): Promise<T>;
72

73
function removeItem(key: string, callback?: (err: any) => void): Promise<void>;
74

75
function clear(callback?: (err: any) => void): Promise<void>;
76
```
77

78
[Storage Operations](./storage-operations.md)
79

80
### Storage Inspection
81

82
Methods for inspecting and iterating over stored data, including key enumeration and batch processing capabilities.
83

84
```javascript { .api }
85
function length(callback?: (err: any, numberOfKeys: number) => void): Promise<number>;
86

87
function key(keyIndex: number, callback?: (err: any, key: string) => void): Promise<string>;
88

89
function keys(callback?: (err: any, keys: string[]) => void): Promise<string[]>;
90

91
function iterate<T, U>(
92
  iteratee: (value: T, key: string, iterationNumber: number) => U,
93
  callback?: (err: any, result: U) => void
94
): Promise<U>;
95
```
96

97
[Storage Inspection](./storage-inspection.md)
98

99
### Configuration and Driver Management
100

101
Configuration system for customizing storage behavior, driver selection, and creating multiple storage instances.
102

103
```javascript { .api }
104
function config(options: LocalForageOptions): boolean;
105
function config(options: string): any;
106
function config(): LocalForageOptions;
107

108
function setDriver(
109
  driver: string | string[],
110
  callback?: () => void,
111
  errorCallback?: (error: any) => void
112
): Promise<void>;
113

114
function createInstance(options: LocalForageOptions): LocalForage;
115

116
function dropInstance(dbInstanceOptions?: LocalForageDbInstanceOptions, callback?: (err: any) => void): Promise<void>;
117
```
118

119
[Configuration](./configuration.md)
120

121
### Driver Development
122

123
Advanced functionality for defining custom storage drivers and inspecting driver capabilities.
124

125
```javascript { .api }
126
function defineDriver(
127
  driver: LocalForageDriver,
128
  callback?: () => void,
129
  errorCallback?: (error: any) => void
130
): Promise<void>;
131

132
function driver(): string;
133

134
function getDriver(driver: string): Promise<LocalForageDriver>;
135

136
function getSerializer(callback?: (serializer: LocalForageSerializer) => void): Promise<LocalForageSerializer>;
137

138
function ready(callback?: (error: any) => void): Promise<void>;
139

140
function supports(driverName: string): boolean;
141
```
142

143
[Driver Development](./driver-development.md)
144

145
## Driver Constants
146

147
```javascript { .api }
148
// Available as properties on the localforage instance
149
const INDEXEDDB: string; // 'asyncStorage'
150
const WEBSQL: string;    // 'webSQLStorage'  
151
const LOCALSTORAGE: string; // 'localStorageWrapper'
152
```
153

154
## Types
155

156
```javascript { .api }
157
interface LocalForageOptions {
158
  driver?: string | string[];
159
  name?: string;
160
  storeName?: string;
161
  size?: number;
162
  version?: number;
163
  description?: string;
164
}
165

166
interface LocalForageDbInstanceOptions {
167
  name?: string;
168
  storeName?: string;
169
}
170

171
interface LocalForage {
172
  // Core storage methods
173
  getItem<T>(key: string, callback?: (err: any, value: T | null) => void): Promise<T | null>;
174
  setItem<T>(key: string, value: T, callback?: (err: any, value: T) => void): Promise<T>;
175
  removeItem(key: string, callback?: (err: any) => void): Promise<void>;
176
  clear(callback?: (err: any) => void): Promise<void>;
177
  
178
  // Storage inspection methods
179
  length(callback?: (err: any, numberOfKeys: number) => void): Promise<number>;
180
  key(keyIndex: number, callback?: (err: any, key: string) => void): Promise<string>;
181
  keys(callback?: (err: any, keys: string[]) => void): Promise<string[]>;
182
  iterate<T, U>(iteratee: (value: T, key: string, iterationNumber: number) => U, callback?: (err: any, result: U) => void): Promise<U>;
183
  
184
  // Configuration and management
185
  config(options: LocalForageOptions): boolean;
186
  config(options: string): any;
187
  config(): LocalForageOptions;
188
  createInstance(options: LocalForageOptions): LocalForage;
189
  setDriver(driver: string | string[], callback?: () => void, errorCallback?: (error: any) => void): Promise<void>;
190
  
191
  // Driver inspection
192
  driver(): string;
193
  getDriver(driver: string): Promise<LocalForageDriver>;
194
  supports(driverName: string): boolean;
195
  ready(callback?: (error: any) => void): Promise<void>;
196
  
197
  // Advanced features
198
  defineDriver(driver: LocalForageDriver, callback?: () => void, errorCallback?: (error: any) => void): Promise<void>;
199
  getSerializer(callback?: (serializer: LocalForageSerializer) => void): Promise<LocalForageSerializer>;
200
  dropInstance(dbInstanceOptions?: LocalForageDbInstanceOptions, callback?: (err: any) => void): Promise<void>;
201
  
202
  // Driver constants
203
  INDEXEDDB: string;
204
  WEBSQL: string;
205
  LOCALSTORAGE: string;
206
}
207

208
interface LocalForageDriver {
209
  _driver: string;
210
  _initStorage(options: LocalForageOptions): void;
211
  _support?: boolean | (() => Promise<boolean>);
212
  
213
  // Core storage methods
214
  getItem<T>(key: string, callback?: (err: any, value: T | null) => void): Promise<T | null>;
215
  setItem<T>(key: string, value: T, callback?: (err: any, value: T) => void): Promise<T>;
216
  removeItem(key: string, callback?: (err: any) => void): Promise<void>;
217
  clear(callback?: (err: any) => void): Promise<void>;
218
  length(callback?: (err: any, numberOfKeys: number) => void): Promise<number>;
219
  key(keyIndex: number, callback?: (err: any, key: string) => void): Promise<string>;
220
  keys(callback?: (err: any, keys: string[]) => void): Promise<string[]>;
221
  iterate<T, U>(iteratee: (value: T, key: string, iterationNumber: number) => U, callback?: (err: any, result: U) => void): Promise<U>;
222
  
223
  // Optional methods
224
  dropInstance?(dbInstanceOptions?: LocalForageDbInstanceOptions, callback?: (err: any) => void): Promise<void>;
225
}
226

227
interface LocalForageSerializer {
228
  serialize<T>(value: T | ArrayBuffer | Blob, callback: (value: string, error: any) => void): void;
229
  deserialize<T>(value: string): T | ArrayBuffer | Blob;  
230
  stringToBuffer(serializedString: string): ArrayBuffer;
231
  bufferToString(buffer: ArrayBuffer): string;
232
}
233
```