@arcpkg/cooks

@arcpkg/cooks est une bibliothèque TypeScript/JavaScript légère et type-safe pour la gestion des cookies dans les navigateurs web. Elle offre une API simple et intuitive pour stocker, récupérer et manipuler des cookies avec support des types complexes et des options avancées.

✨ Fonctionnalités Principales

• 🍪 Gestion complète des cookies : set, get, remove, has, clear
• 🔄 Sérialisation automatique : support des objets, tableaux, dates, et types primitifs
• 🛡️ TypeScript-first : typage complet et auto-complétion
• ⚙️ Options avancées : expiration, secure, sameSite, domain, path
• 🚀 Léger et performant : 0 dépendance, < 5KB minifié
• 🧪 Robuste : gestion d'erreurs et validation
• 🌐 Multi-navigateurs : support de tous les navigateurs modernes

📦 Installation

Via npm/yarn/pnpm

npm install @arcpkg/cooks
# ou
yarn add @arcpkg/cooks
# ou
pnpm add @arcpkg/cooks

Importation directe (CDN)

<script src="@arcpkg/cooks/cooks.all.js"></script>

🚀 Démarrage Rapide

TypeScript/ES Modules

import Cooks from '@arcpkg/cooks';
// ou
import { Cooks } from '@arcpkg/cooks';

CommonJS

const { Cooks } = require('@arcpkg/cooks');

Navigateur (global)

<script src="@arcpkg/cooks/cooks.all.js"></script>
<script>
  // Disponible globalement comme (window as any).Cooks
  Cooks.set('user', { name: 'John', age: 30 });
  const user = Cooks.get('user');
  console.log(user); // { name: 'John', age: 30 }
</script>

📚 Documentation API

Types Supportés

type Serializable = 
  | string
  | number
  | boolean
  | Date
  | object
  | Array<any>
  | null
  | undefined;

Options des Cookies

interface CooksOptions {
  expires?: Date | number; // Date ou nombre de secondes
  path?: string;
  domain?: string;
  secure?: boolean;
  sameSite?: 'strict' | 'lax' | 'none';
}

Cooks.set()

Stocke une valeur dans un cookie avec sérialisation automatique.

// Stocker différents types de données
Cooks.set('user', { name: 'John', age: 30 });
Cooks.set('preferences', ['dark-mode', 'notifications']);
Cooks.set('visitCount', 42);
Cooks.set('isLoggedIn', true);
Cooks.set('lastVisit', new Date());
Cooks.set('message', 'Hello World!');

// Avec options avancées
Cooks.set('session', 'token123', { 
  expires: 7 * 24 * 3600, // 7 jours en secondes
  secure: true,
  sameSite: 'strict',
  path: '/admin',
  domain: 'example.com'
});

Cooks.get()

Récupère et désérialise un cookie.

const user = Cooks.get('user'); // { name: 'John', age: 30 }
const preferences = Cooks.get('preferences'); // ['dark-mode', 'notifications']
const visitCount = Cooks.get('visitCount'); // 42
const isLoggedIn = Cooks.get('isLoggedIn'); // true
const lastVisit = Cooks.get('lastVisit'); // Date object
const message = Cooks.get('message'); // 'Hello World!'
const notFound = Cooks.get('nonexistent'); // null

Cooks.remove()

Supprime un cookie.

Cooks.remove('session');
Cooks.remove('user', '/admin', 'example.com'); // avec path et domain

Cooks.has()

Vérifie si un cookie existe.

if (Cooks.has('user')) {
  console.log('Utilisateur connecté');
}

Cooks.keys()

Retourne toutes les clés de cookies disponibles.

const keys = Cooks.keys(); // ['user', 'preferences', 'visitCount', ...]
console.log('Cookies stockés:', keys);

Cooks.clear()

Supprime tous les cookies (à utiliser avec précaution).

Cooks.clear(); // Supprime tous les cookies accessibles

🎯 Exemples Complets

Exemple 1 : Gestion de Session

// Connexion utilisateur
function login(userData: { id: number; name: string; email: string }) {
  Cooks.set('auth_token', 'jwt_token_here', {
    expires: 24 * 3600, // 1 jour
    secure: true,
    sameSite: 'strict'
  });
  
  Cooks.set('user', userData, {
    expires: 7 * 24 * 3600 // 7 jours
  });
  
  Cooks.set('last_login', new Date());
}

