fantomid 1.0.0

package/.husky/pre-commit

@@ -0,0 +1,2 @@
+prettier $(git diff --cached --name-only --diff-filter=ACMR | sed 's| |\\ |g') -uw
+git update-index --again

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Gabriel de Oliveira <gabrielhk3@gmail.com> (https://nocnitsa.com)
+
+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,34 @@
+# Fantom ID
+
+A tiny, universal ID generator compatible with JavaScript integers.
+Built for generating evenly distributed database identifiers at high concurrency.
+
+```js
+import fantomid from "fantomid";
+fantomid(); //=> 8209108814378532
+```
+
+Fantom ID works by generating a timestamp of 36 bits and 17 random bits in
+reverse order.
+
+Generating a timestamp ensures the IDs are distributed evenly across time,
+while the remaining bits of entropy allows different nodes to generate IDs at
+the exact same moment with a low chance of collision.
+
+```
+
+                                                      Bit-reverse
+                                                          ◄─┐
+     Random bits                   Timestamp                │
+ ┌─────────────────┐ ┌────────────────────────────────────┐ │
+ │11101001010100010│ │010000010110110011011011011000100100│ │
+ └─────────────────┘ └────────────────────────────────────┘
+
+ └───A2D2FF04C5────┘ └──────2025-11-24T19:13:45.994Z──────┘
+
+```
+
+The result is a JavaScript-safe integer represented in bit-reverse order, which
+prevents hotspots by keeping the monotonic part of the ID last.
+
+It works similarly to [UUIDv7](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html#name-uuid-version-7), but restrained to the size of JavaScript integers: 53 bits.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "fantomid",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "A tiny, universal ID generator compatible with JavaScript integers",
+  "keywords": [
+    "random",
+    "id",
+    "isomorphic"
+  ],
+  "author": "Gabriel de Oliveira <gabrielhk3@gmail.com> (https://nocnitsa.com)",
+  "license": "MIT",
+  "scripts": {
+    "prepare": "husky",
+    "build": "rimraf dist && pkgroll --sourcemap",
+    "test": "node --test --experimental-test-module-mocks **/*.spec.js"
+  },
+  "exports": {
+    "require": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "import": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@lukeed/csprng": "^1.1.0"
+  },
+  "devDependencies": {
+    "husky": "^9.1.7",
+    "pkgroll": "^2.21.3",
+    "prettier": "^3.6.2",
+    "rimraf": "^6.1.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/fantomid.js

@@ -0,0 +1,37 @@
+import { random } from "@lukeed/csprng";
+
+const EPOCH = new Date("2024-09-08");
+
+export function fantomid() {
+  const TIMESTAMP_LENGTH = 36;
+  const RANDOM_BITS_LENGTH = 17;
+  const TIMESTAMP_PRECISION_DIVIDER = 100;
+
+  const bits = new Array(TIMESTAMP_LENGTH + RANDOM_BITS_LENGTH);
+
+  // Generates a timestamp to be part of the key. This is
+  // inspired by how UUID v7 works: the idea is that this
+  // will guarantee keys are generated evenly across time.
+  const timestamp = Math.round(
+    // Use a more recent base date instead of the Unix Epoch to
+    // increase the amount of time we can represent in the timestamp.
+    (new Date() - EPOCH) /
+      // Decrease the precision of the timestamp to
+      // increase the amount of bits we can fit in a key.
+      TIMESTAMP_PRECISION_DIVIDER,
+  );
+  for (let i = 0; i < TIMESTAMP_LENGTH; i++) {
+    bits[TIMESTAMP_LENGTH + RANDOM_BITS_LENGTH - 1 - i] = (timestamp >> i) & 1;
+  }
+
+  // Generates a randomized part of the key. If multiple machines generate a
+  // key at the exact same time (limited by the precision of the timestamp),
+  // we are ensured to have a chance of collision of `1` in `2 ** RANDOM_BITS_LENGTH`.
+  const randomBytes = random(Math.ceil(RANDOM_BITS_LENGTH / 8));
+  for (let i = 0; i < RANDOM_BITS_LENGTH; i++) {
+    bits[RANDOM_BITS_LENGTH - 1 - i] =
+      (randomBytes[Math.floor(i / 8)] >> i % 8) & 1;
+  }
+
+  return Number("0b" + bits.reduce((id, bit) => id + bit, String()));
+}

package/src/fantomid.spec.js

@@ -0,0 +1,22 @@
+import { test, mock, before, it } from "node:test";
+import assert from "assert/strict";
+
+test("fantomid", () => {
+  let randomMock = mock.fn();
+  let fantomid;
+
+  before(async () => {
+    mock.module("@lukeed/csprng", { namedExports: { random: randomMock } });
+    ({ fantomid } = await import("./fantomid.js"));
+  });
+
+  it("should generate an id", () => {
+    randomMock.mock.mockImplementationOnce(() =>
+      Buffer.from([0xa2, 0xd2, 0xff, 0x04, 0xc5]),
+    );
+    console.log(Buffer.from([0xa2, 0xd2, 0xff, 0x04, 0xc5]));
+    mock.timers.enable({ now: new Date("2025-11-24T19:13:45.994Z") });
+    const id = fantomid();
+    assert.equal(id, 8209108814378532);
+  });
+});

package/src/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Generates an JavaScript-friendly unique ID.
+ *
+ * ```js
+ * import fantomId from "fantomid";
+ * fantomid(); //=> 5895736349537828
+ * ```
+ *
+ * @returns A random integer.
+ */
+export default function fantomid(): number;

package/src/index.js

@@ -0,0 +1,2 @@
+import { fantomid } from "./fantomid.js";
+export default fantomid;