@ewanc26/tid 1.1.1 → 1.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -131
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,141 +1,13 @@
|
|
|
1
1
|
# @ewanc26/tid
|
|
2
2
|
|
|
3
|
-
Zero-dependency
|
|
4
|
-
|
|
5
|
-
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.
|
|
6
|
-
|
|
7
|
-
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.
|
|
8
|
-
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
## Why this package?
|
|
12
|
-
|
|
13
|
-
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.
|
|
14
|
-
|
|
15
|
-
---
|
|
16
|
-
|
|
17
|
-
## Install
|
|
3
|
+
Zero-dependency AT Protocol TID (Timestamp Identifier) generation. Works in Node.js 20+, Deno, Bun, and browsers.
|
|
18
4
|
|
|
19
5
|
```bash
|
|
20
|
-
npm install @ewanc26/tid
|
|
21
|
-
# or
|
|
22
6
|
pnpm add @ewanc26/tid
|
|
23
7
|
```
|
|
24
8
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
## Usage
|
|
28
|
-
|
|
29
|
-
### TypeScript (recommended)
|
|
30
|
-
|
|
31
|
-
```ts
|
|
32
|
-
import {
|
|
33
|
-
generateTID,
|
|
34
|
-
generateNextTID,
|
|
35
|
-
validateTid,
|
|
36
|
-
decodeTid,
|
|
37
|
-
compareTids,
|
|
38
|
-
} from '@ewanc26/tid';
|
|
39
|
-
|
|
40
|
-
// From ISO string or Date
|
|
41
|
-
const tid: string = generateTID('2023-11-01T12:00:00Z');
|
|
42
|
-
const tid2: string = generateTID(new Date('2024-03-15T09:30:00Z'));
|
|
43
|
-
|
|
44
|
-
// Now
|
|
45
|
-
const currentTid: string = generateNextTID();
|
|
46
|
-
|
|
47
|
-
// Validate
|
|
48
|
-
const ok: boolean = validateTid('3jzfcijpj2z2a');
|
|
49
|
-
|
|
50
|
-
// Decode
|
|
51
|
-
const decoded = decodeTid('3jzfcijpj2z2a');
|
|
52
|
-
console.log(decoded.timestampUs, decoded.clockId, decoded.date);
|
|
53
|
-
|
|
54
|
-
// Sort
|
|
55
|
-
const tids: string[] = ['3jzfcijpj2z2a', '3jzfabc000022', '3jzfzzzzzzz2a'];
|
|
56
|
-
tids.sort(compareTids);
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
### JavaScript (ESM)
|
|
60
|
-
|
|
61
|
-
```js
|
|
62
|
-
import {
|
|
63
|
-
generateTID,
|
|
64
|
-
generateNextTID,
|
|
65
|
-
validateTid,
|
|
66
|
-
decodeTid,
|
|
67
|
-
compareTids,
|
|
68
|
-
} from '@ewanc26/tid';
|
|
69
|
-
|
|
70
|
-
const tid = generateTID('2023-11-01T12:00:00Z');
|
|
71
|
-
const currentTid = generateNextTID();
|
|
72
|
-
console.log(validateTid(tid));
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
### JavaScript (CommonJS)
|
|
76
|
-
|
|
77
|
-
```js
|
|
78
|
-
const {
|
|
79
|
-
generateTID,
|
|
80
|
-
generateNextTID,
|
|
81
|
-
validateTid,
|
|
82
|
-
decodeTid,
|
|
83
|
-
compareTids,
|
|
84
|
-
} = require('@ewanc26/tid');
|
|
85
|
-
|
|
86
|
-
const tid = generateTID('2023-11-01T12:00:00Z');
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
---
|
|
90
|
-
|
|
91
|
-
## API
|
|
92
|
-
|
|
93
|
-
| Export | Signature | Description | | |
|
|
94
|
-
| ----------------- | ----------------------------- | ------------------------------------------------- | ----------------------------------------- | ------------------------------------ |
|
|
95
|
-
| `generateTID` | `(source: string | Date) => string` | Generate a TID for a historical timestamp | |
|
|
96
|
-
| `generateNextTID` | `() => string` | Generate a TID for the current wall-clock time | | |
|
|
97
|
-
| `validateTid` | `(tid: string) => boolean` | Returns `true` if the string is a well-formed TID | | |
|
|
98
|
-
| `decodeTid` | `(tid: string) => DecodedTid` | Decode a TID into timestamp, clockId, and Date | | |
|
|
99
|
-
| `compareTids` | `(a: string, b: string) => -1 | 0 | 1` | Lexicographic comparator for sorting |
|
|
100
|
-
| `resetTidClock` | `() => void` | Reset the monotonic clock (**tests only**) | | |
|
|
101
|
-
|
|
102
|
-
### `DecodedTid`
|
|
103
|
-
|
|
104
|
-
```ts
|
|
105
|
-
interface DecodedTid {
|
|
106
|
-
timestampUs: number; // microseconds since Unix epoch
|
|
107
|
-
clockId: number; // 0–31
|
|
108
|
-
date: Date; // millisecond-precision equivalent
|
|
109
|
-
}
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
---
|
|
113
|
-
|
|
114
|
-
## Spec notes
|
|
115
|
-
|
|
116
|
-
* TIDs are 13 characters in the AT Protocol base-32 alphabet: `234567abcdefghijklmnopqrstuvwxyz`.
|
|
117
|
-
* The first 11 characters encode a microsecond-precision Unix timestamp.
|
|
118
|
-
* 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.
|
|
119
|
-
* 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.
|
|
120
|
-
* Full specification: [https://atproto.com/specs/tid](https://atproto.com/specs/tid)
|
|
121
|
-
|
|
122
|
-
---
|
|
123
|
-
|
|
124
|
-
## Behavioural notes
|
|
125
|
-
|
|
126
|
-
* 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.
|
|
127
|
-
* 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.
|
|
128
|
-
* 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.
|
|
129
|
-
|
|
130
|
-
---
|
|
131
|
-
|
|
132
|
-
## Testing & development
|
|
133
|
-
|
|
134
|
-
* `resetTidClock()` is exported for tests to make deterministic TID generation possible.
|
|
135
|
-
* 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.
|
|
136
|
-
|
|
137
|
-
---
|
|
9
|
+
Full documentation at **[docs.ewancroft.uk](https://docs.ewancroft.uk/projects/tid)**.
|
|
138
10
|
|
|
139
11
|
## Licence
|
|
140
12
|
|
|
141
|
-
AGPL-3.0-only
|
|
13
|
+
AGPL-3.0-only.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ewanc26/tid",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.2",
|
|
4
4
|
"description": "Zero-dependency AT Protocol TID generation for Node.js and browsers",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|
|
@@ -29,7 +29,7 @@
|
|
|
29
29
|
"author": "Ewan Croft",
|
|
30
30
|
"license": "AGPL-3.0-only",
|
|
31
31
|
"devDependencies": {
|
|
32
|
-
"tsup": "^8.5.
|
|
32
|
+
"tsup": "^8.5.1",
|
|
33
33
|
"typescript": "^5.9.3"
|
|
34
34
|
},
|
|
35
35
|
"scripts": {
|