0
# Storage Operations
1

2
Core data storage methods that work consistently across all supported storage backends (IndexedDB, WebSQL, localStorage). These methods form the primary localStorage-like API with full async/await support and optional callback compatibility.
3

4
## Capabilities
5

6
### Get Item
7

8
Retrieves an item from storage by key. Returns `null` if the key doesn't exist.
9

10
```javascript { .api }
11
/**
12
 * Retrieves an item from storage
13
 * @param key - The key of the item to retrieve
14
 * @param callback - Optional callback function
15
 * @returns Promise resolving to the stored value or null
16
 */
17
function getItem<T>(key: string, callback?: (err: any, value: T | null) => void): Promise<T | null>;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
import localforage from 'localforage';
24

25
// Using async/await
26
const user = await localforage.getItem('user');
27
console.log(user); // { name: 'Alice', age: 25 } or null
28

29
// Using callbacks
30
localforage.getItem('user', (err, value) => {
31
  if (err) {
32
    console.error('Error:', err);
33
  } else {
34
    console.log('User:', value);
35
  }
36
});
37

38
// Type-safe retrieval with TypeScript
39
interface User {
40
  name: string;
41
  age: number;
42
}
43

44
const user = await localforage.getItem<User>('user');
45
// user is typed as User | null
46
```
47

48
### Set Item
49

50
Stores an item in storage. The value can be any JavaScript type that can be serialized, including objects, arrays, Blobs, TypedArrays, etc.
51

52
```javascript { .api }
53
/**
54
 * Stores an item in storage
55
 * @param key - The key to store the item under
56
 * @param value - The value to store (any serializable type)
57
 * @param callback - Optional callback function
58
 * @returns Promise resolving to the stored value
59
 */
60
function setItem<T>(key: string, value: T, callback?: (err: any, value: T) => void): Promise<T>;
61
```
62

63
**Usage Examples:**
64

65
```javascript
66
import localforage from 'localforage';
67

68
// Store simple values
69
await localforage.setItem('username', 'alice');
70
await localforage.setItem('score', 1250);
71
await localforage.setItem('isActive', true);
72

73
// Store complex objects
74
const userData = {
75
  name: 'Alice Johnson',
76
  preferences: {
77
    theme: 'dark',
78
    notifications: true
79
  },
80
  tags: ['developer', 'javascript']
81
};
82
await localforage.setItem('user', userData);
83

84
// Store arrays
85
const items = [1, 2, 3, 4, 5];
86
await localforage.setItem('numbers', items);
87

88
// Store Blobs (binary data)
89
const blob = new Blob(['Hello, world!'], { type: 'text/plain' });
90
await localforage.setItem('textFile', blob);
91

92
// Using callbacks
93
localforage.setItem('key', 'value', (err, value) => {
94
  if (err) {
95
    console.error('Storage error:', err);
96
  } else {
97
    console.log('Stored value:', value);
98
  }
99
});
100
```
101

102
### Remove Item
103

104
Removes an item from storage by key. No error is thrown if the key doesn't exist.
105

106
```javascript { .api }
107
/**
108
 * Removes an item from storage
109
 * @param key - The key of the item to remove
110
 * @param callback - Optional callback function
111
 * @returns Promise resolving when the item is removed
112
 */
113
function removeItem(key: string, callback?: (err: any) => void): Promise<void>;
114
```
115

116
**Usage Examples:**
117

118
```javascript
119
import localforage from 'localforage';
120

121
// Remove a single item
122
await localforage.removeItem('temporaryData');
123

124
// Remove user session data
125
await localforage.removeItem('authToken');
126

127
// Using callbacks
128
localforage.removeItem('oldData', (err) => {
129
  if (err) {
130
    console.error('Error removing item:', err);
131
  } else {
132
    console.log('Item removed successfully');
133
  }
134
});
135

136
// Safe removal (no error if key doesn't exist)
137
await localforage.removeItem('nonExistentKey'); // No error thrown
138
```
139

140
### Clear Storage
141

142
Removes all items from the current storage instance. This only affects the current database/store, not other instances.
143

144
```javascript { .api }
145
/**
146
 * Clears all items from storage
147
 * @param callback - Optional callback function
148
 * @returns Promise resolving when all items are cleared
149
 */
150
function clear(callback?: (err: any) => void): Promise<void>;
151
```
152

153
**Usage Examples:**
154

155
```javascript
156
import localforage from 'localforage';
157

158
// Clear all data
159
await localforage.clear();
160
console.log('All data cleared');
161

162
// Clear with confirmation
163
const confirmClear = confirm('Are you sure you want to clear all data?');
164
if (confirmClear) {
165
  await localforage.clear();
166
}
167

168
// Using callbacks
169
localforage.clear((err) => {
170
  if (err) {
171
    console.error('Error clearing storage:', err);
172
  } else {
173
    console.log('Storage cleared successfully');
174
  }
175
});
176

177
// Clear specific instance only
178
const userStore = localforage.createInstance({ name: 'userdata' });
179
await userStore.clear(); // Only clears userdata store
180
```
181

182
## Error Handling
183

184
All storage operations can potentially fail due to quota limits, permissions, or other storage-related issues:
185

186
```javascript
187
try {
188
  await localforage.setItem('largeData', hugeBinaryData);
189
} catch (error) {
190
  if (error.name === 'QuotaExceededError') {
191
    console.error('Storage quota exceeded');
192
  } else {
193
    console.error('Storage error:', error);
194
  }
195
}
196

197
// With callbacks, errors are passed as the first parameter
198
localforage.getItem('key', (err, value) => {
199
  if (err) {
200
    console.error('Failed to retrieve item:', err);
201
    return;
202
  }
203
  // Process value...
204
});
205
```
206

207
## Supported Data Types
208

209
localForage can store any data type that can be handled by the structured clone algorithm:
210

211
- **Primitives**: `string`, `number`, `boolean`, `null`, `undefined`
212
- **Objects**: Plain objects, arrays, dates
213
- **Binary Data**: `ArrayBuffer`, `Blob`, `File`, TypedArrays (`Uint8Array`, etc.)
214
- **Complex Types**: Nested objects, objects with circular references (in some cases)
215

216
```javascript
217
// All of these work seamlessly
218
await localforage.setItem('string', 'Hello World');
219
await localforage.setItem('number', 42);
220
await localforage.setItem('boolean', true);
221
await localforage.setItem('date', new Date());
222
await localforage.setItem('array', [1, 2, 3]);
223
await localforage.setItem('object', { key: 'value' });
224
await localforage.setItem('blob', new Blob(['data']));
225
await localforage.setItem('buffer', new ArrayBuffer(8));
226
```