@wxt-dev/storage 1.2.6 → 1.2.8

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/dist/index.d.mts CHANGED
@@ -1,277 +1,279 @@
1
- import { Browser } from '@wxt-dev/browser';
1
+ import { Browser } from "@wxt-dev/browser";
2
2
 
3
+ //#region src/index.d.ts
3
4
  declare const storage: WxtStorage;
4
5
  interface WxtStorage {
5
- /**
6
- * Get an item from storage, or return `null` if it doesn't exist.
7
- *
8
- * @example
9
- * await storage.getItem<number>("local:installDate");
10
- */
11
- getItem<TValue>(key: StorageItemKey, opts: GetItemOptions<TValue> & {
12
- fallback: TValue;
13
- }): Promise<TValue>;
14
- getItem<TValue>(key: StorageItemKey, opts?: GetItemOptions<TValue>): Promise<TValue | null>;
15
- /**
16
- * Get multiple items from storage. The return order is guaranteed to be the same as the order
17
- * requested.
18
- *
19
- * @example
20
- * await storage.getItems(["local:installDate", "session:someCounter"]);
21
- */
22
- getItems(keys: Array<StorageItemKey | WxtStorageItem<any, any> | {
23
- key: StorageItemKey;
24
- options?: GetItemOptions<any>;
25
- }>): Promise<Array<{
26
- key: StorageItemKey;
27
- value: any;
28
- }>>;
29
- /**
30
- * Return an object containing metadata about the key. Object is stored at `key + "$"`. If value
31
- * is not an object, it returns an empty object.
32
- *
33
- * @example
34
- * await storage.getMeta("local:installDate");
35
- */
36
- getMeta<T extends Record<string, unknown>>(key: StorageItemKey): Promise<T>;
37
- /**
38
- * Get the metadata of multiple storage items.
39
- *
40
- * @param items List of keys or items to get the metadata of.
41
- * @returns An array containing storage keys and their metadata.
42
- */
43
- getMetas(keys: Array<StorageItemKey | WxtStorageItem<any, any>>): Promise<Array<{
44
- key: StorageItemKey;
45
- meta: any;
46
- }>>;
47
- /**
48
- * Set a value in storage. Setting a value to `null` or `undefined` is equivalent to calling
49
- * `removeItem`.
50
- *
51
- * @example
52
- * await storage.setItem<number>("local:installDate", Date.now());
53
- */
54
- setItem<T>(key: StorageItemKey, value: T | null): Promise<void>;
55
- /**
56
- * Set multiple values in storage. If a value is set to `null` or `undefined`, the key is removed.
57
- *
58
- * @example
59
- * await storage.setItem([
60
- * { key: "local:installDate", value: Date.now() },
61
- * { key: "session:someCounter, value: 5 },
62
- * ]);
63
- */
64
- setItems(values: Array<{
65
- key: StorageItemKey;
66
- value: any;
67
- } | {
68
- item: WxtStorageItem<any, any>;
69
- value: any;
70
- }>): Promise<void>;
71
- /**
72
- * Sets metadata properties. If some properties are already set, but are not included in the
73
- * `properties` parameter, they will not be removed.
74
- *
75
- * @example
76
- * await storage.setMeta("local:installDate", { appVersion });
77
- */
78
- setMeta<T extends Record<string, unknown>>(key: StorageItemKey, properties: T | null): Promise<void>;
79
- /**
80
- * Set the metadata of multiple storage items.
81
- *
82
- * @param items List of storage keys or items and metadata to set for each.
83
- */
84
- setMetas(metas: Array<{
85
- key: StorageItemKey;
86
- meta: Record<string, any>;
87
- } | {
88
- item: WxtStorageItem<any, any>;
89
- meta: Record<string, any>;
90
- }>): Promise<void>;
91
- /**
92
- * Removes an item from storage.
93
- *
94
- * @example
95
- * await storage.removeItem("local:installDate");
96
- */
97
- removeItem(key: StorageItemKey, opts?: RemoveItemOptions): Promise<void>;
98
- /**
99
- * Remove a list of keys from storage.
100
- */
101
- removeItems(keys: Array<StorageItemKey | WxtStorageItem<any, any> | {
102
- key: StorageItemKey;
103
- options?: RemoveItemOptions;
104
- } | {
105
- item: WxtStorageItem<any, any>;
106
- options?: RemoveItemOptions;
107
- }>): Promise<void>;
108
- /**
109
- * Removes all items from the provided storage area.
110
- */
111
- clear(base: StorageArea): Promise<void>;
112
- /**
113
- * Remove the entire metadata for a key, or specific properties by name.
114
- *
115
- * @example
116
- * // Remove all metadata properties from the item
117
- * await storage.removeMeta("local:installDate");
118
- *
119
- * // Remove only specific the "v" field
120
- * await storage.removeMeta("local:installDate", "v")
121
- */
122
- removeMeta(key: StorageItemKey, properties?: string | string[]): Promise<void>;
123
- /**
124
- * Return all the items in storage.
125
- */
126
- snapshot(base: StorageArea, opts?: SnapshotOptions): Promise<Record<string, unknown>>;
127
- /**
128
- * Restores the results of `snapshot`. If new properties have been saved since the snapshot, they are
129
- * not overridden. Only values existing in the snapshot are overridden.
130
- */
131
- restoreSnapshot(base: StorageArea, data: any): Promise<void>;
132
- /**
133
- * Watch for changes to a specific key in storage.
134
- */
135
- watch<T>(key: StorageItemKey, cb: WatchCallback<T | null>): Unwatch;
136
- /**
137
- * Remove all watch listeners.
138
- */
139
- unwatch(): void;
140
- /**
141
- * Define a storage item with a default value, type, or versioning.
142
- *
143
- * Read full docs: https://wxt.dev/storage.html#defining-storage-items
144
- */
145
- defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey): WxtStorageItem<TValue | null, TMetadata>;
146
- defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue> & {
147
- fallback: TValue;
148
- }): WxtStorageItem<TValue, TMetadata>;
149
- defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue> & {
150
- defaultValue: TValue;
151
- }): WxtStorageItem<TValue, TMetadata>;
152
- defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue | null, TMetadata>;
153
- }
154
- interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
155
- /**
156
- * The storage key passed when creating the storage item.
157
- */
6
+ /**
7
+ * Get an item from storage, or return `null` if it doesn't exist.
8
+ *
9
+ * @example
10
+ * await storage.getItem<number>("local:installDate");
11
+ */
12
+ getItem<TValue>(key: StorageItemKey, opts: GetItemOptions<TValue> & {
13
+ fallback: TValue;
14
+ }): Promise<TValue>;
15
+ getItem<TValue>(key: StorageItemKey, opts?: GetItemOptions<TValue>): Promise<TValue | null>;
16
+ /**
17
+ * Get multiple items from storage. The return order is guaranteed to be the same as the order
18
+ * requested.
19
+ *
20
+ * @example
21
+ * await storage.getItems(["local:installDate", "session:someCounter"]);
22
+ */
23
+ getItems(keys: Array<StorageItemKey | WxtStorageItem<any, any> | {
158
24
  key: StorageItemKey;
159
- /**
160
- * @deprecated Renamed to fallback, use it instead.
161
- */
162
- defaultValue: TValue;
163
- /**
164
- * The value provided by the `fallback` option.
165
- */
25
+ options?: GetItemOptions<any>;
26
+ }>): Promise<Array<{
27
+ key: StorageItemKey;
28
+ value: any;
29
+ }>>;
30
+ /**
31
+ * Return an object containing metadata about the key. Object is stored at `key + "$"`. If value
32
+ * is not an object, it returns an empty object.
33
+ *
34
+ * @example
35
+ * await storage.getMeta("local:installDate");
36
+ */
37
+ getMeta<T extends Record<string, unknown>>(key: StorageItemKey): Promise<T>;
38
+ /**
39
+ * Get the metadata of multiple storage items.
40
+ *
41
+ * @param keys List of keys or items to get the metadata of.
42
+ * @returns An array containing storage keys and their metadata.
43
+ */
44
+ getMetas(keys: Array<StorageItemKey | WxtStorageItem<any, any>>): Promise<Array<{
45
+ key: StorageItemKey;
46
+ meta: any;
47
+ }>>;
48
+ /**
49
+ * Set a value in storage. Setting a value to `null` or `undefined` is equivalent to calling
50
+ * `removeItem`.
51
+ *
52
+ * @example
53
+ * await storage.setItem<number>("local:installDate", Date.now());
54
+ */
55
+ setItem<T>(key: StorageItemKey, value: T | null): Promise<void>;
56
+ /**
57
+ * Set multiple values in storage. If a value is set to `null` or `undefined`, the key is removed.
58
+ *
59
+ * @example
60
+ * await storage.setItem([
61
+ * { key: "local:installDate", value: Date.now() },
62
+ * { key: "session:someCounter, value: 5 },
63
+ * ]);
64
+ */
65
+ setItems(values: Array<{
66
+ key: StorageItemKey;
67
+ value: any;
68
+ } | {
69
+ item: WxtStorageItem<any, any>;
70
+ value: any;
71
+ }>): Promise<void>;
72
+ /**
73
+ * Sets metadata properties. If some properties are already set, but are not included in the
74
+ * `properties` parameter, they will not be removed.
75
+ *
76
+ * @example
77
+ * await storage.setMeta("local:installDate", { appVersion });
78
+ */
79
+ setMeta<T extends Record<string, unknown>>(key: StorageItemKey, properties: T | null): Promise<void>;
80
+ /**
81
+ * Set the metadata of multiple storage items.
82
+ *
83
+ * @param metas List of storage keys or items and metadata to set for each.
84
+ */
85
+ setMetas(metas: Array<{
86
+ key: StorageItemKey;
87
+ meta: Record<string, any>;
88
+ } | {
89
+ item: WxtStorageItem<any, any>;
90
+ meta: Record<string, any>;
91
+ }>): Promise<void>;
92
+ /**
93
+ * Removes an item from storage.
94
+ *
95
+ * @example
96
+ * await storage.removeItem("local:installDate");
97
+ */
98
+ removeItem(key: StorageItemKey, opts?: RemoveItemOptions): Promise<void>;
99
+ /**
100
+ * Remove a list of keys from storage.
101
+ */
102
+ removeItems(keys: Array<StorageItemKey | WxtStorageItem<any, any> | {
103
+ key: StorageItemKey;
104
+ options?: RemoveItemOptions;
105
+ } | {
106
+ item: WxtStorageItem<any, any>;
107
+ options?: RemoveItemOptions;
108
+ }>): Promise<void>;
109
+ /**
110
+ * Removes all items from the provided storage area.
111
+ */
112
+ clear(base: StorageArea): Promise<void>;
113
+ /**
114
+ * Remove the entire metadata for a key, or specific properties by name.
115
+ *
116
+ * @example
117
+ * // Remove all metadata properties from the item
118
+ * await storage.removeMeta("local:installDate");
119
+ *
120
+ * // Remove only specific the "v" field
121
+ * await storage.removeMeta("local:installDate", "v")
122
+ */
123
+ removeMeta(key: StorageItemKey, properties?: string | string[]): Promise<void>;
124
+ /**
125
+ * Return all the items in storage.
126
+ */
127
+ snapshot(base: StorageArea, opts?: SnapshotOptions): Promise<Record<string, unknown>>;
128
+ /**
129
+ * Restores the results of `snapshot`. If new properties have been saved since the snapshot, they are
130
+ * not overridden. Only values existing in the snapshot are overridden.
131
+ */
132
+ restoreSnapshot(base: StorageArea, data: any): Promise<void>;
133
+ /**
134
+ * Watch for changes to a specific key in storage.
135
+ */
136
+ watch<T>(key: StorageItemKey, cb: WatchCallback<T | null>): Unwatch;
137
+ /**
138
+ * Remove all watch listeners.
139
+ */
140
+ unwatch(): void;
141
+ /**
142
+ * Define a storage item with a default value, type, or versioning.
143
+ *
144
+ * Read full docs: https://wxt.dev/storage.html#defining-storage-items
145
+ */
146
+ defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey): WxtStorageItem<TValue | null, TMetadata>;
147
+ defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue> & {
166
148
  fallback: TValue;
167
- /**
168
- * Get the latest value from storage.
169
- */
170
- getValue(): Promise<TValue>;
171
- /**
172
- * Get metadata.
173
- */
174
- getMeta(): Promise<NullablePartial<TMetadata>>;
175
- /**
176
- * Set the value in storage.
177
- */
178
- setValue(value: TValue): Promise<void>;
179
- /**
180
- * Set metadata properties.
181
- */
182
- setMeta(properties: NullablePartial<TMetadata>): Promise<void>;
183
- /**
184
- * Remove the value from storage.
185
- */
186
- removeValue(opts?: RemoveItemOptions): Promise<void>;
187
- /**
188
- * Remove all metadata or certain properties from metadata.
189
- */
190
- removeMeta(properties?: string[]): Promise<void>;
191
- /**
192
- * Listen for changes to the value in storage.
193
- */
194
- watch(cb: WatchCallback<TValue>): Unwatch;
195
- /**
196
- * If there are migrations defined on the storage item, migrate to the latest version.
197
- *
198
- * **This function is ran automatically whenever the extension updates**, so you don't have to call it
199
- * manually.
200
- */
201
- migrate(): Promise<void>;
149
+ }): WxtStorageItem<TValue, TMetadata>;
150
+ defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue> & {
151
+ defaultValue: TValue;
152
+ }): WxtStorageItem<TValue, TMetadata>;
153
+ defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue> & {
154
+ init: () => TValue | Promise<TValue>;
155
+ }): WxtStorageItem<TValue, TMetadata>;
156
+ defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue | null, TMetadata>;
157
+ }
158
+ interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
159
+ /**
160
+ * The storage key passed when creating the storage item.
161
+ */
162
+ key: StorageItemKey;
163
+ /**
164
+ * @deprecated Renamed to fallback, use it instead.
165
+ */
166
+ defaultValue: TValue;
167
+ /**
168
+ * The value provided by the `fallback` option.
169
+ */
170
+ fallback: TValue;
171
+ /**
172
+ * Get the latest value from storage.
173
+ */
174
+ getValue(): Promise<TValue>;
175
+ /**
176
+ * Get metadata.
177
+ */
178
+ getMeta(): Promise<NullablePartial<TMetadata>>;
179
+ /**
180
+ * Set the value in storage.
181
+ */
182
+ setValue(value: TValue): Promise<void>;
183
+ /**
184
+ * Set metadata properties.
185
+ */
186
+ setMeta(properties: NullablePartial<TMetadata>): Promise<void>;
187
+ /**
188
+ * Remove the value from storage.
189
+ */
190
+ removeValue(opts?: RemoveItemOptions): Promise<void>;
191
+ /**
192
+ * Remove all metadata or certain properties from metadata.
193
+ */
194
+ removeMeta(properties?: string[]): Promise<void>;
195
+ /**
196
+ * Listen for changes to the value in storage.
197
+ */
198
+ watch(cb: WatchCallback<TValue>): Unwatch;
199
+ /**
200
+ * If there are migrations defined on the storage item, migrate to the latest version.
201
+ *
202
+ * **This function is ran automatically whenever the extension updates**, so you don't have to call it
203
+ * manually.
204
+ */
205
+ migrate(): Promise<void>;
202
206
  }
