Tampermonkey Async API Reference

Tampermonkey Async API Reference

Documentation for GM.* promise-based functions.

Overview

The GM.* API provides promise-based versions of GM_* functions. Use with async/await for cleaner code.

Key differences from GM_ functions:*

• Return Promises instead of values/callbacks
• Use await or .then() for results
• Some have slightly different names (note capitalisation)

Naming Conventions

Storage Functions

GM.getValue(key, defaultValue)

// @grant GM.getValue

const username = await GM.getValue('username', 'Anonymous');
const settings = await GM.getValue('settings', { theme: 'dark', lang: 'en' });

GM.setValue(key, value)

// @grant GM.setValue

await GM.setValue('username', 'John');
await GM.setValue('settings', { theme: 'light', lang: 'fr' });
await GM.setValue('lastVisit', Date.now());

GM.deleteValue(key)

// @grant GM.deleteValue

await GM.deleteValue('tempData');

GM.listValues()

// @grant GM.listValues

const keys = await GM.listValues();
console.log('Stored keys:', keys);

GM.getValues(keysOrDefaults) (v5.3+)

// @grant GM.getValues

// With array of keys
const values = await GM.getValues(['foo', 'bar', 'baz']);

// With default values
const values2 = await GM.getValues({
    foo: 1,
    bar: 'default',
    baz: null
});

GM.setValues(values) (v5.3+)

// @grant GM.setValues

await GM.setValues({
    username: 'John',
    theme: 'dark',
    lastLogin: Date.now()
});

GM.deleteValues(keys) (v5.3+)

// @grant GM.deleteValues

await GM.deleteValues(['tempData', 'cache', 'oldSettings']);

GM.addValueChangeListener(key, callback)

// @grant GM.addValueChangeListener

const listenerId = await GM.addValueChangeListener('counter', (key, oldValue, newValue, remote) => {
    console.log(`${key} changed from ${oldValue} to ${newValue}`);
    if (remote) {
        console.log('Change came from another tab');
    }
});

GM.removeValueChangeListener(listenerId)

// @grant GM.removeValueChangeListener

await GM.removeValueChangeListener(listenerId);

Resource Functions

GM.getResourceText(name)

// @resource myCSS https://example.com/style.css
// @grant GM.getResourceText

const cssText = await GM.getResourceText('myCSS');

GM.getResourceUrl(name)

Note: Lowercase "r" and "l" in "Url" (different from sync version).

// @resource myIcon https://example.com/icon.png
// @grant GM.getResourceUrl

const iconUrl = await GM.getResourceUrl('myIcon');
img.src = iconUrl;

Network Requests

GM.xmlHttpRequest(details)

Note: Uppercase "H" in "Http" (different from sync version).

// @grant GM.xmlHttpRequest
// @connect api.example.com

try {
    const response = await GM.xmlHttpRequest({
        method: 'GET',
        url: 'https://api.example.com/data',
        headers: {
            'Accept': 'application/json'
        }
    });

    const data = JSON.parse(response.responseText);
    console.log(data);
} catch (error) {
    console.error('Request failed:', error);
}

The promise also has an abort() function:

const request = GM.xmlHttpRequest({
    method: 'GET',
    url: 'https://api.example.com/large-file'
});

// Cancel after 5 seconds
setTimeout(() => request.abort(), 5000);

try {
    const response = await request;
} catch (error) {
    console.log('Request was aborted or failed');
}

UI Functions

GM.notification(details)

Returns a Promise that resolves to true if clicked, false otherwise.

// @grant GM.notification

const wasClicked = await GM.notification({
    text: 'Click me!',
    title: 'Notification',
    timeout: 10000
});

if (wasClicked) {
    console.log('User clicked the notification');
} else {
    console.log('Notification timed out or was dismissed');
}

GM.setClipboard(data, type)

// @grant GM.setClipboard

await GM.setClipboard('Copied text', 'text');
console.log('Text copied to clipboard');

Tab Functions

GM.getTab()

// @grant GM.getTab

const tab = await GM.getTab();
console.log('Tab data:', tab);

GM.saveTab(tab)

// @grant GM.saveTab

const tab = await GM.getTab();
tab.customData = { lastAction: 'click', timestamp: Date.now() };
await GM.saveTab(tab);

GM.getTabs()

// @grant GM.getTabs

const tabs = await GM.getTabs();
for (const [tabId, tabData] of Object.entries(tabs)) {
    console.log(`Tab ${tabId}:`, tabData);
}

Cookie Functions

GM.cookie.list(details)

// @grant GM.cookie

const cookies = await GM.cookie.list({ domain: 'example.com' });
console.log('Cookies:', cookies);

GM.cookie.set(details)

// @grant GM.cookie

await GM.cookie.set({
    name: 'myCookie',
    value: 'myValue',
    domain: 'example.com',
    path: '/',
    secure: true
});

GM.cookie.delete(details)

// @grant GM.cookie

await GM.cookie.delete({ name: 'myCookie' });

Audio Functions (v5.0+)

GM.audio.setMute(details)

// @grant GM.audio

await GM.audio.setMute({ isMuted: true });
console.log('Tab muted');

GM.audio.getState()

// @grant GM.audio

const state = await GM.audio.getState();
console.log(`Muted: ${state.isMuted}, Audible: ${state.isAudible}`);

GM.audio.addStateChangeListener(listener)

// @grant GM.audio

await GM.audio.addStateChangeListener((event) => {
    if ('muted' in event) console.log('Mute changed:', event.muted);
    if ('audible' in event) console.log('Audible changed:', event.audible);
});

Combining Async Operations

Sequential Operations

async function loadUserData() {
    const userId = await GM.getValue('userId');
    const response = await GM.xmlHttpRequest({
        url: `https://api.example.com/users/${userId}`
    });
    const userData = JSON.parse(response.responseText);
    await GM.setValue('userData', userData);
    return userData;
}

Parallel Operations

async function loadAllSettings() {
    const [theme, language, notifications] = await Promise.all([
        GM.getValue('theme', 'dark'),
        GM.getValue('language', 'en'),
        GM.getValue('notifications', true)
    ]);

    return { theme, language, notifications };
}

Error Handling

async function safeRequest(url) {
    try {
        const response = await GM.xmlHttpRequest({
            method: 'GET',
            url: url,
            timeout: 5000
        });
        return JSON.parse(response.responseText);
    } catch (error) {
        console.error('Request failed:', error);
        await GM.notification({
            text: 'Failed to load data',
            title: 'Error'
        });
        return null;
    }
}