Options
All
  • Public
  • Public/Protected
  • All
Menu

greasetools

Index

Type aliases

Functions

Type aliases

MetadataObject

MetadataObject: Partial<Record<"description" | "exclude" | "grant" | "icon" | "include" | "match" | "name" | "namespace" | "noframes" | "require" | "resource" | "run-at" | "version", MetadataValue>> & Record<string, MetadataValue>

ValuesObject

ValuesObject<Keys>: Record<Keys, GM.Value>

Type parameters

  • Keys: string = string

ValuesPromiseObject

ValuesPromiseObject<Keys>: Record<Keys, Promise<GM.Value>>

Type parameters

  • Keys: string = string

Functions

checkGrants

  • checkGrants(...grants: readonly ("setValue" | "getValue" | "deleteValue" | "listValues" | "xmlHttpRequest")[]): boolean

  • Used by functions to check if grants are present

    Parameters

    • Rest ...grants: readonly ("setValue" | "getValue" | "deleteValue" | "listValues" | "xmlHttpRequest")[]

    Returns boolean

deleteValue

  • deleteValue<Keys, ToDelete>(values: ValuesObject<Keys>, toDelete: ToDelete, id?: string): Promise<Omit<ValuesObject<Keys>, ToDelete>>

  • Requires the GM.deleteValue grant or falls back to localStorage. Deletes a value from a values object. This is only useful if you're using TypeScript or your editor has typing support. If that doesn't describe your use case, then use GM.deleteValue instead

    Type parameters

    • Keys: string

    • ToDelete: string

    Parameters

    • values: ValuesObject<Keys>

      A values object, such as the one returned from getValues

    • toDelete: ToDelete

      The value to delete

    • Optional id: string

      An optional unique identifier for the config. Prefixes all keys with the ID (eg. foo -> myconfig.foo for id myconfig). This won't change the names of the keys on the returned object

    Returns Promise<Omit<ValuesObject<Keys>, ToDelete>>

    A Promise that resolves with a new object without the deleted type, or rejects with nothing if the deletion failed

genBanner

  • genBanner(metaValues: MetadataObject, spacing?: number, start?: string, end?: string): string

  • Generate a UserScript metadata comment from an object. Falsey values will be excluded from the banner, so checking if a value is undefined before passing is not necessary.

    Parameters

    • metaValues: MetadataObject

      Properties to add to metadata

    • spacing: number = 12

      The amount of spaces between the @ and the value, including the prop name. Should be at least 1 greater than the longest prop name

    • start: string = '// ==UserScript=='

      What to put at the start of the banner. Defaults to '// ==UserScript=='

    • end: string = '// ==/UserScript=='

      What to put at the end of the banner. Defaults to '// ==/UserScript=='

    Returns string

    A block of comments to be put at the top of a UserScript including all of the properties passed

getAllValues

  • Requires the GM.getValue and GM.listValues grants or falls back to using localStorage. Returns a values object containing every saved value for the UserScript

    example
    // Logs all key/value pairs from GreaseMonkey
    const allValues = await getAllValues()
    for (const [key, value] of Object.entries(allValues)) {
      console.log(key, value)
    }

    Returns Promise<ValuesObject>

    A Promise that resolves to the defined values or rejects with nothing.

getValues

  • Requires the GM.getValue grant or falls back to using localStorage. Retrieves values from GreaseMonkey based on the generic type provided

    example
    const values = await getValues({
        somethingEnabled: false,
        someNumber: 42,
    })

    console.log(values.somethingEnabled)
    console.log(values.someNumber)

    values.someNumber++ // Does NOT modify GM stored value.
                        // Pass the return of this function to valuesProxy for that functionality

    Type parameters

    • Keys: string

    Parameters

    • defaults: ValuesObject<Keys>

      The default values if they are undefined. Each option will be set to a key from this if it does not exist

    • Optional id: string

      An optional unique identifier for the config. Prefixes all keys with the ID (eg. foo -> myconfig.foo for id myconfig). This won't change the names of the keys on the returned object

    • setDefaults: boolean = false

      Whether or not to store the default value from the defaults argument with GM.setValue if it doesn't exist. Requires the GM.setValue grant

    Returns Promise<ValuesObject<Keys>>

    A Promise that resolves to an object with all of the values

valuesGetProxy

  • Requires the GM.getValue grant or falls back to using localStorage. Get a Proxy that wraps GM.getValue for better typing. Useful when a value may be modified by multiple different sources, meaning the value will need to be retrieved from GM every time. This should not be used if values are only being modified by one source

    example
    const values = valuesProxy(
      await getValues({
        message: 'Hello, World!',
      })
    )

    const valuesGet = valuesGetProxy(values)

    console.log(await valuesGet.message) // Logs the result of GM.getValue('message')

    Type parameters

    • Keys: string

    Parameters

    • values: ValuesObject<Keys>

      A values object, such as the one returned from getValues

    • Optional id: string

      An optional unique identifier for the config. Prefixes all keys with the ID (eg. foo -> myconfig.foo for id myconfig). This won't change the names of the keys on the returned object

    Returns ValuesPromiseObject<Keys>

    A Proxy using the keys of values that wraps GM.getValue

valuesProxy

  • valuesProxy<Keys>(values: ValuesObject<Keys>, id?: string, callback?: (gmSetPromise: Promise<void>) => void): ValuesObject<Keys>

  • Requires the GM.setValue grant or falls back to using localStorage. Get a Proxy that automatically updates values. There should generally only be one Proxy per option (eg. one proxy that controls option1 and option2 and a different one that controls option3 and option4). This is because the returned Proxy doesn't update the value on get, only on set. If multiple Proxies on the same values are being used to set, then a get Proxy (valuesGetProxy) to get values might be a good idea

    example
    const values = valuesProxy(
      await getValues({
        message: 'Hello, World!',
      })
    )

    values.message = 'Hello!' // Runs GM.setValue('message', 'Hello!')
    console.log(values.message) // Logs 'Hello!'. Does NOT run GM.getValue

    Type parameters

    • Keys: string

    Parameters

    • values: ValuesObject<Keys>

      A values object, such as the one from getValues

    • Optional id: string

      An optional unique identifier for the config. Prefixes all keys with the ID (eg. foo -> myconfig.foo for id myconfig). This won't change the names of the keys on the returned object

    • Optional callback: (gmSetPromise: Promise<void>) => void

      Called with the Promise returned by GM.setValue

        • (gmSetPromise: Promise<void>): void

        • Parameters

          • gmSetPromise: Promise<void>

          Returns void

    Returns ValuesObject<Keys>

    A Proxy from values that updates the GM value on set

xhrPromise

  • xhrPromise<Request>(xhrInfo: Request): Promise<GM.Response<Request>>

  • Make a request with GM.xmlHttpRequest using Promises. Requires the GM.xmlHttpRequest grant

    see

    https://wiki.greasespot.net/GM.xmlHttpRequest

    example
    // Make a GET request to https://example.com
    const example = await xhrPromise({
      method: 'GET',
      url: 'https://example.com',
    })

    Type parameters

    • Request: Request<any, Request> = Request<any>

    Parameters

    • xhrInfo: Request

      The XHR info

    Returns Promise<GM.Response<Request>>

    A Promise that resolves with the Greasemonkey Response object

Generated using TypeDoc