@arc-js/timez

@arc-js/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

npm install @arc-js/timez
# ou
yarn add @arc-js/timez
# ou
pnpm add @arc-js/timez

Importation directe (CDN)

<script src="@arc-js/timez/timez.all.js"></script>

🚀 Démarrage Rapide

TypeScript/ES Modules

import Timez from '@arc-js/timez';
// ou
import { Timez } from '@arc-js/timez';

CommonJS

const { Timez } = require('@arc-js/timez');

Navigateur (global)

<script src="@arc-js/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

// 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

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

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

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

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

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é

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

// 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

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

// 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

// 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

// 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

@arc-js/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 pour plus de détails.

🐛 Signaler un Bug

Envoyez nous un mail à l'adresse [email protected] pour :

• Signaler un bug
• Proposer une amélioration
• Poser une question

@arc-js/timez - Parce que le temps, c'est précieux. ⏰

Développé par l'équipe INICODE