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;