Cookies

Paquete: @tiendana/utils

API completa para trabajar con cookies del navegador, proporcionando funciones para leer, escribir y eliminar cookies con soporte para auto-parsing, validación de tamaño y opciones de seguridad.

Características Generales

✅ Auto-parsing de JSON, booleanos y strings
✅ Validación de tamaño (4096 bytes)
✅ Encode/decode automático de caracteres especiales
✅ Soporte completo de opciones (expires, path, domain, secure, sameSite)
✅ Type-safe con TypeScript
✅ Compatible con todos los navegadores modernos

getAllCookies

Obtiene todas las cookies del navegador como un objeto JavaScript, parseando automáticamente JSON y booleanos.

Firma

function getAllCookies(): { [key: string]: any }

Retorno

Tipo: { [key: string]: any }

Objeto con todas las cookies, donde las claves son los nombres y los valores están parseados automáticamente.

Parsing Automático

La función intenta parsear cada valor:

'true' → true (boolean)
'false' → false (boolean)
JSON válido → Objeto/Array parseado
Otros → String original

Ejemplos

Obtener Todas las Cookies

import { getAllCookies } from '@tiendana/utils';

// document.cookie = "token=abc123; theme=dark; user={\"name\":\"Juan\",\"id\":1}; premium=true"

const cookies = getAllCookies();
// {
//   token: 'abc123',
//   theme: 'dark',
//   user: { name: 'Juan', id: 1 },
//   premium: true
// }

Verificar Existencia

const cookies = getAllCookies();

if ('auth_token' in cookies) {
  console.log('Usuario autenticado');
}

Debugging

function debugCookies() {
  const cookies = getAllCookies();
  console.table(cookies);
}

getCookie

Obtiene el valor de una cookie específica por nombre.

Firma

function getCookie(name: string): any

Parámetros

Parámetro	Tipo	Descripción	Requerido
`name`	`string`	Nombre de la cookie a obtener	✅

Retorno

Tipo: any

Valor de la cookie (parseado automáticamente) o null si no existe.

Ejemplos

import { getCookie } from '@tiendana/utils';

const theme = getCookie('theme');
// 'dark' | null

const user = getCookie('user');
// { id: 1, name: 'Juan', email: 'juan@example.com' } | null

if (user) {
  console.log(`Bienvenido, ${user.name}`);
}

Obtener con Valor por Defecto

const language = getCookie('language') || 'es';
// 'es' si la cookie no existe

Verificar Autenticación

function isAuthenticated(): boolean {
  const token = getCookie('auth_token');
  return token !== null && token !== '';
}

setCookie

Establece una cookie con opciones de configuración.

Firma

interface CookieOptions {
  expires?: number | Date;
  path?: string;
  domain?: string;
  secure?: boolean;
  sameSite?: 'Lax' | 'Strict' | 'None';
}

function setCookie(
  name: string,
  value: any,
  options?: CookieOptions
): void

Parámetros

Parámetro	Tipo	Descripción	Requerido
`name`	`string`	Nombre de la cookie	✅
`value`	`any`	Valor de la cookie (se serializa automáticamente)	✅
`options`	`CookieOptions`	Opciones de configuración	❌

Opciones (CookieOptions)

Opción	Tipo	Descripción	Default
`expires`	`number \| Date`	Fecha de expiración (Date) o timestamp Unix (number en segundos)	Session cookie
`path`	`string`	Path donde la cookie es accesible	`/`
`domain`	`string`	Dominio donde la cookie es accesible	Current domain
`secure`	`boolean`	Solo transmitir por HTTPS	`false`
`sameSite`	`'Lax' \| 'Strict' \| 'None'`	Política CSRF	Browser default

Validación de Tamaño

La función valida que la cookie no exceda 4096 bytes (RFC 2109, 2965, 6265). Si lo hace, muestra una advertencia en consola pero aún así la crea.

setCookie('large_data', veryLargeObject);
// ⚠️ Cookie size warning: The cookie "large_data" exceeds the recommended size limit of 4096 bytes...

