@ewanc26/tid 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+# @malachite/tid
+
+Zero-dependency [AT Protocol](https://atproto.com/) TID (Timestamp Identifier) generation for Node.js and browsers.
+
+TIDs are the record keys used throughout ATProto / Bluesky — 13-character, lexicographically sortable, monotonic identifiers derived from a microsecond timestamp and a random clock ID.
+
+## Why this package?
+
+Other TID implementations require native bindings (`node-gyp`, Python) or pull in large dependency trees. This package is **pure JavaScript** with **no runtime dependencies**, and runs anywhere the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) is available — Node.js 20+, Deno, Bun, and all modern browsers.
+
+## Install
+
+```sh
+npm install @ewanc26/tid
+# or
+pnpm add @ewanc26/tid
+```
+
+## Usage
+
+### Generate a TID for a historical timestamp
+
+Pass an ISO 8601 string or a `Date` object. The clock is monotonic — if records arrive out of order, the timestamp is bumped forward so every call produces a strictly increasing TID within the same JS context.
+
+```ts
+import { generateTID } from '@malachite/tid';
+
+// From an ISO string (e.g. a Last.fm scrobble timestamp)
+const tid = generateTID('2023-11-01T12:00:00Z');
+
+// From a Date object
+const tid2 = generateTID(new Date('2024-03-15T09:30:00Z'));
+```
+
+### Generate a TID for right now
+
+```ts
+import { generateNextTID } from '@malachite/tid';
+
+const tid = generateNextTID();
+```
+
+### Validate a TID
+
+```ts
+import { validateTid } from '@malachite/tid';
+
+validateTid('3jzfcijpj2z2a');  // true
+validateTid('not-a-tid');       // false
+```
+
+### Decode a TID
+
+```ts
+import { decodeTid } from '@malachite/tid';
+
+const { timestampUs, clockId, date } = decodeTid('3jzfcijpj2z2a');
+// timestampUs — microseconds since Unix epoch
+// clockId     — random 0–31 clock identifier
+// date        — equivalent JavaScript Date (millisecond precision)
+```
+
+### Compare / sort TIDs
+
+Because the AT Protocol base-32 alphabet is ordered by timestamp, lexicographic string comparison is correct. `compareTids` returns `-1 | 0 | 1` for use as a `sort` comparator.
+
+```ts
+import { compareTids } from '@malachite/tid';
+
+const tids = ['3jzfcijpj2z2a', '3jzfabc000022', '3jzfzzzzzzz2a'];
+tids.sort(compareTids);
+// → ['3jzfabc000022', '3jzfcijpj2z2a', '3jzfzzzzzzz2a']  (chronological)
+```
+
+## API
+
+| Export | Signature | Description |
+|--------|-----------|-------------|
+| `generateTID` | `(source: string \| Date) => string` | Generate a TID for a historical timestamp |
+| `generateNextTID` | `() => string` | Generate a TID for the current wall-clock time |
+| `validateTid` | `(tid: string) => boolean` | Returns `true` if the string is a well-formed TID |
+| `decodeTid` | `(tid: string) => DecodedTid` | Decode a TID into timestamp, clockId, and Date |
+| `compareTids` | `(a: string, b: string) => -1 \| 0 \| 1` | Lexicographic comparator for sorting |
+| `resetTidClock` | `() => void` | Reset the monotonic clock (**tests only**) |
+
+### `DecodedTid`
+
+```ts
+interface DecodedTid {
+  timestampUs: number;  // microseconds since Unix epoch
+  clockId: number;      // 0–31
+  date: Date;           // millisecond-precision equivalent
+}
+```
+
+## Spec notes
+
+- TIDs are 13 characters in the AT Protocol base-32 alphabet (`234567abcdefghijklmnopqrstuvwxyz`).
+- The first 11 characters encode a microsecond-precision Unix timestamp.
+- The last 2 characters encode a random clock ID (0–31) that disambiguates TIDs generated on different machines or in different processes within the same microsecond.
+- The clock ID is randomised once at module load time (per JS context).
+- The full specification is at <https://atproto.com/specs/tid>.
+
+## License
+
+AGPL-3.0-only — same as [Malachite](https://github.com/ewanc26/malachite).

package/dist/index.cjs

@@ -0,0 +1,96 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  compareTids: () => compareTids,
+  decodeTid: () => decodeTid,
+  generateNextTID: () => generateNextTID,
+  generateTID: () => generateTID,
+  resetTidClock: () => resetTidClock,
+  validateTid: () => validateTid
+});
+module.exports = __toCommonJS(index_exports);
+var S32 = "234567abcdefghijklmnopqrstuvwxyz";
+var S32_MAP = {};
+for (let i = 0; i < S32.length; i++) S32_MAP[S32[i]] = i;
+function s32encode(n) {
+  if (n === 0) return "2";
+  let s = "";
+  let v = n;
+  while (v > 0) {
+    s = S32[v % 32] + s;
+    v = Math.floor(v / 32);
+  }
+  return s;
+}
+function s32decode(s) {
+  let n = 0;
+  for (const ch of s) n = n * 32 + (S32_MAP[ch] ?? 0);
+  return n;
+}
+var TID_RE = /^[234567abcdefghij][234567abcdefghijklmnopqrstuvwxyz]{12}$/;
+function validateTid(tid) {
+  return TID_RE.test(tid);
+}
+function decodeTid(tid) {
+  if (!validateTid(tid)) throw new TypeError(`Invalid TID: "${tid}"`);
+  const timestampUs = s32decode(tid.slice(0, 11));
+  const clockId = s32decode(tid.slice(11));
+  return { timestampUs, clockId, date: new Date(Math.floor(timestampUs / 1e3)) };
+}
+var lastUs = 0;
+var CLOCK_ID = (() => {
+  const buf = new Uint8Array(1);
+  (globalThis.crypto ?? globalThis.webcrypto).getRandomValues(buf);
+  return buf[0] % 32;
+})();
+function nextUs(targetUs) {
+  const us = targetUs <= lastUs ? lastUs + 1 : targetUs;
+  lastUs = us;
+  return us;
+}
+function makeTid(us) {
+  return s32encode(us).padStart(11, "2") + s32encode(CLOCK_ID).padStart(2, "2");
+}
+function generateTID(source) {
+  const ms = typeof source === "string" ? new Date(source).getTime() : source.getTime();
+  return makeTid(nextUs(ms * 1e3));
+}
+function generateNextTID() {
+  return makeTid(nextUs(Date.now() * 1e3));
+}
+function compareTids(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+function resetTidClock() {
+  lastUs = 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  compareTids,
+  decodeTid,
+  generateNextTID,
+  generateTID,
+  resetTidClock,
+  validateTid
+});

