@ewanc26/tid 1.0.2 → 1.1.0

package/README.md

@@ -2,105 +2,140 @@
 
 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.
+This package is **written in TypeScript** and compiled to **plain JavaScript**, so it ships with type definitions for TypeScript users and runs anywhere the Web Crypto API is available — Node.js 20+, Deno, Bun, and modern browsers.
+
+TIDs are 13-character, lexicographically sortable record keys used across the AT Protocol and Bluesky. They’re monotonic identifiers derived from a microsecond timestamp and a 5-bit clock ID. When multiple TIDs would otherwise share the same microsecond, this package avoids collisions by nudging the clock ID (initialised per JS context) so each generated TID stays unique and strictly increasing within that runtime.
+
+---
 
 ## 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.
+Other TID implementations either require native bindings (e.g. `node-gyp`) or pull in large dependency trees. This package is **pure JavaScript**, has **no runtime dependencies**, ships with `.d.ts` typings, and is intentionally tiny — ideal for libraries, servers and client code where bundle size and portability matter.
+
+---
 
 ## Install
 
-```sh
+```bash
 npm install @ewanc26/tid
 # or
 pnpm add @ewanc26/tid
 ```
 
-## Usage
+---
 
-### Generate a TID for a historical timestamp
+## Usage
 
-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.
+### TypeScript (recommended)
 
 ```ts
-import { generateTID } from '@ewanc26/tid';
+import {
+  generateTID,
+  generateNextTID,
+  validateTid,
+  decodeTid,
+  compareTids,
+} from '@ewanc26/tid';
+
+// From ISO string or Date
+const tid: string = generateTID('2023-11-01T12:00:00Z');
+const tid2: string = generateTID(new Date('2024-03-15T09:30:00Z'));
+
+// Now
+const currentTid: string = generateNextTID();
+
+// Validate
+const ok: boolean = validateTid('3jzfcijpj2z2a');
+
+// Decode
+const decoded = decodeTid('3jzfcijpj2z2a');
+console.log(decoded.timestampUs, decoded.clockId, decoded.date);
+
+// Sort
+const tids: string[] = ['3jzfcijpj2z2a', '3jzfabc000022', '3jzfzzzzzzz2a'];
+tids.sort(compareTids);
+```
 
-// From an ISO string (e.g. a Last.fm scrobble timestamp)
-const tid = generateTID('2023-11-01T12:00:00Z');
+### JavaScript (ESM)
 
-// From a Date object
-const tid2 = generateTID(new Date('2024-03-15T09:30:00Z'));
+```js
+import {
+  generateTID,
+  generateNextTID,
+  validateTid,
+  decodeTid,
+  compareTids,
+} from '@ewanc26/tid';
+
+const tid = generateTID('2023-11-01T12:00:00Z');
+const currentTid = generateNextTID();
+console.log(validateTid(tid));
 ```
 
-### Generate a TID for right now
+### JavaScript (CommonJS)
 
-```ts
-import { generateNextTID } from '@ewanc26/tid';
+```js
+const {
+  generateTID,
+  generateNextTID,
+  validateTid,
+  decodeTid,
+  compareTids,
+} = require('@ewanc26/tid');
 
-const tid = generateNextTID();
+const tid = generateTID('2023-11-01T12:00:00Z');
 ```
 
-### Validate a TID
+---
 
-```ts
-import { validateTid } from '@ewanc26/tid';
+## API
 
-validateTid('3jzfcijpj2z2a');  // true
-validateTid('not-a-tid');       // false
-```
+| 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**)        |                                           |                                      |
 
-### Decode a TID
+### `DecodedTid`
 
 ```ts
-import { decodeTid } from '@ewanc26/tid';
-
-const { timestampUs, clockId, date } = decodeTid('3jzfcijpj2z2a');
-// timestampUs — microseconds since Unix epoch
-// clockId     — random 0–31 clock identifier
-// date        — equivalent JavaScript Date (millisecond precision)
+interface DecodedTid {
+  timestampUs: number; // microseconds since Unix epoch
+  clockId: number;     // 0–31
+  date: Date;          // millisecond-precision equivalent
+}
 ```
 