203
207
  type StorageArea = 'local' | 'session' | 'sync' | 'managed';
204
208
  type StorageItemKey = `${StorageArea}:${string}`;
205
209
  interface GetItemOptions<T> {
206
- /**
207
- * @deprecated Renamed to `fallback`, use it instead.
208
- */
209
- defaultValue?: T;
210
- /**
211
- * Default value returned when `getItem` would otherwise return `null`.
212
- */
213
- fallback?: T;
210
+ /**
211
+ * @deprecated Renamed to `fallback`, use it instead.
212
+ */
213
+ defaultValue?: T;
214
+ /**
215
+ * Default value returned when `getItem` would otherwise return `null`.
216
+ */
217
+ fallback?: T;
214
218
  }
215
219
  interface RemoveItemOptions {
216
- /**
217
- * Optionally remove metadata when deleting a key.
218
- *
219
- * @default false
220
- */
221
- removeMeta?: boolean;
220
+ /**
221
+ * Optionally remove metadata when deleting a key.
222
+ *
223
+ * @default false
224
+ */
225
+ removeMeta?: boolean;
222
226
  }
223
227
  interface SnapshotOptions {
224
- /**
225
- * Exclude a list of keys. The storage area prefix should be removed since the snapshot is for a
226
- * specific storage area already.
227
- */
228
- excludeKeys?: string[];
228
+ /**
229
+ * Exclude a list of keys. The storage area prefix should be removed since the snapshot is for a
230
+ * specific storage area already.
231
+ */
232
+ excludeKeys?: string[];
229
233
  }
