webext-storage 1.1.0 → 1.2.1

package/distribution/storage-item.d.ts

@@ -3,13 +3,13 @@ export type StorageItemOptions<T> = {
     area?: chrome.storage.AreaName;
     defaultValue?: T;
 };
-export declare class StorageItem<Base, InferredBase extends (Base | undefined) = Base | undefined, Return = InferredBase extends undefined ? Base | undefined : InferredBase> {
+export declare class StorageItem<Base, Default = Base | undefined, Return = Default extends undefined ? Base : Default> {
     readonly key: string;
     readonly area: chrome.storage.AreaName;
-    readonly defaultValue?: InferredBase;
-    constructor(key: string, { area, defaultValue, }?: StorageItemOptions<NonNullable<InferredBase>>);
-    get(): Promise<Return>;
-    set(value: NonNullable<InferredBase>): Promise<void>;
-    remove(): Promise<void>;
-    onChange(callback: (value: NonNullable<InferredBase>) => void, signal?: AbortSignal): void;
+    readonly defaultValue?: Default;
+    constructor(key: string, { area, defaultValue, }?: StorageItemOptions<NonNullable<Default>>);
+    get: () => Promise<Return>;
+    set: (value: NonNullable<Default>) => Promise<void>;
+    remove: () => Promise<void>;
+    onChange(callback: (value: NonNullable<Default>) => void, signal?: AbortSignal): void;
 }

package/distribution/storage-item.js

@@ -8,20 +8,20 @@ export class StorageItem {
         this.area = area;
         this.defaultValue = defaultValue;
     }
-    async get() {
+    get = async () => {
         const result = await chromeP.storage[this.area].get(this.key);
         if (!Object.hasOwn(result, this.key)) {
             return this.defaultValue;
         }
         // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- Assumes the user never uses the Storage API directly
         return result[this.key];
-    }
-    async set(value) {
+    };
+    set = async (value) => {
         await chromeP.storage[this.area].set({ [this.key]: value });
-    }
-    async remove() {
+    };
+    remove = async () => {
         await chromeP.storage[this.area].remove(this.key);
-    }
+    };
     onChange(callback, signal) {
         const changeHandler = (changes, area) => {
             const changedItem = changes[this.key];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "webext-storage",
-	"version": "1.1.0",
+	"version": "1.2.1",
 	"description": "A more usable typed storage API for Web Extensions",
 	"keywords": [
 		"browser",

package/readme.md

@@ -12,6 +12,36 @@
 
 **Sponsored by [PixieBrix](https://www.pixiebrix.com)** :tada:
 
+`chrome.storage.local.get()` is very inconvenient to use and it does not provide type safety. This module provides a better API:
+
+```ts
+// Before
+const storage = await chrome.storage.local.get('user-options');
+const value = storage['user-options']; // The type is `any`
+await chrome.storage.local.set({['user-options']: {color: 'red'}}); // Not type-checked
+chrome.storage.onChanged.addListener((storageArea, change) => {
+	if (storageArea === 'local' && change['user-options']) { // Repetitive
+		console.log('New options', change['user-options'].newValue)
+	}
+});
+
+// After
+const options = new StorageItem<Record<string, string>>('user-options');
+const value = await options.get(); // The type is `Record<string, string> | undefined`
+await options.set({color: 'red'}) // Type-checked
+options.onChange(newValue => {
+	console.log('New options', newValue)
+});
+```
+
+Why this is better:
+
+- The storage item is defined in a single place, including its storageArea, its types and default value
+- `get` only is only `.get()` instead of the awkward post-get object access that
+- Every `get` and `set` operation is type-safe
+- If you provide a `defaultValue`, the return type will not be ` | undefined`
+- The `onChange` example speaks for itself
+
 ## Install
 
 ```sh
@@ -48,7 +78,7 @@ username.onChange(newName => {
 
 ## Related
 
-- [webext-storage-cache](https://github.com/fregante/webext-storage-cache) - Detects where the current browser extension code is being run.
+- [webext-storage-cache](https://github.com/fregante/webext-storage-cache) - Cache values in your Web Extension and clear them on expiration.
 - [webext-tools](https://github.com/fregante/webext-tools) - Utility functions for Web Extensions.
 - [webext-content-scripts](https://github.com/fregante/webext-content-scripts) - Utility functions to inject content scripts in WebExtensions.
 - [webext-base-css](https://github.com/fregante/webext-base-css) - Extremely minimal stylesheet/setup for Web Extensions’ options pages (also dark mode)