// Vérification de session
function checkSession() {
  if (Cooks.has('auth_token')) {
    const user = Cooks.get('user');
    const lastLogin = Cooks.get('last_login');
    
    console.log('Utilisateur connecté:', user);
    console.log('Dernière connexion:', lastLogin);
    return true;
  }
  return false;
}

// Déconnexion
function logout() {
  Cooks.remove('auth_token');
  Cooks.remove('user');
  Cooks.remove('last_login');
}

Exemple 2 : Préférences Utilisateur

// Sauvegarder les préférences
function savePreferences(prefs: {
  theme: 'light' | 'dark';
  language: string;
  notifications: boolean;
}) {
  Cooks.set('preferences', prefs, {
    expires: 365 * 24 * 3600, // 1 an
    path: '/'
  });
}

// Charger les préférences avec valeurs par défaut
function loadPreferences() {
  const defaultPrefs = {
    theme: 'light' as const,
    language: 'fr',
    notifications: true
  };
  
  return Cooks.get('preferences') || defaultPrefs;
}

// Toggle du thème
function toggleTheme() {
  const prefs = loadPreferences();
  prefs.theme = prefs.theme === 'light' ? 'dark' : 'light';
  savePreferences(prefs);
}

Exemple 3 : Panier d'Achat

interface CartItem {
  id: number;
  name: string;
  price: number;
  quantity: number;
}

class ShoppingCart {
  private static readonly CART_KEY = 'shopping_cart';
  
  static addItem(item: CartItem) {
    const cart = this.getCart();
    const existing = cart.find(i => i.id === item.id);
    
    if (existing) {
      existing.quantity += item.quantity;
    } else {
      cart.push(item);
    }
    
    Cooks.set(this.CART_KEY, cart, {
      expires: 2 * 24 * 3600 // 2 jours
    });
  }
  
  static removeItem(itemId: number) {
    const cart = this.getCart().filter(item => item.id !== itemId);
    Cooks.set(this.CART_KEY, cart);
  }
  
  static getCart(): CartItem[] {
    return Cooks.get(this.CART_KEY) || [];
  }
  
  static clearCart() {
    Cooks.remove(this.CART_KEY);
  }
  
  static getTotal(): number {
    return this.getCart().reduce((sum, item) => sum + (item.price * item.quantity), 0);
  }
}

// Utilisation
ShoppingCart.addItem({ id: 1, name: 'Produit A', price: 29.99, quantity: 2 });
console.log('Panier:', ShoppingCart.getCart());
console.log('Total:', ShoppingCart.getTotal());

🔧 Build et Développement

Structure du Projet

@arcpkg/cooks/
├── cooks.all.js
├── cooks.all.min.js
├── index.d.ts
├── index.js
├── index.min.d.ts
├── index.min.js
├── package.json
├── tsconfig.json
└── README.md

📋 Compatibilité

Navigateurs Supportés

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+
• Opera 47+
• Tous les navigateurs supportant les cookies et JSON

Environnements

• Navigateurs web (principal usage)
• Node.js 18+ (avec jsdom pour les tests)
• Tous les environnements ES5+

Dépendances

• @arcpkg/timez (pour la gestion du temps)

🚨 Notes Importantes

Sécurité

• Toujours utiliser secure: true en production pour les cookies sensibles
• Utiliser sameSite: 'strict' pour la protection CSRF
• Ne jamais stocker d'informations sensibles (mots de passe, tokens secrets) dans les cookies
• Valider et assainir toutes les données stockées et récupérées

Limitations des Cookies

• Taille limitée : ~4KB par cookie
• Nombre limité : ~20-50 cookies par domaine (selon le navigateur)
• Accessibilité : Les cookies sont envoyés avec chaque requête HTTP
• Performance : Trop de cookies peuvent ralentir les requêtes

Bonnes Pratiques

// ✅ Bonnes pratiques
Cooks.set('user_prefs', data, {
  expires: 30 * 24 * 3600, // 30 jours max
  secure: (window as any).location.protocol === 'https:',
  sameSite: 'strict',
  path: '/'
});

// ❌ À éviter
Cooks.set('sensitive_data', 'secret'); // Sans options de sécurité
Cooks.set('huge_data', largeObject); // Objet trop volumineux

📄 Licence

MIT License - Voir le fichier LICENSE pour plus de détails.

@arcpkg/cooks - Gestion simple et sécurisée des cookies 🍪

Développé par l'équipe INICODE