230
234
  interface WxtStorageItemOptions<T> {
231
- /**
232
- * @deprecated Renamed to `fallback`, use it instead.
233
- */
234
- defaultValue?: T;
235
- /**
236
- * Default value returned when `getValue` would otherwise return `null`.
237
- */
238
- fallback?: T;
239
- /**
240
- * If passed, a value in storage will be initialized immediately after
241
- * defining the storage item. This function returns the value that will be
242
- * saved to storage during the initialization process if a value doesn't
243
- * already exist.
244
- */
245
- init?: () => T | Promise<T>;
246
- /**
247
- * Provide a version number for the storage item to enable migrations. When changing the version
248
- * in the future, migration functions will be ran on application startup.
249
- */
250
- version?: number;
251
- /**
252
- * A map of version numbers to the functions used to migrate the data to that version.
253
- */
254
- migrations?: Record<number, (oldValue: any) => any>;
255
- /**
256
- * Print debug logs, such as migration process.
257
- * @default false
258
- */
259
- debug?: boolean;
260
- /**
261
- * A callback function that runs on migration complete.
262
- */
263
- onMigrationComplete?: (migratedValue: T, targetVersion: number) => void;
235
+ /**
236
+ * @deprecated Renamed to `fallback`, use it instead.
237
+ */
238
+ defaultValue?: T;
239
+ /**
240
+ * Default value returned when `getValue` would otherwise return `null`.
241
+ */
242
+ fallback?: T;
243
+ /**
244
+ * If passed, a value in storage will be initialized immediately after
245
+ * defining the storage item. This function returns the value that will be
246
+ * saved to storage during the initialization process if a value doesn't
247
+ * already exist.
248
+ */
249
+ init?: () => T | Promise<T>;
250
+ /**
251
+ * Provide a version number for the storage item to enable migrations. When changing the version
252
+ * in the future, migration functions will be ran on application startup.
253
+ */
254
+ version?: number;
255
+ /**
256
+ * A map of version numbers to the functions used to migrate the data to that version.
257
+ */
258
+ migrations?: Record<number, (oldValue: any) => any>;
259
+ /**
260
+ * Print debug logs, such as migration process.
261
+ * @default false
262
+ */
263
+ debug?: boolean;
264
+ /**
265
+ * A callback function that runs on migration complete.
266
+ */
267
+ onMigrationComplete?: (migratedValue: T, targetVersion: number) => void;
264
268
  }
