@jsarc/timez 0.0.0

package/README.md

@@ -0,0 +1,408 @@
+# @jsarc/timez
+
+[![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)
+![Node.js](https://img.shields.io/badge/Node.js-18+-339933)
+
+**@jsarc/timez** est une bibliothèque JavaScript/TypeScript puissante et intuitive pour la manipulation des dates et fuseaux horaires. Inspirée par les meilleures pratiques de Python et Moment.js, elle offre une API fluide et type-safe pour tous vos besoins de gestion temporelle.
+
+## ✨ Fonctionnalités Principales
+
+- 🕐 **Manipulation intuitive des dates** : addition, soustraction, début/fin de période
+- 🌍 **Gestion complète des fuseaux horaires** : UTC, local, et fuseaux personnalisés
+- 📅 **Formatage flexible** : formats prédéfinis, Python-style et personnalisés
+- 🔄 **Parsing intelligent** : multiple formats de date supportés
+- 📊 **Comparaisons avancées** : avant/après, entre, même période
+- 🛡️ **TypeScript-first** : typage complet et auto-complétion
+- 🌐 **Multi-plateforme** : navigateur et Node.js
+
+## 📦 Installation
+
+### Via npm/yarn/pnpm
+
+```bash
+npm install @jsarc/timez
+# ou
+yarn add @jsarc/timez
+# ou
+pnpm add @jsarc/timez
+```
+
+### Importation directe (CDN)
+
+```html
+<script src="@jsarc/timez/timez.all.js"></script>
+```
+
+## 🚀 Démarrage Rapide
+
+### TypeScript/ES Modules
+
+```typescript
+import Timez from '@jsarc/timez';
+// ou
+import { Timez } from '@jsarc/timez';
+```
+
+### CommonJS
+
+```javascript
+const { Timez } = require('@jsarc/timez');
+```
+
+### Navigateur (global)
+
+```html
+<script src="@jsarc/timez/timez.all.js"></script>
+<script>
+  // Disponible globalement comme window.Timez
+  const now = Timez.now();
+  console.log(now.format('EUROPEAN'));
+</script>
+```
+
+## 📚 Documentation API
+
+### Création d'Instances
+
+```typescript
+// Date et heure actuelles
+const now = Timez.now();
+
+// Depuis une chaîne ISO
+const fromIso = new Timez('2024-03-15T10:30:00.000Z');
+
+// Depuis un timestamp Unix
+const fromUnix = Timez.unix(1710000000);
+
+// Depuis un objet Date natif
+const fromDate = new Timez(new Date());
+
+// Depuis un autre Timez
+const copy = new Timez(now);
+
+// UTC actuel
+const utcNow = Timez.utc();
+```
+
+### Méthodes Getters
+
+```typescript
+const t = Timez.now();
+
+t.year();        // 2024 (nombre)
+t.month();       // 3 (1-12)
+t.date();        // 15 (1-31)
+t.hour();        // 14 (0-23)
+t.minute();      // 30 (0-59)
+t.second();      // 45 (0-59)
+t.millisecond(); // 123 (0-999)
+t.day();         // 5 (0-6, 0=dimanche)
+```
+
+### Manipulation des Dates
+
+```typescript
+const t = Timez.now();
+
+// Addition
+t.add(1, 'days');
+t.add(3, 'months');
+t.add(2, 'hours');
+
+// Soustraction
+t.subtract(7, 'days');
+t.subtract(30, 'minutes');
+
+// Début de période
+t.startOf('year');   // 1er janvier 00:00:00
+t.startOf('month');  // 1er du mois 00:00:00
+t.startOf('day');    // Minuit du jour
+t.startOf('hour');   // Début de l'heure
+
+// Fin de période
+t.endOf('day');      // 23:59:59.999
+t.endOf('month');    // Dernier jour du mois 23:59:59.999
+```
+
+### Comparaisons
+
+```typescript
+const today = Timez.now();
+const tomorrow = today.add(1, 'days');
+const yesterday = today.subtract(1, 'days');
+
+// Comparaisons simples
+today.isBefore(tomorrow);      // true
+today.isAfter(yesterday);      // true
+today.isSame(tomorrow, 'day'); // false
+
+// Comparaisons avec inclusivité
+today.isBefore(tomorrow, '(]');    // inclusif à droite
+today.isAfter(yesterday, '[)');    // inclusif à gauche
+
+// Vérification d'intervalle
+today.isBetween(yesterday, tomorrow);            // excluant les bornes
+today.isBetween(yesterday, tomorrow, '[]');     // incluant les deux bornes
+today.isBetween(yesterday, tomorrow, '[)');     // incluant seulement la borne de gauche
+```
+
+### Fuseaux Horaires
+
+```typescript
+const now = Timez.now();
+
+// Conversion vers UTC
+const utcTime = now.utc();
+
+// Retour au fuseau local
+const localTime = utcTime.local();
+
+// Définition d'un fuseau spécifique
+const estTime = now.setTimezone('EST');      // Heure de l'Est (US)
+const cestTime = now.setTimezone('CEST');    // Heure d'été d'Europe centrale
+const customTime = now.setTimezone('+05');   // UTC+5
+const customTime2 = now.setTimezone('-08:00'); // UTC-8
+
+// Informations sur le fuseau
+now.timezone();              // "Europe/Paris"
+now.timezoneAbbr();          // "CEST"
+now.timezoneName();          // "Central European Summer Time"
+now.timezoneOffsetString();  // "+02:00"
+now.utcOffset();             // 120 (minutes)
+now.isDST();                 // true/false (heure d'été)
+```
+
+### Formatage
+
+#### Tokens de Formatage (Style Python)
+
+| Token | Description | Exemple |
+|-------|-------------|---------|
+| `%Y` | Année sur 4 chiffres | 2024 |
+| `%y` | Année sur 2 chiffres | 24 |
+| `%m` | Mois (01-12) | 03 |
+| `%d` | Jour (01-31) | 15 |
+| `%H` | Heure (00-23) | 14 |
+| `%M` | Minute (00-59) | 30 |
+| `%S` | Seconde (00-59) | 45 |
+| `%f` | Millisecondes (000-999) | 123 |
+| `%z` | Offset fuseau horaire | +0200 |
+| `%s` | Timestamp Unix | 1710000000 |
+
+#### Formats Prédéfinis
+
+```typescript
+const t = Timez.now();
+
+// Formats disponibles
+t.format('ISO');           // "2024-03-15T14:30:45.123Z"
+t.format('ISO_DATE');      // "2024-03-15"
+t.format('ISO_TIME');      // "14:30:45.123Z"
+t.format('COMPACT');       // "20240315143045"
+t.format('SLASH_DATETIME');// "2024/03/15 14:30:45.123Z"
+t.format('EUROPEAN');      // "15/03/2024 14:30:45 GMT+0200"
+t.format('SLASH_DATE');    // "2024/03/15"
+t.format('TIME_SEC');      // "14:30:45"
+t.format('CUSTOM_GREETING'); // "Bonjour celestin, la date actuelle est: le 15/03/2024 à 14:30:45.123Z"
+```
+
+#### Formatage Personnalisé
+
+```typescript
+const t = Timez.now();
+
+// Format Python-style
+t.format('%Y-%m-%d %H:%M:%S');          // "2024-03-15 14:30:45"
+t.format('%d/%m/%Y');                   // "15/03/2024"
+t.format('Timestamp: %s');              // "Timestamp: 1710000000"
+
+// Textes littéraux (entre crochets)
+t.format('[Le] %d/%m/%Y [à] %H:%M:%S'); // "Le 15/03/2024 à 14:30:45"
+t.format('Date: %Y-%m-%d | Time: %H:%M'); // "Date: 2024-03-15 | Time: 14:30"
+
+// Format ISO personnalisé
+t.format('%Y-%m-%dT%H:%M:%S.%fZ');      // "2024-03-15T14:30:45.123Z"
+```
+
+### Parsing
+
+```typescript
+// Parsing automatique (détection de format)
+Timez.parse('2024-03-15T14:30:45.123Z');
+Timez.parse('2024-03-15');
+Timez.parse('2024/03/15 14:30:45');
+Timez.parse('20240315143045');
+
+// Parsing avec format spécifié
+Timez.parse('15/03/2024 14:30:45', '%d/%m/%Y %H:%M:%S');
+Timez.parse('03-15-2024', '%m-%d-%Y');
+Timez.parse('2024-03-15T14:30', '%Y-%m-%dT%H:%M');
+
+// Parsing avec texte littéral
+Timez.parse('Date: 2024-03-15', '[Date:] %Y-%m-%d');
+
+// Gestion d'erreur
+const result = Timez.parse('date invalide', '%Y-%m-%d');
+console.log(result.isCorrect()); // false
+```
+
+### Méthodes Utilitaires
+
+```typescript
+const t = Timez.now();
+
+// Conversion vers types natifs
+t.toDate();           // Objet Date JavaScript
+t.toISOString();      // Chaîne ISO 8601
+t.toString();         // Représentation locale
+t.valueOf();          // Timestamp en millisecondes
+t.unix();             // Timestamp Unix (secondes)
+
+// Validation
+t.isCorrect();        // true si la date est valide
+
+// Chaînage de méthodes
+const result = Timez.now()
+  .add(2, 'hours')
+  .subtract(30, 'minutes')
+  .startOf('hour')
+  .format('%Y-%m-%d %H:%M:%S');
+
+// Création depuis un timestamp Unix
+Timez.unix(1710000000); // Depuis des secondes
+new Timez(1710000000000); // Depuis des millisecondes
+```
+
+## 🎯 Exemples Complets
+
+### Exemple 1 : Agenda
+
+```typescript
+// Création d'un événement
+const eventDate = Timez.parse('2024-12-25 20:00:00', '%Y-%m-%d %H:%M:%S')
+  .setTimezone('Europe/Paris');
+
+// Calcul des rappels
+const reminder1Day = eventDate.subtract(1, 'days');
+const reminder1Hour = eventDate.subtract(1, 'hours');
+
+console.log(`Événement: \${eventDate.format('EUROPEAN')}`);
+console.log(`Rappel J-1: \${reminder1Day.format('EUROPEAN')}`);
+console.log(`Rappel H-1: \${reminder1Hour.format('EUROPEAN')}`);
+
+// Vérification si c'est aujourd'hui
+if (eventDate.isSame(Timez.now(), 'day')) {
+  console.log("L'événement est aujourd'hui !");
+}
+```
+
+### Exemple 2 : Traitement de Fichiers
+
+```typescript
+// Génération de nom de fichier avec timestamp
+const timestamp = Timez.now().format('COMPACT');
+const filename = `rapport_\${timestamp}.pdf`;
+// Exemple: "rapport_20240315143045.pdf"
+
+// Parsing de nom de fichier
+const fileDate = Timez.parse(
+  filename.replace('rapport_', '').replace('.pdf', ''),
+  '%Y%m%d%H%M%S'
+);
+
+console.log(`Fichier créé le: \${fileDate.format('EUROPEAN')}`);
+```
+
+### Exemple 3 : Application Multi-fuseaux
+
+```typescript
+// Message envoyé à un timestamp donné
+const messageTime = Timez.unix(1710000000);
+
+// Affichage selon le fuseau de l'utilisateur
+const userTimezone = 'America/New_York'; // Récupéré depuis les préférences
+const localMessageTime = messageTime.setTimezone(userTimezone);
+
+console.log(`Message reçu à: \${localMessageTime.format('%H:%M %Z')}`);
+// Exemple: "Message reçu à: 09:30 EST"
+
+// Calcul de la différence
+const now = Timez.now();
+const diffHours = now.diff(messageTime, 'hours');
+console.log(`Il y a \${diffHours} heures`);
+```
+
+## 🔧 Build et Développement
+
+### Structure du Projet
+
+```
+@jsarc/timez/
+├── timez.all.js
+├── timez.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+
+
+### Environnements
+
+- Node.js 18+
+- Deno 1.30+
+- Bun 1.0+
+- Tous les environnements ES5+
+
+## 🚨 Notes Importantes
+
+### Performances
+
+Timez est optimisé pour la performance mais gardez à l'esprit que :
+- La création d'objets `Intl.DateTimeFormat` peut être coûteuse
+- Préférez réutiliser les instances plutôt que d'en créer de nouvelles
+- Utilisez `Timez.now()` au lieu de `new Timez()` pour la date courante
+
+### Fuseaux Horaires
+
+- Les noms de fuseaux IANA sont supportés (`Europe/Paris`, `America/New_York`)
+- Les abréviations courantes sont reconnues (`EST`, `CEST`, `PST`)
+- Les offsets numériques sont acceptés (`+02:00`, `-05`, `+0530`)
+
+### Sécurité
+
+Timez ne présente pas de vulnérabilités connues, mais :
+- Validez toujours les entrées utilisateur avant parsing
+- Utilisez `isCorrect()` pour vérifier la validité des dates
+- Évitez d'exécuter du code arbitraire dans les formats
+
+## 📄 Licence
+
+MIT License - Voir le fichier [LICENSE](LICENSE) pour plus de détails.
+
+## 🐛 Signaler un Bug
+
+Envoyez nous un mail à l'adresse `contact.inicode@gmail.com` pour :
+- Signaler un bug
+- Proposer une amélioration
+- Poser une question
+
+---
+
+**@jsarc/timez** - Parce que le temps, c'est précieux. ⏰
+
+*Développé par l'équipe INICODE*