cookies

A cookies module is available to assist in cookie manipulation. This module exports two structs, Cookies and SetCookie, each corresponding to one "Cookie" or "Set-Cookie" header respectively.

import {Cookies, SetCookie} from 'cookies';

export function onClientRequest(request) {
  let cookies = new Cookies(request.getHeader('Cookie'));
}

Properties for the SetCookie Object

name

Sets the cookie name.

var cookie = new SetCookie();
cookie.name = 'Cookie1';
response.setHeader('Set-Cookie', cookie.toHeader());

value

Sets the cookie value.

var cookie = new SetCookie();
cookie.name = 'Cookie1';
cookie.value = 'Value1';
response.setHeader('Set-Cookie', cookie.toHeader());
// Set-Cookie: Cookie1=Value1; 

maxAge

Sets the expiry time relative to the current time in seconds. (Optional).

var cookie = new SetCookie();
cookie.name = 'Cookie1';
cookie.value = 'Value1';
cookie.maxAge = 900;
response.setHeader('Set-Cookie', cookie.toHeader());
// Set-Cookie: Cookie1=Value1; Max-Age=900;

domain

Sets the domain name for the cookie. (Optional)

var cookie = new SetCookie();
cookie.name = 'Cookie1';
cookie.value = 'Value1';
cookie.domain = 'example.com';
response.setHeader('Set-Cookie', cookie.toHeader());
// Set-Cookie: Cookie1=Value1; Domain=example.com;

path

Sets the path for the cookie. (Optional)

var cookie = new SetCookie();
cookie.name = 'Cookie1';
cookie.value = 'Value1';
cookie.path = '/';
response.setHeader('Set-Cookie', cookie.toHeader());
// Set-Cookie: Cookie1=Value1; path=/;

expires

Sets the expiry date of the cookie in GMT. If an expiry date is not specified or set to 0, a session cookie is created. (Optional)

var cookie = new SetCookie();
cookie.name = 'Cookie1';
cookie.value = 'Value1';
cookie.expires = new Date('August 23, 2020 03:24:00');
response.setHeader('Set-Cookie', cookie.toHeader());
// Set-Cookie: Cookie1=Value1; Expires=Sun, 23 Aug 2020 03:24:00 GMT;

httpOnly

Helps mitigate the risk of a client side script accessing a protected cookie (if supported by the browser). (Optional)

var cookie = new SetCookie();
cookie.name = 'Cookie1';
cookie.value = 'Value1';
cookie.httpOnly = true; // true or false
response.setHeader('Set-Cookie', cookie.toHeader());
// Set-Cookie: Cookie1=Value1; HttpOnly;

secure

Specifies the cookies to be used with HTTPS only. (Optional)

var cookie = new SetCookie();
cookie.name = 'Cookie1';
cookie.value = 'Value1';
cookie.secure = true; // true or false
response.setHeader('Set-Cookie', cookie.toHeader());
// Set-Cookie: Cookie1=Value1; Secure;

sameSite

Allows servers to prevent cookies from being sent using cross-site requests (where Site is defined by the registrable domain). This provides some protection against cross-site request forgery attacks (CSRF). (Optional)
var cookie = new SetCookie();
cookie.name = 'Cookie1';
cookie.value = 'Value1';
cookie.sameSite = 'Strict'; // Strict, Lax, None
response.setHeader('Set-Cookie', cookie.toHeader());
// Set-Cookie: Cookie1=Value1; SameSite=Strict;

Methods available from the Cookies Module

SetCookie([cookieHeader], [options])

Constructor for a new "SetCookie" object. Holds a specific Set-Cookie header representation and the SetCookie object that corresponds to the "Set-Cookie" header.

Review the table below for information about the possible arguments.

Argument Description Object Type
cookieHeader Passes the raw Set-Cookie header to the constructor to parse. If a string is passed, an attempt is made to parse it as Set-Cookie. If an Object is passed, the constructor copies properties of that object into the SetCookie object for its own properties. (Optional) String/Object
options This object parses an existing Set-Cookie header to override the default decode of the Set-Cookie values. This object must have a function named 'decode' on it, to return the custom decoding results from the string. (Optional) Object
var cookie = new SetCookie(); // Sets empty cookie object
var cookie = new SetCookie( 'Cookie1=Value1; Path=/;');
options
import { SetCookie } from 'cookies';

const options = {
  decode: (s) => { return decodeURI(s); }
};

export function onClientResponse (request, response) {
  var setCookie = new SetCookie('mycookie=value1%20value2', options);
  response.setHeader('set-cookie', setCookie.toHeader());
}

// Set-Cookie: mycookie=value1 value2;

toHeader([options])

Returns the string value to use when setting the Cookie header, encoding values by default.

Review the table below for information about the possible arguments.

Argument Description Object Type
options The Options object overrides the default encoding of the Set-Cookie values. This object must have a function named 'encode' on it, to return the custom encoding results for the string. (Optional) String
import { SetCookie } from 'cookies';

