0
# Storage APIs
1

2
Local storage management with both synchronous and asynchronous operations for persistent data storage in Taro React Native applications.
3

4
## Capabilities
5

6
### Asynchronous Storage Operations
7

8
Promise-based storage operations for non-blocking data access.
9

10
```typescript { .api }
11
/**
12
 * Get data from storage asynchronously
13
 * @param options Storage get options
14
 */
15
function getStorage(options: {
16
  key: string;
17
  success?: (res: { data: any }) => void;
18
  fail?: (res: TaroGeneral.CallbackResult) => void;
19
  complete?: (res: any) => void;
20
}): Promise<{ data: any }>;
21

22
/**
23
 * Set data in storage asynchronously
24
 * @param options Storage set options
25
 */
26
function setStorage(options: {
27
  key: string;
28
  data: any;
29
  success?: (res: TaroGeneral.CallbackResult) => void;
30
  fail?: (res: TaroGeneral.CallbackResult) => void;
31
  complete?: (res: TaroGeneral.CallbackResult) => void;
32
}): Promise<TaroGeneral.CallbackResult>;
33

34
/**
35
 * Remove data from storage asynchronously
36
 * @param options Storage remove options
37
 */
38
function removeStorage(options: {
39
  key: string;
40
  success?: (res: TaroGeneral.CallbackResult) => void;
41
  fail?: (res: TaroGeneral.CallbackResult) => void;
42
  complete?: (res: TaroGeneral.CallbackResult) => void;
43
}): Promise<TaroGeneral.CallbackResult>;
44

45
/**
46
 * Clear all storage data asynchronously
47
 * @param options Storage clear options
48
 */
49
function clearStorage(options?: {
50
  success?: (res: TaroGeneral.CallbackResult) => void;
51
  fail?: (res: TaroGeneral.CallbackResult) => void;
52
  complete?: (res: TaroGeneral.CallbackResult) => void;
53
}): Promise<TaroGeneral.CallbackResult>;
54
```
55

56
**Usage Examples:**
57

58
```typescript
59
import { getStorage, setStorage, removeStorage, clearStorage } from "@tarojs/taro-rn";
60

61
// Store user data
62
await setStorage({
63
  key: 'user',
64
  data: {
65
    id: 123,
66
    name: 'John Doe',
67
    email: 'john@example.com'
68
  }
69
});
70

71
// Retrieve user data
72
const userResult = await getStorage({ key: 'user' });
73
console.log('User data:', userResult.data);
74

75
// Store different data types
76
await setStorage({ key: 'settings', data: { theme: 'dark', notifications: true } });
77
await setStorage({ key: 'token', data: 'abc123def456' });
78
await setStorage({ key: 'count', data: 42 });
79

80
// Remove specific item
81
await removeStorage({ key: 'token' });
82

83
// Clear all storage
84
await clearStorage();
85
```
86

87
### Synchronous Storage Operations
88

89
Immediate storage operations that return values directly.
90

91
```typescript { .api }
92
/**
93
 * Get data from storage synchronously
94
 * @param key Storage key
95
 * @returns Stored data or undefined if not found
96
 */
97
function getStorageSync(key: string): any;
98

99
/**
100
 * Set data in storage synchronously
101
 * @param key Storage key
102
 * @param data Data to store
103
 */
104
function setStorageSync(key: string, data: any): void;
105

106
/**
107
 * Remove data from storage synchronously
108
 * @param key Storage key
109
 */
110
function removeStorageSync(key: string): void;
111

112
/**
113
 * Clear all storage data synchronously
114
 */
115
function clearStorageSync(): void;
116
```
117

118
**Usage Examples:**
119

120
```typescript
121
import { 
122
  getStorageSync, 
123
  setStorageSync, 
124
  removeStorageSync, 
125
  clearStorageSync 
126
} from "@tarojs/taro-rn";
127

128
// Store data synchronously
129
setStorageSync('theme', 'dark');
130
setStorageSync('user_preferences', {
131
  language: 'en',
132
  timezone: 'UTC'
133
});
134

135
// Retrieve data synchronously
136
const theme = getStorageSync('theme');
137
const preferences = getStorageSync('user_preferences');
138

139
console.log('Theme:', theme);
140
console.log('Preferences:', preferences);
141

142
// Remove item synchronously
143
removeStorageSync('theme');
144

145
// Clear all data synchronously
146
clearStorageSync();
147
```
148

149
### Storage Information
150

151
Get information about storage usage and available space.
152

