Trabajar con timestamps Unix en JavaScript
Todo lo que necesitas para trabajar con timestamps Unix en JavaScript — obtener la hora actual, crear Date a partir de timestamps, formatear para cualquier zona horaria y evitar errores comunes — con una chuleta para copiar y pegar y enlaces a las guías a fondo.
Chuleta de timestamps en JavaScript
JavaScript trabaja en milisegundos: Date.now() y el constructor Date usan ambos milisegundos desde el epoch Unix, mientras que la mayoría de los demás sistemas usan segundos — así que casi toda tarea de timestamp en JavaScript se reduce a recordar un × 1000 o un ÷ 1000. La tabla siguiente es la referencia rápida; las secciones posteriores explican cada operación, y las guías a fondo cubren las zonas horarias y la API Temporal por completo.
| Tarea | Código | Resultado |
|---|---|---|
| Hora actual (ms) | Date.now() | 1700000000000 |
| Hora actual (s) | Math.floor(Date.now() / 1000) | 1700000000 |
| Segundos → Date | new Date(s * 1000) | Objeto Date |
| Milisegundos → Date | new Date(ms) | Objeto Date |
| Date → ms | date.getTime() | 1700000000000 |
| Date → ISO 8601 | date.toISOString() | 2023-11-15T06:13:20.000Z |
| Cadena ISO → ms | Date.parse(str) | 1700000000000 |
Obtener el timestamp Unix actual
JavaScript ofrece varias formas equivalentes de obtener la hora actual como timestamp numérico. Todas devuelven el número de milisegundos desde el epoch Unix.
- Date.now() → el más rápido y legible — 1700000000000 (milisegundos)
- Math.floor(Date.now() / 1000) → timestamp Unix en segundos — 1700000000
- +new Date() → igual que Date.now(), con el operador más unario
- new Date().getTime() → llamada a método explícita, mismo resultado que Date.now()
Crear un objeto Date a partir de un timestamp Unix
El constructor Date acepta milisegundos desde el epoch. Multiplica siempre un timestamp basado en segundos por 1000 antes de pasarlo al constructor.
- new Date(1700000000 * 1000) → desde segundos (el caso más común)
- new Date(1700000000000) → desde milisegundos (API de JavaScript, Java)
- new Date(Date.now()) → hora actual como objeto Date
- new Date(0) → el epoch Unix: 1 de enero de 1970 00:00:00 UTC
Formatear fechas — métodos de cadena integrados
El objeto Date tiene varios métodos integrados de conversión a cadena. Cada uno produce un formato distinto.
- .toISOString() → '2023-11-15T06:13:20.000Z' — ISO 8601, siempre UTC, legible por máquina
- .toUTCString() → 'Wed, 15 Nov 2023 06:13:20 GMT' — RFC 7231, UTC legible por humanos
- .toString() → cadena en zona local con el nombre completo de la zona
- .toLocaleString() → formato consciente de la configuración regional, en la zona local del usuario
Formateo consciente de la zona horaria
Para formateo consciente de la zona, usa Intl.DateTimeFormat con un timeZone explícito — aplica el DST automáticamente y no necesita biblioteca. Las zonas horarias son un tema profundo por sí solas; la guía dedicada de zonas en JavaScript cubre formatToParts, detectar la zona del usuario y la difícil dirección reloj-de-pared-a-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 una cadena de fecha en un timestamp Unix
Para ir en la dirección opuesta — de una cadena de fecha a un timestamp Unix — usa Date.parse() o pasa la cadena al constructor Date.
- new Date('2023-11-15T06:13:20Z').getTime() / 1000 → segundos Unix desde ISO 8601 UTC
- new Date('2023-11-15T01:13:20-05:00').getTime() → milisegundos Unix desde ISO con desfase
- Date.parse('2023-11-15T06:13:20Z') → igual que new Date(...).getTime()
- Usa siempre el formato ISO 8601 con zona explícita para un parsing predecible
Trampas comunes
Estos son los errores más frecuentes que cometen los desarrolladores de JavaScript con fechas y timestamps:
- new Date(1700000000) — sin el × 1000 convierte al año ~1970 en lugar de 2023
- getMonth() devuelve 0–11, no 1–12 — suma siempre 1 al mostrar
- new Date('2024-01-01') es medianoche UTC; new Date('2024/01/01') es medianoche local
- new Date(2024, 0, 1) = 1 de enero (el mes también está indexado desde 0 en el constructor)
- Sumar 86400000 ms para obtener 'mañana' puede fallar en las fronteras del DST — usa mejor setDate(d.getDate() + 1)
La API Temporal — reemplazo moderno de Date
La API Temporal de TC39 alcanzó el Stage 4 y se incluye en navegadores modernos y Node.js. Corrige los defectos centrales de Date — es inmutable, precisa al nanosegundo y consciente de zonas — y Temporal.Instant es su tipo timestamp Unix. La API publicada convierte epochs en milisegundos o nanosegundos (el antiguo fromEpochSeconds se eliminó), así que multiplica los segundos Unix por 1000. Consulta la guía completa de Temporal para toda la API.
- Temporal.Now.instant() — el instante actual, con precisión de nanosegundos
- Temporal.Instant.fromEpochMilliseconds(Date.now()) — desde un timestamp JS en milisegundos
- Temporal.Instant.fromEpochMilliseconds(1700000000 * 1000) — desde segundos Unix (× 1000)
- Temporal.ZonedDateTime — instante + zona IANA, el tipo que Date debería haber sido
- Incluido en Firefox 139+, Chrome 144+, Node.js 26+; Safari en Technology Preview; polyfill para el resto
Para ir más allá
FAQ
- ¿Cómo obtengo un timestamp Unix en segundos en JavaScript?
- Usa Math.floor(Date.now() / 1000). Date.now() devuelve milisegundos, así que divide por 1000 y redondea hacia abajo para obtener segundos Unix enteros.
- ¿Cómo convierto un timestamp Unix en una fecha legible en JavaScript?
- Multiplica los segundos por 1000, pásalos al constructor Date y luego formatea: new Date(1700000000 * 1000).toISOString() da "2023-11-14T22:13:20.000Z". Para una zona concreta, usa Intl.DateTimeFormat con una opción timeZone.
- ¿Por qué new Date() con un timestamp Unix muestra 1970?
- El constructor Date espera milisegundos. Un timestamp en segundos de 10 dígitos debe multiplicarse por 1000: new Date(seconds * 1000).
- ¿Cómo formateo una fecha de JavaScript para una zona horaria concreta?
- Usa Intl.DateTimeFormat con una opción timeZone explícita, como new Intl.DateTimeFormat('en-US', { timeZone: 'America/New_York' }). Aplica el horario de verano automáticamente y no necesita ninguna biblioteca externa.
- ¿Debo usar Date o Temporal?
- Para código nuevo donde el runtime lo admita, prefiere Temporal — es inmutable, consciente de zonas y evita las trampas de Date. Date sigue siendo válido para trabajos sencillos en milisegundos epoch y aún es el más ampliamente soportado.