[anurag2787]

What and why

Added a guide on converting Unix timestamps to dates, with examples and common mistakes to avoid

Closes #275

How I tested this

Ran npm run lint, npm run test and npm run build

AI assistance

ChatGPT was used to help with the implementation and tests

Type of change

• Bug fix
• New tool or feature
• Tests
• Refactor or cleanup
• Docs

Checklist

• I was assigned the linked issue
• [s] npm run lint && npm run test && npm run build passes locally
• Logic changes live in lib/ and have a test in lib/__tests__/
• For a bug fix: the new test fails without my change
• No analytics, trackers, or calls that send user data off-device
• Works in both light and dark themes (if UI changed)
• Inputs have labels and it works with the keyboard alone (if UI changed)
• New tool: registry entry, page.tsx, client component, opengraph-image.tsx, and the bug report dropdown are all done

[anurag2787]

Hi @anurag629 could you please review and let me know if other changes required
Thanks!

[anurag629]

Thanks @anurag2787, this reads well and the structure is right. Lint (develop's 11 warnings), all 2331 tests, the build and the pages pass on top of develop, and everything it says about the converter checks out against the code: the four units and their thresholds (16 and 19 digits really are detected as micro and nanoseconds), negative input, the "Interpreted as" line, "3 days ago" and the copyable ISO field. A few technical points need fixing first:

1. The FAQ uses datetime.utcfromtimestamp(seconds).isoformat() + 'Z'. That's deprecated since Python 3.12, and the docs say to use datetime.fromtimestamp() with UTC instead, which is what your Python section already does. Use datetime.fromtimestamp(seconds, tz=timezone.utc).isoformat() in the FAQ too (it prints +00:00, not Z).
2. "Python's datetime supports negative values correctly" (in "Timestamps before 1970" and the FAQ) isn't safe to say. Python's docs say fromtimestamp() may raise OverflowError or OSError outside what the platform's C library handles, and "It's common for this to be restricted to years in 1970 through 2038." datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=-86400) works everywhere, so show that for negative values.
3. "Most modern software, including JavaScript and Python, stores timestamps as 64-bit integers" isn't right for either. A JavaScript Date is a 64-bit float of milliseconds, good for ±8.64e15 ms (up to the year 275760), and Python's ints have no fixed size, so neither has the 2038 problem.
4. "migrate to BIGINT or a native timestamp type": in MySQL the native TIMESTAMP type stops at '2038-01-19 03:14:07' UTC too. Say BIGINT or DATETIME (which goes to 9999) for MySQL.
5. The intro's "multiply by 1000 ... pass it to your language's date constructor" and "take the UTC milliseconds of the date and divide by 1000" are JavaScript only. Python's fromtimestamp() takes seconds as they are, so say it's for JavaScript.

Smaller wording ones: Unix time doesn't count leap seconds (every day is exactly 86,400 of them), so "seconds elapsed since" is better as "seconds since 1970-01-01 00:00:00 UTC, not counting leap seconds". The converter shows UTC above the local time, not side by side. Step 5's "overflows at 2,147,483,647" reads better as "tops out at", since the overflow comes one second later, the way your page section puts it. And if this merges after today, bump publishedAt to that day.

[anurag2787]

Hi @anurag629 i have updated PR could you please re review and let me know if any other changes required
Thanks!

[anurag629]

Thanks @anurag2787, all of it is in and it checks out: the Python and JavaScript notes, the timedelta example, the float and year 275,760 bit, MySQL TIMESTAMP and DATETIME, "tops out at", and UTC above local time. Lint, all 2361 tests, the build and the pages pass on top of develop.

One tiny thing left, in the very first sentence: it now reads "seconds since 1970-01-01 00:00:00 UTC, not counting leap seconds — the Unix epoch", so "the Unix epoch" ends up describing the leap seconds. Put it next to the date: "seconds since 1970-01-01 00:00:00 UTC (the Unix epoch), not counting leap seconds". And bump publishedAt if it merges on a later day.

[anurag2787]

Hi @anurag629 i have updated PR as you said
Thanks!

[anurag629]

Thanks @anurag2787, that's it. Lint (develop's 11 warnings), all 2361 tests, the build and the pages pass on top of develop, and the first sentence reads right now. Every technical point in it checks out against the docs, nice work.