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.cookiesOverview
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 | undefinedReturns the value of the last enabled entry named key, or undefined when there's none.
has(key, value)
list.has(key: string, value?: string): booleanReturns whether there's an enabled entry named key, with the value value when you pass one.
one(key)
list.one(key: string): Entry | undefinedReturns the last entry named key.
idx(index)
list.idx(index: number): Entry | undefinedReturns the entry at index.
indexOf(key)
list.indexOf(key: string): numberReturns the position of the first entry named key, or -1.
count()
list.count(): numberReturns 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): objectReturns 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): voidCalls 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 | undefinedReturns the first entry for which fn returns true.
reduce(fn, initial)
list.reduce(fn: (result: any, entry: Entry) => any, initial: any): anyCombines the entries into a single value.
Changing entries
add(entry)
list.add(entry: { key: string, value: any, disabled?: boolean } | string): voidAdds 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 }): voidSets 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)): voidRemoves every entry named key, or every entry for which the function returns true.
clear()
list.clear(): voidRemoves every entry.
populate(entries)
list.populate(entries: object[]): voidAdds each of entries.
repopulate(entries)
list.repopulate(entries: object[]): voidReplaces every entry with entries.
assimilate(source)
list.assimilate(source: PropertyList | object[] | object): voidUpserts 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(): stringReturns 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: stringThe entry's key.
value
entry.value: stringThe entry's value.
disabled
entry.disabled: booleanWhether the entry is turned off.
update(options)
entry.update(options: { key?: string, value?: any, disabled?: boolean }): voidChanges 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.