Ejemplos

import { setCookie } from '@tiendana/utils';

setCookie('theme', 'dark');
// Session cookie (se borra al cerrar navegador)

Con Expiración (Date)

const expires = new Date();
expires.setDate(expires.getDate() + 7); // 7 días

setCookie('auth_token', 'abc123', {
  expires,
  path: '/',
  secure: true,
  sameSite: 'Strict'
});

Con Expiración (Unix Timestamp)

const sevenDays = Math.floor(Date.now() / 1000) + (7 * 24 * 60 * 60);

setCookie('session', 'xyz789', {
  expires: sevenDays,  // Timestamp en segundos
  path: '/'
});

Guardar Objeto

const user = {
  id: 1,
  name: 'Juan',
  email: 'juan@example.com'
};

setCookie('user', user, {
  expires: new Date('2025-12-31'),
  path: '/'
});

// Se guarda como JSON: {"id":1,"name":"Juan","email":"juan@example.com"}

// Cookie que expira en 1 año
const oneYear = new Date();
oneYear.setFullYear(oneYear.getFullYear() + 1);

setCookie('preferences', { language: 'es', theme: 'dark' }, {
  expires: oneYear,
  path: '/'
});

setCookie('csrf_token', generateToken(), {
  secure: true,     // Solo HTTPS
  sameSite: 'Strict',
  path: '/'
});

setCookie('tracking_id', '123-456-789', {
  domain: '.example.com',  // Accesible en todos los subdominios
  expires: new Date('2030-01-01'),
  path: '/'
});

deleteCookie

Elimina una cookie específica estableciendo su expiración en el pasado.

Firma

function deleteCookie(
  name: string,
  options?: Omit<CookieOptions, 'expires' | 'secure' | 'sameSite'>
): void

Parámetros

Parámetro	Tipo	Descripción	Requerido
`name`	`string`	Nombre de la cookie a eliminar	✅
`options`	`Omit<CookieOptions, 'expires' \| 'secure' \| 'sameSite'>`	Path y domain (deben coincidir con los usados al crear)	❌

Importante: Path y Domain

Para eliminar correctamente una cookie, path y domain deben coincidir exactamente con los valores usados al crearla.

// Cookie creada con path específico
setCookie('token', 'abc', { path: '/admin' });

// ❌ No la eliminará (path diferente)
deleteCookie('token');

// ✅ Correcto (path coincide)
deleteCookie('token', { path: '/admin' });

Ejemplos

import { deleteCookie } from '@tiendana/utils';

deleteCookie('theme');

Eliminar con Path

deleteCookie('session', { path: '/' });

Eliminar con Domain

deleteCookie('tracking_id', {
  domain: '.example.com',
  path: '/'
});

Logout

function logout() {
  deleteCookie('auth_token', { path: '/' });
  deleteCookie('user', { path: '/' });
  deleteCookie('session', { path: '/' });
}

deleteAllCookies

Elimina todas las cookies del navegador. Útil para logout completo o reset de sesión.

Firma

function deleteAllCookies(): void

Parámetros

Ninguno.

Comportamiento

Elimina todas las cookies accesibles en el dominio actual
Establece path=/ para asegurar eliminación
No requiere conocer los nombres de las cookies

Ejemplos

Logout Completo

import { deleteAllCookies } from '@tiendana/utils';

function logoutCompletely() {
  deleteAllCookies();
  window.location.href = '/login';
}

Reset de Sesión

function resetSession() {
  deleteAllCookies();
  window.location.reload();
}

Borrar Datos al Desinstalar

function uninstall() {
  deleteAllCookies();
  localStorage.clear();
  sessionStorage.clear();
  console.log('Todos los datos locales eliminados');
}

Casos de Uso Completos

Sistema de Autenticación

import { setCookie, getCookie, deleteCookie } from '@tiendana/utils';

interface AuthTokens {
  accessToken: string;
  refreshToken: string;
}

