monkey_storage.md

A conveniently usable storage class for tampermonkey/greasemonkey/violentmonkey that automatically stores the settings permanently in the userscript value storage while automatically syncing between multiple instances of the userscript so every tab has the same variables available.

Usage Guide for GMStorage Class

The GMStorage class is an advanced wrapper for Greasemonkey/Tampermonkey's storage APIs. It greatly simplifies data management by providing the following features:

• Simple Read/Write Operations:
  Access and modify storage values as if you were dealing with a standard JavaScript object.

• Deep Proxying for Nested Properties:
  Any modification to a nested property in an object is automatically detected and saved.

• Cross-Tab Synchronization:
  Storage updates in one tab are automatically synchronized with all other tabs running the script.

• Default Value Initialization:
  Easily initialize storage with default values if certain keys aren’t already set.

• Debug Logging:
  Optionally enable debug logging to watch for and troubleshoot changes in real-time.

• Asynchronous Listening for Updates:
  Utilize both one-shot awaiting (using await) and continuous asynchronous iteration (using for await ... of) to react to storage changes.

• Resource Management:
  Clear event listeners efficiently when they are no longer needed.

---

Table of Contents

1. Installation
2. Constructor and Initialization
3. API Reference
   • Reading and Writing Values
   • Working with Default Values
   • Enabling Debug Logging
   • Handling Deep Object Updates
   • Listening for Updates
   • Clearing Listeners
4. Advanced Example
5. Summary of Benefits

---

Installation

Include the script in your userscript's metadata block. Make sure you have the necessary grants:

// ==UserScript==
// @name         Storage Tests
// @namespace    https://wol.ph/
// @version      2025-04-02
// @author       Rick van Hattem <https://wol.ph>
// @description  Demonstrates the usage of the GMStorage class.
// @match        *://*/*
// @grant        GM_setValue
// @grant        GM_getValue
// @grant        GM_listValues
// @grant        GM_addValueChangeListener
// @grant        GM_removeValueChangeListener
// ==/UserScript==

Then include your script file or paste the code inline.

---

Constructor and Initialization

The constructor for GMStorage accepts two optional parameters:

• debugMode (Boolean)

  • Enables debug logging if set to true.
  • Default: false.

• defaultValues (Object)

  • An object with default key/value pairs used to initialize storage if keys are not already set.
  • Default: {}.

Example:

// Initialize with debug mode enabled and default values for storage.
const defaults = {
  username: "Anonymous",
  preferences: {
    theme: "light",
    notifications: true,
  },
};

const storage = new GMStorage(true, defaults);

---

API Reference

1. Reading and Writing Values

Values in storage are accessed and modified as if they were properties of an object.

// Write to storage:
storage.someKey = "Hello, World!";

// Read from storage:
console.log(storage.someKey); // "Hello, World!"

// Update a value:
storage.someKey = "Updated Value";
console.log(storage.someKey); // "Updated Value"

2. Working with Default Values

If a key hasn’t been set, the class initializes it with the default value provided.

const defaults = {
  username: "Anonymous",
  preferences: { theme: "dark", notifications: true },
};

const storage = new GMStorage(false, defaults);

// Will print "Anonymous" if not updated previously:
console.log(storage.username);

// Update the value and it is saved automatically:
storage.username = "JohnDoe";

3. Enabling Debug Logging

When debug mode is enabled, any change log will be output via console.debug().

const storage = new GMStorage(true);

// Changing a value logs the change:
storage.someKey = 42;
// Console Output: GMStorage: key 'someKey' updated from undefined to 42

4. Handling Deep Object Updates

GMStorage uses deep proxies to ensure that nested updates are persisted.

const storage = new GMStorage();

storage.settings = { theme: "light", notifications: false };

// Deep changes are auto-saved:
storage.settings.theme = "dark";
console.log(storage.settings.theme); // "dark"
// Debug log: GMStorage [deep]: key 'settings' modified property 'theme' from 'light' to 'dark'

5. Listening for Updates

a) One-Shot Update Listener

You can await the next update on a key:

(async () => {
  console.log("Waiting for an update on 'someKey'...");
  const newValue = await storage.listen("someKey");
  console.log("Received new value:", newValue);
})();

// Trigger an update after 2000 milliseconds
setTimeout(() => {
  storage.someKey = "New Value";
}, 2000);

b) Continuous Listening Using for await...of

Listen continuously for successive updates:

(async () => {
  console.log("Listening for continuous updates on 'settings'...");
  for await (const value of storage.listen("settings")) {
    console.log("Updated settings:", value);
  }
})();

// Simulate updates:
setTimeout(() => { storage.settings = { theme: "dark" }; }, 1000);
setTimeout(() => { storage.settings.notifications = true; }, 3000);

6. Clearing Listeners

Remove all active listeners to clean up resources:

const storage = new GMStorage();

// ...
storage.clearListeners(); // This stops all active GM_addValueChangeListeners

