{"id":29562240,"url":"https://github.com/edjcase/motoko_tid","last_synced_at":"2026-02-13T03:15:17.015Z","repository":{"id":302536011,"uuid":"1012764438","full_name":"edjCase/motoko_tid","owner":"edjCase","description":"A Motoko library for handling TIDs (Time Identifiers) for atproto","archived":false,"fork":false,"pushed_at":"2025-07-02T22:50:12.000Z","size":6,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-02T23:27:29.141Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Motoko","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edjCase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-02T21:04:27.000Z","updated_at":"2025-07-02T22:50:15.000Z","dependencies_parsed_at":"2025-07-02T23:37:54.894Z","dependency_job_id":null,"html_url":"https://github.com/edjCase/motoko_tid","commit_stats":null,"previous_names":["edjcase/motoko_tid"],"tags_count":0,"template":false,"template_full_name":"edjCase/motoko-library-template","purl":"pkg:github/edjCase/motoko_tid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edjCase%2Fmotoko_tid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edjCase%2Fmotoko_tid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edjCase%2Fmotoko_tid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edjCase%2Fmotoko_tid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edjCase","download_url":"https://codeload.github.com/edjCase/motoko_tid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edjCase%2Fmotoko_tid/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265799117,"owners_count":23830057,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-18T17:11:05.465Z","updated_at":"2026-02-13T03:15:16.977Z","avatar_url":"https://github.com/edjCase.png","language":"Motoko","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Motoko TID Library\n\n[![MOPS](https://img.shields.io/badge/MOPS-tid-blue)](https://mops.one/tid)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/edjcase/motoko_tid/blob/main/LICENSE)\n\nA Motoko library for working with Time Identifiers (TIDs) - compact, sortable identifiers based on timestamps with microsecond precision and clock identifiers. TIDs are designed to be lexicographically sortable and maintain chronological ordering.\n\n## Package\n\n### MOPS\n\n```bash\nmops add tid\n```\n\nTo set up MOPS package manager, follow the instructions from the [MOPS Site](https://mops.one)\n\n## Quick Start\n\n### Import\n\n```motoko\nimport TID \"mo:tid\"\n```\n\n### Example 1: Creating and Converting TIDs\n\n```motoko\n// Create a TID manually\nlet tid : TID.TID = {\n  timestamp = 1640995200000000; // Microseconds since UNIX epoch\n  clockId = 42;                 // Clock identifier (0-1023)\n};\n\n// Convert to text representation\nlet tidText = TID.toText(tid);\nDebug.print(\"TID: \" # tidText); // \"3jzfcijpj2z2a\" (example)\n\n// Parse TID from text\nswitch (TID.fromText(tidText)) {\n  case (#ok(parsedTid)) {\n    Debug.print(\"Parsed successfully: \" # debug_show(parsedTid));\n  };\n  case (#err(error)) {\n    Debug.print(\"Parse error: \" # error);\n  };\n};\n```\n\n### Example 2: Using the TID Generator\n\n```motoko\n// Create a generator\nlet generator = TID.Generator();\n\n// Generate sequential TIDs\nlet tid1 = generator.next(); // clockId = 0\nlet tid2 = generator.next(); // clockId = 1\nlet tid3 = generator.next(); // clockId = 2\n\nDebug.print(\"TID 1: \" # TID.toText(tid1));\nDebug.print(\"TID 2: \" # TID.toText(tid2));\nDebug.print(\"TID 3: \" # TID.toText(tid3));\n```\n\n### Example 3: Comparing and Sorting TIDs\n\n```motoko\nlet tid1 = { timestamp = 1000; clockId = 1 };\nlet tid2 = { timestamp = 2000; clockId = 2 };\nlet tid3 = { timestamp = 2000; clockId = 3 }; // Same timestamp, different clock\n\n// Numeric comparison\nswitch (TID.compare(tid1, tid2)) {\n  case (#less) Debug.print(\"tid1 \u003c tid2\");\n  case (#equal) Debug.print(\"tid1 == tid2\");\n  case (#greater) Debug.print(\"tid1 \u003e tid2\");\n};\n\n// Equality check\nlet isEqual = TID.equal(tid1, tid2); // false\n\n// String sorting matches numeric sorting\nlet text1 = TID.toText(tid1);\nlet text2 = TID.toText(tid2);\nassert(text1 \u003c text2); // Lexicographic ordering matches temporal ordering\n```\n\n### Example 4: Working with Nat64 Representation\n\n```motoko\n// Convert TID to 64-bit integer\nlet tid = { timestamp = 1640995200000000; clockId = 42 };\nlet nat64Value = TID.toNat64(tid);\n\n// Convert back from 64-bit integer\nswitch (TID.fromNat64(nat64Value)) {\n  case (#ok(reconstructedTid)) {\n    assert(TID.equal(tid, reconstructedTid)); // Round-trip successful\n  };\n  case (#err(error)) {\n    Debug.print(\"Conversion error: \" # error);\n  };\n};\n```\n\n## API Reference\n\n### Types\n\n```motoko\n// TID structure\npublic type TID = {\n  timestamp : Nat; // Microseconds since UNIX epoch (max 53 bits)\n  clockId : Nat;   // Clock identifier (max 10 bits: 0-1023)\n};\n```\n\n### Core Functions\n\n```motoko\n// Convert TID to base32-sortable text representation\npublic func toText(tid : TID) : Text;\n\n// Parse TID from base32-sortable text\npublic func fromText(text : Text) : Result.Result\u003cTID, Text\u003e;\n\n// Convert TID to 64-bit integer representation\npublic func toNat64(tid : TID) : Nat64;\n\n// Convert 64-bit integer to TID\npublic func fromNat64(value : Nat64) : Result.Result\u003cTID, Text\u003e;\n\n// Compare two TIDs for sorting\npublic func compare(tid1 : TID, tid2 : TID) : Order.Order;\n\n// Check if two TIDs are equal\npublic func equal(tid1 : TID, tid2 : TID) : Bool;\n```\n\n### TID Generator\n\n```motoko\n// TID generator class\npublic class Generator() {\n  // Generate the next TID with current timestamp and incremented clock ID\n  public func next() : TID;\n}\n```\n\n## TID Format\n\n### Structure\n\nA TID is composed of:\n\n- **1 bit**: Always 0 (reserved for future use)\n- **53 bits**: Timestamp in microseconds since UNIX epoch\n- **10 bits**: Clock identifier (0-1023)\n\n### Text Representation\n\n- **Length**: Exactly 13 characters\n- **Encoding**: Base32-sortable (using AT Protocol's sortable alphabet)\n- **Character set**: `234567abcdefghijklmnopqrstuvwxyz` (no 0, 1, or uppercase)\n- **Ordering**: Lexicographic string sorting matches temporal ordering\n\n### Constraints\n\n- **Maximum timestamp**: 2^53 - 1 (9,007,199,254,740,991) for JavaScript compatibility\n- **Maximum clock ID**: 1,023 (10 bits)\n- **Top bit**: Must always be 0\n\n## Use Cases\n\n- **Distributed systems**: Sortable identifiers across multiple nodes\n- **Database keys**: Time-ordered primary keys with collision resistance\n- **Event logging**: Chronologically sortable event identifiers\n- **AT Protocol**: Compatible with ATProto TID specification\n\n## Error Handling\n\nThe library provides detailed error messages for invalid inputs:\n\n- Invalid TID length (must be exactly 13 characters)\n- Invalid characters (only base32-sortable alphabet allowed)\n- Invalid first character (high bit would be set)\n- Timestamp or clock ID exceeding maximum values\n- Invalid byte representations\n\n## Dependencies\n\n- `core`: Core Motoko libraries\n- `base-x-encoder`: Base32 encoding/decoding\n- `xtended-numbers`: Extended number utilities\n- `buffer`: Buffer utilities\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedjcase%2Fmotoko_tid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedjcase%2Fmotoko_tid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedjcase%2Fmotoko_tid/lists"}