Pourquoi il existe deux standards
Le temps Unix a d'abord été défini en secondes : un entier semblait naturel pour un système qui s'incrémentait à chaque tic d'horloge. L'objet Date de JavaScript, introduit en 1995, a choisi les millisecondes pour gérer la temporisation d'événements sous la seconde dans le navigateur. Beaucoup de bases et de langages backend ont gardé les secondes Unix par défaut. Aujourd'hui, les deux standards coexistent dans tout code qui franchit la frontière JavaScript-serveur, d'où le fait qu'une valeur peut sembler valide tout en représentant une date à des dizaines de milliers d'années.
Quelle unité chaque langage utilise
La façon la plus sûre de retenir le partage : les API Date du navigateur veulent en général des millisecondes, les API serveur de style Unix exposent en général des secondes, et les bibliothèques de temps récentes proposent souvent les deux. Ne déduisez pas l'unité du seul langage en lisant la doc d'une API tierce ; vérifiez la description du champ et les exemples.
- Milliseconds: JavaScript Date.now(), Java System.currentTimeMillis(), Java Instant.toEpochMilli(), .NET ToUnixTimeMilliseconds()
- Seconds: Python time.time() (float), PHP time(), Go time.Now().Unix(), Ruby Time.now.to_i, C time(NULL), PostgreSQL EXTRACT(EPOCH)
- Both: Rust — duration.as_secs() for seconds, duration.as_millis() for milliseconds
- Python note: time.time() returns a float, so milliseconds are available as int(time.time() * 1000)
Détecter l'unité à partir de la valeur
Une heuristique fiable pour les dates modernes : un nombre à 10 chiffres correspond à des secondes ; à 13 chiffres, à des millisecondes. Les secondes Unix actuelles sont autour de 1,7–2,1 milliards (10 chiffres) et n'atteindront pas 13 chiffres avant l'an 33658. Les millisecondes Unix actuelles ont déjà 13 chiffres. L'heuristique est la plus fiable des années 2000 aux quelques milliers d'années à venir ; pour les dates historiques, négatives ou les fixtures de test compactes, utilisez des unités explicites plutôt que de deviner.
- valeur à 10 chiffres → secondes (ex. 1700000000 = 2023-11-14 UTC)
- valeur à 13 chiffres → millisecondes (ex. 1700000000000 = 2023-11-14 UTC)
- valeur à 16 chiffres → microsecondes (diviser par 1,000,000 pour des secondes)
- valeur négative → date avant le 1er janvier 1970 (secondes ou millisecondes)
Modèles de conversion sûrs
La conversion elle-même est une arithmétique simple ; le difficile est de choisir où elle doit se faire. Convertissez à la frontière du système, nommez la valeur convertie et évitez de faire passer des nombres bruts ambigus à travers plusieurs couches.
- Seconds to milliseconds: seconds * 1000
- Milliseconds to whole seconds — JavaScript: Math.floor(ms / 1000)
- Milliseconds to whole seconds — Python: ms // 1000
- Milliseconds to whole seconds — Go: ms / 1000 (integer division)
- Universal guard in JavaScript: const toMs = ts => ts < 1e11 ? ts * 1000 : ts
Comment les bugs d'unité apparaissent en production
Un bug secondes-vs-millisecondes survit souvent à la validation car les deux valeurs ne sont que des nombres. Il apparaît plus tard comme une date impossible : janvier 1970 en JavaScript quand des secondes ont été traitées comme des millisecondes, ou une année très lointaine quand un backend a traité des millisecondes comme des secondes.
- Date de 1970 dans l'UI JavaScript → des secondes ont été passées à new Date() sans multiplier par 1000
- Année 50000+ en Python, Go ou PHP → des millisecondes ont été passées à une API attendant des secondes
- Jetons expirés qui n'expirent jamais → timestamp d'expiration stocké dans la mauvaise unité
- Entrées de cache qui disparaissent aussitôt → millisecondes divisées deux fois ou secondes multipliées deux fois
- Graphiques analytics aux plages vides → les bornes de requête utilisent une unité différente des timestamps d'événements stockés
Conventions de nommage pour les API et les bases
Une petite convention de nommage évite la plupart de ces bugs. Ne publiez jamais un champ d'API nommé timestamp à moins que la doc ne soit exceptionnellement claire. Préférez des noms de champ qui incluent le sens et l'unité.
- createdAtMs — Unix milliseconds, best for JavaScript clients
- createdAtSeconds — Unix seconds, common for backend services
- createdAtIso — ISO 8601 string, useful for human-readable API responses
- expiresAtUnixSeconds — explicit enough for auth tokens and signed URLs
- event_time TIMESTAMPTZ — native database time, with conversion handled by the database
FAQ millisecondes vs secondes
A tiny naming convention prevents most of these bugs. Never publish an API field called timestamp unless the documentation is unusually clear. Prefer field names that include both meaning and unit.
- createdAtMs — Unix milliseconds, best for JavaScript clients
- createdAtSeconds — Unix seconds, common for backend services
- createdAtIso — ISO 8601 string, useful for human-readable API responses
- expiresAtUnixSeconds — explicit enough for auth tokens and signed URLs
- event_time TIMESTAMPTZ — native database time, with conversion handled by the database
Microseconds (16 digits) and nanoseconds (19 digits)
Most production timestamps are seconds (10 digits) or milliseconds (13 digits), but two higher-precision formats also appear in real systems — microseconds and nanoseconds. The same digit-counting rule extends.
- 10 digits ≈ Unix seconds (~1.7×10⁹ today)
- 13 digits ≈ Unix milliseconds (~1.7×10¹²)
- 16 digits ≈ Unix microseconds (~1.7×10¹⁵) — Python time.time_ns()/1000, Postgres TIMESTAMP precision 6
- 19 digits ≈ Unix nanoseconds (~1.7×10¹⁸) — Java Instant.toEpochNano(), Go time.UnixNano(), Temporal.Instant.epochNanoseconds
- PostgreSQL to_timestamp() takes seconds with an optional fractional part; passing milliseconds yields a date around the year 55000
- Convert from any precision to milliseconds via integer arithmetic before doing further math
- Silent truncation: if a database column has millisecond precision but you store nanoseconds, the bottom 6 digits are dropped on insert
How many microseconds in a second? 1 second to milliseconds, microseconds to milliseconds
A quick reference for the unit math that drives every seconds/milliseconds/microseconds bug. The questions "how many microseconds in a second", "1 second to milliseconds", and "microseconds to milliseconds" are all powers of 1000 — but every order of magnitude is one place where production code goes wrong. Keep the table below within reach when writing high-resolution timestamp code.
- 1 second to milliseconds = 1,000 ms (10³)
- How many microseconds in a second? = 1,000,000 µs (10⁶)
- 1 second to nanoseconds = 1,000,000,000 ns (10⁹)
- Microseconds to milliseconds = µs ÷ 1,000 (10³ step down)
- Milliseconds to microseconds = ms × 1,000
- Nanoseconds to microseconds = ns ÷ 1,000
- Common precision: JavaScript Date.now() = ms, performance.now() = sub-ms float, Go time.UnixNano() = ns, Postgres TIMESTAMP precision 6 = µs
- Bug pattern: an API returns µs, code divides by 1000 once expecting seconds — actually got ms; result is 1000× off
Millisecond timer, time to ms, milliseconds to seconds conversion
Quick reference for the unit phrasings: "time to ms" (any time value scaled into milliseconds), "milliseconds to seconds conversion" (÷1000), and "millisecond timer" (a high-resolution timer for short intervals). For measuring elapsed time prefer a monotonic clock — wall-clock time can jump backwards on NTP correction or DST.
- Time to ms / time to milliseconds: seconds × 1000 = ms; microseconds ÷ 1000 = ms; nanoseconds ÷ 1,000,000 = ms
- Milliseconds to seconds conversion: ms ÷ 1000 = seconds; Math.floor(ms/1000) for integer seconds
- Millisecond timer (JavaScript): performance.now() returns sub-ms float since page load; Date.now() returns wall-clock ms
- Millisecond timer (Python): time.perf_counter() (monotonic float seconds); time.monotonic_ns() returns ns
- Millisecond timer (Java): System.nanoTime() for monotonic ns; Instant.now() for wall-clock ns precision
- Stopwatch rule: use monotonic clocks for elapsed time; wall-clock can jump backwards on NTP or DST
FAQ
- Is a 13-digit timestamp always milliseconds?
- For modern real-world Unix timestamps, yes: 13 digits usually means milliseconds. Very far-future seconds timestamps can also reach 13 digits, so critical systems should still carry explicit unit metadata.
- Should I store seconds or milliseconds?
- Store the unit your system naturally uses, but document it and keep it consistent. JavaScript-heavy systems often use milliseconds; Unix-style backends and many databases commonly use seconds or native datetime columns.
- Why use Math.floor(ms / 1000) instead of ms / 1000?
- Unix seconds are usually whole seconds. Math.floor removes the fractional part so APIs expecting integer seconds do not receive a decimal value.
- How do I convert milliseconds to seconds?
- Divide by 1000 and drop the fraction: Math.floor(ms / 1000) in JavaScript, ms // 1000 in Python, or ms / 1000 with integer division in Go. To go the other way, multiply seconds by 1000.