Travailler avec les timestamps Unix en JavaScript
Tout ce qu'il faut pour travailler avec les timestamps Unix en JavaScript — obtenir l'heure actuelle, créer des Date à partir de timestamps, formater pour n'importe quel fuseau et éviter les erreurs courantes — avec un aide-mémoire à copier-coller et des liens vers les guides détaillés.
Aide-mémoire des timestamps JavaScript
JavaScript travaille en millisecondes : Date.now() et le constructeur Date utilisent tous deux des millisecondes depuis l'epoch Unix, tandis que la plupart des autres systèmes utilisent des secondes — donc presque chaque tâche de timestamp en JavaScript se résume à se souvenir d'un × 1000 ou d'un ÷ 1000. Le tableau ci-dessous est la référence rapide ; les sections qui suivent expliquent chaque opération, et les guides détaillés couvrent les fuseaux et l'API Temporal en entier.
| Tâche | Code | Résultat |
|---|---|---|
| Heure actuelle (ms) | Date.now() | 1700000000000 |
| Heure actuelle (s) | Math.floor(Date.now() / 1000) | 1700000000 |
| Secondes → Date | new Date(s * 1000) | Objet Date |
| Millisecondes → Date | new Date(ms) | Objet Date |
| Date → ms | date.getTime() | 1700000000000 |
| Date → ISO 8601 | date.toISOString() | 2023-11-15T06:13:20.000Z |
| Chaîne ISO → ms | Date.parse(str) | 1700000000000 |
Obtenir le timestamp Unix actuel
JavaScript offre plusieurs moyens équivalents d'obtenir l'heure actuelle sous forme de timestamp numérique. Tous renvoient le nombre de millisecondes depuis l'epoch Unix.
- Date.now() → le plus rapide et le plus lisible — 1700000000000 (millisecondes)
- Math.floor(Date.now() / 1000) → timestamp Unix en secondes — 1700000000
- +new Date() → identique à Date.now(), avec l'opérateur plus unaire
- new Date().getTime() → appel de méthode explicite, même résultat que Date.now()
Créer un objet Date à partir d'un timestamp Unix
Le constructeur Date accepte des millisecondes depuis l'epoch. Multiplie toujours un timestamp en secondes par 1000 avant de le passer au constructeur.
- new Date(1700000000 * 1000) → à partir de secondes (cas le plus courant)
- new Date(1700000000000) → à partir de millisecondes (API JavaScript, Java)
- new Date(Date.now()) → heure actuelle comme objet Date
- new Date(0) → l'epoch Unix : 1er janvier 1970 00:00:00 UTC
Formater les dates — méthodes de chaîne intégrées
L'objet Date a plusieurs méthodes intégrées de conversion en chaîne. Chacune produit un format différent.
- .toISOString() → '2023-11-15T06:13:20.000Z' — ISO 8601, toujours UTC, lisible par machine
- .toUTCString() → 'Wed, 15 Nov 2023 06:13:20 GMT' — RFC 7231, UTC lisible par l'humain
- .toString() → chaîne en fuseau local avec le nom complet de la zone
- .toLocaleString() → format conscient de la locale, dans le fuseau local de l'utilisateur
Formatage conscient du fuseau
Pour un formatage conscient du fuseau, utilise Intl.DateTimeFormat avec un timeZone explicite — il applique le DST automatiquement et ne nécessite aucune bibliothèque. Les fuseaux sont un sujet profond à eux seuls ; le guide dédié aux fuseaux en JavaScript couvre formatToParts, la détection du fuseau de l'utilisateur et la direction difficile horloge-murale-vers-UTC.
- new Intl.DateTimeFormat('en-US', { timeZone: 'America/New_York', dateStyle: 'full', timeStyle: 'long' }).format(date)
- date.toLocaleString('en-GB', { timeZone: 'Europe/London', hour12: false })
Reconvertir une chaîne de date en timestamp Unix
Pour aller dans la direction inverse — d'une chaîne de date vers un timestamp Unix — utilise Date.parse() ou passe la chaîne au constructeur Date.
- new Date('2023-11-15T06:13:20Z').getTime() / 1000 → secondes Unix depuis ISO 8601 UTC
- new Date('2023-11-15T01:13:20-05:00').getTime() → millisecondes Unix depuis ISO avec décalage
- Date.parse('2023-11-15T06:13:20Z') → identique à new Date(...).getTime()
- Utilise toujours le format ISO 8601 avec fuseau explicite pour un parsing prévisible
Pièges courants
Voici les erreurs les plus fréquentes que font les développeurs JavaScript avec les dates et les timestamps :
- new Date(1700000000) — sans le × 1000, convertit vers l'année ~1970 au lieu de 2023
- getMonth() renvoie 0–11 et non 1–12 — toujours ajouter 1 à l'affichage
- new Date('2024-01-01') est minuit UTC ; new Date('2024/01/01') est minuit local
- new Date(2024, 0, 1) = 1er janvier (le mois est aussi indexé à 0 dans le constructeur)
- Ajouter 86400000 ms pour obtenir 'demain' peut échouer aux frontières du DST — utilise plutôt setDate(d.getDate() + 1)
L'API Temporal — remplaçant moderne de Date
L'API Temporal de TC39 a atteint le Stage 4 et est livrée dans les navigateurs modernes et Node.js. Elle corrige les défauts fondamentaux de Date — elle est immuable, précise à la nanoseconde et consciente des fuseaux — et Temporal.Instant est son type timestamp Unix. L'API livrée convertit les epochs en millisecondes ou nanosecondes (l'ancien fromEpochSeconds a été retiré), donc multiplie les secondes Unix par 1000. Voir le guide Temporal complet pour toute l'API.
- Temporal.Now.instant() — l'instant actuel, avec précision nanoseconde
- Temporal.Instant.fromEpochMilliseconds(Date.now()) — depuis un timestamp JS en millisecondes
- Temporal.Instant.fromEpochMilliseconds(1700000000 * 1000) — depuis des secondes Unix (× 1000)
- Temporal.ZonedDateTime — instant + fuseau IANA, le type que Date aurait dû être
- Livré dans Firefox 139+, Chrome 144+, Node.js 26+ ; Safari en Technology Preview ; polyfill pour le reste
Pour aller plus loin
FAQ
- Comment obtenir un timestamp Unix en secondes en JavaScript ?
- Utilise Math.floor(Date.now() / 1000). Date.now() renvoie des millisecondes, donc divise par 1000 et arrondis vers le bas pour obtenir des secondes Unix entières.
- Comment convertir un timestamp Unix en date lisible en JavaScript ?
- Multiplie les secondes par 1000, passe-les au constructeur Date, puis formate : new Date(1700000000 * 1000).toISOString() donne "2023-11-14T22:13:20.000Z". Pour un fuseau précis, utilise Intl.DateTimeFormat avec une option timeZone.
- Pourquoi new Date() avec un timestamp Unix affiche 1970 ?
- Le constructeur Date attend des millisecondes. Un timestamp en secondes à 10 chiffres doit être multiplié par 1000 : new Date(seconds * 1000).
- Comment formater une date JavaScript pour un fuseau précis ?
- Utilise Intl.DateTimeFormat avec une option timeZone explicite, comme new Intl.DateTimeFormat('en-US', { timeZone: 'America/New_York' }). Il applique l'heure d'été automatiquement et ne nécessite aucune bibliothèque externe.
- Faut-il utiliser Date ou Temporal ?
- Pour du nouveau code où le runtime le prend en charge, préfère Temporal — il est immuable, conscient des fuseaux et évite les pièges de Date. Date reste très bien pour de simples travaux en millisecondes epoch et demeure le plus largement pris en charge.