An ES6 Map wrapper for the synchronous userscript storage API
MIT License
gm-storage - an ES6 Map wrapper for the synchronous userscript storage API
$ npm install gm-storage
// ==UserScript==
// @name My Userscript
// @include https://www.example.com/*
// @require https://unpkg.com/[email protected]
// @grant GM_deleteValue
// @grant GM_getValue
// @grant GM_listValues
// @grant GM_setValue
// ==/UserScript==
const store = new GMStorage()
// now access userscript storage with the ES6 Map API
store.set('alpha', 'beta') // store
store.set('foo', 'bar').set('baz', 'quux') // store
store.get('foo') // "bar"
store.get('gamma', 'default value') // "default value"
store.delete('alpha') // true
store.size // 2
// iterables
[...store.keys()] // ["foo", "baz"]
[...store.values()] // ["bar", "quux"]
Object.fromEntries(store.entries()) // { foo: "bar", baz: "quux" }
GMStorage implements an ES6 Map compatible wrapper (adapter) for the synchronous userscript storage API.
It augments the built-in API with some useful enhancements such as iterating
over values and entries, and removing all values.
It also adds some features which aren't available in the Map API, e.g.
get
takes an optional default value (the same as GM_getValue
).
The synchronous storage API is supported by most userscript engines:
The notable exceptions are Greasemonkey 4 and FireMonkey, which have moved exclusively to the asynchronous API.
The following types are referenced in the descriptions below:
type Callback<K extends string, V extends Value, U> = (
this: U | undefined,
value: V,
key: K,
store: GMStorage<K, V>
) => void;
type Options = { strict?: boolean };
type Value =
| null
| boolean
| number
| string
| Value[]
| { [key: string]: Value };
class GMStorage<K extends string = string, V extends Value = Value> implements Map<K, V> {}
GMStorage<K extends string = string, V extends Value = Value>(options?: Options)
import GMStorage from 'gm-storage'
const store = new GMStorage()
store.setAll([['foo', 'bar'], ['baz', 'quux']])
console.log(store.size) // 2
Constructs a Map-compatible instance which associates strings with values in
the userscript engine's storage. GMStorage<K, V>
instances are compatible
with Map<K, V>
, where K
extends (and defaults to) string and V
extends
(and defaults to) the type of JSON-serializable values.
The GMStorage
constructor can take the following options:
boolean
true
// don't need GM_deleteValue or GM_listValues
const store = new GMStorage({ strict: false })
store.set('foo', 'bar')
store.get('foo') // "bar"
In order to use all GMStorage methods, the following GM_*
functions must be
defined (i.e. granted):
GM_deleteValue
GM_getValue
GM_listValues
GM_setValue
If this option is true (as it is by default), the existence of these functions is checked when the store is created. If any of the functions are missing, an exception is thrown.
If the option is false, they are not checked, and access to GM_*
functions
required by unused storage methods need not be granted.
clear(): void
GM_deleteValue
, GM_listValues
const store = new GMStorage().setAll([['foo', 'bar'], ['baz', 'quux']])
store.size // 2
store.clear()
store.size // 0
Remove all entries from the store.
delete(key: K): boolean
GM_deleteValue
, GM_getValue
const store = new GMStorage().setAll([['foo', 'bar'], ['baz', 'quux']])
store.size // 2
store.delete('nope') // false
store.delete('foo') // true
store.has('foo') // false
store.size // 1
Delete the value with the specified key from the store. Returns true if the value existed, false otherwise.
entries(): Generator<[K, V]>
GM_getValue
, GM_listValues
Symbol.iterator
for (const [key, value] of store.entries()) {
console.log([key, value])
}
Returns an iterable which yields each key/value pair from the store.
forEach<U>(callback: Callback<K, V, U>, thisArg?: U): void
GM_getValue
, GM_listValues
store.forEach((value, key) => {
console.log([key, value])
})
Iterates over each key/value pair in the store, passing them to the callback,
along with the store itself, and binding the optional second argument to this
inside the callback.
get<D>(key: K, defaultValue?: D): V | D | undefined
GM_getValue
const maybeAge = store.get('age')
const age = store.get('age', 42)
Returns the value corresponding to the supplied key, or the default value (which is undefined by default) if it doesn't exist.
has(key: K): boolean
GM_getValue
if (!store.has(key)) {
console.log('not found')
}
Returns true if a value with the supplied key exists in the store, false otherwise.
keys(): Generator<K, void, undefined>
GM_listValues
for (const key of store.keys()) {
console.log(key)
}
Returns an iterable collection of the store's keys.
Note that, for compatibility with Map#keys
, the return value is iterable but
is not an array.
set(key: K, value: V): this
GM_setValue
store.set('foo', 'bar')
.set('baz', 'quux')
Add a value to the store under the supplied key. Returns this
(i.e. the
GMStorage instance the method was called on) for chaining.
setAll(values?: Iterable<[K, V]>): this
GM_setValue
store.setAll([['foo', 'bar'], ['baz', 'quux']])
store.has('foo') // true
store.get('baz') // "quux"
Add entries (key/value pairs) to the store. Returns this
(i.e. the
GMStorage instance the method was called on) for chaining.
values(): Generator<V>
GM_getValue
, GM_listValues
for (const value of store.values()) {
console.log(value)
}
Returns an iterable collection of the store's values.
number
GM_listValues
console.log(store.size)
Returns the number of values in the store.
An alias for entries
:
for (const [key, value] of store) {
console.log([key, value])
}
The following NPM scripts are available:
GM_*
functions are accessed viaglobalThis
,2.0.3
Copyright © 2020-2022 by chocolateboy.
This is free software; you can redistribute it and/or modify it under the terms of the MIT license.