webext-storage 2.0.1 → 3.0.0

package/distribution/storage-item-map.d.ts

@@ -7,16 +7,17 @@ export declare class StorageItemMap<
 Base, 
 /** The return type will be undefined unless you provide a default value */
 Return = Base | undefined> {
+    #private;
     readonly prefix: `${string}:::`;
     readonly areaName: chrome.storage.AreaName;
     readonly defaultValue?: Return;
     constructor(key: string, { area, defaultValue, }?: StorageItemMapOptions<Exclude<Return, undefined>>);
-    has: (secondaryKey: string) => Promise<boolean>;
-    get: (secondaryKey: string) => Promise<Return>;
-    set: (secondaryKey: string, value: Exclude<Return, undefined>) => Promise<void>;
-    remove: (secondaryKey: string) => Promise<void>;
+    has(secondaryKey: string): Promise<boolean>;
+    get(secondaryKey: string): Promise<Return>;
+    set(secondaryKey: string, value: Exclude<Return, undefined>): Promise<void>;
+    remove(secondaryKey: string): Promise<void>;
     /** @deprecated Only here to match the Map API; use `remove` instead */
-    delete: (secondaryKey: string) => Promise<void>;
+    delete(secondaryKey: string): Promise<void>;
     onChanged(callback: (key: string, value: Exclude<Return, undefined>) => void, signal?: AbortSignal): void;
     private getRawStorageKey;
     private getSecondaryStorageKey;

package/distribution/storage-item-map.js

@@ -1,55 +1,62 @@
-import chromeP from 'webext-polyfill-kinda';
+import { assertChromeStorageAvailable, hasStorageValueChanged } from './utils.js';
 export class StorageItemMap {
     prefix;
     areaName;
     defaultValue;
+    get #storage() {
+        assertChromeStorageAvailable();
+        return chrome.storage[this.areaName];
+    }
     constructor(key, { area = 'local', defaultValue, } = {}) {
         this.prefix = `${key}:::`;
         this.areaName = area;
         this.defaultValue = defaultValue;
     }
-    has = async (secondaryKey) => {
+    async has(secondaryKey) {
         const rawStorageKey = this.getRawStorageKey(secondaryKey);
-        const result = await chromeP.storage[this.areaName].get(rawStorageKey);
+        const result = await this.#storage.get(rawStorageKey);
         // Do not use Object.hasOwn() due to https://github.com/RickyMarou/jest-webextension-mock/issues/20
         return result[rawStorageKey] !== undefined;
-    };
-    get = async (secondaryKey) => {
+    }
+    async get(secondaryKey) {
         const rawStorageKey = this.getRawStorageKey(secondaryKey);
-        const result = await chromeP.storage[this.areaName].get(rawStorageKey);
+        const result = await this.#storage.get(rawStorageKey);
         // Do not use Object.hasOwn() due to https://github.com/RickyMarou/jest-webextension-mock/issues/20
         if (result[rawStorageKey] === undefined) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Assumes the user never uses the Storage API directly for this key
             return this.defaultValue;
         }
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- Assumes the user never uses the Storage API directly for this key
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-type-assertion -- Assumes the user never uses the Storage API directly for this key
         return result[rawStorageKey];
-    };
-    set = async (secondaryKey, value) => {
+    }
+    async set(secondaryKey, value) {
         const rawStorageKey = this.getRawStorageKey(secondaryKey);
         // eslint-disable-next-line unicorn/prefer-ternary -- ur rong
         if (value === undefined) {
-            await chromeP.storage[this.areaName].remove(rawStorageKey);
+            await this.#storage.remove(rawStorageKey);
         }
         else {
-            await chromeP.storage[this.areaName].set({ [rawStorageKey]: value });
+            await this.#storage.set({ [rawStorageKey]: value });
         }
-    };
-    remove = async (secondaryKey) => {
+    }
+    async remove(secondaryKey) {
         const rawStorageKey = this.getRawStorageKey(secondaryKey);
-        await chromeP.storage[this.areaName].remove(rawStorageKey);
-    };
+        await this.#storage.remove(rawStorageKey);
+    }
     /** @deprecated Only here to match the Map API; use `remove` instead */