153
```typescript { .api }
154
/**
155
 * Get storage information asynchronously
156
 * @param options Storage info options
157
 */
158
function getStorageInfo(options?: {
159
  success?: (res: {
160
    keys: string[];
161
    currentSize: number;
162
    limitSize: number;
163
  }) => void;
164
  fail?: (res: TaroGeneral.CallbackResult) => void;
165
  complete?: (res: any) => void;
166
}): Promise<{
167
  keys: string[];
168
  currentSize: number;
169
  limitSize: number;
170
}>;
171

172
/**
173
 * Get storage information synchronously
174
 * @returns Storage information
175
 */
176
function getStorageInfoSync(): {
177
  keys: string[];
178
  currentSize: number;
179
  limitSize: number;
180
};
181
```
182

183
**Usage Examples:**
184

185
```typescript
186
import { getStorageInfo, getStorageInfoSync } from "@tarojs/taro-rn";
187

188
// Get storage info asynchronously
189
const storageInfo = await getStorageInfo();
190
console.log('Stored keys:', storageInfo.keys);
191
console.log('Current size:', storageInfo.currentSize);
192
console.log('Limit size:', storageInfo.limitSize);
193

194
// Get storage info synchronously
195
const syncStorageInfo = getStorageInfoSync();
196
console.log('Available keys:', syncStorageInfo.keys);
197

198
// Check if storage is getting full
199
const usagePercentage = (syncStorageInfo.currentSize / syncStorageInfo.limitSize) * 100;
200
if (usagePercentage > 80) {
201
  console.warn('Storage is getting full!');
202
}
203
```
204

205
## Storage Patterns
206

207
### Data Types
208

209
Storage supports various data types that are automatically serialized:
210

211
```typescript
212
// Strings
213
setStorageSync('message', 'Hello World');
214

215
// Numbers
216
setStorageSync('score', 1250);
217

218
// Booleans
219
setStorageSync('isEnabled', true);
220

221
// Objects
222
setStorageSync('config', {
223
  apiUrl: 'https://api.example.com',
224
  timeout: 5000,
225
  retries: 3
226
});
227

228
// Arrays
229
setStorageSync('items', ['apple', 'banana', 'orange']);
230

231
// Complex nested objects
232
setStorageSync('userData', {
233
  profile: {
234
    name: 'John',
235
    avatar: 'https://example.com/avatar.jpg'
236
  },
237
  settings: {
238
    notifications: {
239
      email: true,
240
      push: false
241
    }
242
  },
243
  history: [
244
    { action: 'login', timestamp: Date.now() },
245
    { action: 'view_profile', timestamp: Date.now() - 1000 }
246
  ]
247
});
248
```
249

250
### Error Handling
251

252
Handle storage errors gracefully:
253

254
```typescript
255
import { getStorage, setStorage } from "@tarojs/taro-rn";
256

257
// Using async/await with try-catch
258
try {
259
  await setStorage({ key: 'data', data: largeObject });
260
  console.log('Data stored successfully');
261
} catch (error) {
262
  console.error('Storage failed:', error);
263
}
264

265
// Using callback pattern
266
setStorage({
267
  key: 'data',
268
  data: someData,
269
  success: (res) => {
270
    console.log('Storage success:', res);
271
  },
272
  fail: (error) => {
273
    console.error('Storage error:', error);
274
  },
275
  complete: (res) => {
276
    console.log('Storage operation completed');
277
  }
278
});
279
```
280

281
### Storage Keys Management
282

283
Organize storage keys effectively:
284

285
```typescript
286
// Use consistent naming conventions
287
const STORAGE_KEYS = {
288
  USER_TOKEN: 'user_token',
289
  USER_PROFILE: 'user_profile',
290
  APP_SETTINGS: 'app_settings',
291
  CACHE_PREFIX: 'cache_',
292
  TEMP_PREFIX: 'temp_'
293
};
294

295
// Store with organized keys
296
setStorageSync(STORAGE_KEYS.USER_TOKEN, 'abc123');
297
setStorageSync(STORAGE_KEYS.USER_PROFILE, userProfile);
298
setStorageSync(`${STORAGE_KEYS.CACHE_PREFIX}api_data`, apiResponse);
299

300
// Clean up temporary data
301
const allKeys = getStorageInfoSync().keys;
302
const tempKeys = allKeys.filter(key => key.startsWith(STORAGE_KEYS.TEMP_PREFIX));
303
tempKeys.forEach(key => removeStorageSync(key));
304
```