webext-storage 1.2.2 → 1.3.1

package/distribution/index.d.ts

@@ -0,0 +1,2 @@
+export * from './storage-item.js';
+export * from './storage-item-map.js';

package/distribution/index.js

@@ -0,0 +1,2 @@
+export * from './storage-item.js';
+export * from './storage-item-map.js';

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

@@ -0,0 +1,22 @@
+export type StorageItemMapOptions<T> = {
+    area?: chrome.storage.AreaName;
+    defaultValue?: T;
+};
+export declare class StorageItemMap<
+/** Only specify this if you don't have a default value */
+Base, 
+/** The return type will be undefined unless you provide a default value */
+Return = Base | undefined> {
+    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>;
+    delete: (secondaryKey: string) => Promise<void>;
+    get: (secondaryKey: string) => Promise<Return>;
+    set: (secondaryKey: string, value: Exclude<Return, undefined>) => Promise<void>;
+    remove: (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

@@ -0,0 +1,63 @@
+import chromeP from 'webext-polyfill-kinda';
+export class StorageItemMap {
+    prefix;
+    areaName;
+    defaultValue;
+    constructor(key, { area = 'local', defaultValue, } = {}) {
+        this.prefix = `${key}:::`;
+        this.areaName = area;
+        this.defaultValue = defaultValue;
+    }
+    has = async (secondaryKey) => {
+        const rawStorageKey = this.getRawStorageKey(secondaryKey);
+        const result = await chromeP.storage[this.areaName].get(rawStorageKey);
+        return Object.hasOwn(result, secondaryKey);
+    };
+    delete = async (secondaryKey) => {
+        const rawStorageKey = this.getRawStorageKey(secondaryKey);
+        await chromeP.storage[this.areaName].remove(rawStorageKey);
+    };
+    get = async (secondaryKey) => {
+        const rawStorageKey = this.getRawStorageKey(secondaryKey);
+        const result = await chromeP.storage[this.areaName].get(rawStorageKey);
+        if (!Object.hasOwn(result, rawStorageKey)) {
+            return this.defaultValue;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- Assumes the user never uses the Storage API directly for this key
+        return result[rawStorageKey];
+    };
+    set = async (secondaryKey, value) => {
+        const rawStorageKey = this.getRawStorageKey(secondaryKey);
+        await chromeP.storage[this.areaName].set({ [rawStorageKey]: value });
+    };
+    remove = async (secondaryKey) => {
+        const rawStorageKey = this.getRawStorageKey(secondaryKey);
+        await chromeP.storage[this.areaName].remove(rawStorageKey);
+    };
+    onChanged(callback, signal) {
+        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
+                    callback(secondaryKey, changes[rawKey].newValue);
+                }
+            }
+        };
+        chrome.storage.onChanged.addListener(changeHandler);
+        signal?.addEventListener('abort', () => {
+            chrome.storage.onChanged.removeListener(changeHandler);
+        }, {
+            once: true,
+        });
+    }
+    getRawStorageKey(secondaryKey) {
+        return this.prefix + secondaryKey;
+    }
+    getSecondaryStorageKey(rawKey) {
+        return rawKey.startsWith(this.prefix) && rawKey.slice(this.prefix.length);
+    }
+}

package/distribution/storage-item.d.ts

@@ -1,17 +1,20 @@
-/// <reference types="chrome" />
 export type StorageItemOptions<T> = {
     area?: chrome.storage.AreaName;
     defaultValue?: T;
 };
