-
Notifications
You must be signed in to change notification settings - Fork 0
/
storage.js
318 lines (281 loc) · 13.9 KB
/
storage.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
import StorageCompatibility from 'mdn-browser-compat-data/webextensions/api/storage.json';
import Base from './core/base';
import Event from './core/event';
/**
* {@link StorageChange} is an object representing a change to a storage area.
*
* @see {@link https://developer.chrome.com/extensions/storage#type-StorageChange}
* @see {@link https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage/StorageChange}
*/
export class StorageChange extends Base {
static Title = 'StorageChange';
static Name = 'storage.StorageChange';
static Prefix = false;
static Compatibility = StorageCompatibility;
static Standard = [
'oldValue',
'newValue'
];
constructor(instance, options = null) {
super(options);
this._instance = instance;
}
get $namespace() {
return this._instance;
}
get $target() {
return this._instance;
}
/**
* The old value of the item, if there was an old value.
*
* @see {@link https://developer.chrome.com/extensions/storage#type-StorageChange}
* @see {@link https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage/StorageChange}
*
* @returns {any}
*/
get oldValue() {
return this.$property('oldValue');
}
/**
* The new value of the item, if there is a new value.
*
* @see {@link https://developer.chrome.com/extensions/storage#type-StorageChange}
* @see {@link https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage/StorageChange}
*
* @returns {any}
*/
get newValue() {
return this.$property('newValue');
}
}
/**
* {@link StorageArea} is an object representing a storage area.
*
* @see {@link https://developer.chrome.com/extensions/storage#type-StorageArea}
* @see {@link https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage/StorageArea}
*/
export class StorageArea extends Base {
static Title = 'StorageArea';
static Name = 'storage.StorageArea';
static Prefix = false;
static Compatibility = StorageCompatibility;
constructor(instance, options = null) {
super(options);
this._instance = instance;
}
get $namespace() {
return this._instance;
}
get $target() {
return this._instance;
}
/**
* Remove all items from the storage area.
*
* @see {@link https://developer.chrome.com/extensions/storage#method-StorageArea-clear}
* @see {@link https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage/StorageArea/clear}
*
* @returns {Promise} A `Promise` that will be fulfilled with no arguments if the operation succeeded. If the
* operation failed, the promise will be rejected with an error message.
*/
clear() {
return this.$promise('clear');
}
/**
* Retrieve one or more items from the storage area.
*  
* Note: When used within a content script in Firefox versions prior to 52, the `Promise` returned by
* `browser.storage.local.get()` is fulfilled with an Array containing one Object. The Object in the
* Array contains the keys found in the storage area, as described above. The `Promise` is correctly
* fulfilled with an Object when used in the background context (background scripts, popups, options
* pages, etc.). When this API is used as `chrome.storage.local.get()`, it correctly passes an Object
* to the callback function.
*
* @see {@link https://developer.chrome.com/extensions/storage#method-StorageArea-get}
* @see {@link https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage/StorageArea/get}
*
* @param {String, String[]} [keys] A key (string) or keys (an array of strings or an object specifying default
* values) to identify the item(s) to be retrieved from storage. If you pass an
* empty string, object or array here, an empty object will be retrieved. If you
* pass null, or an undefined value, the entire storage contents will be retrieved.
*
* @returns {Promise} A `Promise` that will be fulfilled with a `results` object containing every object in `keys`
* that was found in the storage area. If the operation failed, the promise will be rejected
* with an error message.
*/
get(keys) {
return this.$promise('get', keys);
}
/**
* Get the amount of storage space, in bytes, used by one or more items being stored in the storage area.
*
* @see {@link https://developer.chrome.com/extensions/storage#method-StorageArea-getBytesInUse}
* @see {@link https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage/StorageArea/getBytesInUse}
*
* @param {String, String[]} [keys] A key (string) or keys (an array of strings) to identify the item(s) whose
* storage space you want to retrieve. If an empty string or array is passed in,
* `0` will be returned. If you pass `null` here, the function will return the
* space used by the entire storage area.
*
* @returns {Promise} A `Promise` that will be fulfilled with an integer, `bytesUsed`, representing the storage
* space used by the objects that were specified in `keys`. If the operation failed, the promise
* will be rejected with an error message.
*/
getBytesInUse(keys) {
return this.$promise('getBytesInUse', keys);
}
/**
* Remove one or more items from the storage area.
*
* @see {@link https://developer.chrome.com/extensions/storage#method-StorageArea-remove}
* @see {@link https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage/StorageArea/remove}
*
* @param {String, String[]} keys A string, or array of strings, representing the key(s) of the item(s) to
* be removed.
*
* @returns {Promise} A `Promise` that will be fulfilled with no arguments if the operation succeeded. If the
* operation failed, the promise will be rejected with an error message.
*/
remove(keys) {
return this.$promise('remove', keys);
}
/**
* Store one or more items in the storage area, or update existing items.
*  
* Values may be primitive types (such as numbers, booleans, and strings) or Array types.
*  
* It's generally not possible to store other types, such as Function, Date, RegExp, Set, Map, ArrayBuffer
* and so on. Some of these unsupported types will restore as an empty object, and some cause set() to
* throw an error. The exact behavior here is browser-specific.
*  
* When you store or update a value using this API, the {@link Storage#onChanged} event will fire.
*
* @see {@link https://developer.chrome.com/extensions/storage#method-StorageArea-set}
* @see {@link https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage/StorageArea/set}
*
* @param {Object} keys An object containing one or more key/value pairs to be stored in storage. If an item
* already exists, its value will be updated.
*
* @returns {Promise} A `Promise` that will be fulfilled with no arguments if the operation succeeded. If the
* operation failed, the promise will be rejected with an error message.
*/
set(keys) {
return this.$promise('set', keys);
}
}
/**
* Enables extensions to store and retrieve data, and listen for changes to stored items.
*  
* The storage system is based on the Web Storage API, with a few differences. Among other differences,
* these include:
*  
* - It's asynchronous.
*  
* - Values are scoped to the extension, not to a specific domain (i.e. the same set of key/value pairs
* are available to all scripts in the background context and content scripts).
*  
* - The values stored can be any JSON-ifiable value, not just String. Among other things, this includes:
* Array and Object, but only when their contents can can be represented as JSON, which does not include
* DOM nodes. You don't need to convert your values to JSON Strings prior to storing them, but they are
* represented as JSON internally, thus the requirement that they be JSON-ifiable.
*  
* - Multiple key/value pairs can be set or retrieved in the same API call.
*  
* To use this API you need to include the "storage" permission in your manifest.json file.
*  
* Each extension has its own storage area, which can be split into different types of storage.
*  
* Although this API is similar to Window.localStorage it is recommended that you don't use Window.localStorage
* in the extension code to store extension-related data. Firefox will clear data stored by extensions using the
* localStorage API in various scenarios where users clear their browsing history and data for privacy reasons,
* while data saved using the storage.local API will be correctly persisted in these scenarios.
*
* @see {@link https://developer.chrome.com/extensions/storage}
* @see {@link https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage}
*/
export class Storage extends Base {
static Title = 'Storage';
static Name = 'storage';
static Compatibility = StorageCompatibility;
constructor(options = null) {
super(options);
// region Areas
/**
* Represents the local storage area. Items in local storage are local to the machine the extension was
* installed on.
*  
* The browser may restrict the amount of data that an extension can store in the local storage area:
*  
* - Chrome limits the extension to 5MB of data using this API unless it has the "unlimitedStorage"
* permission.
*  
* - Firefox enables you to ask for the "unlimitedStorage" permission from version 56 onwards. It does not
* yet restrict the amount of data your extension can store, but will start doing so in a future release:
* so it's a good idea to ask for the "unlimitedStorage" permission now, if you intend to store a large
* amount of data.
*  
* When the extension is uninstalled, its associated local storage is cleared.
*  
* Also in Firefox, you can prevent the browser from clearing local storage on uninstall by visiting
* "about:config" and setting the following two browser preferences to true: "keepUuidOnUninstall" and
* "keepStorageOnUninstall". This feature is provided to help developers test their extensions. Extensions
* themselves are not able to change these preferences.
*  
* Although this API is similar to {@link Window#localStorage} it is recommended that you don't use
* {@link Window#localStorage} in extension code. Firefox will clear data stored by extensions using
* the localStorage API in various scenarios where users clear their browsing history and data for
* privacy reasons, while data saved using the storage.local API will be correctly persisted in
* these scenarios.
*
* @see {@link https://developer.chrome.com/extensions/storage#property-local}
* @see {@link https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage/local}
*
* @returns {StorageArea}
*/
this.local = new StorageArea(this.$target && this.$target.local);
/**
* Represents the managed storage area. Items in managed storage are set by the domain administrator or other
* native applications installed on user's computer, and are read-only for the extension. Trying to modify
* this storage area results in an error.
*
* @see {@link https://developer.chrome.com/extensions/storage#property-managed}
* @see {@link https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage/managed}
*
* @returns {StorageArea}
*/
this.managed = new StorageArea(this.$target && this.$target.managed);
/**
* Represents the sync storage area. Items in sync storage are synced by the browser, and are available across
* all instances of that browser that the user is logged into (e.g. via Firefox sync, or a Google account),
* across different devices.
*  
* For Firefox a user must have Add-ons checked under the "Sync Settings" options in "about:preferences".
*  
* Note that the implementation of {@link Storage#sync} in Firefox relies on the Add-on ID. If you use
* {@link Storage#sync}, you must set an ID for your extension using the "applications" manifest.json key.
*  
* The main use case of this API is to store preferences about your extension and allow the user to sync them
* to different profiles. You can store up to 100KB of data using this API. If you try to store more than
* this, the call will fail with an error message. The API is provided without any guarantees about uptime
* or performance.
*
* @returns {StorageArea}
*/
this.sync = new StorageArea(this.$target && this.$target.sync);
// endregion
// region Events
/**
* Fired when one or more items change in a storage area.
*
* @see {@link https://developer.chrome.com/extensions/storage#event-onChanged}
* @see {@link https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/storage/onChanged}
*/
this.onChanged = new Event(this, 'onChanged');
// endregion
}
}
export {
StorageCompatibility
};
export default new Storage();