export function onClientResponse (request, response) {
   var cookie = new SetCookie({name: 'cookie', value: 'VALUE1 value2'});
   response.setHeader('Set-Cookie', cookie.toHeader());
}

// Set-Cookie: cookie=VALUE1 value2;
options
import { SetCookie } from 'cookies';

const options = {
  encode: (s) => { return encodeURI(s); }
};

export function onClientResponse (request, response) {
   var cookie = new SetCookie('cookie=VALUE1 value2');
   response.setHeader('Set-Cookie', cookie.toHeader(options));
}

// Set-Cookie: cookie=VALUE1%20value2;

Cookies([cookieHeader], [options])

Constructor for a new "Cookies" object to hold cookies.

Review the table below for information about the possible arguments.

Argument Description Object Type
cookieHeader Passes the raw Cookie header to the constructor to parse. If an array is passed, the first element must be a string that is used as the cookie’s string to parse. If it is not passed, an empty cookies object is returned. (Optional) String/Array
options This object is only used when parsing an existing Cookie header to override the default decode of the Cookie values. This object must have a function named 'decode' on it to return the custom decoding results from the string. (Optional) String
// Cookie: Cookie1=Value1;Cookie2=Value2;Cookie3=Value3;
  let cookies = new Cookies(request.getHeader('Cookie'));

options

import { Cookies } from 'cookies';

  const options = {
    decode: (s) => { return decodeURI(s); }
  };

export function onClientResponse (request, response) {
  const cookie = new Cookies('Cookie1=Value1%20Value2', options);
  response.setHeader('Set-Cookie', cookie.toHeader());
}

// Set-Cookie: Cookie1=Value1 Value2;

toHeader([options])

Returns the string value to use when setting the Cookie header, encoding values by default.

Review the table below for information about the possible arguments.

Argument Description Object Type
options The Options object overrides the default encoding of the Set-Cookie values. This object must have a function named 'encode' on it, to return the custom encoding results for the string. (Optional) String
// Cookie: cookie1=value1;cookie2=value2;
import { Cookies } from 'cookies';
export function onClientResquest (request) {
  const cookieJar = new Cookies(request.getHeader('Cookie'));
  cookieJar.delete('cookie2');
  request.setHeader('Cookie', cookieJar.toHeader());
}
// Cookie: cookie1=value1;
options
import { SetCookie } from 'cookies';

const options = {
  encode: (s) => { return encodeURI(s); }
};

export function onClientResponse (request, response) {
   var cookie = new SetCookie('cookie=VALUE1 value2');
   response.setHeader('Set-Cookie', cookie.toHeader(options));
}

// Set-Cookie: cookie=VALUE1%20value2;

get(name)

Returns the first instance of the cookie matching the specified cookie name.

Review the table below for information about the possible arguments.

Argument Description Object Type
name Name of first matching cookie String
// Cookie: Cookie1=Value1;Cookie2=Value2;Cookie3=Value3;
  let cookies = new Cookies(request.getHeader('Cookie'));
  var cookie1Cookie = cookies.get('Cookie1');
// cookie1Cookie ==> "Value1"

getAll (name)

Returns all cookie instances matching the specified cookie name.

Review the table below for information about the possible arguments.

Argument Description Object Type
name Name of all matching cookies String
// Cookie: Cookie1=Value1;Cookie1=Value2;Cookie1=Value3;
  let cookies = new Cookies(request.getHeader('Cookie'));
  var cookieValues = cookies.getAll('Cookie1');
// cookieValues ==> ["Value1", "Value2", "Value3"]

names()

Returns the names of all existing cookies held by the specified cookies object. Array of Strings.

// Cookie: Cookie1=Value1;Cookie2=Value2;Cookie3=Value3;
 
  let cookies = new Cookies(request.getHeader('Cookie'));
  var cookieNames = cookies.names();
 
// cookieNames ==> ["Cookie1", "Cookie2", "Cookie3"]

add(name, value)

Adds a cookie to an object containing all the cookies.

Review the table below for information about the possible arguments.

Argument Description Object Type
name Name of the cookie to be added String
value Value of the cookie to be added String
// Cookie: Cookie1=Value1;Cookie2=Value2;
  let cookies = new Cookies(request.getHeader('Cookie'));
  cookies.add('Cookie3','Value3');
  cookies.toHeader();
// Cookie: Cookie1=Value1;Cookie2=Value2;Cookie3=Value3;

delete(name)

Removes all cookies with a given name.

Review the table below for information about the possible arguments.

Argument Description Object Type
name Name of the cookie to be removed String
// Cookie: Cookie1=Value1;Cookie2=Value2;Cookie3=Value3;
  let cookies = new Cookies(request.getHeader('Cookie'));
  cookies.delete('Cookie3');
  cookies.toHeader();
// Cookie: Cookie1=Value1;Cookie2=Value2;