{"id":14989075,"url":"https://github.com/chocolateboy/gm-storage","last_synced_at":"2025-04-12T00:32:26.512Z","repository":{"id":40286098,"uuid":"262889156","full_name":"chocolateboy/gm-storage","owner":"chocolateboy","description":"An ES6 Map wrapper for the synchronous userscript storage API","archived":false,"fork":false,"pushed_at":"2023-02-03T07:02:48.000Z","size":690,"stargazers_count":13,"open_issues_count":4,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-07T00:36:57.374Z","etag":null,"topics":["adapter","es6-map","greasemonkey","map","storage","tampermonkey","userscript","userscripts","violentmonkey","wrapper","zero-dependency"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chocolateboy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-10T22:46:37.000Z","updated_at":"2025-01-31T19:37:21.000Z","dependencies_parsed_at":"2023-02-13T23:31:00.482Z","dependency_job_id":null,"html_url":"https://github.com/chocolateboy/gm-storage","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fgm-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fgm-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fgm-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fgm-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chocolateboy","download_url":"https://codeload.github.com/chocolateboy/gm-storage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248501426,"owners_count":21114674,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adapter","es6-map","greasemonkey","map","storage","tampermonkey","userscript","userscripts","violentmonkey","wrapper","zero-dependency"],"created_at":"2024-09-24T14:17:39.830Z","updated_at":"2025-04-12T00:32:26.232Z","avatar_url":"https://github.com/chocolateboy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gm-storage\n\n[![Build Status](https://github.com/chocolateboy/gm-storage/workflows/test/badge.svg)](https://github.com/chocolateboy/gm-storage/actions?query=workflow%3Atest)\n[![NPM Version](https://img.shields.io/npm/v/gm-storage.svg)](https://www.npmjs.org/package/gm-storage)\n\n\u003c!-- TOC --\u003e\n\n- [NAME](#name)\n- [FEATURES](#features)\n- [INSTALLATION](#installation)\n- [USAGE](#usage)\n- [DESCRIPTION](#description)\n- [TYPES](#types)\n- [EXPORTS](#exports)\n  - [GMStorage (default)](#gmstorage-default)\n    - [Constructor](#constructor)\n      - [Options](#options)\n        - [strict](#strict)\n    - [Methods](#methods)\n      - [clear](#clear)\n      - [delete](#delete)\n      - [entries](#entries)\n      - [forEach](#foreach)\n      - [get](#get)\n      - [has](#has)\n      - [keys](#keys)\n      - [set](#set)\n      - [setAll](#setall)\n      - [values](#values)\n    - [Properties](#properties)\n      - [size](#size)\n      - [Symbol.iterator](#symboliterator)\n- [DEVELOPMENT](#development)\n- [COMPATIBILITY](#compatibility)\n- [SEE ALSO](#see-also)\n  - [Libraries](#libraries)\n  - [APIs](#apis)\n- [VERSION](#version)\n- [AUTHOR](#author)\n- [COPYRIGHT AND LICENSE](#copyright-and-license)\n\n\u003c!-- TOC END --\u003e\n\n# NAME\n\ngm-storage - an ES6 Map wrapper for the synchronous userscript storage API\n\n# FEATURES\n\n- implements the full Map API with some helpful extras\n- no dependencies\n- \u0026lt; 500 B minified + gzipped\n- fully typed (TypeScript)\n- CDN builds (UMD) - [jsDelivr][], [unpkg][]\n\n# INSTALLATION\n\n```\n$ npm install gm-storage\n```\n\n# USAGE\n\n```javascript\n// ==UserScript==\n// @name     My Userscript\n// @include  https://www.example.com/*\n// @require  https://unpkg.com/gm-storage@2.0.3\n// @grant    GM_deleteValue\n// @grant    GM_getValue\n// @grant    GM_listValues\n// @grant    GM_setValue\n// ==/UserScript==\n\nconst store = new GMStorage()\n\n// now access userscript storage with the ES6 Map API\n\nstore.set('alpha', 'beta')                 // store\nstore.set('foo', 'bar').set('baz', 'quux') // store\nstore.get('foo')                           // \"bar\"\nstore.get('gamma', 'default value')        // \"default value\"\nstore.delete('alpha')                      // true\nstore.size                                 // 2\n\n// iterables\n[...store.keys()]                   // [\"foo\", \"baz\"]\n[...store.values()]                 // [\"bar\", \"quux\"]\nObject.fromEntries(store.entries()) // { foo: \"bar\", baz: \"quux\" }\n```\n\n# DESCRIPTION\n\nGMStorage implements an ES6 Map compatible wrapper\n([adapter](https://en.wikipedia.org/wiki/Adapter_pattern)) for the synchronous\nuserscript storage API.\n\nIt augments the built-in API with some useful enhancements such as iterating\nover [values](#values) and [entries](#entries), and [removing all values](#clear).\nIt also adds some features which aren't available in the Map API, e.g.\n[`get`](#get) takes an optional default value (the same as `GM_getValue`).\n\nThe synchronous storage API is supported by most userscript engines:\n\n- [Violentmonkey](https://violentmonkey.github.io/)\n- Tampermonkey\n- [USI](https://addons.mozilla.org/firefox/addon/userunified-script-injector/)\n- Greasemonkey 3\n\nThe notable exceptions are [Greasemonkey 4](https://www.greasespot.net/2017/09/greasemonkey-4-for-script-authors.html)\nand [FireMonkey](https://github.com/erosman/support/issues/98), which have\nmoved exclusively to the asynchronous API.\n\n# TYPES\n\nThe following types are referenced in the descriptions below:\n\n\u003cdetails\u003e\n\n```typescript\ntype Callback\u003cK extends string, V extends Value, U\u003e = (\n    this: U | undefined,\n    value: V,\n    key: K,\n    store: GMStorage\u003cK, V\u003e\n) =\u003e void;\n\ntype Options = { strict?: boolean };\n\ntype Value =\n    | null\n    | boolean\n    | number\n    | string\n    | Value[]\n    | { [key: string]: Value };\n\nclass GMStorage\u003cK extends string = string, V extends Value = Value\u003e implements Map\u003cK, V\u003e {}\n```\n\n\u003c/details\u003e\n\n# EXPORTS\n\n## GMStorage (default)\n\n### Constructor\n\n- **Type**: `GMStorage\u003cK extends string = string, V extends Value = Value\u003e(options?: Options)`\n\n```javascript\nimport GMStorage from 'gm-storage'\n\nconst store = new GMStorage()\n\nstore.setAll([['foo', 'bar'], ['baz', 'quux']])\n\nconsole.log(store.size) // 2\n```\n\nConstructs a Map-compatible instance which associates strings with values in\nthe userscript engine's storage. `GMStorage\u003cK, V\u003e` instances are compatible\nwith `Map\u003cK, V\u003e`, where `K` extends (and defaults to) string and `V` extends\n(and defaults to) the type of JSON-serializable values.\n\n#### Options\n\nThe `GMStorage` constructor can take the following options:\n\n##### strict\n\n- **Type**: `boolean`\n- **Default**: `true`\n\n```javascript\n// don't need GM_deleteValue or GM_listValues\nconst store = new GMStorage({ strict: false })\n\nstore.set('foo', 'bar')\nstore.get('foo') // \"bar\"\n```\n\nIn order to use *all* GMStorage methods, the following `GM_*` functions must be\ndefined (i.e. [granted](https://wiki.greasespot.net/@grant)):\n\n  - `GM_deleteValue`\n  - `GM_getValue`\n  - `GM_listValues`\n  - `GM_setValue`\n\nIf this option is true (as it is by default), the existence of these functions\nis checked when the store is created. If any of the functions are missing, an\nexception is thrown.\n\nIf the option is false, they are not checked, and access to `GM_*` functions\nrequired by unused storage methods need not be granted.\n\n### Methods\n\n#### clear\n\n- **Type**: `clear(): void`\n- **Requires**: `GM_deleteValue`, `GM_listValues`\n\n```javascript\nconst store = new GMStorage().setAll([['foo', 'bar'], ['baz', 'quux']])\n\nstore.size    // 2\nstore.clear()\nstore.size    // 0\n```\n\nRemove all entries from the store.\n\n#### delete\n\n- **Type**: `delete(key: K): boolean`\n- **Requires**: `GM_deleteValue`, `GM_getValue`\n\n```javascript\nconst store = new GMStorage().setAll([['foo', 'bar'], ['baz', 'quux']])\n\nstore.size           // 2\nstore.delete('nope') // false\nstore.delete('foo')  // true\nstore.has('foo')     // false\nstore.size           // 1\n```\n\nDelete the value with the specified key from the store. Returns true if the\nvalue existed, false otherwise.\n\n#### entries\n\n- **Type**: `entries(): Generator\u003c[K, V]\u003e`\n- **Requires**: `GM_getValue`, `GM_listValues`\n- **Alias**: [`Symbol.iterator`](#symboliterator)\n\n```javascript\nfor (const [key, value] of store.entries()) {\n    console.log([key, value])\n}\n```\n\nReturns an iterable which yields each key/value pair from the store.\n\n#### forEach\n\n- **Type**: `forEach\u003cU\u003e(callback: Callback\u003cK, V, U\u003e, thisArg?: U): void`\n- **Requires**: `GM_getValue`, `GM_listValues`\n\n```javascript\nstore.forEach((value, key) =\u003e {\n    console.log([key, value])\n})\n```\n\nIterates over each key/value pair in the store, passing them to the callback,\nalong with the store itself, and binding the optional second argument to `this`\ninside the callback.\n\n#### get\n\n- **Type**: `get\u003cD\u003e(key: K, defaultValue?: D): V | D | undefined `\n- **Requires**: `GM_getValue`\n\n```javascript\nconst maybeAge = store.get('age')\nconst age = store.get('age', 42)\n```\n\nReturns the value corresponding to the supplied key, or the default value\n(which is undefined by default) if it doesn't exist.\n\n#### has\n\n- **Type**: `has(key: K): boolean`\n- **Requires**: `GM_getValue`\n\n```javascript\nif (!store.has(key)) {\n    console.log('not found')\n}\n```\n\nReturns true if a value with the supplied key exists in the store, false\notherwise.\n\n#### keys\n\n- **Type**: `keys(): Generator\u003cK, void, undefined\u003e`\n- **Requires**: `GM_listValues`\n\n```javascript\nfor (const key of store.keys()) {\n    console.log(key)\n}\n```\n\nReturns an iterable collection of the store's keys.\n\nNote that, for compatibility with `Map#keys`, the return value is iterable but\nis *not* an array.\n\n#### set\n\n- **Type**: `set(key: K, value: V): this`\n- **Requires**: `GM_setValue`\n\n```javascript\nstore.set('foo', 'bar')\n     .set('baz', 'quux')\n```\n\nAdd a value to the store under the supplied key. Returns `this` (i.e. the\nGMStorage instance the method was called on) for chaining.\n\n#### setAll\n\n- **Type**: `setAll(values?: Iterable\u003c[K, V]\u003e): this`\n- **Requires**: `GM_setValue`\n\n```javascript\nstore.setAll([['foo', 'bar'], ['baz', 'quux']])\nstore.has('foo') // true\nstore.get('baz') // \"quux\"\n```\n\nAdd entries (key/value pairs) to the store. Returns `this` (i.e. the\nGMStorage instance the method was called on) for chaining.\n\n#### values\n\n- **Type**: `values(): Generator\u003cV\u003e`\n- **Requires**: `GM_getValue`, `GM_listValues`\n\n```javascript\nfor (const value of store.values()) {\n    console.log(value)\n}\n```\n\nReturns an iterable collection of the store's values.\n\n### Properties\n\n#### size\n\n- **Type**: `number`\n- **Requires**: `GM_listValues`\n\n```javascript\nconsole.log(store.size)\n```\n\nReturns the number of values in the store.\n\n#### Symbol.iterator\n\nAn alias for [`entries`](#entries):\n\n```javascript\nfor (const [key, value] of store) {\n    console.log([key, value])\n}\n```\n\n# DEVELOPMENT\n\n\u003cdetails\u003e\n\n\u003c!-- TOC:ignore --\u003e\n## NPM Scripts\n\nThe following NPM scripts are available:\n\n- build - compile the library for testing and save to the target directory\n- build:doc - generate the README's TOC (table of contents)\n- build:release - compile the library for release and save to the target directory\n- clean - remove the target directory and its contents\n- rebuild - clean the target directory and recompile the library\n- test - recompile the library and run the test suite\n- test:run - run the test suite\n- typecheck - sanity check the library's type definitions\n\n\u003c/details\u003e\n\n# COMPATIBILITY\n\n- any userscript engine with support for the Greasemonkey 3 storage API\n- any browser with ES6 support\n- the `GM_*` functions are accessed via\n  [`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis),\n  which may need to be polyfilled in older browsers\n\n# SEE ALSO\n\n## Libraries\n\n- [Keyv](https://www.npmjs.com/package/keyv) - simple key-value storage with support for multiple backends\n\n## APIs\n\n- [GM_deleteValue](https://sourceforge.net/p/greasemonkey/wiki/GM_deleteValue/)\n- [GM_getValue](https://sourceforge.net/p/greasemonkey/wiki/GM_getValue/)\n- [GM_listValues](https://sourceforge.net/p/greasemonkey/wiki/GM_listValues/)\n- [GM_setValue](https://sourceforge.net/p/greasemonkey/wiki/GM_setValue/)\n- [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)\n\n# VERSION\n\n2.0.3\n\n# AUTHOR\n\n[chocolateboy](mailto:chocolate@cpan.org)\n\n# COPYRIGHT AND LICENSE\n\nCopyright © 2020-2022 by chocolateboy.\n\nThis is free software; you can redistribute it and/or modify it under the terms\nof the [MIT license](https://opensource.org/licenses/MIT).\n\n[jsDelivr]: https://cdn.jsdelivr.net/npm/gm-storage@2.0.3/dist/index.umd.min.js\n[unpkg]: https://unpkg.com/gm-storage@2.0.3/dist/index.umd.min.js\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchocolateboy%2Fgm-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchocolateboy%2Fgm-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchocolateboy%2Fgm-storage/lists"}