fix: allow TypeID to work with other UUID versions.

Author: akhundMurad

tests/explain/test_engine.py

@@ -177,3 +177,11 @@ def test_to_dict_is_json_serializable():
 
     payload = exp.to_dict()
     json.dumps(payload)  # should not raise
+
+
+def test_explain_nil_uuid_not_sortable_no_created_at():
+    exp = explain("x_00000000000000000000000000", enable_schema=False)
+    assert exp.valid is True
+    assert exp.parsed.uuid == "00000000-0000-0000-0000-000000000000"
+    assert exp.parsed.created_at is None
+    assert exp.parsed.sortable is False

tests/test_spec.py

@@ -18,3 +18,4 @@ def test_valid_spec(valid_spec: list) -> None:
 
         typeid = TypeID.from_uuid(prefix=prefix, suffix=uuid)
         assert str(typeid) == spec["typeid"]
+        assert typeid.uuid == uuid

tests/test_typeid.py

@@ -1,3 +1,5 @@
+from datetime import datetime, timezone
+from uuid import UUID
 import pytest
 import uuid6
 
@@ -142,3 +144,61 @@ def test_uuid_property() -> None:
     assert isinstance(typeid.uuid, uuid6.UUID)
     assert typeid.uuid.version == uuid.version == 7
     assert typeid.uuid.time == uuid.time
+
+
+def test_created_at_none_for_nil_uuid_suffix():
+    tid = TypeID(prefix="x", suffix="00000000000000000000000000")
+    assert tid.created_at is None
+
+
+def test_created_at_none_for_non_v7_uuid_v4():
+    # UUIDv4 (random) must not claim created_at
+    u = UUID("550e8400-e29b-41d4-a716-446655440000")  # version 4
+    tid = TypeID.from_uuid(u, prefix="x")
+    assert tid.created_at is None
+
+
+def test_created_at_is_utc_for_uuid7_generated_typeid():
+    # Default TypeID generation should be UUIDv7; then created_at must be present and UTC
+    tid = TypeID(prefix="x")
+    dt = tid.created_at
+    assert dt is not None
+    _assert_utc_datetime(dt)
+
+
+def test_created_at_monotonic_increasing_for_multiple_new_ids():
+    # UUIDv7 embeds time; created_at should be non-decreasing across consecutive generations.
+    # Note: UUIDv7 can generate multiple IDs within the same millisecond, so equality is allowed.
+    t1 = TypeID(prefix="x").created_at
+    t2 = TypeID(prefix="x").created_at
+    t3 = TypeID(prefix="x").created_at
+
+    assert t1 is not None and t2 is not None and t3 is not None
+    assert t1 <= t2 <= t3
+
+
+def test_created_at_does_not_crash_if_uuid_object_is_unexpected(monkeypatch):
+    # If TypeID.uuid returns something odd that breaks version/int access,
+    # created_at should return None (safe behavior).
+    class WeirdUUID:
+        @property
+        def version(self):
+            raise RuntimeError("nope")
+
+        @property
+        def int(self):
+            raise RuntimeError("nope")
+
+    tid = TypeID(prefix="x", suffix="00000000000000000000000000")
+
+    # monkeypatch instance attribute/property access
+    monkeypatch.setattr(type(tid), "uuid", property(lambda self: WeirdUUID()))
+
+    assert tid.created_at is None
+
+
+def _assert_utc_datetime(dt: datetime) -> None:
+    assert isinstance(dt, datetime)
+    assert dt.tzinfo is timezone.utc
+    # must be timezone-aware and normalized to UTC
+    assert dt.utcoffset() == timezone.utc.utcoffset(dt)

typeid/explain/engine.py

@@ -130,9 +130,11 @@ def _parse_typeid(id_str: str) -> ParsedTypeID:
     # Derived facts from the validated TypeID
     uuid_obj = tid.uuid  # library returns a UUID object (uuid6.UUID)
     uuid_str = str(uuid_obj)
+    
+    ver = _uuid_version(uuid_obj)
 
-    created_at = _uuid7_created_at(uuid_obj)
-    sortable = True  # UUIDv7 is time-ordered by design
+    created_at = _uuid7_created_at(uuid_obj) if ver == 7 else None
+    sortable = True if ver == 7 else False
 
     return ParsedTypeID(
         raw=id_str,
@@ -245,3 +247,11 @@ def _apply_derived_provenance(exp: Explanation) -> None:
         exp.provenance.setdefault("created_at", Provenance.DERIVED_FROM_ID)
     if exp.parsed.sortable is not None:
         exp.provenance.setdefault("sortable", Provenance.DERIVED_FROM_ID)
+
+
+def _uuid_version(u: Any) -> Optional[int]:
+    try:
+        # uuid.UUID and uuid6.UUID both usually expose .version
+        return int(u.version)
+    except Exception:
+        return None

typeid/typeid.py

@@ -1,3 +1,4 @@
+from datetime import datetime, timezone
 import uuid
 import warnings
 from typing import Generic, Optional, TypeVar
@@ -144,6 +145,35 @@ def uuid(self) -> uuid6.UUID:
             - The UUID type here follows `uuid6.UUID` used by the project.
         """
         return _convert_b32_to_uuid(self.suffix)
+    
+    @property
+    def created_at(self) -> Optional[datetime]:
+        """
+        Creation time embedded in the underlying UUID, if available.
+
+        TypeID typically uses UUIDv7 for generated IDs. UUIDv7 encodes the Unix
+        timestamp (milliseconds) in the most significant 48 bits of the 128-bit UUID.
+
+        Returns:
+            A timezone-aware UTC datetime if the underlying UUID is version 7,
+            otherwise None.
+        """
+        u = self.uuid  # must be LOSSLESS: constructed as UUID(bytes=decoded_bytes)
+
+        # Only UUIDv7 has a defined "created_at" in this sense.
+        try:
+            if getattr(u, "version", None) != 7:
+                return None
+        except Exception:
+            return None
+
+        try:
+            # UUID is 128 bits; top 48 bits are unix epoch time in milliseconds.
+            # So: unix_ms = uuid_int >> (128 - 48) = uuid_int >> 80
+            unix_ms = int(u.int) >> 80
+            return datetime.fromtimestamp(unix_ms / 1000.0, tz=timezone.utc)
+        except Exception:
+            return None
 
     def __str__(self) -> str:
         """
@@ -243,4 +273,4 @@ def _convert_uuid_to_b32(uuid_instance: uuid.UUID) -> str:
 def _convert_b32_to_uuid(b32: str) -> uuid6.UUID:
     uuid_bytes = bytes(base32.decode(b32))
     uuid_int = int.from_bytes(uuid_bytes, byteorder="big")
-    return uuid6.UUID(int=uuid_int, version=7)
+    return uuid6.UUID(int=uuid_int)