0
# Promise Wrapping
1

2
Low-level utilities for converting native IndexedDB objects to promise-based equivalents and vice versa. These functions provide the core transformation that enables IDB's promise-based API.
3

4
## Capabilities
5

6
### Wrap Function
7

8
Enhances native IDB objects with promise-based helpers and typed interfaces.
9

10
```typescript { .api }
11
/**
12
 * Enhance an IDB database with helpers
13
 * @param value - Native IDBDatabase to enhance
14
 * @returns Enhanced database with promise-based methods
15
 */
16
function wrap(value: IDBDatabase): IDBPDatabase;
17

18
/**
19
 * Enhance an IDB index with helpers
20
 * @param value - Native IDBIndex to enhance
21
 * @returns Enhanced index with promise-based methods
22
 */
23
function wrap(value: IDBIndex): IDBPIndex;
24

25
/**
26
 * Enhance an IDB object store with helpers
27
 * @param value - Native IDBObjectStore to enhance
28
 * @returns Enhanced object store with promise-based methods
29
 */
30
function wrap(value: IDBObjectStore): IDBPObjectStore;
31

32
/**
33
 * Enhance an IDB transaction with helpers
34
 * @param value - Native IDBTransaction to enhance
35
 * @returns Enhanced transaction with promise-based methods
36
 */
37
function wrap(value: IDBTransaction): IDBPTransaction;
38

39
/**
40
 * Convert an IDB open database request to a promise
41
 * @param value - Native IDBOpenDBRequest
42
 * @returns Promise resolving to enhanced database
43
 */
44
function wrap(value: IDBOpenDBRequest): Promise<IDBPDatabase | undefined>;
45

46
/**
47
 * Convert any IDB request to a promise
48
 * @param value - Native IDBRequest
49
 * @returns Promise resolving to the request result
50
 */
51
function wrap<T>(value: IDBRequest<T>): Promise<T>;
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
import { wrap } from "idb";
58

59
// Wrap a native database (rarely needed - use openDB instead)
60
const nativeDB = await new Promise((resolve, reject) => {
61
  const request = indexedDB.open("my-database");
62
  request.onsuccess = () => resolve(request.result);
63
  request.onerror = () => reject(request.error);
64
});
65
const enhancedDB = wrap(nativeDB);
66

67
// Wrap individual components (useful for migration from native code)
68
const nativeTransaction = nativeDB.transaction(["users"], "readwrite");
69
const enhancedTransaction = wrap(nativeTransaction);
70

71
const nativeStore = nativeTransaction.objectStore("users");
72
const enhancedStore = wrap(nativeStore);
73

74
// Convert requests to promises
75
const nativeRequest = nativeStore.add({ name: "Alice" });
76
const result = await wrap(nativeRequest);
77
```
78

79
### Unwrap Function
80

81
Reverts enhanced IDB objects back to their native equivalents.
82

83
```typescript { .api }
84
/**
85
 * Revert an enhanced cursor with value to native IDBCursorWithValue
86
 * @param value - Enhanced cursor to revert
87
 * @returns Native IDBCursorWithValue
88
 */
89
function unwrap(value: IDBPCursorWithValue<any, any, any, any, any>): IDBCursorWithValue;
90

91
/**
92
 * Revert an enhanced cursor to native IDBCursor
93
 * @param value - Enhanced cursor to revert
94
 * @returns Native IDBCursor
95
 */
96
function unwrap(value: IDBPCursor<any, any, any, any, any>): IDBCursor;
97

98
/**
99
 * Revert an enhanced database to native IDBDatabase
100
 * @param value - Enhanced database to revert
101
 * @returns Native IDBDatabase
102
 */
103
function unwrap(value: IDBPDatabase<any>): IDBDatabase;
104

105
/**
106
 * Revert an enhanced index to native IDBIndex
107
 * @param value - Enhanced index to revert
108
 * @returns Native IDBIndex
109
 */
110
function unwrap(value: IDBPIndex<any, any, any, any, any>): IDBIndex;
111

112
/**
113
 * Revert an enhanced object store to native IDBObjectStore
114
 * @param value - Enhanced object store to revert
115
 * @returns Native IDBObjectStore
116
 */
117
function unwrap(value: IDBPObjectStore<any, any, any, any>): IDBObjectStore;
118

119
/**
120
 * Revert an enhanced transaction to native IDBTransaction
121
 * @param value - Enhanced transaction to revert
122
 * @returns Native IDBTransaction
123
 */
124
function unwrap(value: IDBPTransaction<any, any, any>): IDBTransaction;
125

126
/**
127
 * Revert a database promise back to native IDBOpenDBRequest
128
 * @param value - Promise for enhanced database
129
 * @returns Native IDBOpenDBRequest
130
 */
131
function unwrap<T extends any>(value: Promise<IDBPDatabase<T>>): IDBOpenDBRequest;
132

133
/**
134
 * Revert a database promise back to native IDBOpenDBRequest
135
 * @param value - Promise for enhanced database
136
 * @returns Native IDBOpenDBRequest
137
 */
138
function unwrap(value: Promise<IDBPDatabase>): IDBOpenDBRequest;
139

140
/**
141
 * Revert any promise back to native IDBRequest
142
 * @param value - Promise to revert
143
 * @returns Native IDBRequest
144
 */
145
function unwrap<T>(value: Promise<T>): IDBRequest<T>;
146
```
147

