Exosphere.ATProto.TID (Exosphere v0.3.0)

Copy Markdown View Source

Timestamp ID (TID) generation for Exosphere.ATProto records.

TIDs are used as record keys in Exosphere.ATProto repositories. They are:

  • Lexicographically sortable
  • Collision-resistant (timestamp + random component)
  • Base32-sortable encoded (13 characters)

Format

A TID is a 64-bit value encoded as base32-sortable:

  • Bits 63-10: Microseconds since Unix epoch (54 bits)
  • Bits 9-0: Clock identifier (10 bits, random per process)

Examples

iex> Exosphere.ATProto.TID.generate()
"3jui7kd2lry2e"

iex> Exosphere.ATProto.TID.to_datetime("3jui7kd2lry2e")
{:ok, ~U[2024-01-15 12:30:45.123456Z]}

Summary

Functions

compare(tid1, tid2)

Compare two TIDs chronologically.

generate()

Generate a new TID.

generate_for(dt)

Generate a TID for a specific datetime.

to_datetime(tid)

Parse a TID and extract its timestamp.

valid?(tid)

Validate a TID string against the spec syntax.

Functions

compare(tid1, tid2)

@spec compare(String.t(), String.t()) :: :lt | :eq | :gt

Compare two TIDs chronologically.

Returns :lt, :eq, or :gt.

generate()

@spec generate() :: String.t()

Generate a new TID.

Examples

iex> tid = Exosphere.ATProto.TID.generate()
iex> String.length(tid)
13

generate_for(dt)

@spec generate_for(DateTime.t()) :: String.t()

Generate a TID for a specific datetime.

Useful for testing or creating TIDs for past events.

to_datetime(tid)

@spec to_datetime(String.t()) :: {:ok, DateTime.t()} | {:error, :invalid_tid}

Parse a TID and extract its timestamp.

Examples

iex> {:ok, dt} = Exosphere.ATProto.TID.to_datetime("3jui7kd2lry2e")
iex> dt.year
2024

valid?(tid)

@spec valid?(String.t()) :: boolean()

Validate a TID string against the spec syntax.

Enforces the reference regex /^[234567abcdefghij][234567abcdefghijklmnopqrstuvwxyz]{12}$/: exactly 13 base32-sortable characters with a restricted leading character.