---

Advanced Example: Combining Features

Below is a comprehensive example that demonstrates initializing defaults, modifying nested objects, and listening for updates:

const defaults = {
  user: {
    name: "Anonymous",
    preferences: {
      theme: "light",
      notifications: true,
    },
  },
};

const storage = new GMStorage(true, defaults);

// Output initial default value.
console.log("Username:", storage.user.name); // "Anonymous"

// Modify a nested property.
storage.user.preferences.theme = "dark";

// Listen for further updates on the 'user' key.
(async () => {
  for await (const updatedUser of storage.listen("user")) {
    console.log("User updated:", updatedUser);
  }
})();

// Simulate another update after 2 seconds.
setTimeout(() => {
  storage.user.preferences.notifications = false; // Update triggers listener.
}, 2000);

Expected Console Output:

GMStorage: key 'user' updated from undefined to { name: 'Anonymous', preferences: { theme: 'light', notifications: true } }
GMStorage [deep]: key 'user' modified property 'preferences' from { theme: 'light', notifications: true } to { theme: 'dark', notifications: true }
User updated: { name: 'Anonymous', preferences: { theme: 'dark', notifications: false } }

---

Summary of Benefits

• Simplification of Code:
  No need for multiple GM_* function calls; work with properties directly.

• Automatic Deep Updates:
  Nested objects are automatically observed and updated without extra coding.

• Robust Synchronization:
  Changes propagate across tabs ensuring consistency.

• Flexible Listening:
  Use either one-shot or continuous asynchronous listening to react to changes.

• Easy Debugging:
  Debug logging provides immediate insight into storage modifications.

• Initialization with Defaults:
  Seamlessly handle unset keys by providing default values in the constructor.

---

This guide should help you get started with the GMStorage class and harness its full potential in your userscripts. Enjoy the streamlined experience and happy coding!

storage.js

/**
 * GMStorage class
 *
 * Provides a proxy-based API for effortless reading and writing to GM storage,
 * with support for deep object updates and automatic synchronization between tabs.
 *
 * Usage:
 *   // Create an instance with debugging enabled and default values:
 *   const defaults = { some_key: 42, another_key: { a: 1 } };
 *   const storage = new GMStorage(defaults, true);
 *
 *   // Setting and getting values:
 *   storage.whatever = 123;
 *   console.log(storage.whatever);
 *
 *   // Deep object updates are auto-saved:
 *   storage.some_object = {};
 *   storage.some_object.a = 123;
 *
 *   // One-shot awaiting the next update:
 *   const newValue = await storage.listen('some_key');
 *
 *   // Continuous listening using async iteration:
 *   for await (const value of storage.listen('some_key')) {
 *       console.log("Updated value:", value);
 *   }
 */
class GMStorage {
  /**
   * @param {Object} [defaults={}] - An object containing default key/value pairs to initialize storage.
   * @param {boolean} [debug=false] - Enable debug logging if true.
   */
  constructor(defaults = {}, debug = false) {
    this._debug = debug;
    // Wrapper for console.debug; if debug is false, it's a no-op.
    this._log = debug ? (...args) => console.debug(...args) : () => {};

    // Internal maps to store GM listener IDs and pending awaiters.
    this._listenerMap = {};
    this._pendingListeners = {};
    // Local cache for stored values.
    this._data = {};

    // Retrieve all existing keys from GM storage.
    const existingKeys = GM_listValues();

    // Process keys already in storage.
    for (const key of existingKeys) {
      const value = GM_getValue(key);
      this._data[key] = this._isObject(value)
        ? this._createDeepProxy(value, key)
        : value;
      this._addChangeListener(key);
    }

    // Initialize defaults for keys not already present.
    for (const key in defaults) {
      if (!existingKeys.includes(key)) {
        GM_setValue(key, defaults[key]);
        this._data[key] = this._isObject(defaults[key])
          ? this._createDeepProxy(defaults[key], key)
          : defaults[key];
        this._addChangeListener(key);
      }
    }

    // Return a proxy so properties can be accessed like standard object properties.
    return new Proxy(this, {
      get: (target, prop) => {
        if (prop in target) return target[prop];
        return target._data[prop];
      },
      set: (target, prop, value) => {
        const oldValue = target._data[prop];
        target._data[prop] = target._isObject(value)
          ? target._createDeepProxy(value, prop)
          : value;
        GM_setValue(prop, target._data[prop]);
        target._log(
          `GMStorage: key '${String(prop)}' updated from`,
          oldValue,
          "to",
          target._data[prop]
        );
        target._notifyAwaiters(prop, target._data[prop]);
        if (!target._listenerMap[prop]) {
          target._addChangeListener(prop);
        }
        return true;
      },
      ownKeys: (target) => Reflect.ownKeys(target._data),
      getOwnPropertyDescriptor: (target, prop) => {
        if (prop in target._data) {
          return { configurable: true, enumerable: true, value: target._data[prop] };
        }
        return undefined;
      },
    });
  }

