gm-storage

• NAME
• FEATURES
• INSTALLATION
• USAGE
• DESCRIPTION
• TYPES
• EXPORTS
  • GMStorage (default)
    • Constructor
      • Options
        • strict
    • Methods
      • clear
      • delete
      • entries
      • forEach
      • get
      • has
      • keys
      • set
      • setAll
      • values
    • Properties
      • size
      • Symbol.iterator
• DEVELOPMENT
• COMPATIBILITY
• SEE ALSO
  • Libraries
  • APIs
• VERSION
• AUTHOR
• COPYRIGHT AND LICENSE

NAME

gm-storage - an ES6 Map wrapper for the synchronous userscript storage API

FEATURES

• implements the full Map API with some helpful extras
• no dependencies
• < 500 B minified + gzipped
• fully typed (TypeScript)
• CDN builds (UMD) - jsDelivr, unpkg

INSTALLATION

$ npm install gm-storage

USAGE

// ==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" }

DESCRIPTION

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:

• Violentmonkey
• Tampermonkey
• USI
• Greasemonkey 3

The notable exceptions are Greasemonkey 4 and FireMonkey, which have moved exclusively to the asynchronous API.

TYPES

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> {}

EXPORTS

GMStorage (default)

Constructor

• Type: 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.

Options

The GMStorage constructor can take the following options:

strict

• Type: boolean
• Default: 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.

Methods

clear

• Type: clear(): void
• Requires: 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

• Type: delete(key: K): boolean
• Requires: 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

• Type: entries(): Generator<[K, V]>
• Requires: GM_getValue, GM_listValues
• Alias: 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

• Type: forEach<U>(callback: Callback<K, V, U>, thisArg?: U): void
• Requires: 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

• Type: get<D>(key: K, defaultValue?: D): V | D | undefined
• Requires: 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

• Type: has(key: K): boolean
• Requires: 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

• Type: keys(): Generator<K, void, undefined>
• Requires: 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

• Type: set(key: K, value: V): this
• Requires: 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

• Type: setAll(values?: Iterable<[K, V]>): this
• Requires: 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

• Type: values(): Generator<V>
• Requires: GM_getValue, GM_listValues

for (const value of store.values()) {
    console.log(value)
}

Returns an iterable collection of the store's values.

Properties

size

• Type: number
• Requires: GM_listValues

console.log(store.size)

Returns the number of values in the store.

Symbol.iterator

An alias for entries:

for (const [key, value] of store) {
    console.log([key, value])
}

DEVELOPMENT

NPM Scripts

The following NPM scripts are available:

• build - compile the library for testing and save to the target directory
• build:doc - generate the README's TOC (table of contents)
• build:release - compile the library for release and save to the target directory
• clean - remove the target directory and its contents
• rebuild - clean the target directory and recompile the library
• test - recompile the library and run the test suite
• test:run - run the test suite
• typecheck - sanity check the library's type definitions

COMPATIBILITY

• any userscript engine with support for the Greasemonkey 3 storage API
• any browser with ES6 support
• the GM_* functions are accessed via globalThis, which may need to be polyfilled in older browsers

SEE ALSO

Libraries

• Keyv - simple key-value storage with support for multiple backends

APIs

• GM_deleteValue
• GM_getValue
• GM_listValues
• GM_setValue
• Map

VERSION

2.0.3

AUTHOR

chocolateboy

COPYRIGHT AND LICENSE

Copyright © 2020-2022 by chocolateboy.

This is free software; you can redistribute it and/or modify it under the terms of the MIT license.