@p0xz/cookiejar v1.0.2

cookiejar is simple & lightweight node.js library built for having a place where to store your cookies

Features

• ⚡️ Fast Cookie Parsing: Efficiently parses raw cookie strings
• 🗄️ Cookie Jar Management: Stores and manages multiple cookies
• ⏳ Expiration Handling: Monitor and manage expiring cookies with custom warnings and removal logic
• 🔄 Custom Cookie Interceptors: Dynamically access and update cookies with custom logic
• 🔎 Easy Cookie Retrieval: Retrieve cookies by name
• ✅ TypeScript Support: Built-in type definitions
• 🚀 Zero Dependencies: Lightweight and dependency-free

Install

pnpm i @p0xz/cookiejar

Usage

import cookiejar from "@p0xz/cookiejar";

const jar = new CookieJar();

const exampleCookie = "sessionId=abc123; Domain=example.com; Path=/; Secure; HttpOnly; SameSite=Strict; Expires=Wed, 09 Jun 2025 10:18:14 GMT";

// takes an array with cookie strings and then it will proccess them
jar.setCookies([exampleCookie, ...]);

// returns 'sessionId' value
jar.getCookie("sessionId");

Expiration handling

With the expireChecker function, you can:

• Automatically detect when cookies are about to expire and issue warnings.
• Configure custom thresholds for warnings using the warnLimit option.
• Remove expired cookies and trigger a callback function for custom logic.

import cookiejar from "@p0xz/cookiejar";

const jar = new CookieJar();

const exampleCookie = "sessionId=abc123; SameSite=Strict; Expires=Wed, 09 Jun 2025 10:18:14 GMT";

jar.setCookie([exampleCookie]);

jar.expireChecker("sessionId", () => {
  console.log("Session cookie has expired!");
  // handle aftermath...
}, { warnLimit: "12h", delay: 60 * 60 * 1000 }); // time is in ms

Time format for warnLimit can also be "365y 4w 30d 24h 60m 60s" (order is irrelevant)

Interceptor

With intercept, you can:

• Dynamically update a cookie's value using a callback.
• Check if a cookie has expired with a built-in helper method.
• Access the raw or parsed cookie at any time.

import cookiejar from "@p0xz/cookiejar";

const jar = new CookieJar();

const exampleCookie = "sessionId=abc123; SameSite=Strict; Expires=Wed, 09 Jun 2024 10:18:14 GMT";

jar.setCookie([exampleCookie]);

const sessionIdMiddleware = jar.intercept("sessionId", (options) => {
  if (!options.isExpired()) return;

  console.warn("The sessionId cookie has expired.");
  options.update("sessionId=refreshed123; SameSite=Strict; Expires=Wed, 10 Jun 2025 10:18:14 GMT");
});

// returns cookie with interceptor behind it
sessionIdMiddleware.getCookie();

Methods

🍪 Set and Initialize Cookies

The setCookies method allows you to store and initialize multiple cookies from an array of raw cookie strings.

setCookies(_cookies: string[]);

🔍 Get All Cookies

Retrieves all stored cookies. You can choose to return either raw cookie strings or parsed cookie objects.

getCookies(raw: boolean = true);

🎯 Get a Specific Cookie

Retrieves a specific cookie by name, if it exists.

getCookie(name: string, raw: boolean = true);

🗑️ Clear All Cookies

Removes all stored cookies, leaving the cookie jar empty.

clearCookies();

🍪 Intercept cookie

The intercept method allows you to hook into a specific cookie's lifecycle, enabling dynamic modifications before it is accessed. This is useful for updating cookie values, checking expiration or adding custom behavior.

intercept(cookieName: string, callback: (options: iCookieJar.interceptorOptions) => void);

Once a cookie is intercepted, the method returns a separate getCookie function, which ensures that the interception logic does not interfere with the default getCookie method of the class.

getCookie: (raw?: boolean) => string | iCookieJar.Cookie;

📜 Interface

namespace iCookieJar {
    export interface interceptorOptions {
        update: (cookie: string) => void;
        isExpired: () => void;
    }
    export interface Cookie {
        cookieName: string;
        cookieValue: string;
        attributes: Map<string, any>;
        interceptor?: (options: interceptorOptions) => void;
        raw: string;
    }
}

License

Copyright © 2025 cookieJar

This project is protected under the GNU AGPLv3 License. For more details, refer to the LICENSE file.