@wxt-dev/storage 1.2.5 → 1.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.mjs CHANGED
@@ -1,511 +1,421 @@
1
- import { dequal } from 'dequal/lite';
2
- import { Mutex } from 'async-mutex';
3
- import { browser } from '@wxt-dev/browser';
1
+ import { dequal } from "dequal/lite";
2
+ import { Mutex } from "async-mutex";
3
+ import { browser } from "@wxt-dev/browser";
4
4
 
5
+ //#region src/index.ts
6
+ /**
7
+ * Simplified storage APIs with support for versioned fields, snapshots, metadata, and item definitions.
8
+ *
9
+ * See [the guide](https://wxt.dev/storage.html) for more information.
10
+ * @module @wxt-dev/storage
11
+ */
5
12
  const storage = createStorage();
6
13
  function createStorage() {
7
- const drivers = {
8
- local: createDriver("local"),
9
- session: createDriver("session"),
10
- sync: createDriver("sync"),
11
- managed: createDriver("managed")
12
- };
13
- const getDriver = (area) => {
14
- const driver = drivers[area];
15
- if (driver == null) {
16
- const areaNames = Object.keys(drivers).join(", ");
17
- throw Error(`Invalid area "${area}". Options: ${areaNames}`);
18
- }
19
- return driver;
20
- };
21
- const resolveKey = (key) => {
22
- const deliminatorIndex = key.indexOf(":");
23
- const driverArea = key.substring(0, deliminatorIndex);
24
- const driverKey = key.substring(deliminatorIndex + 1);
25
- if (driverKey == null)
26
- throw Error(
27
- `Storage key should be in the form of "area:key", but received "${key}"`
28
- );
29
- return {
30
- driverArea,
31
- driverKey,
32
- driver: getDriver(driverArea)
33
- };
34
- };
35
- const getMetaKey = (key) => key + "$";
36
- const mergeMeta = (oldMeta, newMeta) => {
37
- const newFields = { ...oldMeta };
38
- Object.entries(newMeta).forEach(([key, value]) => {
39
- if (value == null) delete newFields[key];
40
- else newFields[key] = value;
41
- });
42
- return newFields;
43
- };
44
- const getValueOrFallback = (value, fallback) => value ?? fallback ?? null;
45
- const getMetaValue = (properties) => typeof properties === "object" && !Array.isArray(properties) ? properties : {};
46
- const getItem = async (driver, driverKey, opts) => {
47
- const res = await driver.getItem(driverKey);
48
- return getValueOrFallback(res, opts?.fallback ?? opts?.defaultValue);
49
- };
50
- const getMeta = async (driver, driverKey) => {
51
- const metaKey = getMetaKey(driverKey);
52
- const res = await driver.getItem(metaKey);
53
- return getMetaValue(res);
54
- };
55
- const setItem = async (driver, driverKey, value) => {
56
- await driver.setItem(driverKey, value ?? null);
57
- };
58
- const setMeta = async (driver, driverKey, properties) => {
59
- const metaKey = getMetaKey(driverKey);
60
- const existingFields = getMetaValue(await driver.getItem(metaKey));
61
- await driver.setItem(metaKey, mergeMeta(existingFields, properties));
62
- };
63
- const removeItem = async (driver, driverKey, opts) => {
64
- await driver.removeItem(driverKey);
65
- if (opts?.removeMeta) {
66
- const metaKey = getMetaKey(driverKey);
67
- await driver.removeItem(metaKey);
68
- }
69
- };
70
- const removeMeta = async (driver, driverKey, properties) => {
71
- const metaKey = getMetaKey(driverKey);
72
- if (properties == null) {
73
- await driver.removeItem(metaKey);
74
- } else {
75
- const newFields = getMetaValue(await driver.getItem(metaKey));
76
- [properties].flat().forEach((field) => delete newFields[field]);
77
- await driver.setItem(metaKey, newFields);
78
- }
79
- };
80
- const watch = (driver, driverKey, cb) => {
81
- return driver.watch(driverKey, cb);
82
- };
83
- const storage2 = {
84
- getItem: async (key, opts) => {
85
- const { driver, driverKey } = resolveKey(key);
86
- return await getItem(driver, driverKey, opts);
87
- },
88
- getItems: async (keys) => {
89
- const areaToKeyMap = /* @__PURE__ */ new Map();
90
- const keyToOptsMap = /* @__PURE__ */ new Map();
91
- const orderedKeys = [];
92
- keys.forEach((key) => {
93
- let keyStr;
94
- let opts;
95
- if (typeof key === "string") {
96
- keyStr = key;
97
- } else if ("getValue" in key) {
98
- keyStr = key.key;
99
- opts = { fallback: key.fallback };
100
- } else {
101
- keyStr = key.key;
102
- opts = key.options;
103
- }
104
- orderedKeys.push(keyStr);
105
- const { driverArea, driverKey } = resolveKey(keyStr);
106
- const areaKeys = areaToKeyMap.get(driverArea) ?? [];
107
- areaToKeyMap.set(driverArea, areaKeys.concat(driverKey));
108
- keyToOptsMap.set(keyStr, opts);
109
- });
110
- const resultsMap = /* @__PURE__ */ new Map();
111
- await Promise.all(
112
- Array.from(areaToKeyMap.entries()).map(async ([driverArea, keys2]) => {
113
- const driverResults = await drivers[driverArea].getItems(keys2);
114
- driverResults.forEach((driverResult) => {
115
- const key = `${driverArea}:${driverResult.key}`;
116
- const opts = keyToOptsMap.get(key);
117
- const value = getValueOrFallback(
118
- driverResult.value,
119
- opts?.fallback ?? opts?.defaultValue
120
- );
121
- resultsMap.set(key, value);
122
- });
123
- })
124
- );
125
- return orderedKeys.map((key) => ({
126
- key,
127
- value: resultsMap.get(key)
128
- }));
129
- },
130
- getMeta: async (key) => {
131
- const { driver, driverKey } = resolveKey(key);
132
- return await getMeta(driver, driverKey);
133
- },
134
- getMetas: async (args) => {
135
- const keys = args.map((arg) => {
136
- const key = typeof arg === "string" ? arg : arg.key;
137
- const { driverArea, driverKey } = resolveKey(key);
138
- return {
139
- key,
140
- driverArea,
141
- driverKey,
142
- driverMetaKey: getMetaKey(driverKey)
143
- };
144
- });
145
- const areaToDriverMetaKeysMap = keys.reduce((map, key) => {
146
- map[key.driverArea] ??= [];
147
- map[key.driverArea].push(key);
148
- return map;
149
- }, {});
150
- const resultsMap = {};
151
- await Promise.all(
152
- Object.entries(areaToDriverMetaKeysMap).map(async ([area, keys2]) => {
153
- const areaRes = await browser.storage[area].get(
154
- keys2.map((key) => key.driverMetaKey)
155
- );
156
- keys2.forEach((key) => {
157
- resultsMap[key.key] = areaRes[key.driverMetaKey] ?? {};
158
- });
159
- })
160
- );
161
- return keys.map((key) => ({
162
- key: key.key,
163
- meta: resultsMap[key.key]
164
- }));
165
- },
166
- setItem: async (key, value) => {
167
- const { driver, driverKey } = resolveKey(key);
168
- await setItem(driver, driverKey, value);
169
- },
170
- setItems: async (items) => {
171
- const areaToKeyValueMap = {};
172
- items.forEach((item) => {
173
- const { driverArea, driverKey } = resolveKey(
174
- "key" in item ? item.key : item.item.key
175
- );
176
- areaToKeyValueMap[driverArea] ??= [];
177
- areaToKeyValueMap[driverArea].push({
178
- key: driverKey,
179
- value: item.value
180
- });
181
- });
182
- await Promise.all(
183
- Object.entries(areaToKeyValueMap).map(async ([driverArea, values]) => {
184
- const driver = getDriver(driverArea);
185
- await driver.setItems(values);
186
- })
187
- );
188
- },
189
- setMeta: async (key, properties) => {
190
- const { driver, driverKey } = resolveKey(key);
191
- await setMeta(driver, driverKey, properties);
192
- },
193
- setMetas: async (items) => {
194
- const areaToMetaUpdatesMap = {};
195
- items.forEach((item) => {
196
- const { driverArea, driverKey } = resolveKey(
197
- "key" in item ? item.key : item.item.key
198
- );
199
- areaToMetaUpdatesMap[driverArea] ??= [];
200
- areaToMetaUpdatesMap[driverArea].push({
201
- key: driverKey,
202
- properties: item.meta
203
- });
204
- });
205
- await Promise.all(
206
- Object.entries(areaToMetaUpdatesMap).map(
207
- async ([storageArea, updates]) => {
208
- const driver = getDriver(storageArea);
209
- const metaKeys = updates.map(({ key }) => getMetaKey(key));
210
- const existingMetas = await driver.getItems(metaKeys);
211
- const existingMetaMap = Object.fromEntries(
212
- existingMetas.map(({ key, value }) => [key, getMetaValue(value)])
213
- );
214
- const metaUpdates = updates.map(({ key, properties }) => {
215
- const metaKey = getMetaKey(key);
216
- return {
217
- key: metaKey,
218
- value: mergeMeta(existingMetaMap[metaKey] ?? {}, properties)
219
- };
220
- });
221
- await driver.setItems(metaUpdates);
222
- }
223
- )
224
- );
225
- },
226
- removeItem: async (key, opts) => {
227
- const { driver, driverKey } = resolveKey(key);
228
- await removeItem(driver, driverKey, opts);
229
- },
230
- removeItems: async (keys) => {
231
- const areaToKeysMap = {};
232
- keys.forEach((key) => {
233
- let keyStr;
234
- let opts;
235
- if (typeof key === "string") {
236
- keyStr = key;
237
- } else if ("getValue" in key) {
238
- keyStr = key.key;
239
- } else if ("item" in key) {
240
- keyStr = key.item.key;
241
- opts = key.options;
242
- } else {
243
- keyStr = key.key;
244
- opts = key.options;
245
- }
246
- const { driverArea, driverKey } = resolveKey(keyStr);
247
- areaToKeysMap[driverArea] ??= [];
248
- areaToKeysMap[driverArea].push(driverKey);
249
- if (opts?.removeMeta) {
250
- areaToKeysMap[driverArea].push(getMetaKey(driverKey));
251
- }
252
- });
253
- await Promise.all(
254
- Object.entries(areaToKeysMap).map(async ([driverArea, keys2]) => {
255
- const driver = getDriver(driverArea);
256
- await driver.removeItems(keys2);
257
- })
258
- );
259
- },
260
- clear: async (base) => {
261
- const driver = getDriver(base);
262
- await driver.clear();
263
- },
264
- removeMeta: async (key, properties) => {
265
- const { driver, driverKey } = resolveKey(key);
266
- await removeMeta(driver, driverKey, properties);
267
- },
268
- snapshot: async (base, opts) => {
269
- const driver = getDriver(base);
270
- const data = await driver.snapshot();
271
- opts?.excludeKeys?.forEach((key) => {
272
- delete data[key];
273
- delete data[getMetaKey(key)];
274
- });
275
- return data;
276
- },
277
- restoreSnapshot: async (base, data) => {
278
- const driver = getDriver(base);
279
- await driver.restoreSnapshot(data);
280
- },
281
- watch: (key, cb) => {
282
- const { driver, driverKey } = resolveKey(key);
283
- return watch(driver, driverKey, cb);
284
- },
285
- unwatch() {
286
- Object.values(drivers).forEach((driver) => {
287
- driver.unwatch();
288
- });
289
- },
290
- defineItem: (key, opts) => {
291
- const { driver, driverKey } = resolveKey(key);
292
- const {
293
- version: targetVersion = 1,
294
- migrations = {},
295
- onMigrationComplete,
296
- debug = false
297
- } = opts ?? {};
298
- if (targetVersion < 1) {
299
- throw Error(
300
- "Storage item version cannot be less than 1. Initial versions should be set to 1, not 0."
301
- );
302
- }
303
- const migrate = async () => {
304
- const driverMetaKey = getMetaKey(driverKey);
305
- const [{ value }, { value: meta }] = await driver.getItems([
306
- driverKey,
307
- driverMetaKey
308
- ]);
309
- if (value == null) return;
310
- const currentVersion = meta?.v ?? 1;
311
- if (currentVersion > targetVersion) {
312
- throw Error(
313
- `Version downgrade detected (v${currentVersion} -> v${targetVersion}) for "${key}"`
314
- );
315
- }
316
- if (currentVersion === targetVersion) {
317
- return;
318
- }
319
- if (debug === true) {
320
- console.debug(
321
- `[@wxt-dev/storage] Running storage migration for ${key}: v${currentVersion} -> v${targetVersion}`
322
- );
323
- }
324
- const migrationsToRun = Array.from(
325
- { length: targetVersion - currentVersion },
326
- (_, i) => currentVersion + i + 1
327
- );
328
- let migratedValue = value;
329
- for (const migrateToVersion of migrationsToRun) {
330
- try {
331
- migratedValue = await migrations?.[migrateToVersion]?.(migratedValue) ?? migratedValue;
332
- if (debug === true) {
333
- console.debug(
334
- `[@wxt-dev/storage] Storage migration processed for version: v${migrateToVersion}`
335
- );
336
- }
337
- } catch (err) {
338
- throw new MigrationError(key, migrateToVersion, {
339
- cause: err
340
- });
341
- }
342
- }
343
- await driver.setItems([
344
- { key: driverKey, value: migratedValue },
345
- { key: driverMetaKey, value: { ...meta, v: targetVersion } }
346
- ]);
347
- if (debug === true) {
348
- console.debug(
349
- `[@wxt-dev/storage] Storage migration completed for ${key} v${targetVersion}`,
350
- { migratedValue }
351
- );
352
- }
353
- onMigrationComplete?.(migratedValue, targetVersion);
354
- };
355
- const migrationsDone = opts?.migrations == null ? Promise.resolve() : migrate().catch((err) => {
356
- console.error(
357
- `[@wxt-dev/storage] Migration failed for ${key}`,
358
- err
359
- );
360
- });
361
- const initMutex = new Mutex();
362
- const getFallback = () => opts?.fallback ?? opts?.defaultValue ?? null;
363
- const getOrInitValue = () => initMutex.runExclusive(async () => {
364
- const value = await driver.getItem(driverKey);
365
- if (value != null || opts?.init == null) return value;
366
- const newValue = await opts.init();
367
- await driver.setItem(driverKey, newValue);
368
- return newValue;
369
- });
370
- migrationsDone.then(getOrInitValue);
371
- return {
372
- key,
373
- get defaultValue() {
374
- return getFallback();
375
- },
376
- get fallback() {
377
- return getFallback();
378
- },
379
- getValue: async () => {
380
- await migrationsDone;
381
- if (opts?.init) {
382
- return await getOrInitValue();
383
- } else {
384
- return await getItem(driver, driverKey, opts);
385
- }
386
- },
387
- getMeta: async () => {
388
- await migrationsDone;
389
- return await getMeta(driver, driverKey);
390
- },
391
- setValue: async (value) => {
392
- await migrationsDone;
393
- return await setItem(driver, driverKey, value);
394
- },
395
- setMeta: async (properties) => {
396
- await migrationsDone;
397
- return await setMeta(driver, driverKey, properties);
398
- },
399
- removeValue: async (opts2) => {
400
- await migrationsDone;
401
- return await removeItem(driver, driverKey, opts2);
402
- },
403
- removeMeta: async (properties) => {
404
- await migrationsDone;
405
- return await removeMeta(driver, driverKey, properties);
406
- },
407
- watch: (cb) => watch(
408
- driver,
409
- driverKey,
410
- (newValue, oldValue) => cb(newValue ?? getFallback(), oldValue ?? getFallback())
411
- ),
412
- migrate
413
- };
414
- }
415
- };
416
- return storage2;
14
+ const drivers = {
15
+ local: createDriver("local"),
16
+ session: createDriver("session"),
17
+ sync: createDriver("sync"),
18
+ managed: createDriver("managed")
19
+ };
20
+ const getDriver = (area) => {
21
+ const driver = drivers[area];
22
+ if (driver == null) {
23
+ const areaNames = Object.keys(drivers).join(", ");
24
+ throw Error(`Invalid area "${area}". Options: ${areaNames}`);
25
+ }
26
+ return driver;
27
+ };
28
+ const resolveKey = (key) => {
29
+ const deliminatorIndex = key.indexOf(":");
30
+ const driverArea = key.substring(0, deliminatorIndex);
31
+ const driverKey = key.substring(deliminatorIndex + 1);
32
+ if (driverKey == null) throw Error(`Storage key should be in the form of "area:key", but received "${key}"`);
33
+ return {
34
+ driverArea,
35
+ driverKey,
36
+ driver: getDriver(driverArea)
37
+ };
38
+ };
39
+ const getMetaKey = (key) => key + "$";
40
+ const mergeMeta = (oldMeta, newMeta) => {
41
+ const newFields = { ...oldMeta };
42
+ Object.entries(newMeta).forEach(([key, value]) => {
43
+ if (value == null) delete newFields[key];
44
+ else newFields[key] = value;
45
+ });
46
+ return newFields;
47
+ };
48
+ const getValueOrFallback = (value, fallback) => value ?? fallback ?? null;
49
+ const getMetaValue = (properties) => typeof properties === "object" && !Array.isArray(properties) ? properties : {};
50
+ const getItem = async (driver, driverKey, opts) => {
51
+ return getValueOrFallback(await driver.getItem(driverKey), opts?.fallback ?? opts?.defaultValue);
52
+ };
53
+ const getMeta = async (driver, driverKey) => {
54
+ const metaKey = getMetaKey(driverKey);
55
+ return getMetaValue(await driver.getItem(metaKey));
56
+ };
57
+ const setItem = async (driver, driverKey, value) => {
58
+ await driver.setItem(driverKey, value ?? null);
59
+ };
60
+ const setMeta = async (driver, driverKey, properties) => {
61
+ const metaKey = getMetaKey(driverKey);
62
+ const existingFields = getMetaValue(await driver.getItem(metaKey));
63
+ await driver.setItem(metaKey, mergeMeta(existingFields, properties));
64
+ };
65
+ const removeItem = async (driver, driverKey, opts) => {
66
+ await driver.removeItem(driverKey);
67
+ if (opts?.removeMeta) {
68
+ const metaKey = getMetaKey(driverKey);
69
+ await driver.removeItem(metaKey);
70
+ }
71
+ };
72
+ const removeMeta = async (driver, driverKey, properties) => {
73
+ const metaKey = getMetaKey(driverKey);
74
+ if (properties == null) await driver.removeItem(metaKey);
75
+ else {
76
+ const newFields = getMetaValue(await driver.getItem(metaKey));
77
+ [properties].flat().forEach((field) => delete newFields[field]);
78
+ await driver.setItem(metaKey, newFields);
79
+ }
80
+ };
81
+ const watch = (driver, driverKey, cb) => driver.watch(driverKey, cb);
82
+ return {
83
+ getItem: async (key, opts) => {
84
+ const { driver, driverKey } = resolveKey(key);
85
+ return await getItem(driver, driverKey, opts);
86
+ },
87
+ getItems: async (keys) => {
88
+ const areaToKeyMap = /* @__PURE__ */ new Map();
89
+ const keyToOptsMap = /* @__PURE__ */ new Map();
90
+ const orderedKeys = [];
91
+ keys.forEach((key) => {
92
+ let keyStr;
93
+ let opts;
94
+ if (typeof key === "string") keyStr = key;
95
+ else if ("getValue" in key) {
96
+ keyStr = key.key;
97
+ opts = { fallback: key.fallback };
98
+ } else {
99
+ keyStr = key.key;
100
+ opts = key.options;
101
+ }
102
+ orderedKeys.push(keyStr);
103
+ const { driverArea, driverKey } = resolveKey(keyStr);
104
+ const areaKeys = areaToKeyMap.get(driverArea) ?? [];
105
+ areaToKeyMap.set(driverArea, areaKeys.concat(driverKey));
106
+ keyToOptsMap.set(keyStr, opts);
107
+ });
108
+ const resultsMap = /* @__PURE__ */ new Map();
109
+ await Promise.all(Array.from(areaToKeyMap.entries()).map(async ([driverArea, keys]) => {
110
+ (await drivers[driverArea].getItems(keys)).forEach((driverResult) => {
111
+ const key = `${driverArea}:${driverResult.key}`;
112
+ const opts = keyToOptsMap.get(key);
113
+ const value = getValueOrFallback(driverResult.value, opts?.fallback ?? opts?.defaultValue);
114
+ resultsMap.set(key, value);
115
+ });
116
+ }));
117
+ return orderedKeys.map((key) => ({
118
+ key,
119
+ value: resultsMap.get(key)
120
+ }));
121
+ },
122
+ getMeta: async (key) => {
123
+ const { driver, driverKey } = resolveKey(key);
124
+ return await getMeta(driver, driverKey);
125
+ },
126
+ getMetas: async (args) => {
127
+ const keys = args.map((arg) => {
128
+ const key = typeof arg === "string" ? arg : arg.key;
129
+ const { driverArea, driverKey } = resolveKey(key);
130
+ return {
131
+ key,
132
+ driverArea,
133
+ driverKey,
134
+ driverMetaKey: getMetaKey(driverKey)
135
+ };
136
+ });
137
+ const areaToDriverMetaKeysMap = keys.reduce((map, key) => {
138
+ map[key.driverArea] ??= [];
139
+ map[key.driverArea].push(key);
140
+ return map;
141
+ }, {});
142
+ const resultsMap = {};
143
+ await Promise.all(Object.entries(areaToDriverMetaKeysMap).map(async ([area, keys]) => {
144
+ const areaRes = await browser.storage[area].get(keys.map((key) => key.driverMetaKey));
145
+ keys.forEach((key) => {
146
+ resultsMap[key.key] = areaRes[key.driverMetaKey] ?? {};
147
+ });
148
+ }));
149
+ return keys.map((key) => ({
150
+ key: key.key,
151
+ meta: resultsMap[key.key]
152
+ }));
153
+ },
154
+ setItem: async (key, value) => {
155
+ const { driver, driverKey } = resolveKey(key);
156
+ await setItem(driver, driverKey, value);
157
+ },
158
+ setItems: async (items) => {
159
+ const areaToKeyValueMap = {};
160
+ items.forEach((item) => {
161
+ const { driverArea, driverKey } = resolveKey("key" in item ? item.key : item.item.key);
162
+ areaToKeyValueMap[driverArea] ??= [];
163
+ areaToKeyValueMap[driverArea].push({
164
+ key: driverKey,
165
+ value: item.value
166
+ });
167
+ });
168
+ await Promise.all(Object.entries(areaToKeyValueMap).map(async ([driverArea, values]) => {
169
+ await getDriver(driverArea).setItems(values);
170
+ }));
171
+ },
172
+ setMeta: async (key, properties) => {
173
+ const { driver, driverKey } = resolveKey(key);
174
+ await setMeta(driver, driverKey, properties);
175
+ },
176
+ setMetas: async (items) => {
177
+ const areaToMetaUpdatesMap = {};
178
+ items.forEach((item) => {
179
+ const { driverArea, driverKey } = resolveKey("key" in item ? item.key : item.item.key);
180
+ areaToMetaUpdatesMap[driverArea] ??= [];
181
+ areaToMetaUpdatesMap[driverArea].push({
182
+ key: driverKey,
183
+ properties: item.meta
184
+ });
185
+ });
186
+ await Promise.all(Object.entries(areaToMetaUpdatesMap).map(async ([storageArea, updates]) => {
187
+ const driver = getDriver(storageArea);
188
+ const metaKeys = updates.map(({ key }) => getMetaKey(key));
189
+ const existingMetas = await driver.getItems(metaKeys);
190
+ const existingMetaMap = Object.fromEntries(existingMetas.map(({ key, value }) => [key, getMetaValue(value)]));
191
+ const metaUpdates = updates.map(({ key, properties }) => {
192
+ const metaKey = getMetaKey(key);
193
+ return {
194
+ key: metaKey,
195
+ value: mergeMeta(existingMetaMap[metaKey] ?? {}, properties)
196
+ };
197
+ });
198
+ await driver.setItems(metaUpdates);
199
+ }));
200
+ },
201
+ removeItem: async (key, opts) => {
202
+ const { driver, driverKey } = resolveKey(key);
203
+ await removeItem(driver, driverKey, opts);
204
+ },
205
+ removeItems: async (keys) => {
206
+ const areaToKeysMap = {};
207
+ keys.forEach((key) => {
208
+ let keyStr;
209
+ let opts;
210
+ if (typeof key === "string") keyStr = key;
211
+ else if ("getValue" in key) keyStr = key.key;
212
+ else if ("item" in key) {
213
+ keyStr = key.item.key;
214
+ opts = key.options;
215
+ } else {
216
+ keyStr = key.key;
217
+ opts = key.options;
218
+ }
219
+ const { driverArea, driverKey } = resolveKey(keyStr);
220
+ areaToKeysMap[driverArea] ??= [];
221
+ areaToKeysMap[driverArea].push(driverKey);
222
+ if (opts?.removeMeta) areaToKeysMap[driverArea].push(getMetaKey(driverKey));
223
+ });
224
+ await Promise.all(Object.entries(areaToKeysMap).map(async ([driverArea, keys]) => {
225
+ await getDriver(driverArea).removeItems(keys);
226
+ }));
227
+ },
228
+ clear: async (base) => {
229
+ await getDriver(base).clear();
230
+ },
231
+ removeMeta: async (key, properties) => {
232
+ const { driver, driverKey } = resolveKey(key);
233
+ await removeMeta(driver, driverKey, properties);
234
+ },
235
+ snapshot: async (base, opts) => {
236
+ const data = await getDriver(base).snapshot();
237
+ opts?.excludeKeys?.forEach((key) => {
238
+ delete data[key];
239
+ delete data[getMetaKey(key)];
240
+ });
241
+ return data;
242
+ },
243
+ restoreSnapshot: async (base, data) => {
244
+ await getDriver(base).restoreSnapshot(data);
245
+ },
246
+ watch: (key, cb) => {
247
+ const { driver, driverKey } = resolveKey(key);
248
+ return watch(driver, driverKey, cb);
249
+ },
250
+ unwatch() {
251
+ Object.values(drivers).forEach((driver) => {
252
+ driver.unwatch();
253
+ });
254
+ },
255
+ defineItem: (key, opts) => {
256
+ const { driver, driverKey } = resolveKey(key);
257
+ const { version: targetVersion = 1, migrations = {}, onMigrationComplete, debug = false } = opts ?? {};
258
+ if (targetVersion < 1) throw Error("Storage item version cannot be less than 1. Initial versions should be set to 1, not 0.");
259
+ const migrate = async () => {
260
+ const driverMetaKey = getMetaKey(driverKey);
261
+ const [{ value }, { value: meta }] = await driver.getItems([driverKey, driverMetaKey]);
262
+ if (value == null) return;
263
+ const currentVersion = meta?.v ?? 1;
264
+ if (currentVersion > targetVersion) throw Error(`Version downgrade detected (v${currentVersion} -> v${targetVersion}) for "${key}"`);
265
+ if (currentVersion === targetVersion) return;
266
+ if (debug) console.debug(`[@wxt-dev/storage] Running storage migration for ${key}: v${currentVersion} -> v${targetVersion}`);
267
+ const migrationsToRun = Array.from({ length: targetVersion - currentVersion }, (_, i) => currentVersion + i + 1);
268
+ let migratedValue = value;
269
+ for (const migrateToVersion of migrationsToRun) try {
270
+ migratedValue = await migrations?.[migrateToVersion]?.(migratedValue) ?? migratedValue;
271
+ if (debug) console.debug(`[@wxt-dev/storage] Storage migration processed for version: v${migrateToVersion}`);
272
+ } catch (err) {
273
+ throw new MigrationError(key, migrateToVersion, { cause: err });
274
+ }
275
+ await driver.setItems([{
276
+ key: driverKey,
277
+ value: migratedValue
278
+ }, {
279
+ key: driverMetaKey,
280
+ value: {
281
+ ...meta,
282
+ v: targetVersion
283
+ }
284
+ }]);
285
+ if (debug) console.debug(`[@wxt-dev/storage] Storage migration completed for ${key} v${targetVersion}`, { migratedValue });
286
+ onMigrationComplete?.(migratedValue, targetVersion);
287
+ };
288
+ const migrationsDone = opts?.migrations == null ? Promise.resolve() : migrate().catch((err) => {
289
+ console.error(`[@wxt-dev/storage] Migration failed for ${key}`, err);
290
+ });
291
+ const initMutex = new Mutex();
292
+ const getFallback = () => opts?.fallback ?? opts?.defaultValue ?? null;
293
+ const getOrInitValue = () => initMutex.runExclusive(async () => {
294
+ const value = await driver.getItem(driverKey);
295
+ if (value != null || opts?.init == null) return value;
296
+ const newValue = await opts.init();
297
+ await driver.setItem(driverKey, newValue);
298
+ if (value == null && targetVersion > 1) await setMeta(driver, driverKey, { v: targetVersion });
299
+ return newValue;
300
+ });
301
+ migrationsDone.then(getOrInitValue);
302
+ return {
303
+ key,
304
+ get defaultValue() {
305
+ return getFallback();
306
+ },
307
+ get fallback() {
308
+ return getFallback();
309
+ },
310
+ getValue: async () => {
311
+ await migrationsDone;
312
+ if (opts?.init) return await getOrInitValue();
313
+ else return await getItem(driver, driverKey, opts);
314
+ },
315
+ getMeta: async () => {
316
+ await migrationsDone;
317
+ return await getMeta(driver, driverKey);
318
+ },
319
+ setValue: async (value) => {
320
+ await migrationsDone;
321
+ return await setItem(driver, driverKey, value);
322
+ },
323
+ setMeta: async (properties) => {
324
+ await migrationsDone;
325
+ return await setMeta(driver, driverKey, properties);
326
+ },
327
+ removeValue: async (opts) => {
328
+ await migrationsDone;
329
+ return await removeItem(driver, driverKey, opts);
330
+ },
331
+ removeMeta: async (properties) => {
332
+ await migrationsDone;
333
+ return await removeMeta(driver, driverKey, properties);
334
+ },
335
+ watch: (cb) => watch(driver, driverKey, (newValue, oldValue) => cb(newValue ?? getFallback(), oldValue ?? getFallback())),
336
+ migrate
337
+ };
338
+ }
339
+ };
417
340
  }