export const auth = {
  login(tokens: AuthTokens, rememberMe: boolean = false) {
    const expires = rememberMe 
      ? new Date(Date.now() + 30 * 24 * 60 * 60 * 1000) // 30 días
      : undefined; // Session cookie

    setCookie('access_token', tokens.accessToken, {
      expires,
      path: '/',
      secure: true,
      sameSite: 'Strict'
    });

    setCookie('refresh_token', tokens.refreshToken, {
      expires,
      path: '/',
      secure: true,
      sameSite: 'Strict'
    });
  },

  getAccessToken(): string | null {
    return getCookie('access_token');
  },

  isAuthenticated(): boolean {
    return this.getAccessToken() !== null;
  },

  logout() {
    deleteCookie('access_token', { path: '/' });
    deleteCookie('refresh_token', { path: '/' });
  }
};

Gestión de Preferencias

interface UserPreferences {
  theme: 'light' | 'dark';
  language: string;
  fontSize: number;
  notifications: boolean;
}

export const preferences = {
  save(prefs: UserPreferences) {
    setCookie('preferences', prefs, {
      expires: new Date('2030-01-01'),
      path: '/'
    });
  },

  load(): UserPreferences {
    return getCookie('preferences') || {
      theme: 'light',
      language: 'es',
      fontSize: 14,
      notifications: true
    };
  },

  update(partial: Partial<UserPreferences>) {
    const current = this.load();
    this.save({ ...current, ...partial });
  }
};

interface ConsentOptions {
  necessary: boolean;      // Siempre true
  analytics: boolean;
  marketing: boolean;
  preferences: boolean;
}

export const cookieConsent = {
  save(consent: ConsentOptions) {
    setCookie('cookie_consent', consent, {
      expires: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000), // 1 año
      path: '/',
      sameSite: 'Lax'
    });
  },

  load(): ConsentOptions | null {
    return getCookie('cookie_consent');
  },

  hasConsented(): boolean {
    return this.load() !== null;
  },

  canUse(category: keyof ConsentOptions): boolean {
    const consent = this.load();
    if (!consent) return false;
    return consent[category] === true;
  },

  showBanner(): boolean {
    return !this.hasConsented();
  }
};

Notas Técnicas

Encoding

Nombres y valores se codifican automáticamente con encodeURIComponent()
Se decodifican con decodeURIComponent() al leer
Maneja caracteres especiales, espacios, UTF-8

Parsing

Al leer cookies, se intenta parsear en este orden:

String 'true' → true
String 'false' → false
JSON válido → Objeto/Array parseado
Otros → String original

Timestamps

setCookie acepta dos formatos para expires:

Date object: new Date('2025-12-31')
Unix timestamp en segundos: Math.floor(Date.now() / 1000) + 86400

El timestamp se convierte internamente a Date y luego a UTC string.

Validación de Tamaño

Límite: 4096 bytes (según RFC 2109 §6.3, RFC 2965 §5.3, RFC 6265)

La validación usa Blob para calcular el tamaño exacto en bytes (incluyendo encoding).

const cookieByteSize = new Blob([cookieString]).size;
if (cookieByteSize > 4096) {
  console.warn(`Cookie "${name}" excede 4096 bytes...`);
}

Limitaciones

Path y Domain en deleteCookie

Para eliminar correctamente una cookie, path y domain deben coincidir EXACTAMENTE con los valores usados al crearla:

// Crear
setCookie('token', 'abc', { path: '/admin', domain: '.example.com' });

// ❌ No eliminará
deleteCookie('token');

// ✅ Correcto
deleteCookie('token', { path: '/admin', domain: '.example.com' });

deleteAllCookies solo elimina cookies accesibles

deleteAllCookies() solo puede eliminar cookies del dominio actual y path /. Cookies con domain o path específicos pueden no eliminarse.

Para eliminar cookies específicas, usa deleteCookie() con las opciones correctas.

HttpOnly cookies no son accesibles

