wxt-svelte-storage 0.0.0-stage → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,98 @@
1
- # Temporary Holding Version
1
+ # WXT Svelte Storage
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Simple to use function and classes that wrap both Svelte built-ins and the browser extension storage API together into state-like reactive storages.
4
+
5
+ ## Usage
6
+
7
+ This package lists [@wxt-dev/storage](https://www.npmjs.com/package/@wxt-dev/storage) as a dependency, and works best with [WXT](https://wxt.dev/) although it can be used with other frameworks like [crxjs](https://github.com/crxjs/chrome-extension-tools).
8
+
9
+ It's best to export all of your individual state objects, maps, or sets in a single file such as `src/lib/Storage.ts`.
10
+
11
+ ### Basic example
12
+
13
+ `Storage.ts`:
14
+ ```typescript
15
+ import { stateStorage, SvelteMapStorage } from "wxt-svelte-storage";
16
+
17
+ // Strict typing
18
+ export const settings = stateStorage<{ theme: "light" | "dark" }>("local:settings", { theme: "light" });
19
+
20
+ // Inferred typing -- "clicks" will be a number
21
+ export const syncData = stateStorage("sync:data", { clicks: 0 });
22
+
23
+ // SvelteMapStorage example
24
+ export const items = new SvelteMapStorage<{ [key: string]: boolean }>("local:items", { "firstKey": true, "secondKey": false });
25
+ ```
26
+
27
+ `Component.svelte`:
28
+ ```svelte
29
+ <script lang="ts">
30
+ import { settings, syncData, items } from "Storage";
31
+ </script>
32
+
33
+ <div data-theme="{settings.theme}">
34
+ <button onclick={() => settings.theme = settings.theme === "light" ? "dark" : "light"}>Toggle {settings.theme} theme</button>
35
+ <button onclick={() => syncData.clicks++}>Click me!</button>
36
+ {#each items as [key, value]}
37
+ <div>
38
+ <span>{key}: {value}</span>
39
+ <button onclick={() => items.set(key, !value)}>Toggle {key}</button>
40
+ </div>
41
+ {/each}
42
+ {#if items.get("firstKey")}
43
+ <span>First key!</span>
44
+ {/if}
45
+ </div>
46
+ ```
47
+
48
+ ### Manually updating
49
+ You can set the `manualUpdate` argument to `true` when defining your storage constant, which returns a function to use to manually trigger the browser's storage update while still tracking and maintaining UI updates.
50
+
51
+ This is useful if you are rapidly causing state changes -- which trigger a slew of storage inserts that can cause the page to lag.
52
+
53
+ `Storage.ts`:
54
+ ```typescript
55
+ import { stateStorage } from "wxt-svelte-storage";
56
+
57
+ export const [settings, updateSettings] = stateStorage("sync:settings", { username: "" }, { manualUpdate: true });
58
+ ```
59
+
60
+ `Component.svelte`:
61
+ ```svelte
62
+ <script lang="ts">
63
+ import { settings, updateSettings } from "Storage";
64
+ </script>
65
+
66
+ <input type="text" bind:value={settings.username} onkeyup={updateSettings}>
67
+ ```
68
+
69
+ ### Avoiding flashing/flipping on storage load
70
+ Due to the fact that browser storage updates using [@wxt-dev/storage](https://www.npmjs.com/package/@wxt-dev/storage) are asynchronous, a quick flash or flip between the `initialValue` argument provided to `stateStorage` or `SvelteMapStorage` and the value actually stored on the browser may occur on page/content script load.
71
+
72
+ To avoid this, you can pass `async` to the settings when defining your storage constant.
73
+
74
+ `Storage.ts`:
75
+ ```typescript
76
+ import { stateStorage } from "wxt-svelte-storage";
77
+
78
+ // settings becomes a promise with a return type of { username: string; }
79
+ export const settings = stateStorage("sync:settings", { username: "" }, { async: true });
80
+ ```
81
+
82
+ You will have to `await` the initial value in your component -- either in the template or in an `onMount()` -- ex:
83
+
84
+ `Component.svelte`:
85
+ ```svelte
86
+ <script lang="ts">
87
+ import { settings } from "Storage";
88
+ </script>
89
+
90
+ <span>
91
+ Your username is:
92
+ {#await settings}
93
+ (loading...)
94
+ {:then fetchedSettings}
95
+ {fetchedSettings.username}
96
+ {/await}
97
+ </span>
98
+ ```
package/dist/index.cjs ADDED
@@ -0,0 +1,115 @@
1
+ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
+ let svelte_reactivity = require("svelte/reactivity");
3
+ let _wxt_dev_storage = require("@wxt-dev/storage");
4
+ // src/index.ts
5
+ function stateStorage(key, initialValue, { manualUpdate = false, async = false } = {}) {
6
+ let subscriberUpdate;
7
+ let currentState = initialValue;
8
+ const updateFromStorage = (result) => {
9
+ if (!result) return;
10
+ Object.assign(currentState, result);
11
+ subscriberUpdate?.();
12
+ };
13
+ const storageDefinition = _wxt_dev_storage.storage.defineItem(key, {
14
+ init: () => initialValue,
15
+ fallback: initialValue
16
+ });
17
+ const subscribe = (0, svelte_reactivity.createSubscriber)((update) => {
18
+ subscriberUpdate = update;
19
+ return storageDefinition.watch(updateFromStorage);
20
+ });
21
+ const proxy = new Proxy(currentState, {
22
+ get(target, prop, receiver) {
23
+ subscribe();
24
+ return Reflect.get(target, prop, receiver);
25
+ },
26
+ set(target, prop, value, receiver) {
27
+ const oldValue = Reflect.get(target, prop, receiver);
28
+ const result = Reflect.set(target, prop, value, receiver);
29
+ if (result && !Object.is(oldValue, target)) {
30
+ if (!manualUpdate) storageDefinition.setValue(target);
31
+ subscriberUpdate?.();
32
+ }
33
+ return result;
34
+ },
35
+ deleteProperty(target, prop) {
36
+ const hadKey = Reflect.has(target, prop);
37
+ const result = Reflect.deleteProperty(target, prop);
38
+ if (result && hadKey) {
39
+ if (!manualUpdate) storageDefinition.setValue(target);
40
+ subscriberUpdate?.();
41
+ }
42
+ return result;
43
+ }
44
+ });
45
+ const returnValue = manualUpdate ? [proxy, () => storageDefinition.setValue(currentState)] : proxy;
46
+ return async ? storageDefinition.getValue().then(updateFromStorage).then(() => Promise.resolve(returnValue)) : returnValue;
47
+ }
48
+ var SvelteMapStorage = class extends svelte_reactivity.SvelteMap {
49
+ storageDefinition;
50
+ manualUpdate;
51
+ constructor(key, initialValue, manualUpdate) {
52
+ super();
53
+ this.manualUpdate = !!manualUpdate;
54
+ this.storageDefinition = _wxt_dev_storage.storage.defineItem(key, {
55
+ init: () => initialValue,
56
+ fallback: initialValue
57
+ });
58
+ this.storageDefinition.getValue().then((results) => this.updateFromStorage(results)).finally(() => this.storageDefinition.watch((results) => this.updateFromStorage(results)));
59
+ }
60
+ updateFromStorage(results) {
61
+ if (!results) return;
62
+ super.clear();
63
+ for (const [key, value] of Object.entries(results)) super.set(key, value);
64
+ }
65
+ update() {
66
+ return this.storageDefinition.setValue(Object.fromEntries(this));
67
+ }
68
+ set(key, value) {
69
+ const newMap = super.set(key, value);
70
+ if (!this.manualUpdate) this.update();
71
+ return newMap;
72
+ }
73
+ delete(key) {
74
+ const deleted = super.delete(key);
75
+ if (deleted && !this.manualUpdate) this.update();
76
+ return deleted;
77
+ }
78
+ get(key) {
79
+ return super.get(key);
80
+ }
81
+ };
82
+ var SvelteSetStorage = class extends svelte_reactivity.SvelteSet {
83
+ storageDefinition;
84
+ manualUpdate;
85
+ constructor(key, initialValue, manualUpdate) {
86
+ super();
87
+ this.manualUpdate = !!manualUpdate;
88
+ this.storageDefinition = _wxt_dev_storage.storage.defineItem(key, {
89
+ init: () => initialValue,
90
+ fallback: initialValue
91
+ });
92
+ this.storageDefinition.getValue().then((results) => this.updateFromStorage(results)).finally(() => this.storageDefinition.watch((results) => this.updateFromStorage(results)));
93
+ }
94
+ updateFromStorage(results) {
95
+ if (!results) return;
96
+ super.clear();
97
+ for (const value of results) super.add(value);
98
+ }
99
+ update() {
100
+ return this.storageDefinition.setValue(this.values());
101
+ }
102
+ add(value) {
103
+ const newSet = super.add(value);
104
+ if (!this.manualUpdate) this.update();
105
+ return newSet;
106
+ }
107
+ delete(value) {
108
+ const deleted = super.delete(value);
109
+ if (deleted && !this.manualUpdate) this.update();
110
+ return deleted;
111
+ }
112
+ };
113
+ exports.SvelteMapStorage = SvelteMapStorage;
114
+ exports.SvelteSetStorage = SvelteSetStorage;
115
+ exports.stateStorage = stateStorage;
@@ -0,0 +1,28 @@
1
+ import { SvelteMap, SvelteSet } from "svelte/reactivity";
2
+ import { StorageItemKey } from "@wxt-dev/storage";
3
+ type StateStorageSettings = {
4
+ manualUpdate?: boolean;
5
+ async?: boolean;
6
+ };
7
+ type StateStorageReturn<T, S extends StateStorageSettings> = S['manualUpdate'] extends true ? [S['async'] extends true ? Promise<T> : T, () => Promise<void>] : S['async'] extends true ? Promise<T> : T;
8
+ export declare function stateStorage<T extends Record<string, unknown>, S extends StateStorageSettings = {}>(key: StorageItemKey, initialValue: T, settings?: S): StateStorageReturn<T, S>;
9
+ export declare class SvelteMapStorage<T extends Record<string, unknown>, K extends keyof T & string = keyof T & string> extends SvelteMap<K, T[K]> {
10
+ private storageDefinition;
11
+ private manualUpdate;
12
+ constructor(key: StorageItemKey, initialValue?: T, manualUpdate?: boolean);
13
+ private updateFromStorage;
14
+ update(): Promise<void>;
15
+ set(key: K, value: T[K]): this;
16
+ delete(key: K): boolean;
17
+ get<H extends T[K] = T[K]>(key: K): H;
18
+ }
19
+ export declare class SvelteSetStorage<T> extends SvelteSet<T> {
20
+ private storageDefinition;
21
+ private manualUpdate;
22
+ constructor(key: StorageItemKey, initialValue?: Iterable<T>, manualUpdate?: boolean);
23
+ private updateFromStorage;
24
+ update(): Promise<void>;
25
+ add(value: T): this;
26
+ delete(value: T): boolean;
27
+ }
28
+ export {};
@@ -0,0 +1,28 @@
1
+ import { SvelteMap, SvelteSet } from "svelte/reactivity";
2
+ import { StorageItemKey } from "@wxt-dev/storage";
3
+ type StateStorageSettings = {
4
+ manualUpdate?: boolean;
5
+ async?: boolean;
6
+ };
7
+ type StateStorageReturn<T, S extends StateStorageSettings> = S['manualUpdate'] extends true ? [S['async'] extends true ? Promise<T> : T, () => Promise<void>] : S['async'] extends true ? Promise<T> : T;
8
+ export declare function stateStorage<T extends Record<string, unknown>, S extends StateStorageSettings = {}>(key: StorageItemKey, initialValue: T, settings?: S): StateStorageReturn<T, S>;
9
+ export declare class SvelteMapStorage<T extends Record<string, unknown>, K extends keyof T & string = keyof T & string> extends SvelteMap<K, T[K]> {
10
+ private storageDefinition;
11
+ private manualUpdate;
12
+ constructor(key: StorageItemKey, initialValue?: T, manualUpdate?: boolean);
13
+ private updateFromStorage;
14
+ update(): Promise<void>;
15
+ set(key: K, value: T[K]): this;
16
+ delete(key: K): boolean;
17
+ get<H extends T[K] = T[K]>(key: K): H;
18
+ }
19
+ export declare class SvelteSetStorage<T> extends SvelteSet<T> {
20
+ private storageDefinition;
21
+ private manualUpdate;
22
+ constructor(key: StorageItemKey, initialValue?: Iterable<T>, manualUpdate?: boolean);
23
+ private updateFromStorage;
24
+ update(): Promise<void>;
25
+ add(value: T): this;
26
+ delete(value: T): boolean;
27
+ }
28
+ export {};
package/dist/index.mjs ADDED
@@ -0,0 +1,112 @@
1
+ import { SvelteMap, SvelteSet, createSubscriber } from "svelte/reactivity";
2
+ import { storage } from "@wxt-dev/storage";
3
+ // src/index.ts
4
+ function stateStorage(key, initialValue, { manualUpdate = false, async = false } = {}) {
5
+ let subscriberUpdate;
6
+ let currentState = initialValue;
7
+ const updateFromStorage = (result) => {
8
+ if (!result) return;
9
+ Object.assign(currentState, result);
10
+ subscriberUpdate?.();
11
+ };
12
+ const storageDefinition = storage.defineItem(key, {
13
+ init: () => initialValue,
14
+ fallback: initialValue
15
+ });
16
+ const subscribe = createSubscriber((update) => {
17
+ subscriberUpdate = update;
18
+ return storageDefinition.watch(updateFromStorage);
19
+ });
20
+ const proxy = new Proxy(currentState, {
21
+ get(target, prop, receiver) {
22
+ subscribe();
23
+ return Reflect.get(target, prop, receiver);
24
+ },
25
+ set(target, prop, value, receiver) {
26
+ const oldValue = Reflect.get(target, prop, receiver);
27
+ const result = Reflect.set(target, prop, value, receiver);
28
+ if (result && !Object.is(oldValue, target)) {
29
+ if (!manualUpdate) storageDefinition.setValue(target);
30
+ subscriberUpdate?.();
31
+ }
32
+ return result;
33
+ },
34
+ deleteProperty(target, prop) {
35
+ const hadKey = Reflect.has(target, prop);
36
+ const result = Reflect.deleteProperty(target, prop);
37
+ if (result && hadKey) {
38
+ if (!manualUpdate) storageDefinition.setValue(target);
39
+ subscriberUpdate?.();
40
+ }
41
+ return result;
42
+ }
43
+ });
44
+ const returnValue = manualUpdate ? [proxy, () => storageDefinition.setValue(currentState)] : proxy;
45
+ return async ? storageDefinition.getValue().then(updateFromStorage).then(() => Promise.resolve(returnValue)) : returnValue;
46
+ }
47
+ var SvelteMapStorage = class extends SvelteMap {
48
+ storageDefinition;
49
+ manualUpdate;
50
+ constructor(key, initialValue, manualUpdate) {
51
+ super();
52
+ this.manualUpdate = !!manualUpdate;
53
+ this.storageDefinition = storage.defineItem(key, {
54
+ init: () => initialValue,
55
+ fallback: initialValue
56
+ });
57
+ this.storageDefinition.getValue().then((results) => this.updateFromStorage(results)).finally(() => this.storageDefinition.watch((results) => this.updateFromStorage(results)));
58
+ }
59
+ updateFromStorage(results) {
60
+ if (!results) return;
61
+ super.clear();
62
+ for (const [key, value] of Object.entries(results)) super.set(key, value);
63
+ }
64
+ update() {
65
+ return this.storageDefinition.setValue(Object.fromEntries(this));
66
+ }
67
+ set(key, value) {
68
+ const newMap = super.set(key, value);
69
+ if (!this.manualUpdate) this.update();
70
+ return newMap;
71
+ }
72
+ delete(key) {
73
+ const deleted = super.delete(key);
74
+ if (deleted && !this.manualUpdate) this.update();
75
+ return deleted;
76
+ }
77
+ get(key) {
78
+ return super.get(key);
79
+ }
80
+ };
81
+ var SvelteSetStorage = class extends SvelteSet {
82
+ storageDefinition;
83
+ manualUpdate;
84
+ constructor(key, initialValue, manualUpdate) {
85
+ super();
86
+ this.manualUpdate = !!manualUpdate;
87
+ this.storageDefinition = storage.defineItem(key, {
88
+ init: () => initialValue,
89
+ fallback: initialValue
90
+ });
91
+ this.storageDefinition.getValue().then((results) => this.updateFromStorage(results)).finally(() => this.storageDefinition.watch((results) => this.updateFromStorage(results)));
92
+ }
93
+ updateFromStorage(results) {
94
+ if (!results) return;
95
+ super.clear();
96
+ for (const value of results) super.add(value);
97
+ }
98
+ update() {
99
+ return this.storageDefinition.setValue(this.values());
100
+ }
101
+ add(value) {
102
+ const newSet = super.add(value);
103
+ if (!this.manualUpdate) this.update();
104
+ return newSet;
105
+ }
106
+ delete(value) {
107
+ const deleted = super.delete(value);
108
+ if (deleted && !this.manualUpdate) this.update();
109
+ return deleted;
110
+ }
111
+ };
112
+ export { SvelteMapStorage, SvelteSetStorage, stateStorage };
package/package.json CHANGED
@@ -1,6 +1,39 @@
1
1
  {
2
- "name": "wxt-svelte-storage",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "wxt-svelte-storage",
3
+ "version": "0.0.1",
4
+ "keywords": [
5
+ "svelte"
6
+ ],
7
+ "type": "module",
8
+ "main": "./dist/index.cjs",
9
+ "module": "./dist/index.mjs",
10
+ "types": "./dist/index.d.cts",
11
+ "files": [
12
+ "dist"
13
+ ],
14
+ "scripts": {
15
+ "build": "tsdown",
16
+ "check": "bun run build && check",
17
+ "prepublishOnly": "bun run build"
18
+ },
19
+ "devDependencies": {
20
+ "@arethetypeswrong/core": "^0.18.5",
21
+ "@types/bun": "^1.4.5",
22
+ "publint": "^0.3.25",
23
+ "tsdown": "^0.23.7",
24
+ "typescript": "6.0.2"
25
+ },
26
+ "dependencies": {
27
+ "@wxt-dev/storage": "^1.4.0"
28
+ },
29
+ "peerDependencies": {
30
+ "svelte": "^5.59.1"
31
+ },
32
+ "exports": {
33
+ ".": {
34
+ "import": "./dist/index.mjs",
35
+ "require": "./dist/index.cjs"
36
+ },
37
+ "./package.json": "./package.json"
38
+ }
39
+ }