fast-ulid 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shaul Lavo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# fast-ulid
+
+Fastest spec-compliant monotonic ULID generator for JavaScript. ~62ns per ID, zero dependencies.
+
+## Install
+
+```bash
+npm install fast-ulid
+```
+
+## Usage
+
+```ts
+import { ulid, createUlid, timestamp } from 'fast-ulid'
+
+// Generate a ULID
+const id = ulid()
+// → "01HYX3QGZK4P8RJ5N0VWMT6B2A"
+
+// Extract the timestamp
+const ms = timestamp(id)
+// → 1700000000000
+
+// Create an isolated generator (useful for Workers)
+const generate = createUlid()
+generate()
+generate()
+```
+
+## API
+
+### `ulid(): string`
+
+Generate a ULID using the default shared generator. Returns a 26-character Crockford Base32 string.
+
+### `createUlid(): () => string`
+
+Create an isolated generator with its own monotonic state. Use this when you need a dedicated generator per Worker thread to avoid contention.
+
+### `timestamp(id: string): number`
+
+Extract the UNIX millisecond timestamp from a ULID string. Unrolled decode — ~5.8ns per call.
+
+## Benchmark
+
+Measured on Apple M1, Bun 1.3.10:
+
+| Operation | fast-ulid | crypto.randomUUID() |
+|---|---|---|
+| Single ID | **62 ns** | 44 ns |
+| Batch 1000 | **84 µs** | 43 µs |
+
+`crypto.randomUUID()` is a native C++ call that formats 128 random bits. `fast-ulid` does more work — timestamp encoding, monotonic ordering, Crockford Base32 — and is still within 1.5x.
+
+```bash
+bun run bench
+```
+
+## What makes it fast
+
+- **Batched randomness** — `crypto.getRandomValues` called once per 8,192 IDs, not every call
+- **Pre-computed lookup table** — Uint8Array maps digit → charCode, no string indexing
+- **Reused output buffer** — single `Uint8Array(26)` + `TextDecoder`, zero allocations in hot path
+- **Monotonic increment** — same-ms IDs bump a counter instead of regenerating randomness
+- **Bit masking** — `& 31` instead of modulo
+- **Unrolled loops** — timestamp encode/decode fully unrolled, no loop overhead
+
+## Spec compliance
+
+Fully compliant with the [ULID spec](https://github.com/ulid/spec). 26 tests verify:
+
+| Requirement | |
+|---|---|
+| 26-char Crockford Base32 string | ✅ |
+| 48-bit ms timestamp (10 chars) | ✅ |
+| 80-bit cryptographic randomness (16 chars) | ✅ |
+| Monotonic: same-ms IDs increment by 1 | ✅ |
+| Overflow advances timestamp | ✅ |
+| Lexicographic sort = chronological sort | ✅ |
+| Clock rollback resilience | ✅ |
+| 10,000+ unique IDs | ✅ |
+| Encode/decode roundtrip | ✅ |
+
+```bash
+bun test
+```
+
+## Runtime support
+
+Works everywhere with `crypto.getRandomValues`, `Date.now`, and `TextDecoder`:
+
+- Node.js 16+
+- Bun
+- Deno
+- Modern browsers
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/** Create an isolated ULID generator with its own monotonic state. Useful for Workers. */
+export declare function createUlid(): () => string;
+/** Default shared ULID generator. */
+export declare const ulid: () => string;
+/** Extract the UNIX-ms timestamp from a ULID string. */
+export declare function timestamp(id: string): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsGA,0FAA0F;AAC1F,wBAAgB,UAAU,IAAI,MAAM,MAAM,CA+BzC;AAED,qCAAqC;AACrC,eAAO,MAAM,IAAI,QAlCmB,MAkCJ,CAAA;AAOhC,wDAAwD;AACxD,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAe5C"}

package/dist/index.js

@@ -0,0 +1,125 @@
+// fast-ulid — Monotonic ULID implementation
+// - Lexicographically increasing even for multiple IDs in the same millisecond
+// - Monotonic under clock rollback by pinning to the last emitted timestamp
+// - `createUlid()` provides isolated state so callers can create one generator per Worker
+// - Zero dependencies, works in Node, Bun, Deno, and browsers
+const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const RANDOM_DIGITS = 16;
+const MAX_DIGIT = 31;
+const BATCH = 8192;
+const ENC = new Uint8Array(32);
+for (let i = 0; i < 32; i++)
+    ENC[i] = ENCODING.charCodeAt(i);
+function fillRandomPool(state) {
+    crypto.getRandomValues(state.randomPool);
+    state.randomPoolPos = 0;
+}
+function setRandomFromPool(state) {
+    if (state.randomPoolPos >= BATCH)
+        fillRandomPool(state);
+    const poolOffset = state.randomPoolPos * RANDOM_DIGITS;
+    state.randomPoolPos += 1;
+    for (let i = 0; i < RANDOM_DIGITS; i++) {
+        const digit = state.randomPool[poolOffset + i] & MAX_DIGIT;
+        state.lastRandom[i] = digit;
+        state.outBuf[10 + i] = ENC[digit];
+    }
+}
+function incrementRandom(state) {
+    const random = state.lastRandom;
+    const out = state.outBuf;
+    for (let i = RANDOM_DIGITS - 1; i >= 0; i--) {
+        const value = random[i];
+        if (value < MAX_DIGIT) {
+            const next = value + 1;
+            random[i] = next;
+            out[10 + i] = ENC[next];
+            return true;
+        }
+        random[i] = 0;
+        out[10 + i] = ENC[0];
+    }
+    return false;
+}
+function nextTimestamp(previousTimestamp) {
+    let timestamp = Date.now();
+    if (timestamp > previousTimestamp)
+        return timestamp;
+    while (timestamp <= previousTimestamp) {
+        timestamp = Date.now();
+    }
+    return timestamp;
+}
+function setTimestamp(out, timestamp) {
+    // 10 chars of timestamp (48 bits, 5 bits per char, Crockford base32, MSB first).
+    // Divisors are exact powers of 2, so Math.floor division is float-precise.
+    out[0] =
+        ENC[Math.floor(timestamp / 35184372088832) & MAX_DIGIT]; // 2^45
+    out[1] =
+        ENC[Math.floor(timestamp / 1099511627776) & MAX_DIGIT]; // 2^40
+    out[2] =
+        ENC[Math.floor(timestamp / 34359738368) & MAX_DIGIT]; // 2^35
+    out[3] =
+        ENC[Math.floor(timestamp / 1073741824) & MAX_DIGIT]; // 2^30
+    out[4] = ENC[Math.floor(timestamp / 33554432) & MAX_DIGIT]; // 2^25
+    out[5] = ENC[Math.floor(timestamp / 1048576) & MAX_DIGIT]; // 2^20
+    out[6] = ENC[Math.floor(timestamp / 32768) & MAX_DIGIT]; // 2^15
+    out[7] = ENC[Math.floor(timestamp / 1024) & MAX_DIGIT]; // 2^10
+    out[8] = ENC[Math.floor(timestamp / 32) & MAX_DIGIT]; // 2^5
+    out[9] = ENC[timestamp & MAX_DIGIT]; // 2^0
+}
+function nextMonotonicTimestamp(lastTimestamp, now) {
+    if (now > lastTimestamp)
+        return now;
+    return lastTimestamp;
+}
+/** Create an isolated ULID generator with its own monotonic state. Useful for Workers. */
+export function createUlid() {
+    const state = {
+        lastTimestamp: -1,
+        lastRandom: new Uint8Array(RANDOM_DIGITS),
+        randomPool: new Uint8Array(BATCH * RANDOM_DIGITS),
+        randomPoolPos: BATCH,
+        outBuf: new Uint8Array(26),
+        decoder: new TextDecoder()
+    };
+    return function ulidFromState() {
+        const timestamp = nextMonotonicTimestamp(state.lastTimestamp, Date.now());
+        if (timestamp > state.lastTimestamp) {
+            state.lastTimestamp = timestamp;
+            setTimestamp(state.outBuf, state.lastTimestamp);
+            setRandomFromPool(state);
+            return state.decoder.decode(state.outBuf);
+        }
+        if (incrementRandom(state)) {
+            return state.decoder.decode(state.outBuf);
+        }
+        state.lastTimestamp = nextTimestamp(state.lastTimestamp);
+        setTimestamp(state.outBuf, state.lastTimestamp);
+        setRandomFromPool(state);
+        return state.decoder.decode(state.outBuf);
+    };
+}
+/** Default shared ULID generator. */
+export const ulid = createUlid();
+// Reverse lookup: charCode → base32 digit value (0-31), 0xFF = invalid.
+// Covers ASCII 0–127. Built once at module load.
+const DEC = new Uint8Array(128).fill(0xff);
+for (let i = 0; i < 32; i++)
+    DEC[ENCODING.charCodeAt(i)] = i;
+/** Extract the UNIX-ms timestamp from a ULID string. */
+export function timestamp(id) {
+    // 10 Crockford base32 chars → 50 bits → fits in a JS number (53-bit mantissa).
+    // Unrolled to avoid loop overhead.
+    return (DEC[id.charCodeAt(0)] * 35184372088832 + // 2^45
+        DEC[id.charCodeAt(1)] * 1099511627776 + // 2^40
+        DEC[id.charCodeAt(2)] * 34359738368 + // 2^35
+        DEC[id.charCodeAt(3)] * 1073741824 + // 2^30
+        DEC[id.charCodeAt(4)] * 33554432 + // 2^25
+        DEC[id.charCodeAt(5)] * 1048576 + // 2^20
+        DEC[id.charCodeAt(6)] * 32768 + // 2^15
+        DEC[id.charCodeAt(7)] * 1024 + // 2^10
+        DEC[id.charCodeAt(8)] * 32 + // 2^5
+        DEC[id.charCodeAt(9)] // 2^0
+    );
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "fast-ulid",
+	"version": "1.0.0",
+	"description": "Fastest spec-compliant monotonic ULID generator. ~62ns/id, zero dependencies.",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"test": "bun test",
+		"bench": "bun run test/bench.ts",
+		"prepublishOnly": "bun run build"
+	},
+	"keywords": [
+		"ulid",
+		"id",
+		"uuid",
+		"monotonic",
+		"sortable",
+		"unique",
+		"identifier",
+		"crockford",
+		"base32",
+		"fast"
+	],
+	"author": "Shaul Lavo",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/ShaulLavo/fast-ulid.git"
+	},
+	"homepage": "https://github.com/ShaulLavo/fast-ulid",
+	"bugs": {
+		"url": "https://github.com/ShaulLavo/fast-ulid/issues"
+	},
+	"devDependencies": {
+		"mitata": "^1.0.34",
+		"typescript": "^5.7.0",
+		"bun-types": "latest"
+	}
+}

