A Unix timestamp in microseconds counts the number of microseconds (one-millionth of a second) since the epoch 1970-01-01T00:00:00Z. Microsecond resolution appears in databases such as PostgreSQL timestamptz, in tracing systems, and in scientific data. Because these values can be larger than JavaScript can represent exactly with a normal number, this converter uses BigInt to keep every digit correct.
How it works
The tool parses the microsecond value as a BigInt, then splits it into whole milliseconds and a remaining microsecond fraction:
const us = BigInt(input);
const ms = us / 1000n; // whole milliseconds
const remUs = us % 1000n; // leftover microseconds (0..999)
const date = new Date(Number(ms));
The Date gives the calendar date-time down to the millisecond, and the leftover remUs is appended to the fractional-seconds part of the ISO-8601 output so no precision is lost. To encode, the tool parses the date to milliseconds and multiplies by 1000n.
A present-day microsecond timestamp is about 16 digits, for example 1700000000000000. If your value has ~13 digits it is in milliseconds; ~10 digits means seconds.
Tips and notes
- BigInt is used so timestamps past
Number.MAX_SAFE_INTEGER(about 9 quadrillion) stay exact. - Date-time parsing only resolves to millisecond precision, so encoding a string yields a microsecond value ending in three zeros unless the string itself carries microsecond digits.
- Always store the canonical UTC form; local time is for display only.