Overview
Menu

Cookies

The Cookies API provides a group of methods for you to manage cookies.
Note:
The unique keys of Cookies objects are in the format of name + domain + path. You can manage Cookies objects based on the unique keys.

Constructor API

const cookies = new Cookies(cookieStr?: string, isSetCookie?: boolean);

Parameters

Parameter
Type
Required
Description
cookieStr
string
No
The Cookie string or Set-Cookie string.
isSetCookie
boolean
No
Specifies whether the value of the cookieStr parameter is a Set-Cookie string. Default value: false.

Methods

get

cookies.get(name?: string): null | Cookie | Array<Cookie>;
The get() method obtains the Cookie object of the specified name. If multiple objects are matched, a Cookie array is returned.

Parameters

Parameter
Type
Required
Description
name
string
No
The name of Cookie object. Valid options:
Default name
Obtains all Cookie objects.
Specified name
Obtains the Cookie object of the specified name. If multiple objects are matched, a Cookie array is returned.
The following table describes the attributes of the Cookie object. For more information, see Set-Cookie.
Attribute
Type
Read-only
Description
name
string
Yes
The name of the Cookie object.
value
string
Yes
The value of the Cookie object.
domain
string
Yes
The host to which the Cookie object will be sent.
path
string
Yes
The path to which the Cookie object will be sent.
expires
string
Yes
The maximum effective time of the Cookie object. The value meets the HTTP Date header standards.
max_age
string
Yes
The number of seconds until the Cookie object expires.
samesite
string
Yes
Controls whether the Cookie object is sent with cross-site requests, providing some protection against cross-site request forgery (CSRF) attacks.
httponly
boolean
Yes
Forbids JavaScript from accessing the Cookie object. The attribute is carried only by HTTP requests.
secure
boolean
Yes
Specifies that the Cookie object can be carried only by HTTPS requests.

set

cookies.set(name: string, value: string, options?: Cookie): boolean;
The set() method adds cookies in overwrite mode. If true is returned, cookies are successfully added. If false is returned, cookies fail to be added because the number of cookies exceeds the upper limit. For more information, see Cookie limits.
Note:
Cookies are added in overwrite mode based on unique keys in the format of name + domain + path.

Parameters

Parameter
Type
Required
Description
name
string
Yes
The name of the Cookie object.
value
string
Yes
The value of the Cookie object.
Cookie
string
No
The configuration items of the Cookie object.

append

cookies.append(name: string, value: string, options?: Cookie): boolean;
The append() method appends cookies in scenarios where multiple values correspond to the same name. If true is returned, cookies are successfully appended. If false is returned, cookies fail to be appended because the value already exists or the number of cookies exceeds the upper limit. For more information, see Cookie limits.
Note:
Cookies are appended based on unique keys in the format of name + domain + path.

remove

cookies.remove(name: string, options?: Cookie): boolean;
The remove() method deletes cookies.
Note:
Cookies are deleted based on unique keys in the format of name + domain + path.

Parameters

Parameter
Type
Required
Description
name
string
Yes
The name of the Cookie object.
options
Yes
The configuration items of the Cookie object. The configuration items `domain` and `path` support the wildcard character (*), indicating that all items are matched.

Use Limits

Automatic escape of special characters

The following characters are automatically escaped if they are contained in the value of the name attribute: " ( ) , / : ; ? < = > ? @ [ ] \ { }. 0x00~0x1F and 0x7F~0xFF.
The following characters are automatically escaped if they are contained in the value of the value attribute: , , ; " \. 0x00~0x1F and 0x7F~0xFF.

Cookie limits

The size of the Cookie attribute name cannot exceed 64 bytes.
The accumulated size of the Cookie attributes value, domain, path, expires, max_age, and samesite cannot exceed 1 KB.
The total length of all fields after escape of cookies cannot exceed 4 KB.
The total number of Cookie objects contained in cookies cannot exceed 64.

Sample Code

function handleEvent(event) {
const response = new Response('hello world');

// Generate a Cookies object.
const cookies = new Cookies('ssid=helloworld; expires=Sun, 10-Dec-2023 03:10:01 GMT; path=/; domain=.tencentcloud.com; samesite=.tencentcloud.com', true);

// Set the response header Set-Cookie.
response.setCookies(cookies);

return response;
}

addEventListener('fetch', (event) => {
event.respondWith(handleEvent(event));
});

References