@ewanc26/tid 1.0.3 → 1.1.0

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.3",
+  "version": "1.1.0",
   "description": "Zero-dependency AT Protocol TID generation for Node.js and browsers",
   "type": "module",
   "exports": {