@wxt-dev/storage 1.1.0 → 1.2.0

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.d.mts CHANGED
@@ -1,3 +1,5 @@
1
+ import { Browser } from '@wxt-dev/browser';
2
+
1
3
  declare const storage: WxtStorage;
2
4
  interface WxtStorage {
3
5
  /**
@@ -141,7 +143,13 @@ interface WxtStorage {
141
143
  * Read full docs: https://wxt.dev/storage.html#defining-storage-items
142
144
  */
143
145
  defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey): WxtStorageItem<TValue | null, TMetadata>;
144
- defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue, TMetadata>;
146
+ defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue> & {
147
+ fallback: TValue;
148
+ }): WxtStorageItem<TValue, TMetadata>;
149
+ defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue> & {
150
+ defaultValue: TValue;
151
+ }): WxtStorageItem<TValue, TMetadata>;
152
+ defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue | null, TMetadata>;
145
153
  }
146
154
  interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
147
155
  /**
@@ -244,9 +252,18 @@ interface WxtStorageItemOptions<T> {
244
252
  * A map of version numbers to the functions used to migrate the data to that version.
245
253
  */
246
254
  migrations?: Record<number, (oldValue: any) => any>;
255
+ /**
256
+ * Print debug logs, such as migration process.
257
+ * @default false
258
+ */
259
+ debug?: boolean;
260
+ /**
261
+ * A callback function that runs on migration complete.
262
+ */
263
+ onMigrationComplete?: (migratedValue: T, targetVersion: number) => void;
247
264
  }
248
265
  type StorageAreaChanges = {
249
- [key: string]: chrome.storage.StorageChange;
266
+ [key: string]: Browser.storage.StorageChange;
250
267
  };
251
268
  /**
252
269
  * Same as `Partial`, but includes `| null`. It makes all the properties of an object optional and
@@ -269,4 +286,5 @@ declare class MigrationError extends Error {
269
286
  constructor(key: string, version: number, options?: ErrorOptions);
270
287
  }
271
288
 
272
- export { type GetItemOptions, MigrationError, type RemoveItemOptions, type SnapshotOptions, type StorageArea, type StorageAreaChanges, type StorageItemKey, type Unwatch, type WatchCallback, type WxtStorage, type WxtStorageItem, type WxtStorageItemOptions, storage };
289
+ export { MigrationError, storage };
290
+ export type { GetItemOptions, RemoveItemOptions, SnapshotOptions, StorageArea, StorageAreaChanges, StorageItemKey, Unwatch, WatchCallback, WxtStorage, WxtStorageItem, WxtStorageItemOptions };
package/dist/index.d.ts CHANGED
@@ -1,3 +1,5 @@
1
+ import { Browser } from '@wxt-dev/browser';
2
+
1
3
  declare const storage: WxtStorage;
2
4
  interface WxtStorage {
3
5
  /**
@@ -141,7 +143,13 @@ interface WxtStorage {
141
143
  * Read full docs: https://wxt.dev/storage.html#defining-storage-items
142
144
  */
143
145
  defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey): WxtStorageItem<TValue | null, TMetadata>;
144
- defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue, TMetadata>;
146
+ defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue> & {
147
+ fallback: TValue;
148
+ }): WxtStorageItem<TValue, TMetadata>;
149
+ defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue> & {
150
+ defaultValue: TValue;
151
+ }): WxtStorageItem<TValue, TMetadata>;
152
+ defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue | null, TMetadata>;
145
153
  }
146
154
  interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
147
155
  /**
@@ -244,9 +252,18 @@ interface WxtStorageItemOptions<T> {
244
252
  * A map of version numbers to the functions used to migrate the data to that version.
245
253
  */
246
254
  migrations?: Record<number, (oldValue: any) => any>;
255
+ /**
256
+ * Print debug logs, such as migration process.
257
+ * @default false
258
+ */
259
+ debug?: boolean;
260
+ /**
261
+ * A callback function that runs on migration complete.
262
+ */
263
+ onMigrationComplete?: (migratedValue: T, targetVersion: number) => void;
247
264
  }
248
265
  type StorageAreaChanges = {
249
- [key: string]: chrome.storage.StorageChange;
266
+ [key: string]: Browser.storage.StorageChange;
250
267
  };