418
341
  function createDriver(storageArea) {
419
- const getStorageArea = () => {
420
- if (browser.runtime == null) {
421
- throw Error(
422
- [
423
- "'wxt/storage' must be loaded in a web extension environment",
424
- "\n - If thrown during a build, see https://github.com/wxt-dev/wxt/issues/371",
425
- " - If thrown during tests, mock 'wxt/browser' correctly. See https://wxt.dev/guide/go-further/testing.html\n"
426
- ].join("\n")
427
- );
428
- }
429
- if (browser.storage == null) {
430
- throw Error(
431
- "You must add the 'storage' permission to your manifest to use 'wxt/storage'"
432
- );
433
- }
434
- const area = browser.storage[storageArea];
435
- if (area == null)
436
- throw Error(`"browser.storage.${storageArea}" is undefined`);
437
- return area;
438
- };
439
- const watchListeners = /* @__PURE__ */ new Set();
440
- return {
441
- getItem: async (key) => {
442
- const res = await getStorageArea().get(key);
443
- return res[key];
444
- },
445
- getItems: async (keys) => {
446
- const result = await getStorageArea().get(keys);
447
- return keys.map((key) => ({ key, value: result[key] ?? null }));
448
- },
449
- setItem: async (key, value) => {
450
- if (value == null) {
451
- await getStorageArea().remove(key);
452
- } else {
453
- await getStorageArea().set({ [key]: value });
454
- }
455
- },
456
- setItems: async (values) => {
457
- const map = values.reduce(
458
- (map2, { key, value }) => {
459
- map2[key] = value;
460
- return map2;
461
- },
462
- {}
463
- );
464
- await getStorageArea().set(map);
465
- },
466
- removeItem: async (key) => {
467
- await getStorageArea().remove(key);
468
- },
469
- removeItems: async (keys) => {
470
- await getStorageArea().remove(keys);
471
- },
472
- clear: async () => {
473
- await getStorageArea().clear();
474
- },
475
- snapshot: async () => {
476
- return await getStorageArea().get();
477
- },
478
- restoreSnapshot: async (data) => {
479
- await getStorageArea().set(data);
480
- },
481
- watch(key, cb) {
482
- const listener = (changes) => {
483
- const change = changes[key];
484
- if (change == null) return;
485
- if (dequal(change.newValue, change.oldValue)) return;
486
- cb(change.newValue ?? null, change.oldValue ?? null);
487
- };
488
- getStorageArea().onChanged.addListener(listener);
489
- watchListeners.add(listener);
490
- return () => {
491
- getStorageArea().onChanged.removeListener(listener);
492
- watchListeners.delete(listener);
493
- };
494
- },
495
- unwatch() {
496
- watchListeners.forEach((listener) => {
497
- getStorageArea().onChanged.removeListener(listener);
498
- });
499
- watchListeners.clear();
500
- }
501
- };
502
- }
503
- class MigrationError extends Error {
504
- constructor(key, version, options) {
505
- super(`v${version} migration failed for "${key}"`, options);
506
- this.key = key;
507
- this.version = version;
508
- }
342
+ const getStorageArea = () => {
343
+ if (browser.runtime == null) throw Error(`'wxt/storage' must be loaded in a web extension environment
344
+
345
+ - If thrown during a build, see https://github.com/wxt-dev/wxt/issues/371
346
+ - If thrown during tests, mock 'wxt/browser' correctly. See https://wxt.dev/guide/go-further/testing.html
347
+ `);
348
+ if (browser.storage == null) throw Error("You must add the 'storage' permission to your manifest to use 'wxt/storage'");
349
+ const area = browser.storage[storageArea];
350
+ if (area == null) throw Error(`"browser.storage.${storageArea}" is undefined`);
351
+ return area;
352
+ };
353
+ const watchListeners = /* @__PURE__ */ new Set();
354
+ return {
355
+ getItem: async (key) => {
356
+ return (await getStorageArea().get(key))[key];
357
+ },
358
+ getItems: async (keys) => {
359
+ const result = await getStorageArea().get(keys);
360
+ return keys.map((key) => ({
361
+ key,
362
+ value: result[key] ?? null
363
+ }));
364
+ },
365
+ setItem: async (key, value) => {
366
+ if (value == null) await getStorageArea().remove(key);
367
+ else await getStorageArea().set({ [key]: value });
368
+ },
369
+ setItems: async (values) => {
370
+ const map = values.reduce((map, { key, value }) => {
371
+ map[key] = value;
372
+ return map;
373
+ }, {});
374
+ await getStorageArea().set(map);
375
+ },
376
+ removeItem: async (key) => {
377
+ await getStorageArea().remove(key);
378
+ },
379
+ removeItems: async (keys) => {
380
+ await getStorageArea().remove(keys);
381
+ },
382
+ clear: async () => {
383
+ await getStorageArea().clear();
384
+ },
385
+ snapshot: async () => {
386
+ return await getStorageArea().get();
387
+ },
388
+ restoreSnapshot: async (data) => {
389
+ await getStorageArea().set(data);
390
+ },
391
+ watch(key, cb) {
392
+ const listener = (changes) => {
393
+ const change = changes[key];
394
+ if (change == null || dequal(change.newValue, change.oldValue)) return;
395
+ cb(change.newValue ?? null, change.oldValue ?? null);
396
+ };
397
+ getStorageArea().onChanged.addListener(listener);
398
+ watchListeners.add(listener);
399
+ return () => {
400
+ getStorageArea().onChanged.removeListener(listener);
401
+ watchListeners.delete(listener);
402
+ };
403
+ },
404
+ unwatch() {
405
+ watchListeners.forEach((listener) => {
406
+ getStorageArea().onChanged.removeListener(listener);
407
+ });
408
+ watchListeners.clear();
409
+ }
410
+ };
509
411
  }
412
+ var MigrationError = class extends Error {
413
+ constructor(key, version, options) {
414
+ super(`v${version} migration failed for "${key}"`, options);
415
+ this.key = key;
416
+ this.version = version;
417
+ }
418
+ };
510
419
 
511
- export { MigrationError, storage };
420
+ //#endregion
421
+ export { MigrationError, storage };