package/src/index.ts

@@ -0,0 +1,161 @@
+// fast-ulid — Monotonic ULID implementation
+// - Lexicographically increasing even for multiple IDs in the same millisecond
+// - Monotonic under clock rollback by pinning to the last emitted timestamp
+// - `createUlid()` provides isolated state so callers can create one generator per Worker
+// - Zero dependencies, works in Node, Bun, Deno, and browsers
+
+const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+const RANDOM_DIGITS = 16
+const MAX_DIGIT = 31
+const BATCH = 8192
+
+interface UlidState {
+	lastTimestamp: number
+	lastRandom: Uint8Array<ArrayBuffer>
+	randomPool: Uint8Array<ArrayBuffer>
+	randomPoolPos: number
+	outBuf: Uint8Array<ArrayBuffer>
+	decoder: TextDecoder
+}
+
+const ENC = new Uint8Array(32)
+for (let i = 0; i < 32; i++) ENC[i] = ENCODING.charCodeAt(i)
+
+function fillRandomPool(state: UlidState): void {
+	crypto.getRandomValues(state.randomPool)
+	state.randomPoolPos = 0
+}
+
+function setRandomFromPool(state: UlidState): void {
+	if (state.randomPoolPos >= BATCH) fillRandomPool(state)
+
+	const poolOffset = state.randomPoolPos * RANDOM_DIGITS
+	state.randomPoolPos += 1
+
+	for (let i = 0; i < RANDOM_DIGITS; i++) {
+		const digit =
+			state.randomPool[poolOffset + i] & MAX_DIGIT
+		state.lastRandom[i] = digit
+		state.outBuf[10 + i] = ENC[digit]
+	}
+}
+
+function incrementRandom(state: UlidState): boolean {
+	const random = state.lastRandom
+	const out = state.outBuf
+	for (let i = RANDOM_DIGITS - 1; i >= 0; i--) {
+		const value = random[i]
+		if (value < MAX_DIGIT) {
+			const next = value + 1
+			random[i] = next
+			out[10 + i] = ENC[next]
+			return true
+		}
+
+		random[i] = 0
+		out[10 + i] = ENC[0]
+	}
+
+	return false
+}
+
+function nextTimestamp(previousTimestamp: number): number {
+	let timestamp = Date.now()
+	if (timestamp > previousTimestamp) return timestamp
+
+	while (timestamp <= previousTimestamp) {
+		timestamp = Date.now()
+	}
+
+	return timestamp
+}
+
+function setTimestamp(
+	out: Uint8Array,
+	timestamp: number
+): void {
+	// 10 chars of timestamp (48 bits, 5 bits per char, Crockford base32, MSB first).
+	// Divisors are exact powers of 2, so Math.floor division is float-precise.
+	out[0] =
+		ENC[Math.floor(timestamp / 35184372088832) & MAX_DIGIT] // 2^45
+	out[1] =
+		ENC[Math.floor(timestamp / 1099511627776) & MAX_DIGIT] // 2^40
+	out[2] =
+		ENC[Math.floor(timestamp / 34359738368) & MAX_DIGIT] // 2^35
+	out[3] =
+		ENC[Math.floor(timestamp / 1073741824) & MAX_DIGIT] // 2^30
+	out[4] = ENC[Math.floor(timestamp / 33554432) & MAX_DIGIT] // 2^25
+	out[5] = ENC[Math.floor(timestamp / 1048576) & MAX_DIGIT] // 2^20
+	out[6] = ENC[Math.floor(timestamp / 32768) & MAX_DIGIT] // 2^15
+	out[7] = ENC[Math.floor(timestamp / 1024) & MAX_DIGIT] // 2^10
+	out[8] = ENC[Math.floor(timestamp / 32) & MAX_DIGIT] // 2^5
+	out[9] = ENC[timestamp & MAX_DIGIT] // 2^0
+}
+
+function nextMonotonicTimestamp(
+	lastTimestamp: number,
+	now: number
+): number {
+	if (now > lastTimestamp) return now
+	return lastTimestamp
+}
+
+/** Create an isolated ULID generator with its own monotonic state. Useful for Workers. */
+export function createUlid(): () => string {
+	const state: UlidState = {
+		lastTimestamp: -1,
+		lastRandom: new Uint8Array(RANDOM_DIGITS),
+		randomPool: new Uint8Array(BATCH * RANDOM_DIGITS),
+		randomPoolPos: BATCH,
+		outBuf: new Uint8Array(26),
+		decoder: new TextDecoder()
+	}
+
+	return function ulidFromState(): string {
+		const timestamp = nextMonotonicTimestamp(
+			state.lastTimestamp,
+			Date.now()
+		)
+		if (timestamp > state.lastTimestamp) {
+			state.lastTimestamp = timestamp
+			setTimestamp(state.outBuf, state.lastTimestamp)
+			setRandomFromPool(state)
+			return state.decoder.decode(state.outBuf)
+		}
+
+		if (incrementRandom(state)) {
+			return state.decoder.decode(state.outBuf)
+		}
+
+		state.lastTimestamp = nextTimestamp(state.lastTimestamp)
+		setTimestamp(state.outBuf, state.lastTimestamp)
+		setRandomFromPool(state)
+		return state.decoder.decode(state.outBuf)
+	}
+}
+
+/** Default shared ULID generator. */
+export const ulid = createUlid()
+
+// Reverse lookup: charCode → base32 digit value (0-31), 0xFF = invalid.
+// Covers ASCII 0–127. Built once at module load.
+const DEC = new Uint8Array(128).fill(0xff)
+for (let i = 0; i < 32; i++) DEC[ENCODING.charCodeAt(i)] = i
+
+/** Extract the UNIX-ms timestamp from a ULID string. */
+export function timestamp(id: string): number {
+	// 10 Crockford base32 chars → 50 bits → fits in a JS number (53-bit mantissa).
+	// Unrolled to avoid loop overhead.
+	return (
+		DEC[id.charCodeAt(0)] * 35184372088832 + // 2^45
+		DEC[id.charCodeAt(1)] * 1099511627776 + // 2^40
+		DEC[id.charCodeAt(2)] * 34359738368 + // 2^35
+		DEC[id.charCodeAt(3)] * 1073741824 + // 2^30
+		DEC[id.charCodeAt(4)] * 33554432 + // 2^25
+		DEC[id.charCodeAt(5)] * 1048576 + // 2^20
+		DEC[id.charCodeAt(6)] * 32768 + // 2^15
+		DEC[id.charCodeAt(7)] * 1024 + // 2^10
+		DEC[id.charCodeAt(8)] * 32 + // 2^5
+		DEC[id.charCodeAt(9)] // 2^0
+	)
+}