From dc3f9e5dfe0da33eb10712d356f6f18c2614b4cd Mon Sep 17 00:00:00 2001 From: Charlie Tonneslan Date: Sun, 17 May 2026 09:13:19 -0400 Subject: [PATCH] docs(NewWithTime): note 4-byte timestamp can't hold post-2106 times The xid format reserves 4 bytes for the timestamp, so any time whose Unix seconds don't fit in a uint32 (anything before 1970 or after 2106-02-07 06:28:15 UTC) silently wraps when encoded. The current NewWithTime godoc doesn't mention this, so callers who feed in arbitrary user-supplied times can quietly end up with IDs whose Time() returns nonsense. Document the bounds so callers know to clamp/reject themselves. For #107 Signed-off-by: Charlie Tonneslan --- id.go | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/id.go b/id.go index a659282..ca5e60b 100644 --- a/id.go +++ b/id.go @@ -164,7 +164,13 @@ func New() ID { return NewWithTime(time.Now()) } -// NewWithTime generates a globally unique ID with the passed in time +// NewWithTime generates a globally unique ID with the passed in time. +// +// The XID format stores the timestamp in 4 bytes, so it can only represent +// times whose Unix seconds fit in a uint32. Times before 1970-01-01 or +// after 2106-02-07 06:28:15 UTC silently wrap when encoded; callers +// generating IDs from arbitrary user-supplied times should clamp or +// reject those values themselves. func NewWithTime(t time.Time) ID { var id ID // Timestamp, 4 bytes, big endian