epochlens 0.1.0

A smart bidirectional timestamp inspector: paste any unix timestamp (s/ms/us/ns auto-detected) or date, see every representation. Zero dependencies.

epochlens

A smart, bidirectional timestamp inspector. Paste any unix timestamp — in seconds, milliseconds, microseconds or nanoseconds, auto-detected — or a date string, and see every representation at once. No flags to remember, no date -r vs date -d @ platform roulette.

pipx run epochlens 1718750000
#   input     1718750000  (unix seconds)
#
#   unix s    1718750000
#   unix ms   1718750000000
#   unix µs   1718750000000000
#   unix ns   1718750000000000000
#   iso utc   2024-06-18T22:33:20Z
#   iso local 2024-06-19T06:33:20+08:00
#   relative  2 minutes ago
#   rfc 2822  Tue, 18 Jun 2024 22:33:20 +0000

Zero dependencies, pure standard library. Also on npm (npx epochlens) — the two builds produce byte-for-byte identical output.

Why

date can do this, but date -r 1718750000 (BSD/macOS) and date -d @1718750000 (GNU/Linux) are different commands, neither auto-detects whether you pasted seconds or milliseconds, and neither shows you all the forms at once. Online epoch converters do, but you have to leave the terminal and paste your data into someone else's website.

epochlens is the one command that just works on every platform, guesses the unit the way you'd expect, and goes both directions:

epochlens 1718750000123          # millis? micros? it figures it out
epochlens 2024-06-18T22:33:20Z   # date string -> every epoch precision
epochlens now                    # the current moment, all forms
echo 1718750000 | epochlens      # reads stdin too

Usage

epochlens <timestamp|date>
epochlens --unit ms 1718750000      # force the unit if the guess is wrong
epochlens --offset +05:30 1718750000  # add a row in a fixed UTC offset
epochlens --json 1718750000          # machine-readable

Auto-detection. A bare number is classified by magnitude: ~10 digits → seconds, ~13 → milliseconds, ~16 → microseconds, ~19 → nanoseconds. The detected unit is always echoed back so you can catch a wrong guess and re-run with --unit. A value with a decimal point is read as seconds.

Accepted input. Unix timestamps (any precision), ISO 8601 (2024-06-18T22:33:20Z, 2024-06-18 22:33:20, 2024-06-18, with or without a Z/±HH:MM offset), and RFC 2822 (Tue, 18 Jun 2024 22:33:20 +0000). A date string without an offset is read as UTC.

--json emits the unix values as strings so nanosecond precision survives a 19-digit integer:

{
  "input": "1718750000123",
  "detected": "unix milliseconds",
  "unix": { "s": "1718750000", "ms": "1718750000123", "us": "1718750000123000", "ns": "1718750000123000000" },
  "iso_utc": "2024-06-18T22:33:20.123Z",
  "iso_local": "2024-06-19T06:33:20.123+08:00",
  "iso_offset": null,
  "relative": "2 minutes ago",
  "rfc2822": "Tue, 18 Jun 2024 22:33:20 +0000"
}

Exit codes: 0 ok · 2 error (unparseable input, out-of-range date).

How it works

Date/time handling is a minefield of cross-platform and cross-language disagreements, so epochlens does none of its conversion through the runtime's date library. datetime.fromisoformat, isoformat, strftime (and Node's Date.parse/toISOString) all differ between (and within) the two runtimes. Instead every conversion is plain integer arithmetic over a proleptic-Gregorian civil-day algorithm, and all formatting is hand-rolled. That's what lets the Node and Python builds stay byte-identical, and it's why nanosecond values stay exact (native ints in Python, BigInt in Node).

Scope

The MVP shows UTC, your machine's local time, and any fixed --offset. Named IANA zones (--tz America/New_York) are intentionally left out for now: Python's zoneinfo needs an OS tz database that Windows lacks, which would break the zero-dependency promise. Natural-language input ("3 days ago") is also out of scope — relative time is shown as output only.

Install

pip install epochlens   # or pipx run epochlens
npm i -g epochlens      # Node build, identical behaviour

Python ≥ 3.8 or Node ≥ 18. No dependencies.

License

MIT