package/dist/index.d.cts

@@ -0,0 +1,62 @@
+/**
+ * @malachite/tid — AT Protocol TID generation
+ *
+ * Zero-dependency, spec-compliant TID (Timestamp Identifier) generation for
+ * the AT Protocol. Works in Node.js 20+ and all modern browsers.
+ *
+ * Spec: https://atproto.com/specs/tid
+ */
+/**
+ * Returns `true` if `tid` is a well-formed AT Protocol TID.
+ */
+declare function validateTid(tid: string): boolean;
+interface DecodedTid {
+    /** Microseconds since the Unix epoch. */
+    timestampUs: number;
+    /** Clock identifier (0–31). */
+    clockId: number;
+    /** Convenience: the timestamp as a `Date` (millisecond precision). */
+    date: Date;
+}
+/**
+ * Decode a TID into its constituent parts.
+ * Throws a `TypeError` if the TID is malformed.
+ */
+declare function decodeTid(tid: string): DecodedTid;
+/**
+ * Generate a TID for a historical timestamp.
+ *
+ * Accepts either an ISO 8601 string or a `Date` object. Monotonicity is
+ * guaranteed — if records arrive out of order the clock is bumped forward so
+ * every call produces a strictly increasing TID within the same JS context.
+ *
+ * @example
+ * const tid = generateTID('2023-11-01T12:00:00Z');
+ * const tid = generateTID(new Date());
+ */
+declare function generateTID(source: string | Date): string;
+/**
+ * Generate a TID for the current wall-clock time.
+ *
+ * @example
+ * const tid = generateNextTID();
+ */
+declare function generateNextTID(): string;
+/**
+ * Compare two TIDs lexicographically.
+ *
+ * Because the AT Protocol base-32 alphabet is lexicographically ordered by
+ * timestamp, string comparison is sufficient and correct.
+ *
+ * Returns `-1`, `0`, or `1` (suitable as a `Array.prototype.sort` comparator).
+ */
+declare function compareTids(a: string, b: string): -1 | 0 | 1;
+/**
+ * Reset the module-level monotonic clock to zero.
+ *
+ * **Only use this in tests.** Calling it in production risks generating
+ * duplicate or non-monotonic TIDs.
+ */
+declare function resetTidClock(): void;
+
+export { type DecodedTid, compareTids, decodeTid, generateNextTID, generateTID, resetTidClock, validateTid };

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @malachite/tid — AT Protocol TID generation
+ *
+ * Zero-dependency, spec-compliant TID (Timestamp Identifier) generation for
+ * the AT Protocol. Works in Node.js 20+ and all modern browsers.
+ *
+ * Spec: https://atproto.com/specs/tid
+ */
+/**
+ * Returns `true` if `tid` is a well-formed AT Protocol TID.
+ */
+declare function validateTid(tid: string): boolean;
+interface DecodedTid {
+    /** Microseconds since the Unix epoch. */
+    timestampUs: number;
+    /** Clock identifier (0–31). */
+    clockId: number;
+    /** Convenience: the timestamp as a `Date` (millisecond precision). */
+    date: Date;
+}
+/**
+ * Decode a TID into its constituent parts.
+ * Throws a `TypeError` if the TID is malformed.
+ */
+declare function decodeTid(tid: string): DecodedTid;
+/**
+ * Generate a TID for a historical timestamp.
+ *
+ * Accepts either an ISO 8601 string or a `Date` object. Monotonicity is
+ * guaranteed — if records arrive out of order the clock is bumped forward so
+ * every call produces a strictly increasing TID within the same JS context.
+ *
+ * @example
+ * const tid = generateTID('2023-11-01T12:00:00Z');
+ * const tid = generateTID(new Date());
+ */
+declare function generateTID(source: string | Date): string;
+/**
+ * Generate a TID for the current wall-clock time.
+ *
+ * @example
+ * const tid = generateNextTID();
+ */
+declare function generateNextTID(): string;
+/**
+ * Compare two TIDs lexicographically.
+ *
+ * Because the AT Protocol base-32 alphabet is lexicographically ordered by
+ * timestamp, string comparison is sufficient and correct.
+ *
+ * Returns `-1`, `0`, or `1` (suitable as a `Array.prototype.sort` comparator).
+ */
+declare function compareTids(a: string, b: string): -1 | 0 | 1;
+/**
+ * Reset the module-level monotonic clock to zero.
+ *
+ * **Only use this in tests.** Calling it in production risks generating
+ * duplicate or non-monotonic TIDs.
+ */
+declare function resetTidClock(): void;
+
+export { type DecodedTid, compareTids, decodeTid, generateNextTID, generateTID, resetTidClock, validateTid };

