wxt 0.12.5 → 0.13.0

package/dist/{chunk-JK5CNMJT.js → chunk-GNIOSZT6.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.12.5";
+var version = "0.13.0";
 
 // src/core/utils/arrays.ts
 function every(array, predicate) {

package/dist/cli.js

@@ -4,7 +4,7 @@ import "./chunk-VBXJIVYU.js";
 import cac from "cac";
 
 // package.json
-var version = "0.12.5";
+var version = "0.13.0";
 
 // src/core/utils/fs.ts
 import fs from "fs-extra";

package/dist/index.cjs

@@ -4334,7 +4334,7 @@ function getChunkSortWeight(filename) {
 var import_picocolors3 = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "0.12.5";
+var version = "0.13.0";
 
 // src/core/utils/log/printHeader.ts
 var import_consola2 = require("consola");

package/dist/index.d.cts

@@ -62,6 +62,6 @@ declare function prepare(config: InlineConfig): Promise<void>;
  */
 declare function zip(config?: InlineConfig): Promise<string[]>;
 
-var version = "0.12.5";
+var version = "0.13.0";
 
 export { BuildOutput, ExtensionRunnerConfig, InlineConfig, UserConfig, WxtDevServer, build, clean, createServer, defineConfig, defineRunnerConfig, initialize, prepare, version, zip };

package/dist/index.d.ts

@@ -62,6 +62,6 @@ declare function prepare(config: InlineConfig): Promise<void>;
  */
 declare function zip(config?: InlineConfig): Promise<string[]>;
 
-var version = "0.12.5";
+var version = "0.13.0";
 
 export { BuildOutput, ExtensionRunnerConfig, InlineConfig, UserConfig, WxtDevServer, build, clean, createServer, defineConfig, defineRunnerConfig, initialize, prepare, version, zip };

package/dist/index.js

@@ -15,7 +15,7 @@ import {
   rebuild,
   resolvePerBrowserOption,
   version
-} from "./chunk-JK5CNMJT.js";
+} from "./chunk-GNIOSZT6.js";
 import "./chunk-VBXJIVYU.js";
 
 // src/core/build.ts

package/dist/storage.cjs

@@ -17,7 +17,6 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
 var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
   // If the importer is in node compatibility mode or this is not an ESM
   // file that has been converted to a CommonJS file using a Babel-
@@ -31,111 +30,339 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/storage.ts
 var storage_exports = {};
 __export(storage_exports, {
-  storage: () => storage,
-  webExtensionDriver: () => webExtensionDriver
+  storage: () => storage
 });
 module.exports = __toCommonJS(storage_exports);
-var import_unstorage = require("unstorage");
 
 // src/browser.ts
 var import_webextension_polyfill = __toESM(require("webextension-polyfill"), 1);
 var browser = import_webextension_polyfill.default;
 
 // src/storage.ts
-__reExport(storage_exports, require("unstorage"), module.exports);
-var webExtensionDriver = (0, import_unstorage.defineDriver)((opts) => {
-  const checkPermission = () => {
-    if (browser.storage == null)
+var import_lite = require("dequal/lite");
+var storage = createStorage();
+function createStorage() {
+  const drivers = {
+    local: createDriver("local"),
+    session: createDriver("session"),
+    sync: createDriver("sync"),
+    managed: createDriver("managed")
+  };
+  const getDriver = (area) => {
+    const driver = drivers[area];
+    if (driver == null) {
+      const areaNames = Object.keys(drivers).join(", ");
+      throw Error(`Invalid area "${area}". Options: ${areaNames}`);
+    }
+    return driver;
+  };
+  const resolveKey = (key) => {
+    const [driverArea, driverKey] = key.split(":", 2);
+    if (driverKey == null)
       throw Error(
-        "You must request the 'storage' permission to use webExtensionDriver"
+        `Storage key should be in the form of "area:key", but recieved "${key}"`
       );
+    return {
+      driverArea,
+      driverKey,
+      driver: getDriver(driverArea)
+    };
   };
-  const _storageListener = (changes) => {
-    Object.entries(changes).forEach(([key, { newValue }]) => {
-      _listeners.forEach((callback) => {
-        callback(newValue ? "update" : "remove", key);
-      });
+  const getMetaKey = (key) => key + "$";
+  const getValueOrDefault = (value, defaultValue) => value ?? defaultValue ?? null;
+  const getMetaValue = (properties) => typeof properties === "object" && !Array.isArray(properties) ? properties : {};
+  const getItem = async (driver, driverKey, opts) => {
+    const res = await driver.getItem(driverKey);
+    return getValueOrDefault(res, opts?.defaultValue);
+  };
+  const getMeta = async (driver, driverKey) => {
+    const metaKey = getMetaKey(driverKey);
+    const res = await driver.getItem(metaKey);
+    return getMetaValue(res);
+  };
+  const setItem = async (driver, driverKey, value) => {
+    await driver.setItem(driverKey, value ?? null);
+  };
+  const setMeta = async (driver, driverKey, properties) => {
+    const metaKey = getMetaKey(driverKey);
+    const existingFields = getMetaValue(await driver.getItem(metaKey));
+    const newFields = { ...existingFields };
+    Object.entries(properties).forEach(([key, value]) => {
+      if (value == null) {
+        delete newFields[key];
+      } else {
+        newFields[key] = value;
+      }
     });
+    await driver.setItem(metaKey, newFields);
   };
-  const _listeners = /* @__PURE__ */ new Set();
-  return {
-    name: "web-extension:" + opts.storageArea,
-    async hasItem(key) {
-      checkPermission();
-      const res = await browser.storage[opts.storageArea].get(key);
-      return res[key] != null;
-    },
-    async getItem(key) {
-      checkPermission();
-      const res = await browser.storage[opts.storageArea].get(key);
-      return res[key] ?? null;
-    },
-    async getItems(items) {
-      checkPermission();
-      const res = await browser.storage[opts.storageArea].get(
-        items.map((item) => item.key)
+  const removeItem = async (driver, driverKey, opts) => {
+    await driver.removeItem(driverKey);
+    if (opts?.removeMeta) {
+      const metaKey = getMetaKey(driverKey);
+      await driver.removeItem(metaKey);
+    }
+  };
+  const removeMeta = async (driver, driverKey, properties) => {
+    const metaKey = getMetaKey(driverKey);
+    if (properties == null) {
+      await driver.removeItem(metaKey);
+    } else {
+      const newFields = getMetaValue(await driver.getItem(metaKey));
+      [properties].flat().forEach((field) => delete newFields[field]);
+      await driver.setItem(metaKey, newFields);
+    }
+  };
+  const watch = (driver, driverKey, cb) => {
+    return driver.watch(driverKey, cb);
+  };
+  const storage2 = {
+    getItem: async (key, opts) => {
+      const { driver, driverKey } = resolveKey(key);
+      return await getItem(driver, driverKey, opts);
+    },
+    getItems: async (keys) => {
+      const areaToKeyMap = /* @__PURE__ */ new Map();
+      const keyToOptsMap = /* @__PURE__ */ new Map();
+      keys.forEach((key) => {
+        let keyStr;
+        let opts;
+        if (typeof key === "string") {
+          keyStr = key;
+        } else {
+          keyStr = key.key;
+          opts = key.options;
+        }
+        const { driverArea, driverKey } = resolveKey(keyStr);
+        const keys2 = areaToKeyMap.get(driverArea) ?? [];
+        areaToKeyMap.set(driverArea, keys2.concat(driverKey));
+        keyToOptsMap.set(keyStr, opts);
+      });
+      const results = await Promise.all(
+        Array.from(areaToKeyMap.entries()).map(async ([driverArea, keys2]) => {
+          const driverResults = await drivers[driverArea].getItems(keys2);
+          return driverResults.map((driverResult) => {
+            const key = `${driverArea}:${driverResult.key}`;
+            const value = getValueOrDefault(
+              driverResult.value,
+              keyToOptsMap.get(key)?.defaultValue
+            );
+            return { key, value };
+          });
+        })
       );
-      return items.map((item) => ({
-        key: item.key,
-        value: res[item.key] ?? null
-      }));
-    },
-    async setItem(key, value) {
-      checkPermission();
-      await browser.storage[opts.storageArea].set({ [key]: value ?? null });
-    },
-    async setItems(items) {
-      checkPermission();
-      const map = items.reduce((map2, item) => {
-        map2[item.key] = item.value ?? null;
-        return map2;
-      }, {});
-      await browser.storage[opts.storageArea].set(map);
-    },
-    async removeItem(key) {
-      checkPermission();
-      await browser.storage[opts.storageArea].remove(key);
-    },
-    async getKeys() {
-      checkPermission();
-      const all = await browser.storage[opts.storageArea].get();
-      return Object.keys(all);
-    },
-    async clear() {
-      checkPermission();
-      await browser.storage[opts.storageArea].clear();
-    },
-    watch(callback) {
-      checkPermission();
-      _listeners.add(callback);
-      if (_listeners.size === 1) {
-        browser.storage[opts.storageArea].onChanged.addListener(
-          _storageListener
+      return results.flat();
+    },
+    getMeta: async (key) => {
+      const { driver, driverKey } = resolveKey(key);
+      return await getMeta(driver, driverKey);
+    },
+    setItem: async (key, value) => {
+      const { driver, driverKey } = resolveKey(key);
+      await setItem(driver, driverKey, value);
+    },
+    setItems: async (values) => {
+      const areaToKeyValueMap = /* @__PURE__ */ new Map();
+      values.forEach(({ key, value }) => {
+        const { driverArea, driverKey } = resolveKey(key);
+        const values2 = areaToKeyValueMap.get(driverArea) ?? [];
+        areaToKeyValueMap.set(
+          driverArea,
+          values2.concat({ key: driverKey, value })
+        );
+      });
+      await Promise.all(
+        Array.from(areaToKeyValueMap.entries()).map(
+          async ([driverArea, values2]) => {
+            const driver = getDriver(driverArea);
+            await driver.setItems(values2);
+          }
+        )
+      );
+    },
+    setMeta: async (key, properties) => {
+      const { driver, driverKey } = resolveKey(key);
+      await setMeta(driver, driverKey, properties);
+    },
+    removeItem: async (key, opts) => {
+      const { driver, driverKey } = resolveKey(key);
+      await removeItem(driver, driverKey, opts);
+    },
+    removeItems: async (keys) => {
+      const areaToKeysMap = /* @__PURE__ */ new Map();
+      keys.forEach((key) => {
+        let keyStr;
+        let opts;
+        if (typeof key === "string") {
+          keyStr = key;
+        } else {
+          keyStr = key.key;
+          opts = key.options;
+        }
+        const { driverArea, driverKey } = resolveKey(keyStr);
+        const areaKeys = areaToKeysMap.get(driverArea) ?? [];
+        areaKeys.push(driverKey);
+        if (opts?.removeMeta) {
+          areaKeys.push(getMetaKey(driverKey));
+        }
+        areaToKeysMap.set(driverArea, areaKeys);
+      });
+      await Promise.all(
+        Array.from(areaToKeysMap.entries()).map(async ([driverArea, keys2]) => {
+          const driver = getDriver(driverArea);
+          await driver.removeItems(keys2);
+        })
+      );
+    },
+    removeMeta: async (key, properties) => {
+      const { driver, driverKey } = resolveKey(key);
+      await removeMeta(driver, driverKey, properties);
+    },
+    snapshot: async (base, opts) => {
+      const driver = getDriver(base);
+      const data = await driver.snapshot();
+      opts?.excludeKeys?.forEach((key) => {
+        delete data[key];
+        delete data[getMetaKey(key)];
+      });
+      return data;
+    },
+    restoreSnapshot: async (base, data) => {
+      const driver = getDriver(base);
+      await driver.restoreSnapshot(data);
+    },
+    watch: (key, cb) => {
+      const { driver, driverKey } = resolveKey(key);
+      return watch(driver, driverKey, cb);
+    },
+    unwatch() {
+      Object.values(drivers).forEach((driver) => {
+        driver.unwatch();
+      });
+    },
+    defineItem: (key, opts) => {
+      const { driver, driverKey } = resolveKey(key);
+      const { version: targetVersion = 1, migrations = {} } = opts ?? {};
+      if (targetVersion < 1) {
+        throw Error(
+          "Storage item version cannot be less than 1. Initial versions should be set to 1, not 0."
         );
       }
-      return () => {
-        _listeners.delete(callback);
-        if (_listeners.size === 0) {
-          browser.storage[opts.storageArea].onChanged.removeListener(
-            _storageListener
+      const runMigrations = async () => {
+        const [value, meta] = await Promise.all([
+          // TODO: Optimize with getItems
+          getItem(driver, driverKey, void 0),
+          getMeta(driver, driverKey)
+        ]);
+        if (value == null)
+          return;
+        const currentVersion = meta.v ?? 1;
+        if (currentVersion > targetVersion) {
+          throw Error(
+            `[wxt/storage] Migration ignored for "${key}", version downgrade detected (${currentVersion} -> ${targetVersion})`
           );
         }
+        const migrationsToRun = Array.from(
+          { length: targetVersion - currentVersion },
+          (_, i) => currentVersion + i + 1
+        );
+        let migratedValue = value;
+        for (const migrateToVersion of migrationsToRun) {
+          migratedValue = await migrations?.[migrateToVersion]?.(migratedValue) ?? migratedValue;
+        }
+        await Promise.all([
+          // TODO: Optimize with `setItem`
+          setItem(driver, driverKey, migratedValue),
+          setMeta(driver, driverKey, { v: targetVersion })
+        ]);
+      };
+      let _migrationsCompleted = runMigrations();
+      return {
+        _migrationsCompleted,
+        getValue: () => getItem(driver, driverKey, opts),
+        getMeta: () => getMeta(driver, driverKey),
+        setValue: (value) => setItem(driver, driverKey, value),
+        setMeta: (properties) => setMeta(driver, driverKey, properties),
+        removeValue: (opts2) => removeItem(driver, driverKey, opts2),
+        removeMeta: (properties) => removeMeta(driver, driverKey, properties),
+        watch: (cb) => watch(driver, driverKey, cb)
       };
     }
   };
-});
-function createWebExtensionStorage() {
-  const storage2 = (0, import_unstorage.createStorage)();
-  storage2.mount("local", webExtensionDriver({ storageArea: "local" }));
-  storage2.mount("session", webExtensionDriver({ storageArea: "session" }));
-  storage2.mount("sync", webExtensionDriver({ storageArea: "sync" }));
-  storage2.mount("managed", webExtensionDriver({ storageArea: "managed" }));
   return storage2;
 }
-var storage = createWebExtensionStorage();
+function createDriver(storageArea) {
+  const getStorageArea = () => {
+    if (browser.storage == null)
+      throw Error(
+        "You must add the 'storage' permission to your manifest to use 'wxt/storage'"
+      );
+    return browser.storage[storageArea];
+  };
+  const watchListeners = /* @__PURE__ */ new Set();
+  return {
+    getItem: async (key) => {
+      const res = await getStorageArea().get(key);
+      return res[key];
+    },
+    getItems: async (keys) => {
+      const result = await getStorageArea().get(keys);
+      return keys.map((key) => ({ key, value: result[key] ?? null }));
+    },
+    setItem: async (key, value) => {
+      if (value == null) {
+        await getStorageArea().remove(key);
+      } else {
+        await getStorageArea().set({ [key]: value });
+      }
+    },
+    setItems: async (values) => {
+      const map = values.reduce(
+        (map2, { key, value }) => {
+          map2[key] = value;
+          return map2;
+        },
+        {}
+      );
+      await getStorageArea().set(map);
+    },
+    removeItem: async (key) => {
+      await getStorageArea().remove(key);
+    },
+    removeItems: async (keys) => {
+      await getStorageArea().remove(keys);
+    },
+    snapshot: async () => {
+      return await getStorageArea().get();
+    },
+    restoreSnapshot: async (data) => {
+      await getStorageArea().set(data);
+    },
+    watch(key, cb) {
+      const listener = (changes) => {
+        const change = changes[key];
+        if (change == null)
+          return;
+        if ((0, import_lite.dequal)(change.newValue, change.oldValue))
+          return;
+        cb(change.newValue ?? null, change.oldValue ?? null);
+      };
+      getStorageArea().onChanged.addListener(listener);
+      watchListeners.add(listener);
+      return () => {
+        getStorageArea().onChanged.removeListener(listener);
+        watchListeners.delete(listener);
+      };
+    },
+    unwatch() {
+      watchListeners.forEach((listener) => {
+        getStorageArea().onChanged.removeListener(listener);
+      });
+      watchListeners.clear();
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  storage,
-  webExtensionDriver,
-  ...require("unstorage")
+  storage
 });

package/dist/storage.d.cts

@@ -1,15 +1,188 @@
-import { Driver, Storage } from 'unstorage';
-export * from 'unstorage';
-
+declare const storage: WxtStorage;
+interface WxtStorage {
+    /**
+     * Get an item from storage, or return `null` if it doesn't exist.
+     *
+     * @example
+     * await storage.getItem<number>("local:installDate");
+     */
+    getItem<T>(key: string, opts?: GetItemOptions<T>): Promise<T | null>;
+    /**
+     * Get multiple items from storage. There is no guarentee of order in the returned array.
+     *
+     * @example
+     * await storage.getItems(["local:installDate", "session:someCounter"]);
+     */
+    getItems(keys: Array<string | {
+        key: string;
+        options?: GetItemOptions<any>;
+    }>): Promise<Array<{
+        key: string;
+        value: any;
+    }>>;
+    /**
+     * Return an object containing metadata about the key. Object is stored at `key + "$"`. If value
+     * is not an object, it returns an empty object.
+     *
+     * @example
+     * await storage.getMeta("local:installDate");
+     */
+    getMeta<T extends Record<string, unknown>>(key: string): Promise<T>;
+    /**
+     * Set a value in storage. Setting a value to `null` or `undefined` is equivalent to calling
+     * `removeItem`.
+     *
+     * @example
+     * await storage.setItem<number>("local:installDate", Date.now());
+     */
+    setItem<T>(key: string, value: T | null): Promise<void>;
+    /**
+     * Set multiple values in storage. If a value is set to `null` or `undefined`, the key is removed.
+     *
+     * @example
+     * await storage.setItem([
+     *   { key: "local:installDate", value: Date.now() },
+     *   { key: "session:someCounter, value: 5 },
+     * ]);
+     */
+    setItems(values: Array<{
+        key: string;
+        value: any;
+    }>): Promise<void>;
+    /**
+     * Sets metadata properties. If some properties are already set, but are not included in the
+     * `properties` parameter, they will not be removed.
+     *
+     * @example
+     * await storage.setMeta("local:installDate", { appVersion });
+     */
+    setMeta<T extends Record<string, unknown>>(key: string, properties: T | null): Promise<void>;
+    /**
+     * Removes an item from storage.
+     *
+     * @example
+     * await storage.removeItem("local:installDate");
+     */
+    removeItem(key: string, opts?: RemoveItemOptions): Promise<void>;
+    /**
+     * Remove a list of keys from storage.
+     */
+    removeItems(keys: Array<string | {
+        key: string;
+        options?: RemoveItemOptions;
+    }>): Promise<void>;
+    /**
+     * Remove the entire metadata for a key, or specific properties by name.
+     *
+     * @example
+     * // Remove all metadata properties from the item
+     * await storage.removeMeta("local:installDate");
+     *
+     * // Remove only specific the "v" field
+     * await storage.removeMeta("local:installDate", "v")
+     */
+    removeMeta(key: string, properties?: string | string[]): Promise<void>;
+    /**
+     * Return all the items in storage.
+     */
+    snapshot(base: string, opts?: SnapshotOptions): Promise<Record<string, unknown>>;
+    /**
+     * Restores the results of `snapshot`. If new properties have been saved since the snapshot, they are
+     * not overridden. Only values existing in the snapshot are overritten.
+     */
+    restoreSnapshot(base: string, data: any): Promise<void>;
+    /**
+     * Watch for changes to a specific key in storage.
+     */
+    watch<T>(key: string, cb: WatchCallback<T>): Unwatch;
+    /**
+     * Remove all watch listeners.
+     */
+    unwatch(): void;
+    /**
+     * Define a constant with utilities for reading/writing to a single value in storage.
+     *
+     * @example
+     * export const installDate = storage.defineItem<number>("local:installDate");
+     */
+    defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: string, options?: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue, TMetadata>;
+}
+interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
+    /**
+     * Get the latest value from storage.
+     */
+    getValue(): Promise<TValue>;
+    /**
+     * Get metadata.
+     */
+    getMeta(): Promise<NullablePartial<TMetadata>>;
+    /**
+     * Set the value in storage.
+     */
+    setValue(value: TValue | null): Promise<void>;
+    /**
+     * Set metadata properties.
+     */
+    setMeta(properties: NullablePartial<TMetadata>): Promise<void>;
+    /**
+     * Remove the value from storage.
+     */
+    removeValue(opts?: RemoveItemOptions): Promise<void>;
+    /**
+     * Remove all metadata or certain properties from metadata.
+     */
+    removeMeta(properties?: string[]): Promise<void>;
+    /**
+     * Listen for changes to the value in storage.
+     */
+    watch(cb: WatchCallback<TValue>): Unwatch;
+}
+interface GetItemOptions<T> {
+    /**
+     * Value returned from `getValue` when it would otherwise return null.
+     */
+    defaultValue?: T;
+}
+interface RemoveItemOptions {
+    /**
+     * Optionally remove metadata when deleting a key.
+     *
+     * @default false
+     */
+    removeMeta?: boolean;
+}
+interface SnapshotOptions {
+    /**
+     * Exclude a list of keys. The storage area prefix should be removed since the snapshot is for a
+     * specific storage area already.
+     */
+    excludeKeys?: string[];
+}
+interface WxtStorageItemOptions<T> extends GetItemOptions<T> {
+    /**
+     * Provide a version number for the storage item to enable migrations. When changing the version
+     * in the future, migration functions will be ran on application startup.
+     */
+    version?: number;
+    /**
+     * A map of version numbers to the functions used to migrate the data to that version.
+     */
+    migrations?: Record<number, (oldValue: any) => any>;
+}
 /**
- * @module wxt/storage
+ * Same as `Partial`, but includes `| null`. It makes all the properties of an object optional and
+ * nullable.
  */
+type NullablePartial<T> = {
+    [key in keyof T]+?: T[key] | undefined | null;
+};
+/**
+ * Callback called when a value in storage is changed.
+ */
+type WatchCallback<T> = (newValue: T | null, oldValue: T | null) => void;
+/**
+ * Call to remove a watch listener
+ */
+type Unwatch = () => void;
 
-interface WebExtensionDriverOptions {
-    storageArea: 'sync' | 'local' | 'managed' | 'session';
-}
-declare const webExtensionDriver: (opts: WebExtensionDriverOptions) => Driver;
-type StorageValue = null | string | number | boolean | object;
-declare const storage: Storage<StorageValue>;
-
-export { type StorageValue, type WebExtensionDriverOptions, storage, webExtensionDriver };
+export { type GetItemOptions, type NullablePartial, type RemoveItemOptions, type SnapshotOptions, type Unwatch, type WatchCallback, type WxtStorage, type WxtStorageItem, type WxtStorageItemOptions, storage };

package/dist/storage.d.ts

@@ -1,15 +1,188 @@
-import { Driver, Storage } from 'unstorage';
-export * from 'unstorage';
-
+declare const storage: WxtStorage;
+interface WxtStorage {
+    /**
+     * Get an item from storage, or return `null` if it doesn't exist.
+     *
+     * @example
+     * await storage.getItem<number>("local:installDate");
+     */
+    getItem<T>(key: string, opts?: GetItemOptions<T>): Promise<T | null>;
+    /**
+     * Get multiple items from storage. There is no guarentee of order in the returned array.
+     *
+     * @example
+     * await storage.getItems(["local:installDate", "session:someCounter"]);
+     */
+    getItems(keys: Array<string | {
+        key: string;
+        options?: GetItemOptions<any>;
+    }>): Promise<Array<{
+        key: string;
+        value: any;
+    }>>;
+    /**
+     * Return an object containing metadata about the key. Object is stored at `key + "$"`. If value
+     * is not an object, it returns an empty object.
+     *
+     * @example
+     * await storage.getMeta("local:installDate");
+     */
+    getMeta<T extends Record<string, unknown>>(key: string): Promise<T>;
+    /**
+     * Set a value in storage. Setting a value to `null` or `undefined` is equivalent to calling
+     * `removeItem`.
+     *
+     * @example
+     * await storage.setItem<number>("local:installDate", Date.now());
+     */
+    setItem<T>(key: string, value: T | null): Promise<void>;
+    /**
+     * Set multiple values in storage. If a value is set to `null` or `undefined`, the key is removed.
+     *
+     * @example
+     * await storage.setItem([
+     *   { key: "local:installDate", value: Date.now() },
+     *   { key: "session:someCounter, value: 5 },
+     * ]);
+     */
+    setItems(values: Array<{
+        key: string;
+        value: any;
+    }>): Promise<void>;
+    /**
+     * Sets metadata properties. If some properties are already set, but are not included in the
+     * `properties` parameter, they will not be removed.
+     *
+     * @example
+     * await storage.setMeta("local:installDate", { appVersion });
+     */
+    setMeta<T extends Record<string, unknown>>(key: string, properties: T | null): Promise<void>;
+    /**
+     * Removes an item from storage.
+     *
+     * @example
+     * await storage.removeItem("local:installDate");
+     */
+    removeItem(key: string, opts?: RemoveItemOptions): Promise<void>;
+    /**
+     * Remove a list of keys from storage.
+     */
+    removeItems(keys: Array<string | {
+        key: string;
+        options?: RemoveItemOptions;
+    }>): Promise<void>;
+    /**
+     * Remove the entire metadata for a key, or specific properties by name.
+     *
+     * @example
+     * // Remove all metadata properties from the item
+     * await storage.removeMeta("local:installDate");
+     *
+     * // Remove only specific the "v" field
+     * await storage.removeMeta("local:installDate", "v")
+     */
+    removeMeta(key: string, properties?: string | string[]): Promise<void>;
+    /**
+     * Return all the items in storage.
+     */
+    snapshot(base: string, opts?: SnapshotOptions): Promise<Record<string, unknown>>;
+    /**
+     * Restores the results of `snapshot`. If new properties have been saved since the snapshot, they are
+     * not overridden. Only values existing in the snapshot are overritten.
+     */
+    restoreSnapshot(base: string, data: any): Promise<void>;
+    /**
+     * Watch for changes to a specific key in storage.
+     */
+    watch<T>(key: string, cb: WatchCallback<T>): Unwatch;
+    /**
+     * Remove all watch listeners.
+     */
+    unwatch(): void;
+    /**
+     * Define a constant with utilities for reading/writing to a single value in storage.
+     *
+     * @example
+     * export const installDate = storage.defineItem<number>("local:installDate");
+     */
+    defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: string, options?: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue, TMetadata>;
+}
+interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
+    /**
+     * Get the latest value from storage.
+     */
+    getValue(): Promise<TValue>;
+    /**
+     * Get metadata.
+     */
+    getMeta(): Promise<NullablePartial<TMetadata>>;
+    /**
+     * Set the value in storage.
+     */
+    setValue(value: TValue | null): Promise<void>;
+    /**
+     * Set metadata properties.
+     */
+    setMeta(properties: NullablePartial<TMetadata>): Promise<void>;
+    /**
+     * Remove the value from storage.
+     */
+    removeValue(opts?: RemoveItemOptions): Promise<void>;
+    /**
+     * Remove all metadata or certain properties from metadata.
+     */
+    removeMeta(properties?: string[]): Promise<void>;
+    /**
+     * Listen for changes to the value in storage.
+     */
+    watch(cb: WatchCallback<TValue>): Unwatch;
+}
+interface GetItemOptions<T> {
+    /**
+     * Value returned from `getValue` when it would otherwise return null.
+     */
+    defaultValue?: T;
+}
+interface RemoveItemOptions {
+    /**
+     * Optionally remove metadata when deleting a key.
+     *
+     * @default false
+     */
+    removeMeta?: boolean;
+}
+interface SnapshotOptions {
+    /**
+     * Exclude a list of keys. The storage area prefix should be removed since the snapshot is for a
+     * specific storage area already.
+     */
+    excludeKeys?: string[];
+}
+interface WxtStorageItemOptions<T> extends GetItemOptions<T> {
+    /**
+     * Provide a version number for the storage item to enable migrations. When changing the version
+     * in the future, migration functions will be ran on application startup.
+     */
+    version?: number;
+    /**
+     * A map of version numbers to the functions used to migrate the data to that version.
+     */
+    migrations?: Record<number, (oldValue: any) => any>;
+}
 /**
- * @module wxt/storage
+ * Same as `Partial`, but includes `| null`. It makes all the properties of an object optional and
+ * nullable.
  */
+type NullablePartial<T> = {
+    [key in keyof T]+?: T[key] | undefined | null;
+};
+/**
+ * Callback called when a value in storage is changed.
+ */
+type WatchCallback<T> = (newValue: T | null, oldValue: T | null) => void;
+/**
+ * Call to remove a watch listener
+ */
+type Unwatch = () => void;
 
-interface WebExtensionDriverOptions {
-    storageArea: 'sync' | 'local' | 'managed' | 'session';
-}
-declare const webExtensionDriver: (opts: WebExtensionDriverOptions) => Driver;
-type StorageValue = null | string | number | boolean | object;
-declare const storage: Storage<StorageValue>;
-
-export { type StorageValue, type WebExtensionDriverOptions, storage, webExtensionDriver };
+export { type GetItemOptions, type NullablePartial, type RemoveItemOptions, type SnapshotOptions, type Unwatch, type WatchCallback, type WxtStorage, type WxtStorageItem, type WxtStorageItemOptions, storage };

package/dist/storage.js

@@ -1,108 +1,333 @@
 import "./chunk-VBXJIVYU.js";
 
-// src/storage.ts
-import {
-  createStorage,
-  defineDriver
-} from "unstorage";
-
 // src/browser.ts
 import originalBrowser from "webextension-polyfill";
 var browser = originalBrowser;
 
 // src/storage.ts
-export * from "unstorage";
-var webExtensionDriver = defineDriver((opts) => {
-  const checkPermission = () => {
-    if (browser.storage == null)
+import { dequal } from "dequal/lite";
+var storage = createStorage();
+function createStorage() {
+  const drivers = {
+    local: createDriver("local"),
+    session: createDriver("session"),
+    sync: createDriver("sync"),
+    managed: createDriver("managed")
+  };
+  const getDriver = (area) => {
+    const driver = drivers[area];
+    if (driver == null) {
+      const areaNames = Object.keys(drivers).join(", ");
+      throw Error(`Invalid area "${area}". Options: ${areaNames}`);
+    }
+    return driver;
+  };
+  const resolveKey = (key) => {
+    const [driverArea, driverKey] = key.split(":", 2);
+    if (driverKey == null)
       throw Error(
-        "You must request the 'storage' permission to use webExtensionDriver"
+        `Storage key should be in the form of "area:key", but recieved "${key}"`
       );
+    return {
+      driverArea,
+      driverKey,
+      driver: getDriver(driverArea)
+    };
   };
-  const _storageListener = (changes) => {
-    Object.entries(changes).forEach(([key, { newValue }]) => {
-      _listeners.forEach((callback) => {
-        callback(newValue ? "update" : "remove", key);
-      });
+  const getMetaKey = (key) => key + "$";
+  const getValueOrDefault = (value, defaultValue) => value ?? defaultValue ?? null;
+  const getMetaValue = (properties) => typeof properties === "object" && !Array.isArray(properties) ? properties : {};
+  const getItem = async (driver, driverKey, opts) => {
+    const res = await driver.getItem(driverKey);
+    return getValueOrDefault(res, opts?.defaultValue);
+  };
+  const getMeta = async (driver, driverKey) => {
+    const metaKey = getMetaKey(driverKey);
+    const res = await driver.getItem(metaKey);
+    return getMetaValue(res);
+  };
+  const setItem = async (driver, driverKey, value) => {
+    await driver.setItem(driverKey, value ?? null);
+  };
+  const setMeta = async (driver, driverKey, properties) => {
+    const metaKey = getMetaKey(driverKey);
+    const existingFields = getMetaValue(await driver.getItem(metaKey));
+    const newFields = { ...existingFields };
+    Object.entries(properties).forEach(([key, value]) => {
+      if (value == null) {
+        delete newFields[key];
+      } else {
+        newFields[key] = value;
+      }
     });
+    await driver.setItem(metaKey, newFields);
   };
-  const _listeners = /* @__PURE__ */ new Set();
-  return {
-    name: "web-extension:" + opts.storageArea,
-    async hasItem(key) {
-      checkPermission();
-      const res = await browser.storage[opts.storageArea].get(key);
-      return res[key] != null;
-    },
-    async getItem(key) {
-      checkPermission();
-      const res = await browser.storage[opts.storageArea].get(key);
-      return res[key] ?? null;
-    },
-    async getItems(items) {
-      checkPermission();
-      const res = await browser.storage[opts.storageArea].get(
-        items.map((item) => item.key)
+  const removeItem = async (driver, driverKey, opts) => {
+    await driver.removeItem(driverKey);
+    if (opts?.removeMeta) {
+      const metaKey = getMetaKey(driverKey);
+      await driver.removeItem(metaKey);
+    }
+  };
+  const removeMeta = async (driver, driverKey, properties) => {
+    const metaKey = getMetaKey(driverKey);
+    if (properties == null) {
+      await driver.removeItem(metaKey);
+    } else {
+      const newFields = getMetaValue(await driver.getItem(metaKey));
+      [properties].flat().forEach((field) => delete newFields[field]);
+      await driver.setItem(metaKey, newFields);
+    }
+  };
+  const watch = (driver, driverKey, cb) => {
+    return driver.watch(driverKey, cb);
+  };
+  const storage2 = {
+    getItem: async (key, opts) => {
+      const { driver, driverKey } = resolveKey(key);
+      return await getItem(driver, driverKey, opts);
+    },
+    getItems: async (keys) => {
+      const areaToKeyMap = /* @__PURE__ */ new Map();
+      const keyToOptsMap = /* @__PURE__ */ new Map();
+      keys.forEach((key) => {
+        let keyStr;
+        let opts;
+        if (typeof key === "string") {
+          keyStr = key;
+        } else {
+          keyStr = key.key;
+          opts = key.options;
+        }
+        const { driverArea, driverKey } = resolveKey(keyStr);
+        const keys2 = areaToKeyMap.get(driverArea) ?? [];
+        areaToKeyMap.set(driverArea, keys2.concat(driverKey));
+        keyToOptsMap.set(keyStr, opts);
+      });
+      const results = await Promise.all(
+        Array.from(areaToKeyMap.entries()).map(async ([driverArea, keys2]) => {
+          const driverResults = await drivers[driverArea].getItems(keys2);
+          return driverResults.map((driverResult) => {
+            const key = `${driverArea}:${driverResult.key}`;
+            const value = getValueOrDefault(
+              driverResult.value,
+              keyToOptsMap.get(key)?.defaultValue
+            );
+            return { key, value };
+          });
+        })
+      );
+      return results.flat();
+    },
+    getMeta: async (key) => {
+      const { driver, driverKey } = resolveKey(key);
+      return await getMeta(driver, driverKey);
+    },
+    setItem: async (key, value) => {
+      const { driver, driverKey } = resolveKey(key);
+      await setItem(driver, driverKey, value);
+    },
+    setItems: async (values) => {
+      const areaToKeyValueMap = /* @__PURE__ */ new Map();
+      values.forEach(({ key, value }) => {
+        const { driverArea, driverKey } = resolveKey(key);
+        const values2 = areaToKeyValueMap.get(driverArea) ?? [];
+        areaToKeyValueMap.set(
+          driverArea,
+          values2.concat({ key: driverKey, value })
+        );
+      });
+      await Promise.all(
+        Array.from(areaToKeyValueMap.entries()).map(
+          async ([driverArea, values2]) => {
+            const driver = getDriver(driverArea);
+            await driver.setItems(values2);
+          }
+        )
       );
-      return items.map((item) => ({
-        key: item.key,
-        value: res[item.key] ?? null
-      }));
-    },
-    async setItem(key, value) {
-      checkPermission();
-      await browser.storage[opts.storageArea].set({ [key]: value ?? null });
-    },
-    async setItems(items) {
-      checkPermission();
-      const map = items.reduce((map2, item) => {
-        map2[item.key] = item.value ?? null;
-        return map2;
-      }, {});
-      await browser.storage[opts.storageArea].set(map);
-    },
-    async removeItem(key) {
-      checkPermission();
-      await browser.storage[opts.storageArea].remove(key);
-    },
-    async getKeys() {
-      checkPermission();
-      const all = await browser.storage[opts.storageArea].get();
-      return Object.keys(all);
-    },
-    async clear() {
-      checkPermission();
-      await browser.storage[opts.storageArea].clear();
-    },
-    watch(callback) {
-      checkPermission();
-      _listeners.add(callback);
-      if (_listeners.size === 1) {
-        browser.storage[opts.storageArea].onChanged.addListener(
-          _storageListener
+    },
+    setMeta: async (key, properties) => {
+      const { driver, driverKey } = resolveKey(key);
+      await setMeta(driver, driverKey, properties);
+    },
+    removeItem: async (key, opts) => {
+      const { driver, driverKey } = resolveKey(key);
+      await removeItem(driver, driverKey, opts);
+    },
+    removeItems: async (keys) => {
+      const areaToKeysMap = /* @__PURE__ */ new Map();
+      keys.forEach((key) => {
+        let keyStr;
+        let opts;
+        if (typeof key === "string") {
+          keyStr = key;
+        } else {
+          keyStr = key.key;
+          opts = key.options;
+        }
+        const { driverArea, driverKey } = resolveKey(keyStr);
+        const areaKeys = areaToKeysMap.get(driverArea) ?? [];
+        areaKeys.push(driverKey);
+        if (opts?.removeMeta) {
+          areaKeys.push(getMetaKey(driverKey));
+        }
+        areaToKeysMap.set(driverArea, areaKeys);
+      });
+      await Promise.all(
+        Array.from(areaToKeysMap.entries()).map(async ([driverArea, keys2]) => {
+          const driver = getDriver(driverArea);
+          await driver.removeItems(keys2);
+        })
+      );
+    },
+    removeMeta: async (key, properties) => {
+      const { driver, driverKey } = resolveKey(key);
+      await removeMeta(driver, driverKey, properties);
+    },
+    snapshot: async (base, opts) => {
+      const driver = getDriver(base);
+      const data = await driver.snapshot();
+      opts?.excludeKeys?.forEach((key) => {
+        delete data[key];
+        delete data[getMetaKey(key)];
+      });
+      return data;
+    },
+    restoreSnapshot: async (base, data) => {
+      const driver = getDriver(base);
+      await driver.restoreSnapshot(data);
+    },
+    watch: (key, cb) => {
+      const { driver, driverKey } = resolveKey(key);
+      return watch(driver, driverKey, cb);
+    },
+    unwatch() {
+      Object.values(drivers).forEach((driver) => {
+        driver.unwatch();
+      });
+    },
+    defineItem: (key, opts) => {
+      const { driver, driverKey } = resolveKey(key);
+      const { version: targetVersion = 1, migrations = {} } = opts ?? {};
+      if (targetVersion < 1) {
+        throw Error(
+          "Storage item version cannot be less than 1. Initial versions should be set to 1, not 0."
         );
       }
-      return () => {
-        _listeners.delete(callback);
-        if (_listeners.size === 0) {
-          browser.storage[opts.storageArea].onChanged.removeListener(
-            _storageListener
+      const runMigrations = async () => {
+        const [value, meta] = await Promise.all([
+          // TODO: Optimize with getItems
+          getItem(driver, driverKey, void 0),
+          getMeta(driver, driverKey)
+        ]);
+        if (value == null)
+          return;
+        const currentVersion = meta.v ?? 1;
+        if (currentVersion > targetVersion) {
+          throw Error(
+            `[wxt/storage] Migration ignored for "${key}", version downgrade detected (${currentVersion} -> ${targetVersion})`
           );
         }
+        const migrationsToRun = Array.from(
+          { length: targetVersion - currentVersion },
+          (_, i) => currentVersion + i + 1
+        );
+        let migratedValue = value;
+        for (const migrateToVersion of migrationsToRun) {
+          migratedValue = await migrations?.[migrateToVersion]?.(migratedValue) ?? migratedValue;
+        }
+        await Promise.all([
+          // TODO: Optimize with `setItem`
+          setItem(driver, driverKey, migratedValue),
+          setMeta(driver, driverKey, { v: targetVersion })
+        ]);
+      };
+      let _migrationsCompleted = runMigrations();
+      return {
+        _migrationsCompleted,
+        getValue: () => getItem(driver, driverKey, opts),
+        getMeta: () => getMeta(driver, driverKey),
+        setValue: (value) => setItem(driver, driverKey, value),
+        setMeta: (properties) => setMeta(driver, driverKey, properties),
+        removeValue: (opts2) => removeItem(driver, driverKey, opts2),
+        removeMeta: (properties) => removeMeta(driver, driverKey, properties),
+        watch: (cb) => watch(driver, driverKey, cb)
       };
     }
   };
-});
-function createWebExtensionStorage() {
-  const storage2 = createStorage();
-  storage2.mount("local", webExtensionDriver({ storageArea: "local" }));
-  storage2.mount("session", webExtensionDriver({ storageArea: "session" }));
-  storage2.mount("sync", webExtensionDriver({ storageArea: "sync" }));
-  storage2.mount("managed", webExtensionDriver({ storageArea: "managed" }));
   return storage2;
 }
-var storage = createWebExtensionStorage();
+function createDriver(storageArea) {
+  const getStorageArea = () => {
+    if (browser.storage == null)
+      throw Error(
+        "You must add the 'storage' permission to your manifest to use 'wxt/storage'"
+      );
+    return browser.storage[storageArea];
+  };
+  const watchListeners = /* @__PURE__ */ new Set();
+  return {
+    getItem: async (key) => {
+      const res = await getStorageArea().get(key);
+      return res[key];
+    },
+    getItems: async (keys) => {
+      const result = await getStorageArea().get(keys);
+      return keys.map((key) => ({ key, value: result[key] ?? null }));
+    },
+    setItem: async (key, value) => {
+      if (value == null) {
+        await getStorageArea().remove(key);
+      } else {
+        await getStorageArea().set({ [key]: value });
+      }
+    },
+    setItems: async (values) => {
+      const map = values.reduce(
+        (map2, { key, value }) => {
+          map2[key] = value;
+          return map2;
+        },
+        {}
+      );
+      await getStorageArea().set(map);
+    },
+    removeItem: async (key) => {
+      await getStorageArea().remove(key);
+    },
+    removeItems: async (keys) => {
+      await getStorageArea().remove(keys);
+    },
+    snapshot: async () => {
+      return await getStorageArea().get();
+    },
+    restoreSnapshot: async (data) => {
+      await getStorageArea().set(data);
+    },
+    watch(key, cb) {
+      const listener = (changes) => {
+        const change = changes[key];
+        if (change == null)
+          return;
+        if (dequal(change.newValue, change.oldValue))
+          return;
+        cb(change.newValue ?? null, change.oldValue ?? null);
+      };
+      getStorageArea().onChanged.addListener(listener);
+      watchListeners.add(listener);
+      return () => {
+        getStorageArea().onChanged.removeListener(listener);
+        watchListeners.delete(listener);
+      };
+    },
+    unwatch() {
+      watchListeners.forEach((listener) => {
+        getStorageArea().onChanged.removeListener(listener);
+      });
+      watchListeners.clear();
+    }
+  };
+}
 export {
-  storage,
-  webExtensionDriver
+  storage
 };

package/dist/testing.js

@@ -5,7 +5,7 @@ import {
   tsconfigPaths,
   unimport,
   webextensionPolyfillMock
-} from "./chunk-JK5CNMJT.js";
+} from "./chunk-GNIOSZT6.js";
 import "./chunk-VBXJIVYU.js";
 
 // src/testing/fake-browser.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wxt",
   "type": "module",
-  "version": "0.12.5",
+  "version": "0.13.0",
   "description": "Next gen framework for developing web extensions",
   "engines": {
     "node": ">=18",
@@ -89,6 +89,7 @@
     "chokidar": "^3.5.3",
     "consola": "^3.2.3",
     "defu": "^6.1.3",
+    "dequal": "^2.0.3",
     "esbuild": "^0.19.5",
     "fast-glob": "^3.3.1",
     "filesize": "^10.0.8",
@@ -107,7 +108,6 @@
     "prompts": "^2.4.2",
     "rollup-plugin-visualizer": "^5.9.2",
     "unimport": "^3.4.0",
-    "unstorage": "^1.9.0",
     "vite": "^5.0.0",
     "web-ext-run": "^0.1.0",
     "webextension-polyfill": "^0.10.0",