265
269
  type StorageAreaChanges = {
266
- [key: string]: Browser.storage.StorageChange;
270
+ [key: string]: Browser.storage.StorageChange;
267
271
  };
268
272
  /**
269
273
  * Same as `Partial`, but includes `| null`. It makes all the properties of an object optional and
270
274
  * nullable.
271
275
  */
272
- type NullablePartial<T> = {
273
- [key in keyof T]+?: T[key] | undefined | null;
274
- };
276
+ type NullablePartial<T> = { [key in keyof T]+?: T[key] | undefined | null };
275
277
  /**
276
278
  * Callback called when a value in storage is changed.
277
279
  */
@@ -281,10 +283,9 @@ type WatchCallback<T> = (newValue: T, oldValue: T) => void;
281
283
  */
282
284
  type Unwatch = () => void;
283
285
  declare class MigrationError extends Error {
284
- key: string;
285
- version: number;
286
- constructor(key: string, version: number, options?: ErrorOptions);
286
+ key: string;
287
+ version: number;
288
+ constructor(key: string, version: number, options?: ErrorOptions);
287
289
  }
288
-
289
- export { MigrationError, storage };
290
- export type { GetItemOptions, RemoveItemOptions, SnapshotOptions, StorageArea, StorageAreaChanges, StorageItemKey, Unwatch, WatchCallback, WxtStorage, WxtStorageItem, WxtStorageItemOptions };
290
+ //#endregion
291
+ export { GetItemOptions, MigrationError, RemoveItemOptions, SnapshotOptions, StorageArea, StorageAreaChanges, StorageItemKey, Unwatch, WatchCallback, WxtStorage, WxtStorageItem, WxtStorageItemOptions, storage };