Scripting API

PropertyList

The list of keys and values behind headers, query parameters, form fields and cookies.

Declaration

relay.request.headers
relay.request.url.query
relay.request.body.urlencoded
relay.request.body.formdata
relay.response.headers
relay.cookies

Overview

A property list holds entries, each with a key, a value and whether it's disabled. Header lists match keys without regard to case; other lists match them exactly. Lists from the request can be changed in a pre-request script, and the changes apply to this send. Lists from the response are read-only, and changing one throws an error.

// Add a correlation ID unless the request already has one.
if (!relay.request.headers.has("X-Request-Id")) {
  relay.request.headers.add({ key: "X-Request-Id", value: crypto.randomUUID() });
}

// Drop an empty query parameter.
relay.request.url.query.remove(param => param.value === "");

Topics

Reading entries

get(key)

list.get(key: string): string | undefined

Returns the value of the last enabled entry named key, or undefined when there's none.

has(key, value)

list.has(key: string, value?: string): boolean

Returns whether there's an enabled entry named key, with the value value when you pass one.

one(key)

list.one(key: string): Entry | undefined

Returns the last entry named key.

idx(index)

list.idx(index: number): Entry | undefined

Returns the entry at index.

indexOf(key)

list.indexOf(key: string): number

Returns the position of the first entry named key, or -1.

count()

list.count(): number

Returns the number of entries, including disabled ones.

all()

list.all(): Entry[]

Returns every entry as an array. The members property returns the same array.

toObject(excludeDisabled, caseSensitive)

list.toObject(excludeDisabled?: boolean, caseSensitive?: boolean): object

Returns the entries as an object of keys and values. Disabled entries are left out unless excludeDisabled is false. For a header list, pass false for caseSensitive to lowercase the keys.

Iterating

each(fn)

list.each(fn: (entry: Entry) => void): void

Calls fn with each entry. forEach(fn) does the same, and for…of loops over the entries too.

map(fn)

list.map(fn: (entry: Entry) => any): any[]

Returns an array of fn's result for each entry.

filter(fn)

list.filter(fn: (entry: Entry) => boolean): Entry[]

Returns the entries for which fn returns true.

find(fn)

list.find(fn: (entry: Entry) => boolean): Entry | undefined

Returns the first entry for which fn returns true.

reduce(fn, initial)

list.reduce(fn: (result: any, entry: Entry) => any, initial: any): any

Combines the entries into a single value.

Changing entries

add(entry)

list.add(entry: { key: string, value: any, disabled?: boolean } | string): void

Adds an entry, keeping any others with the same key. A string such as "Accept: application/json" is split at its first separator. append(entry) does the same.

upsert(entry)

list.upsert(entry: { key: string, value: any }): void

Sets the value of the last enabled entry with the same key, or adds the entry when there's none.

remove(keyOrFn)

list.remove(keyOrFn: string | ((entry: Entry) => boolean)): void

Removes every entry named key, or every entry for which the function returns true.

clear()

list.clear(): void

Removes every entry.

populate(entries)

list.populate(entries: object[]): void

Adds each of entries.

repopulate(entries)

list.repopulate(entries: object[]): void

Replaces every entry with entries.

assimilate(source)

list.assimilate(source: PropertyList | object[] | object): void

Upserts each entry of another list, an array, or an object of keys and values.

Serialization

toJSON()

list.toJSON(): object[]

Returns the entries as { key, value } objects, with disabled: true on disabled ones.

toString()

list.toString(): string

Returns the enabled entries as lines of Key: value for headers, or joined as key=value&… for query parameters and form fields.

Entries

Each entry is an object with these members. Changing one changes the list.

key

entry.key: string

The entry's key.

value

entry.value: string

The entry's value.

disabled

entry.disabled: boolean

Whether the entry is turned off.

update(options)

entry.update(options: { key?: string, value?: any, disabled?: boolean }): void

Changes any of the entry's key, value and whether it's disabled.

Discussion

Values are stored as text: numbers and Booleans become their text, and objects become JSON.

See Also

  • relay.request: The request being sent, which pre-request scripts can change.
  • relay.response: The response a post-response script checks, with its status, headers and body.
  • relay.cookies: The cookies the response set.