sparkid 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,20 @@
+/**
+ * Generate a unique, time-sortable, 22-char Base58 ID.
+ *
+ * Each ID is composed of:
+ *   - 8-char timestamp prefix (milliseconds, Base58-encoded, sortable)
+ *   - 14-char random suffix  (rejection-sampled from crypto.randomFillSync, no modulo bias)
+ *
+ * Properties:
+ *   - 22 characters, fixed length
+ *   - Lexicographically sortable by creation time
+ *   - URL-safe, no ambiguous characters
+ *   - ~58^14 (~1.8 x 10^24) random combinations per millisecond
+ *   - Cryptographically secure randomness (os.urandom / crypto.randomFillSync)
+ *
+ * Thread safety: Node.js is single-threaded. Worker threads get their own
+ * module instance, so the module-level state is naturally isolated.
+ */
+declare function generateId(): string;
+
+export { generateId };

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Generate a unique, time-sortable, 22-char Base58 ID.
+ *
+ * Each ID is composed of:
+ *   - 8-char timestamp prefix (milliseconds, Base58-encoded, sortable)
+ *   - 14-char random suffix  (rejection-sampled from crypto.randomFillSync, no modulo bias)
+ *
+ * Properties:
+ *   - 22 characters, fixed length
+ *   - Lexicographically sortable by creation time
+ *   - URL-safe, no ambiguous characters
+ *   - ~58^14 (~1.8 x 10^24) random combinations per millisecond
+ *   - Cryptographically secure randomness (os.urandom / crypto.randomFillSync)
+ *
+ * Thread safety: Node.js is single-threaded. Worker threads get their own
+ * module instance, so the module-level state is naturally isolated.
+ */
+declare function generateId(): string;
+
+export { generateId };

package/dist/index.js

@@ -0,0 +1,93 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  generateId: () => generateId
+});
+module.exports = __toCommonJS(index_exports);
+var import_crypto = require("crypto");
+var ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+var BASE = ALPHABET.length;
+var RANDOM_CHAR_COUNT = 14;
+var RANDOM_BATCH_SIZE = 1024;
+var TIMESTAMP_LOOKUP = Array.from({ length: BASE }, (_, i) => ALPHABET[i]);
+var RANDOM_LOOKUP = Array.from({ length: 256 }, (_, byte) => {
+  const value = byte & 63;
+  return value < BASE ? ALPHABET[value] : null;
+});
+var randomRawBuffer = Buffer.alloc(RANDOM_BATCH_SIZE);
+var timestampCacheMs = 0;
+var timestampCachePrefix = "";
+var randomCharBuffer = "";
+var randomCharPosition = 0;
+function encodeTimestamp(timestamp) {
+  timestampCacheMs = timestamp;
+  let remainder;
+  remainder = timestamp % BASE;
+  timestamp = Math.trunc(timestamp / BASE);
+  const char7 = TIMESTAMP_LOOKUP[remainder];
+  remainder = timestamp % BASE;
+  timestamp = Math.trunc(timestamp / BASE);
+  const char6 = TIMESTAMP_LOOKUP[remainder];
+  remainder = timestamp % BASE;
+  timestamp = Math.trunc(timestamp / BASE);
+  const char5 = TIMESTAMP_LOOKUP[remainder];
+  remainder = timestamp % BASE;
+  timestamp = Math.trunc(timestamp / BASE);
+  const char4 = TIMESTAMP_LOOKUP[remainder];
+  remainder = timestamp % BASE;
+  timestamp = Math.trunc(timestamp / BASE);
+  const char3 = TIMESTAMP_LOOKUP[remainder];
+  remainder = timestamp % BASE;
+  timestamp = Math.trunc(timestamp / BASE);
+  const char2 = TIMESTAMP_LOOKUP[remainder];
+  remainder = timestamp % BASE;
+  timestamp = Math.trunc(timestamp / BASE);
+  const char1 = TIMESTAMP_LOOKUP[remainder];
+  timestampCachePrefix = TIMESTAMP_LOOKUP[timestamp] + char1 + char2 + char3 + char4 + char5 + char6 + char7;
+}
+function refillRandom() {
+  (0, import_crypto.randomFillSync)(randomRawBuffer);
+  const lookup = RANDOM_LOOKUP;
+  let result = "";
+  for (let i = 0; i < RANDOM_BATCH_SIZE; i++) {
+    const char = lookup[randomRawBuffer[i]];
+    if (char !== null) result += char;
+  }
+  randomCharBuffer = result;
+  randomCharPosition = 0;
+}
+function generateId() {
+  const timestamp = Date.now();
+  if (timestamp !== timestampCacheMs) {
+    encodeTimestamp(timestamp);
+  }
+  while (randomCharPosition + RANDOM_CHAR_COUNT > randomCharBuffer.length) {
+    refillRandom();
+  }
+  const position = randomCharPosition;
+  randomCharPosition = position + RANDOM_CHAR_COUNT;
+  return timestampCachePrefix + randomCharBuffer.slice(position, position + RANDOM_CHAR_COUNT);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  generateId
+});