Las cookies marcadas como HttpOnly (establecidas por el servidor) NO son accesibles desde JavaScript por razones de seguridad. Estas funciones no pueden leer ni eliminar HttpOnly cookies.

Seguridad

Secure Flag

Usa secure: true para cookies sensibles (tokens, sesiones):

setCookie('session_token', token, {
  secure: true,  // Solo HTTPS
  sameSite: 'Strict',
  path: '/'
});

SameSite Attribute

Strict: Cookie solo se envía en requests del mismo sitio. Máxima seguridad CSRF.
Lax: Cookie se envía en navegación top-level cross-site (default moderno).
None: Cookie se envía en todos los requests. Requiere secure: true.

// Para APIs de terceros
setCookie('api_token', token, {
  sameSite: 'None',
  secure: true  // Requerido con SameSite=None
});

No Guardar Datos Sensibles

Evita guardar passwords, números de tarjeta, SSN, etc. en cookies. Usa almacenamiento del lado del servidor.

Ver También

Validation - Validar datos antes de guardar en cookies
Objects - Trabajar con objetos guardados en cookies

Características Generales​

getAllCookies​

Firma​

Retorno​

Parsing Automático​

Ejemplos​

Obtener Todas las Cookies​

Verificar Existencia​

Debugging​

getCookie​

Firma​

Parámetros​

Retorno​

Ejemplos​

Obtener Cookie Simple​

Obtener Cookie con Objeto​

Obtener con Valor por Defecto​

Verificar Autenticación​

setCookie​

Firma​

Parámetros​

Opciones (CookieOptions)​

Validación de Tamaño​

Ejemplos​

Cookie Simple​

Con Expiración (Date)​

Con Expiración (Unix Timestamp)​

Guardar Objeto​

Cookie de Larga Duración​

Cookie Segura (HTTPS)​

Cookie Cross-Domain​

deleteCookie​

Firma​

Parámetros​

Importante: Path y Domain​

Ejemplos​

Eliminar Cookie Simple​

Eliminar con Path​

Eliminar con Domain​

Logout​

deleteAllCookies​

Firma​

Parámetros​

Comportamiento​

Ejemplos​

Logout Completo​

Reset de Sesión​

Borrar Datos al Desinstalar​

Casos de Uso Completos​

Sistema de Autenticación​

Gestión de Preferencias​

Cookie Consent Manager​

Notas Técnicas​

Encoding​

Parsing​

Timestamps​

Validación de Tamaño​

Limitaciones​

Seguridad​

Secure Flag​

SameSite Attribute​

No Guardar Datos Sensibles​

Ver También​

Características Generales

getAllCookies

Firma

Retorno

Parsing Automático

Ejemplos

Obtener Todas las Cookies

Verificar Existencia

Debugging

getCookie

Firma

Parámetros

Retorno

Ejemplos

Obtener Cookie Simple

Obtener Cookie con Objeto

Obtener con Valor por Defecto

Verificar Autenticación

setCookie

Firma

Parámetros

Opciones (CookieOptions)

Validación de Tamaño

Ejemplos

Cookie Simple

Con Expiración (Date)

Con Expiración (Unix Timestamp)

Guardar Objeto

Cookie de Larga Duración

Cookie Segura (HTTPS)

Cookie Cross-Domain

deleteCookie

Firma

Parámetros

Importante: Path y Domain

Ejemplos

Eliminar Cookie Simple

Eliminar con Path

Eliminar con Domain

Logout

deleteAllCookies

Firma

Parámetros

Comportamiento

Ejemplos

Logout Completo

Reset de Sesión

Borrar Datos al Desinstalar

Casos de Uso Completos

Sistema de Autenticación

Gestión de Preferencias

Cookie Consent Manager

Notas Técnicas

Encoding

Parsing

Timestamps

Validación de Tamaño

Limitaciones

Seguridad

Secure Flag

SameSite Attribute

No Guardar Datos Sensibles

Ver También