  /**
   * Checks whether a value is a non-null object.
   * @param {*} val The value to check.
   * @returns {boolean} True if 'val' is a non-null object.
   */
  _isObject(val) {
    return val !== null && typeof val === 'object';
  }

  /**
   * Creates a deep proxy for an object so that nested updates are persisted.
   * @param {Object} obj The object to wrap.
   * @param {string} topKey The corresponding top-level storage key.
   * @returns {Proxy} A deep proxy of the object.
   */
  _createDeepProxy(obj, topKey) {
    return new Proxy(obj, {
      get: (target, prop) => {
        const value = target[prop];
        return this._isObject(value)
          ? this._createDeepProxy(value, topKey)
          : value;
      },
      set: (target, prop, value) => {
        const oldValue = target[prop];
        target[prop] = value;
        GM_setValue(topKey, obj);
        this._log(
          `GMStorage [deep]: key '${topKey}' modified property '${String(prop)}' from`,
          oldValue,
          "to",
          value
        );
        this._notifyAwaiters(topKey, obj);
        return true;
      },
      deleteProperty: (target, prop) => {
        if (prop in target) {
          delete target[prop];
          GM_setValue(topKey, obj);
          this._log(
            `GMStorage [deep]: key '${topKey}' property '${String(prop)}' deleted`
          );
          this._notifyAwaiters(topKey, obj);
        }
        return true;
      },
    });
  }

  /**
   * Sets a change listener for a storage key so that updates in other tabs are captured.
   * @param {string} key The storage key.
   */
  _addChangeListener(key) {
    if (this._listenerMap[key]) return;
    const id = GM_addValueChangeListener(key, (name, oldValue, newValue, remote) => {
      if (remote) {
        this._data[name] = this._isObject(newValue)
          ? this._createDeepProxy(newValue, name)
          : newValue;
        this._log(
          `GMStorage (remote): key '${name}' updated from`,
          oldValue,
          "to",
          newValue
        );
        this._notifyAwaiters(name, newValue);
      }
    });
    this._listenerMap[key] = id;
  }

  /**
   * Notifies all pending listeners waiting for the next update on a key.
   * @param {string} key The storage key.
   * @param {*} newValue The new value for the key.
   */
  _notifyAwaiters(key, newValue) {
    if (this._pendingListeners[key] && this._pendingListeners[key].length > 0) {
      for (const resolve of this._pendingListeners[key]) {
        resolve(newValue);
      }
      this._pendingListeners[key] = [];
    }
  }

  /**
   * Returns a promise that resolves on the next update for the specified key.
   * @param {string} key The storage key.
   * @returns {Promise<*>} A promise that resolves with the new value.
   * @private
   */
  _listenOnce(key) {
    return new Promise((resolve) => {
      if (!this._pendingListeners[key]) {
        this._pendingListeners[key] = [];
      }
      this._pendingListeners[key].push(resolve);
    });
  }

  /**
   * Returns an asynchronous listener that supports both one-shot awaits (via promise)
   * and continuous async iteration (via a for-await loop).
   *
   * Usage:
   *
   *   // One-shot await:
   *   const newVal = await storage.listen('some_key');
   *
   *   // Continuous iteration:
   *   for await (const value of storage.listen('some_key')) {
   *       console.log("Updated value:", value);
   *   }
   *
   * @param {string} key The storage key to listen for updates.
   * @returns {AsyncListener} An object that is both thenable and async iterable.
   */
  listen(key) {
    return new AsyncListener(this, key);
  }

  /**
   * Clears all GM_addValueChangeListeners added by this instance.
   */
  clearListeners() {
    for (const key in this._listenerMap) {
      GM_removeValueChangeListener(this._listenerMap[key]);
      delete this._listenerMap[key];
    }
  }
}

/**
 * AsyncListener class: Enables both promise-based (await) and async iterator usage.
 * When awaited, it resolves to the next update of the provided key; its async iterator
 * continuously yields successive updates.
 */
class AsyncListener {
  /**
   * @param {GMStorage} storage The GMStorage instance.
   * @param {string} key The storage key to listen for.
   */
  constructor(storage, key) {
    this.storage = storage;
    this.key = key;
  }

  /**
   * Thenable implementation for "await listener".
   * @param {Function} resolve Resolve callback.
   * @param {Function} reject Reject callback.
   * @returns {Promise<*>} A promise that resolves with the next update.
   */
  then(resolve, reject) {
    return this.storage._listenOnce(this.key).then(resolve, reject);
  }

  /**
   * Async iterator implementation for "for await (const value of listener)".
   * @returns {Object} An async iterator yielding successive updates.
   */
  [Symbol.asyncIterator]() {
    const storage = this.storage;
    const key = this.key;
    return {
      async next() {
        const value = await storage._listenOnce(key);
        return { value, done: false };
      },
    };
  }
}