-### 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.
+## Spec notes
 
-```ts
-import { compareTids } from '@ewanc26/tid';
+* 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 5-bit clock ID (0–31) which disambiguates TIDs generated on different machines or processes within the same microsecond.
+* The clock ID is randomised once at module load time (per JS context). When multiple TIDs would collide at the same microsecond, the implementation adjusts (nudges) the clock ID so collisions are avoided while preserving lexicographic ordering and monotonicity within that runtime.
+* Full specification: [https://atproto.com/specs/tid](https://atproto.com/specs/tid)
 
-const tids = ['3jzfcijpj2z2a', '3jzfabc000022', '3jzfzzzzzzz2a'];
-tids.sort(compareTids);
-// → ['3jzfabc000022', '3jzfcijpj2z2a', '3jzfzzzzzzz2a']  (chronological)
-```
+---
 
-## API
+## Behavioural notes
 
-| 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**) |
+* Monotonicity is maintained per JS context. If records arrive out of chronological order in the same runtime, the package bumps the timestamp forward to ensure every generated TID is strictly increasing.
+* Clock ID collisions across processes or machines are extremely unlikely due to the randomised 5-bit clock ID; the clock-nudging only applies inside a JS context to disambiguate simultaneous generations.
+* The package does not attempt cross-process coordination — if you need globally unique sequencing beyond the TID spec, consider a server-side sequencer or combining TIDs with per-host identifiers.
 
-### `DecodedTid`
+---
 
-```ts
-interface DecodedTid {
-  timestampUs: number;  // microseconds since Unix epoch
-  clockId: number;      // 0–31
-  date: Date;           // millisecond-precision equivalent
-}
-```
+## Testing & development
 
-## Spec notes
+* `resetTidClock()` is exported for tests to make deterministic TID generation possible.
+* The library has zero runtime deps and uses the Web Crypto API for secure randomness. When running in older environments, provide a compatible Web Crypto polyfill if necessary.
 
-- 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
+## Licence
 
-AGPL-3.0-only — same as [Malachite](https://github.com/ewanc26/malachite).
+AGPL-3.0-only — same as [Malachite](https://github.com/ewanc26/malachite/tree/main).

package/dist/index.cjs

@@ -20,11 +20,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  InvalidTidError: () => InvalidTidError,
+  areMonotonic: () => areMonotonic,
   compareTids: () => compareTids,
   decodeTid: () => decodeTid,
+  decodeTidClockId: () => decodeTidClockId,
+  decodeTidTimestamp: () => decodeTidTimestamp,
+  ensureValidTid: () => ensureValidTid,
   generateNextTID: () => generateNextTID,
   generateTID: () => generateTID,
+  getTidClockState: () => getTidClockState,
   resetTidClock: () => resetTidClock,
+  seedTidClock: () => seedTidClock,
   validateTid: () => validateTid
 });
 module.exports = __toCommonJS(index_exports);
@@ -50,25 +57,45 @@ var TID_RE = /^[234567abcdefghij][234567abcdefghijklmnopqrstuvwxyz]{12}$/;
 function validateTid(tid) {
   return TID_RE.test(tid);
 }
+var InvalidTidError = class extends Error {
+  constructor(message, tid) {
+    super(message);
+    this.tid = tid;
+    this.name = "InvalidTidError";
+  }
+};
+function ensureValidTid(tid) {
+  if (!validateTid(tid)) {
+    throw new InvalidTidError(`Invalid TID format: "${tid}"`, 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)) };
+  const decodedClockId = s32decode(tid.slice(11));
+  return { timestampUs, clockId: decodedClockId, date: new Date(Math.floor(timestampUs / 1e3)) };
+}
+function decodeTidTimestamp(tid) {
+  return decodeTid(tid).timestampUs;
+}
+function decodeTidClockId(tid) {
+  return decodeTid(tid).clockId;
 }
 var lastUs = 0;