-export declare class StorageItem<Base, Default = Base | undefined, Return = Default extends undefined ? Base : Default> {
+export declare class StorageItem<
+/** Only specify this if you don't have a default value */
+Base, 
+/** The return type will be undefined unless you provide a default value */
+Return = Base | undefined> {
     readonly key: string;
     readonly area: chrome.storage.AreaName;
-    readonly defaultValue?: Default;
+    readonly defaultValue?: Return;
     /** @deprecated Use `onChanged` instead */
-    onChange: (callback: (value: NonNullable<Default>) => void, signal?: AbortSignal) => void;
-    constructor(key: string, { area, defaultValue, }?: StorageItemOptions<NonNullable<Default>>);
+    onChange: (callback: (value: Exclude<Return, undefined>) => void, signal?: AbortSignal) => void;
+    constructor(key: string, { area, defaultValue, }?: StorageItemOptions<Exclude<Return, undefined>>);
     get: () => Promise<Return>;
-    set: (value: NonNullable<Default>) => Promise<void>;
+    set: (value: Exclude<Return, undefined>) => Promise<void>;
     remove: () => Promise<void>;
-    onChanged(callback: (value: NonNullable<Default>) => void, signal?: AbortSignal): void;
+    onChanged(callback: (value: Exclude<Return, undefined>) => void, signal?: AbortSignal): void;
 }

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,53 @@
+/* eslint-disable @typescript-eslint/ban-types */
+/* eslint-disable no-new -- Type tests only */
+import { expectType, expectNotAssignable, expectAssignable } from 'tsd';
+import { StorageItem } from './storage-item.js';
+new StorageItem('key', { area: 'local' });
+new StorageItem('key', { area: 'sync' });
+// No type, no default, return `unknown`
+const unknownItem = new StorageItem('key');
+expectAssignable(unknownItem.get());
+await unknownItem.set(1);
+await unknownItem.set(null);
+// Explicit type, no default, return `T | undefined`
+const objectNoDefault = new StorageItem('key');
+expectType(objectNoDefault.get());
+expectType(objectNoDefault.set({ name: 'new name' }));
+// NonNullable from default
+const stringDefault = new StorageItem('key', { defaultValue: 'SMASHING' });
+expectAssignable(stringDefault.get());
+expectNotAssignable(stringDefault.get());
+expectType(stringDefault.get());
+expectType(stringDefault.set('some string'));
+// NonNullable from default, includes broader type as generic
+// The second type parameter must be re-specified because TypeScript stops inferring it
+// https://github.com/microsoft/TypeScript/issues/26242
+const broadGeneric = new StorageItem('key', { defaultValue: { a: 1 } });
+expectAssignable(broadGeneric.get());
+// Allows null as a value via default value
+const storeNull = new StorageItem('key', { defaultValue: null });
+await storeNull.set(null);
+expectType(storeNull.get());
+// Allows null as a value type parameters
+const storeSomeNull = new StorageItem('key');
+await storeSomeNull.set(1);
+await storeSomeNull.set(null);
+expectType(storeSomeNull.get());
+// @ts-expect-error Type is string
+await stringDefault.set(1);
+// @ts-expect-error Type is string
+await stringDefault.set(true);
+// @ts-expect-error Type is string
+await stringDefault.set([true, 'string']);
+// @ts-expect-error Type is string
+await stringDefault.set({ wow: [true, 'string'] });
+// @ts-expect-error Type is string
+await stringDefault.set(1, { days: 1 });
+stringDefault.onChanged(value => {
+    expectType(value);
+});
+objectNoDefault.onChanged(value => {
+    expectType(value);
+});
+// @ts-expect-error Don't allow mismatched types
+new StorageItem('key', { defaultValue: 'SMASHING' });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "webext-storage",
-	"version": "1.2.2",
+	"version": "1.3.1",
 	"description": "A more usable typed storage API for Web Extensions",
 	"keywords": [
 		"browser",
@@ -21,17 +21,13 @@
 	"license": "MIT",
 	"author": "Federico Brigante <me@fregante.com> (https://fregante.com)",
 	"type": "module",
-	"exports": "./distribution/storage-item.js",
-	"main": "./distribution/storage-item.js",
-	"types": "./distribution/storage-item.d.ts",
-	"files": [
-		"distribution/storage-item.js",
-		"distribution/storage-item.d.ts"
-	],
+	"exports": "./distribution/index.js",
+	"main": "./distribution/index.js",
+	"types": "./distribution/index.d.ts",
 	"scripts": {
 		"build": "tsc",
 		"prepack": "tsc --sourceMap false",
-		"test": "tsc --noEmit && xo && tsd && vitest run",
+		"test": "tsc && xo && tsd && vitest run",
 		"test:watch": "vitest",
 		"watch": "tsc --watch"
 	},
@@ -47,15 +43,15 @@
 		"webext-polyfill-kinda": "^1.0.2"
 	},
 	"devDependencies": {
-		"@sindresorhus/tsconfig": "^5.0.0",
-		"@types/chrome": "^0.0.248",
-		"@types/sinon-chrome": "^2.2.13",
+		"@sindresorhus/tsconfig": "^7.0.0",
+		"@types/chrome": "^0.0.300",
+		"@types/sinon-chrome": "^2.2.15",
 		"jest-chrome": "^0.8.0",
 		"sinon-chrome": "^3.0.1",
-		"tsd": "^0.29.0",
-		"typescript": "^5.2.2",
-		"vitest": "^0.34.6",
-		"xo": "^0.56.0"
+		"tsd": "^0.31.2",
+		"typescript": "^5.7.3",
+		"vitest": "^3.0.4",
+		"xo": "^0.60.0"
 	},
 	"engines": {
 		"node": ">=20"

package/readme.md

@@ -5,27 +5,13 @@
 
 > A more usable typed storage API for Web Extensions
 
-- Browsers: Chrome, Firefox, and Safari
-- Manifest: v2 and v3
-- Permissions: `storage` or `unlimitedStorage`
-- Context: They can be called from any context
-
 **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:
+`chrome.storage.local.get()` is very inconvenient to use and it's not type-safe. 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)
-	}
-});
+<details><summary>Comparison 💥</summary>
 
-// After
+```ts
 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
@@ -34,47 +20,48 @@ options.onChanged(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
+- `item.get()` returns the raw value instead of an object
 - Every `get` and `set` operation is type-safe
 - If you provide a `defaultValue`, the return type will not be ` | undefined`
 - The `onChanged` example speaks for itself
 
+Now compare it to the native API:
+
+```ts
+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)
+	}
+});
+```
+
+</details>
+
 ## Install
 
 ```sh
 npm install webext-storage
 ```
 
-Or download the [standalone bundle](https://bundle.fregante.com/?pkg=webext-storage&name=StorageItem) to include in your `manifest.json`.
+Or download the [standalone bundle](https://bundle.fregante.com/?pkg=webext-storage&name=window) to include in your `manifest.json`.
 
 ## Usage
 
-```ts
-import {StorageItem} from "webext-storage";
+The package exports two classes:
 
-const username = new StorageItem<string>('username')
-// Or
-const username = new StorageItem('username', {defaultValue: 'admin'})
+- [StorageItem](./source/storage-item.md) - Store a single value in storage
+- [StorageItemMap](./source/storage-item-map.md) - Store multiple related values in storage with the same type, similar to `new Map()`
 
-await username.set('Ugo');
-// Promise<void>
+Support:
 
-await username.get();
-// Promise<string>
-
-await username.remove();
-// Promise<void>
-
-await username.set({name: 'Ugo'});
-// TypeScript Error: Argument of type '{ name: string; }' is not assignable to parameter of type 'string'.
-
-username.onChanged(newName => {
-	console.log('The user’s new name is', newName);
-});
-```
+- Browsers: Chrome, Firefox, and Safari
+- Manifest: v2 and v3
+- Permissions: `storage` or `unlimitedStorage`
+- Context: They can be called from any context
 
 ## Related