251
268
  /**
252
269
  * Same as `Partial`, but includes `| null`. It makes all the properties of an object optional and
@@ -269,4 +286,5 @@ declare class MigrationError extends Error {
269
286
  constructor(key: string, version: number, options?: ErrorOptions);
270
287
  }
271
288
 
272
- export { type GetItemOptions, MigrationError, type RemoveItemOptions, type SnapshotOptions, type StorageArea, type StorageAreaChanges, type StorageItemKey, type Unwatch, type WatchCallback, type WxtStorage, type WxtStorageItem, type WxtStorageItemOptions, storage };
289
+ export { MigrationError, storage };
290
+ export type { GetItemOptions, RemoveItemOptions, SnapshotOptions, StorageArea, StorageAreaChanges, StorageItemKey, Unwatch, WatchCallback, WxtStorage, WxtStorageItem, WxtStorageItemOptions };
package/dist/index.mjs CHANGED
@@ -1,13 +1,7 @@
1
1
  import { dequal } from 'dequal/lite';
2
2
  import { Mutex } from 'async-mutex';
3
+ import { browser } from '@wxt-dev/browser';
3
4
 
4
- const browser = (
5
- // @ts-expect-error
6
- globalThis.browser?.runtime?.id == null ? globalThis.chrome : (
7
- // @ts-expect-error
8
- globalThis.browser
9
- )
10
- );
11
5
  const storage = createStorage();
12
6
  function createStorage() {
13
7
  const drivers = {
@@ -42,10 +36,8 @@ function createStorage() {
42
36
  const mergeMeta = (oldMeta, newMeta) => {
43
37
  const newFields = { ...oldMeta };
44
38
  Object.entries(newMeta).forEach(([key, value]) => {
45
- if (value == null)
46
- delete newFields[key];
47
- else
48
- newFields[key] = value;
39
+ if (value == null) delete newFields[key];
40
+ else newFields[key] = value;
49
41
  });
50
42
  return newFields;
51
43
  };
@@ -151,8 +143,7 @@ function createStorage() {
151
143
  };
152
144
  });
153
145
  const areaToDriverMetaKeysMap = keys.reduce((map, key) => {
154
- var _a;
155
- map[_a = key.driverArea] ?? (map[_a] = []);
146
+ map[key.driverArea] ??= [];
156
147
  map[key.driverArea].push(key);
157
148
  return map;
158
149
  }, {});
@@ -182,7 +173,7 @@ function createStorage() {
182
173
  const { driverArea, driverKey } = resolveKey(
183
174
  "key" in item ? item.key : item.item.key
184
175
  );
185
- areaToKeyValueMap[driverArea] ?? (areaToKeyValueMap[driverArea] = []);
176
+ areaToKeyValueMap[driverArea] ??= [];
186
177
  areaToKeyValueMap[driverArea].push({
187
178
  key: driverKey,
188
179
  value: item.value
@@ -205,7 +196,7 @@ function createStorage() {
205
196
  const { driverArea, driverKey } = resolveKey(
206
197
  "key" in item ? item.key : item.item.key
207
198
  );
208
- areaToMetaUpdatesMap[driverArea] ?? (areaToMetaUpdatesMap[driverArea] = []);
199
+ areaToMetaUpdatesMap[driverArea] ??= [];
209
200
  areaToMetaUpdatesMap[driverArea].push({
210
201
  key: driverKey,
211
202
  properties: item.meta
@@ -216,7 +207,6 @@ function createStorage() {
216
207
  async ([storageArea, updates]) => {
217
208
  const driver = getDriver(storageArea);
218
209
  const metaKeys = updates.map(({ key }) => getMetaKey(key));
219
- console.log(storageArea, metaKeys);
220
210
  const existingMetas = await driver.getItems(metaKeys);
221
211
  const existingMetaMap = Object.fromEntries(
222
212
  existingMetas.map(({ key, value }) => [key, getMetaValue(value)])
@@ -254,7 +244,7 @@ function createStorage() {
254
244
  opts = key.options;
255
245
  }
256
246
  const { driverArea, driverKey } = resolveKey(keyStr);
257
- areaToKeysMap[driverArea] ?? (areaToKeysMap[driverArea] = []);
247
+ areaToKeysMap[driverArea] ??= [];
258
248
  areaToKeysMap[driverArea].push(driverKey);
259
249
  if (opts?.removeMeta) {
260
250
  areaToKeysMap[driverArea].push(getMetaKey(driverKey));
@@ -299,7 +289,12 @@ function createStorage() {
299
289
  },
300
290
  defineItem: (key, opts) => {
301
291
  const { driver, driverKey } = resolveKey(key);
302
- const { version: targetVersion = 1, migrations = {} } = opts ?? {};
292
+ const {
293
+ version: targetVersion = 1,
294
+ migrations = {},
295
+ onMigrationComplete,
296
+ debug = false
297
+ } = opts ?? {};
303
298
  if (targetVersion < 1) {
304
299
  throw Error(
305
300
  "Storage item version cannot be less than 1. Initial versions should be set to 1, not 0."
@@ -311,17 +306,21 @@ function createStorage() {
311
306
  driverKey,
312
307
  driverMetaKey
313
308
  ]);
314
- if (value == null)
315
- return;
309
+ if (value == null) return;
316
310
  const currentVersion = meta?.v ?? 1;
317
311
  if (currentVersion > targetVersion) {
318
312
  throw Error(
319
313
  `Version downgrade detected (v${currentVersion} -> v${targetVersion}) for "${key}"`
320
314
  );
321
315
  }
322
- console.debug(
323
- `[@wxt-dev/storage] Running storage migration for ${key}: v${currentVersion} -> v${targetVersion}`
324
- );
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
+ }
325
324
  const migrationsToRun = Array.from(
326
325
  { length: targetVersion - currentVersion },
327
326
  (_, i) => currentVersion + i + 1
@@ -330,8 +329,13 @@ function createStorage() {
330
329
  for (const migrateToVersion of migrationsToRun) {
331
330
  try {
332
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
+ }
333
337
  } catch (err) {
334
- throw Error(`v${migrateToVersion} migration failed for "${key}"`, {
338
+ throw new MigrationError(key, migrateToVersion, {
335
339
  cause: err
336
340
  });
337
341
  }
@@ -340,10 +344,13 @@ function createStorage() {
340
344
  { key: driverKey, value: migratedValue },
341
345
  { key: driverMetaKey, value: { ...meta, v: targetVersion } }
342
346
  ]);
343
- console.debug(
344
- `[@wxt-dev/storage] Storage migration completed for ${key} v${targetVersion}`,
345
- { migratedValue }
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);
347
354
  };
348
355
  const migrationsDone = opts?.migrations == null ? Promise.resolve() : migrate().catch((err) => {
349
356
  console.error(
@@ -355,8 +362,7 @@ function createStorage() {
355
362
  const getFallback = () => opts?.fallback ?? opts?.defaultValue ?? null;
356
363
  const getOrInitValue = () => initMutex.runExclusive(async () => {
357
364
  const value = await driver.getItem(driverKey);
358
- if (value != null || opts?.init == null)
359
- return value;
365
+ if (value != null || opts?.init == null) return value;
360
366
  const newValue = await opts.init();
361
367
  await driver.setItem(driverKey, newValue);
362
368
  return newValue;
@@ -475,10 +481,8 @@ function createDriver(storageArea) {
475
481
  watch(key, cb) {
476
482
  const listener = (changes) => {
477
483
  const change = changes[key];
478
- if (change == null)
479
- return;
480
- if (dequal(change.newValue, change.oldValue))
481
- return;
484
+ if (change == null) return;
485
+ if (dequal(change.newValue, change.oldValue)) return;
482
486
  cb(change.newValue ?? null, change.oldValue ?? null);
483
487
  };
484
488
  getStorageArea().onChanged.addListener(listener);
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@wxt-dev/storage",
3
3
  "description": "Web extension storage API provided by WXT, supports all browsers.",
4
- "version": "1.1.0",
4
+ "version": "1.2.0",
5
5
  "type": "module",
6
6
  "repository": {
7
7
  "type": "git",
@@ -23,19 +23,20 @@
23
23
  "email": "aaronklinker1+wxt@gmail.com"
24
24
  },
25
25
  "license": "MIT",
26
+ "funding": "https://github.com/sponsors/wxt-dev",
26
27
  "dependencies": {
27
28
  "async-mutex": "^0.5.0",
28
- "dequal": "^2.0.3"
29
+ "dequal": "^2.0.3",
30
+ "@wxt-dev/browser": "^0.1.4"
29
31
  },
30
32
  "devDependencies": {
31
- "@aklinker1/check": "^1.4.5",
32
- "@types/chrome": "^0.0.268",
33
- "@webext-core/fake-browser": "^1.3.1",
34
- "oxlint": "^0.9.9",
35
- "publint": "^0.2.11",
36
- "typescript": "^5.6.2",
37
- "unbuild": "^2.0.0",
38
- "vitest": "^2.0.0"
33
+ "@aklinker1/check": "^2.1.0",
34
+ "@webext-core/fake-browser": "^1.3.2",
35
+ "oxlint": "^1.14.0",
36
+ "publint": "^0.3.12",
37
+ "typescript": "^5.9.2",
38
+ "unbuild": "^3.6.1",
39
+ "vitest": "^3.2.4"
39
40
  },
40
41
  "module": "./dist/index.mjs",
41
42
  "types": "./dist/index.d.ts",