-    // eslint-disable-next-line @typescript-eslint/member-ordering -- invalid
-    delete = this.remove;
+    async delete(secondaryKey) {
+        return this.remove(secondaryKey);
+    }
     onChanged(callback, signal) {
+        assertChromeStorageAvailable();
         const changeHandler = (changes, area) => {
             if (area !== this.areaName) {
                 return;
             }
             for (const rawKey of Object.keys(changes)) {
                 const secondaryKey = this.getSecondaryStorageKey(rawKey);
-                if (secondaryKey) {
-                    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument -- Assumes the user never uses the Storage API directly
+                if (secondaryKey && hasStorageValueChanged(changes[rawKey])) {
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-type-assertion -- Assumes the user never uses the Storage API directly
                     callback(secondaryKey, changes[rawKey].newValue);
                 }
             }

package/distribution/storage-item.d.ts

@@ -7,15 +7,14 @@ export declare class StorageItem<
 Base, 
 /** The return type will be undefined unless you provide a default value */
 Return = Base | undefined> {
-    readonly key: string;
+    #private;
     readonly area: chrome.storage.AreaName;
     readonly defaultValue?: Return;
-    /** @deprecated Use `onChanged` instead */
-    onChange: (callback: (value: Exclude<Return, undefined>) => void, signal?: AbortSignal) => void;
+    readonly key: string;
     constructor(key: string, { area, defaultValue, }?: StorageItemOptions<Exclude<Return, undefined>>);
-    get: () => Promise<Return>;
-    set: (value: Exclude<Return, undefined>) => Promise<void>;
-    has: () => Promise<boolean>;
-    remove: () => Promise<void>;
+    get(): Promise<Return>;
+    set(value: Exclude<Return, undefined>): Promise<void>;
+    has(): Promise<boolean>;
+    remove(): Promise<void>;
     onChanged(callback: (value: Exclude<Return, undefined>) => void, signal?: AbortSignal): void;
 }

package/distribution/storage-item.js

@@ -1,46 +1,50 @@
-import chromeP from 'webext-polyfill-kinda';
+import { assertChromeStorageAvailable, hasStorageValueChanged } from './utils.js';
 export class StorageItem {
-    key;
     area;
     defaultValue;
-    /** @deprecated Use `onChanged` instead */
-    onChange = this.onChanged;
+    key;
+    get #storage() {
+        assertChromeStorageAvailable();
+        return chrome.storage[this.area];
+    }
     constructor(key, { area = 'local', defaultValue, } = {}) {
         this.key = key;
         this.area = area;
         this.defaultValue = defaultValue;
     }
-    get = async () => {
-        const result = await chromeP.storage[this.area].get(this.key);
+    async get() {
+        const result = await this.#storage.get(this.key);
         // Do not use Object.hasOwn() due to https://github.com/RickyMarou/jest-webextension-mock/issues/20
         if (result[this.key] === undefined) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Assumes the user never uses the Storage API directly
             return this.defaultValue;
         }
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- Assumes the user never uses the Storage API directly
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-type-assertion -- Assumes the user never uses the Storage API directly
         return result[this.key];
-    };
-    set = async (value) => {
+    }
+    async set(value) {
         // eslint-disable-next-line unicorn/prefer-ternary -- ur rong
         if (value === undefined) {
-            await chromeP.storage[this.area].remove(this.key);
+            await this.#storage.remove(this.key);
         }
         else {
-            await chromeP.storage[this.area].set({ [this.key]: value });
+            await this.#storage.set({ [this.key]: value });
         }
-    };
-    has = async () => {
-        const result = await chromeP.storage[this.area].get(this.key);
+    }
+    async has() {
+        const result = await this.#storage.get(this.key);
         // Do not use Object.hasOwn() due to https://github.com/RickyMarou/jest-webextension-mock/issues/20
         return result[this.key] !== undefined;
-    };
-    remove = async () => {
-        await chromeP.storage[this.area].remove(this.key);
-    };
+    }
+    async remove() {
+        await this.#storage.remove(this.key);
+    }
     onChanged(callback, signal) {
+        assertChromeStorageAvailable();
         const changeHandler = (changes, area) => {
             const changedItem = changes[this.key];
-            if (area === this.area && changedItem) {
-                // eslint-disable-next-line @typescript-eslint/no-unsafe-argument -- Assumes the user never uses the Storage API directly
+            if (area === this.area && changedItem && hasStorageValueChanged(changedItem)) {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-type-assertion -- Assumes the user never uses the Storage API directly
                 callback(changedItem.newValue);
             }
         };

package/distribution/storage-item.test-d.js

@@ -1,4 +1,5 @@
-/* eslint-disable @typescript-eslint/ban-types */
+/* eslint-disable @typescript-eslint/no-unnecessary-type-arguments -- Explicit type arguments are intentional in tsd assertions */
+/* eslint-disable @typescript-eslint/no-restricted-types -- null is an intentional test value */
 /* eslint-disable no-new -- Type tests only */
 import { expectType, expectNotAssignable, expectAssignable } from 'tsd';
 import { StorageItem } from './storage-item.js';

package/distribution/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function assertChromeStorageAvailable(): void;
+export declare function hasStorageValueChanged(change: chrome.storage.StorageChange): boolean;

package/distribution/utils.js

@@ -0,0 +1,12 @@
+export function assertChromeStorageAvailable() {
+    if (!globalThis.chrome?.storage) {
+        throw new TypeError('`chrome.storage` is not available. Make sure you\'re running in a browser extension context.');
+    }
+}
+// Workaround for https://github.com/w3c/webextensions/issues/511
+// Firefox fires onChanged even when set() is called with the same value
+export function hasStorageValueChanged(change) {
+    // eslint-disable-next-line n/no-unsupported-features/node-builtins -- browser extension context, not Node.js
+    return !globalThis.navigator?.userAgent.includes('Firefox')
+        || JSON.stringify(change.newValue) !== JSON.stringify(change.oldValue);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "webext-storage",
-	"version": "2.0.1",
+	"version": "3.0.0",
 	"description": "A more usable typed storage API for Web Extensions",
 	"keywords": [
 		"browser",
@@ -31,27 +31,14 @@
 		"test:watch": "vitest",
 		"watch": "tsc --watch"
 	},
-	"xo": {
-		"envs": [
-			"browser"
-		],
-		"globals": [
-			"chrome"
-		]
-	},
-	"dependencies": {
-		"webext-polyfill-kinda": "^1.0.2"
-	},
 	"devDependencies": {
-		"@sindresorhus/tsconfig": "^7.0.0",
-		"@types/chrome": "^0.0.300",
-		"@types/sinon-chrome": "^2.2.15",
+		"@sindresorhus/tsconfig": "^8.1.0",
+		"@types/chrome": "^0.1.39",
 		"jest-chrome": "^0.8.0",
-		"sinon-chrome": "^3.0.1",
-		"tsd": "^0.31.2",
-		"typescript": "^5.7.3",
-		"vitest": "^3.0.4",
-		"xo": "^0.60.0"
+		"tsd": "^0.33.0",
+		"typescript": "^6.0.2",
+		"vitest": "^4.1.2",
+		"xo": "^2.0.2"
 	},
 	"engines": {
 		"node": ">=20"

package/readme.md

@@ -60,7 +60,7 @@ The package exports two classes:
 Support:
 
 - Browsers: Chrome, Firefox, and Safari
-- Manifest: v2 and v3
+- Manifest: v3
 - Permissions: `storage` or `unlimitedStorage`
 - Context: They can be called from any context