webext-storage 0.0.0 → 1.1.0

package/distribution/storage-item.d.ts

@@ -1,12 +1,15 @@
 /// <reference types="chrome" />
-export type StorageItemOptions = {
+export type StorageItemOptions<T> = {
     area?: chrome.storage.AreaName;
+    defaultValue?: T;
 };
-export declare class StorageItem<T> {
+export declare class StorageItem<Base, InferredBase extends (Base | undefined) = Base | undefined, Return = InferredBase extends undefined ? Base | undefined : InferredBase> {
     readonly key: string;
     readonly area: chrome.storage.AreaName;
-    constructor(key: string, { area }?: StorageItemOptions);
-    get(): Promise<T | undefined>;
-    set(value: T): Promise<void>;
-    onChange(callback: (value: T) => void, signal?: AbortSignal): void;
+    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;
 }

package/distribution/storage-item.js

@@ -2,14 +2,16 @@ import chromeP from 'webext-polyfill-kinda';
 export class StorageItem {
     key;
     area;
-    constructor(key, { area = 'local' } = {}) {
+    defaultValue;
+    constructor(key, { area = 'local', defaultValue, } = {}) {
         this.key = key;
         this.area = area;
+        this.defaultValue = defaultValue;
     }
     async get() {
         const result = await chromeP.storage[this.area].get(this.key);
         if (!Object.hasOwn(result, this.key)) {
-            return;
+            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];
@@ -17,9 +19,11 @@ export class StorageItem {
     async set(value) {
         await chromeP.storage[this.area].set({ [this.key]: value });
     }
+    async remove() {
+        await chromeP.storage[this.area].remove(this.key);
+    }
     onChange(callback, signal) {
         const changeHandler = (changes, area) => {
-            console.log('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
@@ -29,6 +33,8 @@ export class StorageItem {
         chrome.storage.onChanged.addListener(changeHandler);
         signal?.addEventListener('abort', () => {
             chrome.storage.onChanged.removeListener(changeHandler);
-        }, { once: true });
+        }, {
+            once: true,
+        });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "webext-storage",
-	"version": "0.0.0",
+	"version": "1.1.0",
 	"description": "A more usable typed storage API for Web Extensions",
 	"keywords": [
 		"browser",
@@ -25,7 +25,8 @@
 	"main": "./distribution/storage-item.js",
 	"types": "./distribution/storage-item.d.ts",
 	"files": [
-		"distribution"
+		"distribution/storage-item.js",
+		"distribution/storage-item.d.ts"
 	],
 	"scripts": {
 		"build": "tsc",
@@ -51,7 +52,7 @@
 		"@types/sinon-chrome": "^2.2.13",
 		"jest-chrome": "^0.8.0",
 		"sinon-chrome": "^3.0.1",
-		"tsd": "^0.28.1",
+		"tsd": "^0.29.0",
 		"typescript": "^5.2.2",
 		"vitest": "^0.34.6",
 		"xo": "^0.56.0"

package/readme.md

@@ -5,6 +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:
+
 ## Install
 
 ```sh
@@ -19,6 +26,8 @@ Or download the [standalone bundle](https://bundle.fregante.com/?pkg=webext-stor
 import {StorageItem} from "webext-storage";
 
 const username = new StorageItem<string>('username')
+// Or
+const username = new StorageItem('username', {defaultValue: 'admin'})
 
 await username.set('Ugo');
 // Promise<void>
@@ -26,6 +35,9 @@ await username.set('Ugo');
 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'.
 

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

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

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

@@ -1,25 +0,0 @@
-/* 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' });
-const unknownItem = new StorageItem('key');
-expectAssignable(unknownItem.get());
-const objectItem = new StorageItem('key');
-expectType(objectItem.get());
-expectType(objectItem.set({ name: 'new name' }));
-const stringItem = new StorageItem('key');
-expectAssignable(stringItem.get());
-expectNotAssignable(stringItem.get());
-expectType(stringItem.get());
-expectType(stringItem.set('some string'));
-// @ts-expect-error Type is string
-await stringItem.set(1);
-// @ts-expect-error Type is string
-await stringItem.set(true);
-// @ts-expect-error Type is string
-await stringItem.set([true, 'string']);
-// @ts-expect-error Type is string
-await stringItem.set({ wow: [true, 'string'] });
-// @ts-expect-error Type is string
-await stringItem.set(1, { days: 1 });