@arc-js/cooks 0.0.1

package/README.md

@@ -0,0 +1,372 @@
+# @arc-js/cooks
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-007ACC)
+![Browser](https://img.shields.io/badge/browser-compatible-green)
+![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+
+**@arc-js/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
+
+```bash
+npm install @arc-js/cooks
+# ou
+yarn add @arc-js/cooks
+# ou
+pnpm add @arc-js/cooks
+```
+
+### Importation directe (CDN)
+
+```html
+<script src="@arc-js/cooks/cooks.all.js"></script>
+```
+
+## 🚀 Démarrage Rapide
+
+### TypeScript/ES Modules
+
+```typescript
+import Cooks from '@arc-js/cooks';
+// ou
+import { Cooks } from '@arc-js/cooks';
+```
+
+### CommonJS
+
+```javascript
+const { Cooks } = require('@arc-js/cooks');
+```
+
+### Navigateur (global)
+
+```html
+<script src="@arc-js/cooks/cooks.all.js"></script>
+<script>
+  // Disponible globalement comme window.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
+
+```typescript
+type Serializable = 
+  | string
+  | number
+  | boolean
+  | Date
+  | object
+  | Array<any>
+  | null
+  | undefined;
+```
+
+### Options des Cookies
+
+```typescript
+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.
+
+```typescript
+// 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.
+
+```typescript
+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.
+
+```typescript
+Cooks.remove('session');
+Cooks.remove('user', '/admin', 'example.com'); // avec path et domain
+```
+
+### Cooks.has()
+
+Vérifie si un cookie existe.
+
+```typescript
+if (Cooks.has('user')) {
+  console.log('Utilisateur connecté');
+}
+```
+
+### Cooks.keys()
+
+Retourne toutes les clés de cookies disponibles.
+
+```typescript
+const keys = Cooks.keys(); // ['user', 'preferences', 'visitCount', ...]
+console.log('Cookies stockés:', keys);
+```
+
+### Cooks.clear()
+
+Supprime tous les cookies (à utiliser avec précaution).
+
+```typescript
+Cooks.clear(); // Supprime tous les cookies accessibles
+```
+
+## 🎯 Exemples Complets
+
+### Exemple 1 : Gestion de Session
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+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
+
+```
+@arc-js/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
+
+- @arc-js/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
+
+```typescript
+// ✅ Bonnes pratiques
+Cooks.set('user_prefs', data, {
+  expires: 30 * 24 * 3600, // 30 jours max
+  secure: window.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](LICENSE) pour plus de détails.
+
+---
+
+**@arc-js/cooks** - Gestion simple et sécurisée des cookies 🍪
+
+*Développé par l'équipe INICODE*