@lucid-softworks/ulid 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucid Softworks
+
+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,13 @@
+# `@lucid-softworks/ulid`
+
+Canonical ULID generation, timestamp decoding, and monotonic generation with
+injectable clocks and randomness.
+
+```ts
+const id = ulid();
+const createdAt = decodeUlidTime(id);
+const nextId = monotonicUlidFactory();
+```
+
+Generated IDs are 26 uppercase Crockford Base32 characters. Custom random
+sources must return values in `[0, 1)`.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type RandomSource = () => number;
+/** Creates a canonical 26-character ULID. */
+export declare function ulid(time?: number, random?: RandomSource): string;
+/** Returns a ULID generator that remains monotonic within one millisecond. */
+export declare function monotonicUlidFactory(now?: () => number, random?: RandomSource): () => string;
+/** Extracts the millisecond timestamp from a canonical ULID. */
+export declare function decodeUlidTime(value: 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":"AAGA,MAAM,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC;AAExC,6CAA6C;AAC7C,wBAAgB,IAAI,CAClB,IAAI,GAAE,MAAmB,EACzB,MAAM,GAAE,YAA0B,GACjC,MAAM,CAER;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAM,MAAiB,EAC5B,MAAM,GAAE,YAA0B,GACjC,MAAM,MAAM,CAed;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASpD"}

package/dist/index.js

@@ -0,0 +1,75 @@
+const alphabet = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const maximumTime = 2 ** 48 - 1;
+/** Creates a canonical 26-character ULID. */
+export function ulid(time = Date.now(), random = Math.random) {
+    return encodeTime(time) + encodeRandom(random);
+}
+/** Returns a ULID generator that remains monotonic within one millisecond. */
+export function monotonicUlidFactory(now = Date.now, random = Math.random) {
+    let lastTime = -1;
+    let digits = [];
+    return () => {
+        const observed = now();
+        validateTime(observed);
+        const time = Math.max(observed, lastTime);
+        if (time > lastTime) {
+            digits = randomDigits(random);
+            lastTime = time;
+        }
+        else {
+            increment(digits);
+        }
+        return encodeTime(time) + digits.map((digit) => alphabet[digit]).join("");
+    };
+}
+/** Extracts the millisecond timestamp from a canonical ULID. */
+export function decodeUlidTime(value) {
+    if (!/^[0-9A-HJKMNP-TV-Z]{26}$/u.test(value) || value[0] > "7") {
+        throw new RangeError("value must be a canonical ULID");
+    }
+    let time = 0n;
+    for (const character of value.slice(0, 10)) {
+        time = time * 32n + BigInt(alphabet.indexOf(character));
+    }
+    return Number(time);
+}
+function encodeTime(time) {
+    validateTime(time);
+    let remaining = BigInt(time);
+    let output = "";
+    for (let index = 0; index < 10; index += 1) {
+        output = alphabet[Number(remaining % 32n)] + output;
+        remaining /= 32n;
+    }
+    return output;
+}
+function encodeRandom(random) {
+    return randomDigits(random)
+        .map((digit) => alphabet[digit])
+        .join("");
+}
+function randomDigits(random) {
+    return Array.from({ length: 16 }, () => {
+        const value = random();
+        if (!Number.isFinite(value) || value < 0 || value >= 1) {
+            throw new RangeError("random source must return values from 0 up to 1");
+        }
+        return Math.floor(value * 32);
+    });
+}
+function increment(digits) {
+    for (let index = digits.length - 1; index >= 0; index -= 1) {
+        if (digits[index] < 31) {
+            digits[index] = digits[index] + 1;
+            return;
+        }
+        digits[index] = 0;
+    }
+    throw new RangeError("monotonic ULID random space exhausted");
+}
+function validateTime(time) {
+    if (!Number.isSafeInteger(time) || time < 0 || time > maximumTime) {
+        throw new RangeError("time must be a non-negative 48-bit integer");
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@lucid-softworks/ulid",
+  "version": "0.0.0",
+  "description": "Canonical and monotonic ULID generation and timestamp decoding.",
+  "keywords": [
+    "javascript",
+    "typescript",
+    "ulid",
+    "utility"
+  ],
+  "homepage": "https://github.com/lucid-softworks/ulid#readme",
+  "bugs": {
+    "url": "https://github.com/lucid-softworks/ulid/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucid-softworks/ulid.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "bench": "vitest bench --run",
+    "bench:smoke": "VITEST_BENCHMARK_SMOKE=1 vitest bench --run",
+    "build": "tsc -p tsconfig.build.json",
+    "check": "oxfmt --check . && oxlint . && tsc -p tsconfig.json && tsc -p tsconfig.build.json && vitest run --coverage && publint && VITEST_BENCHMARK_SMOKE=1 vitest bench --run",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint .",
+    "pack:check": "publint",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@lucid-softworks/oxfmt-config": "^0.1.1",
+    "@lucid-softworks/oxlint-config": "^0.1.0",
+    "@lucid-softworks/tsconfig": "^0.1.0",
+    "@lucid-softworks/vitest-config": "^0.1.1",
+    "@types/node": "26.1.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "oxfmt": "0.60.0",
+    "oxlint": "1.75.0",
+    "publint": "0.3.22",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@11.16.0"
+}