148
**Usage Examples:**
149

150
```typescript
151
import { openDB, unwrap } from "idb";
152

153
// Get enhanced database
154
const enhancedDB = await openDB("my-database");
155

156
// Revert to native for legacy code integration
157
const nativeDB = unwrap(enhancedDB);
158

159
// Use native API
160
const nativeTransaction = nativeDB.transaction(["users"], "readonly");
161
const nativeStore = nativeTransaction.objectStore("users");
162

163
// Mix enhanced and native APIs as needed
164
const enhancedTransaction = enhancedDB.transaction("users");
165
const nativeStore2 = unwrap(enhancedTransaction.store);
166

167
// Revert promises to requests (useful for event handling)
168
const getUserPromise = enhancedDB.get("users", "user123");
169
const nativeRequest = unwrap(getUserPromise);
170

171
nativeRequest.addEventListener("success", (event) => {
172
  console.log("Request succeeded:", event.target.result);
173
});
174
```
175

176
### Replacement Traps
177

178
Advanced functionality for customizing the behavior of wrapped objects.
179

180
```typescript { .api }
181
/**
182
 * Replace the proxy traps used for wrapping IDB objects
183
 * @param callback - Function that receives current traps and returns new traps
184
 */
185
function replaceTraps(
186
  callback: (currentTraps: ProxyHandler<any>) => ProxyHandler<any>
187
): void;
188
```
189

190
**Advanced Usage:**
191

192
```typescript
193
import { replaceTraps } from "idb";
194

195
// Add custom logging to all wrapped objects
196
replaceTraps((currentTraps) => ({
197
  ...currentTraps,
198
  get(target, prop, receiver) {
199
    console.log(`Accessing property: ${String(prop)}`);
200
    return currentTraps.get!(target, prop, receiver);
201
  }
202
}));
203

204
// Custom behavior for specific properties
205
replaceTraps((currentTraps) => ({
206
  ...currentTraps,
207
  get(target, prop, receiver) {
208
    if (prop === "customMethod") {
209
      return () => console.log("Custom method called");
210
    }
211
    return currentTraps.get!(target, prop, receiver);
212
  }
213
}));
214
```
215

216
## Integration Patterns
217

218
### Migration from Native IndexedDB
219

220
When migrating existing code from native IndexedDB to IDB:
221

222
```typescript
223
// Before: Native IndexedDB
224
const request = indexedDB.open("my-database");
225
request.onsuccess = () => {
226
  const db = request.result;
227
  const transaction = db.transaction(["users"], "readwrite");
228
  const store = transaction.objectStore("users");
229
  const addRequest = store.add({ name: "Alice" });
230
  addRequest.onsuccess = () => {
231
    console.log("User added");
232
  };
233
};
234

235
// After: Using IDB with openDB (recommended)
236
const db = await openDB("my-database");
237
await db.add("users", { name: "Alice" });
238
console.log("User added");
239

240
// Alternative: Using wrap for gradual migration
241
const nativeDB = await new Promise((resolve, reject) => {
242
  const request = indexedDB.open("my-database");
243
  request.onsuccess = () => resolve(request.result);
244
  request.onerror = () => reject(request.error);
245
});
246
const enhancedDB = wrap(nativeDB);
247
await enhancedDB.add("users", { name: "Alice" });
248
```
249

250
### Working with Legacy Code
251

252
When you need to interface with existing code that expects native IDB objects:
253

254
```typescript
255
import { openDB, unwrap } from "idb";
256

257
async function legacyFunction(nativeDB: IDBDatabase) {
258
  // Legacy code expects native IDBDatabase
259
  const transaction = nativeDB.transaction(["users"], "readonly");
260
  // ... legacy operations
261
}
262

263
// Use enhanced database normally
264
const enhancedDB = await openDB("my-database");
265

266
// Convert for legacy function
267
await legacyFunction(unwrap(enhancedDB));
268

269
// Continue using enhanced database
270
const users = await enhancedDB.getAll("users");
271
```