-var CLOCK_ID = (() => {
+var clockId = (() => {
   const buf = new Uint8Array(1);
   (globalThis.crypto ?? globalThis.webcrypto).getRandomValues(buf);
   return buf[0] % 32;
 })();
+var generatedCount = 0;
 function nextUs(targetUs) {
   const us = targetUs <= lastUs ? lastUs + 1 : targetUs;
   lastUs = us;
+  generatedCount++;
   return us;
 }
 function makeTid(us) {
-  return s32encode(us).padStart(11, "2") + s32encode(CLOCK_ID).padStart(2, "2");
+  return s32encode(us).padStart(11, "2") + s32encode(clockId).padStart(2, "2");
 }
 function generateTID(source) {
   const ms = typeof source === "string" ? new Date(source).getTime() : source.getTime();
@@ -82,15 +109,37 @@ function compareTids(a, b) {
   if (a > b) return 1;
   return 0;
 }
+function areMonotonic(tids) {
+  for (let i = 1; i < tids.length; i++) {
+    if (tids[i] <= tids[i - 1]) return false;
+  }
+  return true;
+}
+function getTidClockState() {
+  return { lastTimestampUs: lastUs, clockId, generatedCount };
+}
 function resetTidClock() {
   lastUs = 0;
+  generatedCount = 0;
+}
+function seedTidClock(startUs = 0, newClockId = 0) {
+  lastUs = startUs;
+  clockId = newClockId % 32;
+  generatedCount = 0;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  InvalidTidError,
+  areMonotonic,
   compareTids,
   decodeTid,
+  decodeTidClockId,
+  decodeTidTimestamp,
+  ensureValidTid,
   generateNextTID,
   generateTID,
+  getTidClockState,
   resetTidClock,
+  seedTidClock,
   validateTid
 });

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 /**
- * @malachite/tid — AT Protocol TID generation
+ * @ewanc26/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.
@@ -10,6 +10,18 @@
  * Returns `true` if `tid` is a well-formed AT Protocol TID.
  */
 declare function validateTid(tid: string): boolean;
+/**
+ * Error thrown by `ensureValidTid` when a TID fails validation.
+ */
+declare class InvalidTidError extends Error {
+    readonly tid?: string | undefined;
+    constructor(message: string, tid?: string | undefined);
+}
+/**
+ * Assert that `tid` is a valid AT Protocol TID.
+ * Throws `InvalidTidError` if the format check fails.
+ */
+declare function ensureValidTid(tid: string): asserts tid is string;
 interface DecodedTid {
     /** Microseconds since the Unix epoch. */
     timestampUs: number;
@@ -23,6 +35,16 @@ interface DecodedTid {
  * Throws a `TypeError` if the TID is malformed.
  */
 declare function decodeTid(tid: string): DecodedTid;
+/**
+ * Decode a TID and return only the microsecond timestamp.
+ * Prefer `decodeTid` for new code.
+ */
+declare function decodeTidTimestamp(tid: string): number;
+/**
+ * Decode a TID and return only the clock identifier.
+ * Prefer `decodeTid` for new code.
+ */
+declare function decodeTidClockId(tid: string): number;
 /**
  * Generate a TID for a historical timestamp.
  *
@@ -51,12 +73,50 @@ declare function generateNextTID(): string;
  * Returns `-1`, `0`, or `1` (suitable as a `Array.prototype.sort` comparator).
  */
 declare function compareTids(a: string, b: string): -1 | 0 | 1;
+/**
+ * Returns `true` if every TID in the array is strictly greater than the one
+ * before it (lexicographic / chronological order).
+ */
+declare function areMonotonic(tids: string[]): boolean;
+/**
+ * Snapshot of the module-level clock state.
+ * Intended for debugging and test assertions.
+ */
+interface TidClockState {
+    lastTimestampUs: number;
+    clockId: number;
+    generatedCount: number;
+}
+/**
+ * Return a snapshot of the current clock state.
+ * Useful for asserting counts in tests.
+ */
+declare function getTidClockState(): TidClockState;
 /**
  * Reset the module-level monotonic clock to zero.
+ * Resets `lastTimestampUs` and `generatedCount` but preserves `clockId`.
  *
  * **Only use this in tests.** Calling it in production risks generating
  * duplicate or non-monotonic TIDs.
  */
 declare function resetTidClock(): void;
+/**
+ * Seed the clock with a fixed starting timestamp and clock identifier,
+ * making all subsequent TID generation deterministic.
+ *
+ * - `startUs` becomes the floor for the next generated timestamp (µs).
+ * - `newClockId` overrides the random clock identifier (0–31, default 0).
+ * - `generatedCount` is reset to 0.
+ *
+ * **Only use this in tests.**
+ *
+ * @example
+ * seedTidClock(1_000_000_000_000_000, 0);
+ * const tid1 = generateNextTID();
+ * seedTidClock(1_000_000_000_000_000, 0);
+ * const tid2 = generateNextTID();
+ * // tid1 === tid2
+ */
+declare function seedTidClock(startUs?: number, newClockId?: number): void;
 
-export { type DecodedTid, compareTids, decodeTid, generateNextTID, generateTID, resetTidClock, validateTid };
+export { type DecodedTid, InvalidTidError, type TidClockState, areMonotonic, compareTids, decodeTid, decodeTidClockId, decodeTidTimestamp, ensureValidTid, generateNextTID, generateTID, getTidClockState, resetTidClock, seedTidClock, validateTid };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @malachite/tid — AT Protocol TID generation
+ * @ewanc26/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.
@@ -10,6 +10,18 @@
  * Returns `true` if `tid` is a well-formed AT Protocol TID.
  */
 declare function validateTid(tid: string): boolean;
+/**
+ * Error thrown by `ensureValidTid` when a TID fails validation.
+ */
+declare class InvalidTidError extends Error {
+    readonly tid?: string | undefined;
+    constructor(message: string, tid?: string | undefined);
+}
+/**
+ * Assert that `tid` is a valid AT Protocol TID.
+ * Throws `InvalidTidError` if the format check fails.
+ */
+declare function ensureValidTid(tid: string): asserts tid is string;
 interface DecodedTid {
     /** Microseconds since the Unix epoch. */
     timestampUs: number;
@@ -23,6 +35,16 @@ interface DecodedTid {
  * Throws a `TypeError` if the TID is malformed.
  */
 declare function decodeTid(tid: string): DecodedTid;
+/**
+ * Decode a TID and return only the microsecond timestamp.
+ * Prefer `decodeTid` for new code.
+ */
+declare function decodeTidTimestamp(tid: string): number;
+/**
+ * Decode a TID and return only the clock identifier.
+ * Prefer `decodeTid` for new code.
+ */
+declare function decodeTidClockId(tid: string): number;
 /**
  * Generate a TID for a historical timestamp.
  *
@@ -51,12 +73,50 @@ declare function generateNextTID(): string;
  * Returns `-1`, `0`, or `1` (suitable as a `Array.prototype.sort` comparator).
  */
 declare function compareTids(a: string, b: string): -1 | 0 | 1;
+/**
+ * Returns `true` if every TID in the array is strictly greater than the one
+ * before it (lexicographic / chronological order).
+ */
+declare function areMonotonic(tids: string[]): boolean;
+/**
+ * Snapshot of the module-level clock state.
+ * Intended for debugging and test assertions.
+ */
+interface TidClockState {
+    lastTimestampUs: number;
+    clockId: number;
+    generatedCount: number;
+}
+/**
+ * Return a snapshot of the current clock state.
+ * Useful for asserting counts in tests.
+ */
+declare function getTidClockState(): TidClockState;
 /**
  * Reset the module-level monotonic clock to zero.
+ * Resets `lastTimestampUs` and `generatedCount` but preserves `clockId`.
  *
  * **Only use this in tests.** Calling it in production risks generating
  * duplicate or non-monotonic TIDs.
  */
 declare function resetTidClock(): void;
+/**
+ * Seed the clock with a fixed starting timestamp and clock identifier,
+ * making all subsequent TID generation deterministic.
+ *
+ * - `startUs` becomes the floor for the next generated timestamp (µs).
+ * - `newClockId` overrides the random clock identifier (0–31, default 0).
+ * - `generatedCount` is reset to 0.
+ *
+ * **Only use this in tests.**
+ *
+ * @example
+ * seedTidClock(1_000_000_000_000_000, 0);
+ * const tid1 = generateNextTID();
+ * seedTidClock(1_000_000_000_000_000, 0);
+ * const tid2 = generateNextTID();
+ * // tid1 === tid2
+ */
+declare function seedTidClock(startUs?: number, newClockId?: number): void;
 
-export { type DecodedTid, compareTids, decodeTid, generateNextTID, generateTID, resetTidClock, validateTid };
+export { type DecodedTid, InvalidTidError, type TidClockState, areMonotonic, compareTids, decodeTid, decodeTidClockId, decodeTidTimestamp, ensureValidTid, generateNextTID, generateTID, getTidClockState, resetTidClock, seedTidClock, validateTid };

package/dist/index.js

@@ -21,25 +21,45 @@ var TID_RE = /^[234567abcdefghij][234567abcdefghijklmnopqrstuvwxyz]{12}$/;
 function validateTid(tid) {
   return TID_RE.test(tid);
 }
+var InvalidTidError = class extends Error {
+  constructor(message, tid) {
+    super(message);
+    this.tid = tid;
+    this.name = "InvalidTidError";
+  }
+};
+function ensureValidTid(tid) {
+  if (!validateTid(tid)) {
+    throw new InvalidTidError(`Invalid TID format: "${tid}"`, 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)) };
+  const decodedClockId = s32decode(tid.slice(11));
+  return { timestampUs, clockId: decodedClockId, date: new Date(Math.floor(timestampUs / 1e3)) };
+}
+function decodeTidTimestamp(tid) {
+  return decodeTid(tid).timestampUs;
+}
+function decodeTidClockId(tid) {
+  return decodeTid(tid).clockId;
 }
 var lastUs = 0;
-var CLOCK_ID = (() => {
+var clockId = (() => {
   const buf = new Uint8Array(1);
   (globalThis.crypto ?? globalThis.webcrypto).getRandomValues(buf);
   return buf[0] % 32;
 })();
+var generatedCount = 0;
 function nextUs(targetUs) {
   const us = targetUs <= lastUs ? lastUs + 1 : targetUs;
   lastUs = us;
+  generatedCount++;
   return us;
 }
 function makeTid(us) {
-  return s32encode(us).padStart(11, "2") + s32encode(CLOCK_ID).padStart(2, "2");
+  return s32encode(us).padStart(11, "2") + s32encode(clockId).padStart(2, "2");
 }
 function generateTID(source) {
   const ms = typeof source === "string" ? new Date(source).getTime() : source.getTime();
@@ -53,14 +73,36 @@ function compareTids(a, b) {
   if (a > b) return 1;
   return 0;
 }
+function areMonotonic(tids) {
+  for (let i = 1; i < tids.length; i++) {
+    if (tids[i] <= tids[i - 1]) return false;
+  }
+  return true;
+}
+function getTidClockState() {
+  return { lastTimestampUs: lastUs, clockId, generatedCount };
+}
 function resetTidClock() {
   lastUs = 0;
+  generatedCount = 0;
+}
+function seedTidClock(startUs = 0, newClockId = 0) {
+  lastUs = startUs;
+  clockId = newClockId % 32;
+  generatedCount = 0;
 }
 export {
+  InvalidTidError,
+  areMonotonic,
   compareTids,
   decodeTid,
+  decodeTidClockId,
+  decodeTidTimestamp,
+  ensureValidTid,
   generateNextTID,
   generateTID,
+  getTidClockState,
   resetTidClock,
+  seedTidClock,
   validateTid
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ewanc26/tid",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Zero-dependency AT Protocol TID generation for Node.js and browsers",
   "type": "module",
   "exports": {