@sonardigital/cookie

A lightweight, type-safe cookie management utility for frontend applications. Built on top of the popular js-cookie library, this package provides a clean and simple API for handling browser cookies with TypeScript support.

Features

• 🍪 Simple API - Clean and intuitive methods for cookie operations
• 🔒 Type-safe - Full TypeScript support with proper type definitions
• ⚡ Lightweight - Minimal bundle size with zero dependencies beyond js-cookie
• 🛡️ Secure - Built-in support for secure cookie attributes
• 🌐 Cross-browser - Works across all modern browsers

Installation

Install the package using your preferred package manager:

npm install @sonardigital/cookie

yarn add @sonardigital/cookie

pnpm add @sonardigital/cookie

Usage

Basic Usage

import { cookies } from '@sonardigital/cookie';

// Set a cookie
cookies.set('username', 'john_doe');

// Get a cookie
const username = cookies.get('username'); // 'john_doe'

// Check if a cookie exists
const hasCookie = cookies.exists('username'); // true

// Remove a cookie
cookies.remove('username');

// Get all cookies
const allCookies = cookies.getAll(); // { username: 'john_doe', theme: 'dark' }

Advanced Usage with Options

import { cookies } from '@sonardigital/cookie';

// Set cookie with options
cookies.set('session_token', 'abc123', {
  expires: 7, // expires in 7 days
  secure: true, // only send over HTTPS
  sameSite: 'strict', // CSRF protection
  path: '/', // available across the entire site
  domain: '.example.com' // share across subdomains
});

// Remove cookie with specific options
cookies.remove('session_token', {
  path: '/',
  domain: '.example.com'
});

API Reference

cookies.set(name, value, options?)

Sets a cookie with the given name and value.

Parameters:

• name (string): The cookie name
• value (string): The cookie value
• options (CookieAttributes, optional): Cookie configuration options

Options:

• expires (number | Date): Expiration date or days until expiration
• path (string): Cookie path (default: '/')
• domain (string): Cookie domain
• secure (boolean): Only send over HTTPS
• sameSite ('strict' | 'lax' | 'none'): SameSite attribute for CSRF protection

cookies.get(name)

Retrieves a cookie by name.

Parameters:

• name (string): The cookie name

Returns:

• string | undefined: The cookie value or undefined if not found

cookies.exists(name)

Checks if a cookie exists.

Parameters:

• name (string): The cookie name

Returns:

• boolean: True if the cookie exists, false otherwise

cookies.remove(name, options?)

Removes a cookie.

Parameters:

• name (string): The cookie name to remove
• options (CookieAttributes, optional): Must match the options used when setting the cookie

cookies.getAll()

Retrieves all cookies as an object.

Returns:

• Record<string, string>: Object with cookie names as keys and values as values

TypeScript Support

This package is built with TypeScript and includes comprehensive type definitions:

import { cookies, CookieType } from '@sonardigital/cookie';

// Type the cookies utility
const cookieManager: CookieType = cookies;

// Type-safe cookie operations
interface UserPreferences {
  theme: 'light' | 'dark';
  language: string;
}

const preferences: UserPreferences = {
  theme: cookies.get('theme') as 'light' | 'dark' || 'light',
  language: cookies.get('language') || 'en'
};

Development

Prerequisites

• Node.js 16+
• TypeScript 5.0+

Setup

# Install dependencies
npm install

# Run linting
npm run lint

# Format code
npm run format

# Run pre-commit hooks
npm run precommit

Scripts

• npm run lint - Run ESLint
• npm run format - Format code with Prettier
• npm run precommit - Run pre-commit hooks (lint + format)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

ISC

Dependencies

• js-cookie - The underlying cookie library