{
  "path": "/projects/tid",
  "site": "at://did:plc:ofrbh253gwicbkc5nktqepol/site.standard.publication/3mfyq5mpohw25",
  "tags": [
    "atproto",
    "music",
    "pkgs",
    "tooling",
    "typescript"
  ],
  "$type": "site.standard.document",
  "title": "@ewanc26/tid",
  "description": "Zero-dependency, spec-compliant AT Protocol TID generation for Node.js and browsers.",
  "publishedAt": "2026-03-04T00:00:00.000Z",
  "textContent": "@ewanc26/tid is a tiny TypeScript library for generating, validating, decoding, and comparing AT Protocol TIDs (Timestamp Identifiers). It has no runtime dependencies, ships with type definitions, and works in Node.js 20+, Deno, Bun, and modern browsers via the Web Crypto API.\n\nPart of the @ewanc26/pkgs monorepo.\n\nTIDs are 13-character, lexicographically sortable record keys used across the AT Protocol and Bluesky. They encode a microsecond-precision Unix timestamp and a 5-bit clock ID. Within a JS context, the library guarantees monotonicity — if records arrive out of order, the clock is bumped forward so every generated TID is strictly increasing.\n\nInstall\n\nUsage\n\nGenerate a TID\n\nValidate\n\nDecode\n\nSort\n\nCommonJS\n\nAPI\n\n| Export | Signature | Description |\n|---|---|---|\n| generateTID | (source: string \\| Date) => string | Generate a TID for a historical timestamp |\n| generateNextTID | () => string | Generate a TID for the current wall-clock time |\n| validateTid | (tid: string) => boolean | Returns true if the string is a well-formed TID |\n| decodeTid | (tid: string) => DecodedTid | Decode a TID into its timestamp, clockId, and Date |\n| compareTids | (a: string, b: string) => -1 \\| 0 \\| 1 | Lexicographic comparator for sorting |\n| resetTidClock | () => void | Reset the monotonic clock (tests only) |\n\nDecodedTid\n\nSpec notes\n\n- TIDs use a custom AT Protocol base-32 alphabet: 234567abcdefghijklmnopqrstuvwxyz.\n- The first 11 characters encode a microsecond-precision Unix timestamp; the last 2 encode a 5-bit clock ID (0–31).\n- The clock ID is randomised once at module load (per JS context). When multiple TIDs would land on the same microsecond the implementation nudges the timestamp forward rather than the clock ID, preserving lexicographic monotonicity.\n- Full specification: atproto.com/specs/tid.\n\nBehavioural notes\n\n- Monotonicity is per-JS-context only. Records generated in different processes or machines may collide within the same microsecond, which is why the 5-bit clock ID exists.\n- The package does not coordinate across processes. If you need globally unique sequencing beyond the spec, combine TIDs with a per-host identifier or use a server-side sequencer.\n\nLicence\n\nAGPL-3.0-only — see the pkgs monorepo.",
  "canonicalUrl": "https://docs.ewancroft.uk/projects/tid"
}