cookie-events

Lightweight, event-driven cookie manager for parsing, setting, and tracking cookies with ease.

Installation

To include cookie-events in Node, first install with npm.

npm install cookie-events

How to build cookie-events

Clone a copy of the main cookie-events git repo by running:

git clone git://github.com/jsvibe/cookie-events.git

Including cookie-events

Below are some of the most common ways to include cookie-events.

Browser

CDN Link

<script src="https://cdn.jsdelivr.net/npm/[email protected]/lib/cookie.min.js"></script>

You can add the script manually to your project:

<script src="cookie.js"></script>

ESM

import cookieEvents from 'cookie-events'
const cookie = new cookieEvents;

Webpack / Browserify / Babel

There are several ways to use Webpack, Browserify or Babel. For more information on using these tools, please refer to the corresponding project's documentation. In the script, including cookie-events will usually look like this:

import cookieEvents from 'cookie-events'
const cookie = new cookieEvents;

Methods or Features

This library provides a robust and modern API for managing browser cookies, with support for creation, retrieval, updates, deletion, and real-time event handling.

|Methods|Description| |:------|:---------------------------------------------------------------------------------| |set|Creates a new cookie with optional attributes (expires, path, domain, etc). | |getAll|Returns all cookies as a key-value object. | |store|Exposes the internal cookie store object. | |param|Converts cookies into a query-style string (e.g., name=John&age=30). | |get|Retrieves the value of a specific cookie by key. | |update|Updates an existing cookie’s value and attributes. | |json|Converts all cookies into a JSON string. | |UTC|Converts a custom date string into a UTC-formatted string. | |parse|Returns cookies as an array of [key, value] pairs. | |has|Checks if a cookie with the given key exists. | |remove|Deletes a specific cookie by setting expiry in the past. | |clear|Asynchronously clears all cookies using the Cookie Store API. | |on|Registers event listeners for cookie changes (insert, update, delete, etc). |

set

Creates or overwrites a cookie with optional attributes.

Parameters:

• key (String) Name of the cookie.
• value (Any) Value to store (objects/arrays auto-serialized as JSON).
• expires (String | Number) Expiry date (UTC string) or max-age in seconds.
• path (String, optional) Path scope (default: /).
• domain (String, optional) Domain scope.
• secure (Boolean, optional) If true, cookie only sent over HTTPS.
• SameSite (String, optional) "Strict", "Lax", or "None".

Example:

const Cookie = new Cookie;
Cookie.set("theme", "dark", Cookie.UTC("2025-12-31 23:59:59"));

getAll

Returns all cookies as a key-value object.

Example:

const Cookie = new Cookie;
console.log(Cookie.getAll()); // Output: e.g, { theme: "dark", user: { id: 1 } }

store

Exposes the internal cookie store object (for debugging/inspection).

Example:

const Cookie = new Cookie;
console.log(Cookie.store);

param

Converts cookies into a query-style string.

Example:

const Cookie = new Cookie;
console.log(Cookie.param()); // Output: e.g, "theme=dark&user=%7B%22id%22%3A1%7D"

get

Retrieves the value of a cookie by its name.

Parameters:

• key (String) Cookie name.
• Returns: Value (Any) or null if not found.

Example:

const Cookie = new Cookie;
console.log(Cookie.get("theme")); // "dark"

update

Updates the value of an existing cookie. Throws error if cookie does not exist.

Parameters:

• key (String) Name of the cookie.
• value (Any) Value to store (objects/arrays auto-serialized as JSON).
• expires (String | Number) Expiry date (UTC string) or max-age in seconds.
• path (String, optional) Path scope (default: /).
• domain (String, optional) Domain scope.
• secure (Boolean, optional) If true, cookie only sent over HTTPS.
• SameSite (String, optional) "Strict", "Lax", or "None".

Example:

const Cookie = new Cookie;
Cookie.update("theme", "light", Cookie.UTC("2026-01-01 00:00:00"));

json

Converts all cookies into a JSON string.

Example:

console.log(Cookie.json()); // Output: e.g, {"theme":"dark","user":{"id":1}}

UTC

Converts a date string into UTC format (for expires attribute).

Parameters:

• date (String) Example: "2025-12-31 23:59:59"
• Returns: String UTC date string.

Example:

const Cookie = new Cookie;
let exp = Cookie.UTC("2025-12-31 23:59:59");
Cookie.set("session", "active", exp);

parse

Parses cookies into an array of [key, value] pairs.

• Returns: Array Example: [["theme","dark"], ["user",{id:1}]]

Example:

const Cookie = new Cookie;
console.log(Cookie.parse());

has

Checks if a cookie exists.

• Returns: boolean Return true if exists. Otherwise false

Example:

const Cookie = new Cookie;
if (Cookie.has("theme")) {
  console.log("Theme cookie exists!");
}

remove

Deletes a specific cookie by setting its expiry to the past.

Parameters:

• key (String) The name of the cookie to remove.
• path (String) The path the cookie was set on. Default is "/".
• domain (String) The domain the cookie was set on.

Example:

const Cookie = new Cookie;
Cookie.remove("theme");

clear

Asynchronously removes all cookies using the Cookie Store API.

⚠️ Works only in secure contexts (HTTPS) and supported browsers.

Example:

const Cookie = new Cookie;
await Cookie.clear();

on

Registers event listeners for cookie changes.

Parameters:

• types (String) Space-separated events (insert, update, delete, clear, change).
• callback (Function) Called when event occurs.

const Cookie = new Cookie;
Cookie.on("insert update delete", (e) => {
  console.log("Cookie event:", e.type, e.changed, e.deleted);
});

Supported Events

• insert → A new cookie was added.
• update → An existing cookie was updated.
• delete → A cookie was removed.
• clear → All cookies were cleared.
• change → Fired on any cookie change.

License

MIT License © 2025 Indian Modassir
See LICENSE for details.

Contributions

Pull requests, bug reports, and feedback are welcome!
Visit the GitHub Repository to contribute.