package/dist/index.mjs

@@ -0,0 +1,68 @@
+// src/index.ts
+import { randomFillSync } from "crypto";
+var ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+var BASE = ALPHABET.length;
+var RANDOM_CHAR_COUNT = 14;
+var RANDOM_BATCH_SIZE = 1024;
+var TIMESTAMP_LOOKUP = Array.from({ length: BASE }, (_, i) => ALPHABET[i]);
+var RANDOM_LOOKUP = Array.from({ length: 256 }, (_, byte) => {
+  const value = byte & 63;
+  return value < BASE ? ALPHABET[value] : null;
+});
+var randomRawBuffer = Buffer.alloc(RANDOM_BATCH_SIZE);
+var timestampCacheMs = 0;
+var timestampCachePrefix = "";
+var randomCharBuffer = "";
+var randomCharPosition = 0;
+function encodeTimestamp(timestamp) {
+  timestampCacheMs = timestamp;
+  let remainder;
+  remainder = timestamp % BASE;
+  timestamp = Math.trunc(timestamp / BASE);
+  const char7 = TIMESTAMP_LOOKUP[remainder];
+  remainder = timestamp % BASE;
+  timestamp = Math.trunc(timestamp / BASE);
+  const char6 = TIMESTAMP_LOOKUP[remainder];
+  remainder = timestamp % BASE;
+  timestamp = Math.trunc(timestamp / BASE);
+  const char5 = TIMESTAMP_LOOKUP[remainder];
+  remainder = timestamp % BASE;
+  timestamp = Math.trunc(timestamp / BASE);
+  const char4 = TIMESTAMP_LOOKUP[remainder];
+  remainder = timestamp % BASE;
+  timestamp = Math.trunc(timestamp / BASE);
+  const char3 = TIMESTAMP_LOOKUP[remainder];
+  remainder = timestamp % BASE;
+  timestamp = Math.trunc(timestamp / BASE);
+  const char2 = TIMESTAMP_LOOKUP[remainder];
+  remainder = timestamp % BASE;
+  timestamp = Math.trunc(timestamp / BASE);
+  const char1 = TIMESTAMP_LOOKUP[remainder];
+  timestampCachePrefix = TIMESTAMP_LOOKUP[timestamp] + char1 + char2 + char3 + char4 + char5 + char6 + char7;
+}
+function refillRandom() {
+  randomFillSync(randomRawBuffer);
+  const lookup = RANDOM_LOOKUP;
+  let result = "";
+  for (let i = 0; i < RANDOM_BATCH_SIZE; i++) {
+    const char = lookup[randomRawBuffer[i]];
+    if (char !== null) result += char;
+  }
+  randomCharBuffer = result;
+  randomCharPosition = 0;
+}
+function generateId() {
+  const timestamp = Date.now();
+  if (timestamp !== timestampCacheMs) {
+    encodeTimestamp(timestamp);
+  }
+  while (randomCharPosition + RANDOM_CHAR_COUNT > randomCharBuffer.length) {
+    refillRandom();
+  }
+  const position = randomCharPosition;
+  randomCharPosition = position + RANDOM_CHAR_COUNT;
+  return timestampCachePrefix + randomCharBuffer.slice(position, position + RANDOM_CHAR_COUNT);
+}
+export {
+  generateId
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "sparkid",
+  "version": "1.0.0",
+  "description": "Fast, time-sortable, 22-char Base58 unique ID generator",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "bench": "tsx bench/benchmark.ts"
+  },
+  "keywords": [
+    "id",
+    "uuid",
+    "unique",
+    "sortable",
+    "base58",
+    "ulid",
+    "ksuid"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}