package/dist/index.js

@@ -0,0 +1,66 @@
+// src/index.ts
+var S32 = "234567abcdefghijklmnopqrstuvwxyz";
+var S32_MAP = {};
+for (let i = 0; i < S32.length; i++) S32_MAP[S32[i]] = i;
+function s32encode(n) {
+  if (n === 0) return "2";
+  let s = "";
+  let v = n;
+  while (v > 0) {
+    s = S32[v % 32] + s;
+    v = Math.floor(v / 32);
+  }
+  return s;
+}
+function s32decode(s) {
+  let n = 0;
+  for (const ch of s) n = n * 32 + (S32_MAP[ch] ?? 0);
+  return n;
+}
+var TID_RE = /^[234567abcdefghij][234567abcdefghijklmnopqrstuvwxyz]{12}$/;
+function validateTid(tid) {
+  return TID_RE.test(tid);
+}
+function decodeTid(tid) {
+  if (!validateTid(tid)) throw new TypeError(`Invalid TID: "${tid}"`);
+  const timestampUs = s32decode(tid.slice(0, 11));
+  const clockId = s32decode(tid.slice(11));
+  return { timestampUs, clockId, date: new Date(Math.floor(timestampUs / 1e3)) };
+}
+var lastUs = 0;
+var CLOCK_ID = (() => {
+  const buf = new Uint8Array(1);
+  (globalThis.crypto ?? globalThis.webcrypto).getRandomValues(buf);
+  return buf[0] % 32;
+})();
+function nextUs(targetUs) {
+  const us = targetUs <= lastUs ? lastUs + 1 : targetUs;
+  lastUs = us;
+  return us;
+}
+function makeTid(us) {
+  return s32encode(us).padStart(11, "2") + s32encode(CLOCK_ID).padStart(2, "2");
+}
+function generateTID(source) {
+  const ms = typeof source === "string" ? new Date(source).getTime() : source.getTime();
+  return makeTid(nextUs(ms * 1e3));
+}
+function generateNextTID() {
+  return makeTid(nextUs(Date.now() * 1e3));
+}
+function compareTids(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+function resetTidClock() {
+  lastUs = 0;
+}
+export {
+  compareTids,
+  decodeTid,
+  generateNextTID,
+  generateTID,
+  resetTidClock,
+  validateTid
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ewanc26/tid",
+  "version": "1.0.0",
+  "description": "Zero-dependency AT Protocol TID generation for Node.js and browsers",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types":   "./dist/index.d.ts",
+      "import":  "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main":  "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md", "LICENCE"],
+  "scripts": {
+    "build":      "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev":        "tsup src/index.ts --format esm,cjs --dts --watch",
+    "type-check": "tsc --noEmit",
+    "test":       "node --test dist/index.test.js"
+  },
+  "keywords": [
+    "atproto",
+    "bluesky",
+    "tid",
+    "timestamp",
+    "identifier",
+    "lexicon"
+  ],
+  "author": "",
+  "license": "AGPL-3.0-only",
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  }
+}