node-flakes 1.1.0 → 2.1.0

package/README.md

@@ -25,37 +25,64 @@ The Node identity lib that provides:
 
 The sequence number increments for each subsequent id requested within the same millisecond.
 
+## Requirements
+
+- Node.js 18 or newer
+
 ## API
 
-### `require('node-flakes')`
+### `getBase62Provider()`
+
+Returns a function that creates base62 ids that sort lexicographically by time.
+
+```javascript
+const { getBase62Provider } = require('node-flakes');
 
-Requiring `node-flakes` returns a function. Even when required and executed multiple times the same instance gets returned. This is worth noting so that you don't have to go through extra effort to pass around the seed value or continue to re-initialize it every time.
+const nextId = getBase62Provider();
+const id = nextId();
+```
+
+```typescript
+import { getBase62Provider } from 'node-flakes';
+
+const nextId = getBase62Provider();
+const id = nextId();
+```
 
-### Using MACAddress or HostName as seed
+### `getBigIntIdProvider()`
 
-If no seed is provided, you can use `seedFromEnvironment` to use either the MAC address or host name plus the process id as the seed. This may not prevent duplicate seeds or id collisions, because of scenario where duplicate MACs or host names in your environment can occur.
+Returns a function that creates bigint ids ordered by time.
 
 ```javascript
-const flakes = require('node-flakes')();
-flakes.seedFromEnvironment() // this call returns a promise and can be awaited if in an async call
-  .then(
-    () => {
-      const id = flakes.create(); // ta-da
-    }
-  );
+const { getBigIntIdProvider } = require('node-flakes');
+
+const nextId = getBigIntIdProvider();
+const id = nextId();
+```
+
+### `getBigIntIdProviderFromMac(macNumber: bigint)`
+
+Uses a provided 48-bit node id (MAC address) to seed the generator.
+
+```javascript
+const { getBigIntIdProviderFromMac } = require('node-flakes');
+
+const nextId = getBigIntIdProviderFromMac(0x112233445566n);
+const id = nextId();
 ```
 
-### Unique seeds
+### `bigIntTo62(num: bigint)`
 
-Anything can seed the node id. node-flakes uses farmhash to create a unique 32 bit integer from whatever you have lying around. This needs to be unique for every instance creating ids.
+Converts a bigint into a 22-character base62 id that preserves lexicographic order.
 
 ```javascript
-const flakes = require('node-flakes')('Hey, look, a (terrible) string based seed.');
-const id = flakes.create(); // ta-da
+const { bigIntTo62 } = require('node-flakes');
+
+const id = bigIntTo62(123456789n);
 ```
 
 ### Speed
-Looks like this tops out around 20 / ms on modern processors. Do with that what you will :)
+Looks like this tops out around 500 / ms on comodity processors. Do with that what you will :)
 
 [travis-image]: https://travis-ci.org/arobson/node-flakes.svg?branch=master
 [travis-url]: https://travis-ci.org/arobson/node-flakes

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export declare function getBigIntIdProvider(nodeIdentifier?: string): () => bigint;
+export declare function getBase62Provider(nodeIdentifier?: string): () => string;
+export declare function getBase36Provider(nodeIdentifier: string): () => string;
+export declare function getBigIntIdProviderWithNodeId(nodeIdentifier: bigint): () => bigint;
+export declare function bigIntTo62(num: bigint): string;
+export declare function bigIntTo36(num: bigint): string;

package/dist/index.js

@@ -0,0 +1,104 @@
+"use strict";
+// * Note: This implementation is based on the 128-bit flake id algorithm
+// * developed by Boundary (github.com/boundary/flake) and implementations
+// * I've written in other languages.
+// * IMPORTANT: This implementation will require a custom epoch offset
+// * in order to avoid the 2038 problem. The epoch offset *cannot* be
+// * changed after the first id is generated in a given database.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBigIntIdProvider = getBigIntIdProvider;
+exports.getBase62Provider = getBase62Provider;
+exports.getBase36Provider = getBase36Provider;
+exports.getBigIntIdProviderWithNodeId = getBigIntIdProviderWithNodeId;
+exports.bigIntTo62 = bigIntTo62;
+exports.bigIntTo36 = bigIntTo36;
+const getmac_1 = __importDefault(require("getmac"));
+const farmhash_1 = __importDefault(require("farmhash"));
+const EPOCH = 1577862000000n; // 2020-01-01T00:00:00.000Z
+// Returns a function that is guaranteed to return a unique bigint
+// that will be k-ordered (time ordered) when compared to other ids
+function getBigIntIdProvider(nodeIdentifier) {
+    const nodeId = nodeIdentifier ? getNodeIdentifierAsBigInt(nodeIdentifier) : getMacAddressAsBigInt();
+    return getBigIntIdProviderWithNodeId(nodeId);
+}
+// Returns a function that is guaranteed to return a unique base62 string
+// that will lexicographically sort in k-order (time ordered) when compared to other ids
+// nodeIdentifier is an optional arbitrary string that is hashed to create the node id portion
+// if not provided, the host mac address will be used
+function getBase62Provider(nodeIdentifier) {
+    const idProvider = getBigIntIdProvider(nodeIdentifier);
+    return () => bigIntTo62(idProvider());
+}
+// Returns a function that is guaranteed to return a unique base36 string
+// that will lexicographically sort in k-order (time ordered) when compared to other ids
+function getBase36Provider(nodeIdentifier) {
+    const idProvider = getBigIntIdProvider(nodeIdentifier);
+    return () => bigIntTo36(idProvider());
+}
+// Creates a unique bigint id that is k-ordered (time ordered) when compared to other ids
+function getBigIntIdProviderWithNodeId(nodeIdentifier) {
+    let lastTime = 0n;
+    let iteration = 0n;
+    return () => {
+        const now = BigInt(Date.now()) - EPOCH;
+        if (now === lastTime) {
+            iteration++;
+            if (iteration > 0xffffn) {
+                throw new Error('Too many iterations in the same millisecond');
+            }
+        }
+        else if (now < lastTime) {
+            throw new Error('NTP clock skew detected');
+        }
+        else {
+            lastTime = now;
+            iteration = 0n;
+        }
+        return (lastTime << 64n) + (nodeIdentifier << 16n) + iteration;
+    };
+}
+// Converts a bigint to a base62 string that will sort lexicographically
+const BASE62_ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+function bigIntTo62(num) {
+    let result = '';
+    while (num > 0n) {
+        result = `${BASE62_ALPHABET[Number(num % 62n)]}${result}`;
+        num = num / 62n;
+    }
+    const len = 22 - result.length;
+    for (let i = 0; i < len; i++) {
+        result = `0${result}`;
+    }
+    return result;
+}
+// converts a bigint to a base36 string that will sort lexicographically
+const BASE36_ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+function bigIntTo36(num) {
+    let result = '';
+    while (num > 0n) {
+        result = `${BASE36_ALPHABET[Number(num % 36n)]}${result}`;
+        num = num / 36n;
+    }
+    const len = 25 - result.length;
+    for (let i = 0; i < len; i++) {
+        result = `0${result}`;
+    }
+    return result;
+}
+// Converts the host's mac address to a big int for use in the 48 bit
+// node id portion of the flake id
+function getMacAddressAsBigInt() {
+    return (0, getmac_1.default)()
+        .split(':')
+        .reduce((acc, octet, i) => {
+        return acc + (BigInt(`0x${octet}`) << BigInt(i * 8));
+    }, 0n);
+}
+// Take an arbitrary node identifier as a string, use farmhash to hash it to
+// a 48 bit number for use in the node id portion of the flake id
+function getNodeIdentifierAsBigInt(identifier) {
+    return BigInt(farmhash_1.default.hash32(identifier) & 0x0000FFFFFFFFFFFF);
+}

package/package.json

@@ -1,15 +1,31 @@
 {
   "name": "node-flakes",
-  "version": "1.1.0",
-  "description": "128-bit, k-ordered, lexicographically sortable, base 62, coordination free id generation for Node that stay crunchy in milk",
-  "main": "src/index.js",
+  "version": "2.1.0",
+  "description": "128-bit, k-ordered, lexicographically sortable, base 62, coordination-free id generation for Node that stays crunchy in milk",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
-    "lint": "semistandard",
-    "lint-fix": "semistandard --fix",
-    "pretest": "semistandard",
-    "test": "./node_modules/mocha/bin/mocha spec/**/*.spec.js",
-    "coverage": "nyc npm test",
-    "release": "standard-version"
+    "build": "tsc -p tsconfig.json",
+    "lint": "semistandard src/* --ext .js,.ts",
+    "lint-fix": "semistandard src/* --fix --ext .js,.ts",
+    "pretest": "npm run lint",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "release": "standard-version",
+    "prepublishOnly": "npm run build"
   },
   "author": "Alex Robson",
   "publishConfig": {
@@ -26,29 +42,63 @@
     "128 bit",
     "flake"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "devDependencies": {
-    "chai": "^4.2.0",
-    "coveralls": "^3.1.0",
-    "fauxdash": "^1.7.0",
-    "mocha": "^8.2.1",
-    "mocha-lcov-reporter": "^1.3.0",
-    "nyc": "^15.1.0",
-    "semistandard": "^16.0.0",
-    "standard-version": "^9.1.0"
+    "@types/node": "^18.19.0",
+    "@typescript-eslint/eslint-plugin": "^8.51.0",
+    "@typescript-eslint/parser": "^8.51.0",
+    "@vitest/coverage-v8": "^1.6.0",
+    "semistandard": "^17.0.0",
+    "standard-version": "^9.1.0",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
   },
   "dependencies": {
-    "basejump": "^1.1.0",
-    "farmhash": "^3.2.0",
-    "getmac": "^1.4.6"
+    "farmhash": "^5.0.1",
+    "getmac": "^6.6.0"
   },
   "semistandard": {
+    "parser": "@typescript-eslint/parser",
+    "parserOptions": {
+      "ecmaVersion": 2020,
+      "sourceType": "module",
+      "project": "./tsconfig.json"
+    },
+    "plugins": [
+      "@typescript-eslint"
+    ],
     "env": [
-      "mocha"
+      "node",
+      "es2020"
     ],
     "globals": [
-      "should",
+      "_",
+      "afterEach",
+      "beforeEach",
+      "describe",
       "expect",
-      "_"
+      "it",
+      "vi"
+    ],
+    "ignore": [
+      "dist/**",
+      "node_modules/**"
     ]
+  },
+  "vitest": {
+    "coverage": {
+      "provider": "v8",
+      "reporter": [
+        "text",
+        "lcov"
+      ],
+      "reportsDirectory": "coverage",
+      "exclude": [
+        "dist/**",
+        "node_modules/**"
+      ]
+    }
   }
 }

package/.editorconfig

@@ -1,27 +0,0 @@
-# This file is for unifying the coding style for different editors and IDEs
-# editorconfig.org
-
-root = true
-
-[*]
-end_of_line = lf
-charset = utf-8
-trim_trailing_whitespace = true
-insert_final_newline = true
-
-# Tabs in JS unless otherwise specified
-[**.js]
-indent_style = space
-indent_size = 2
-
-[**.jsx]
-indent_style = space
-indent_size = 2
-
-[**.html]
-indent_style = space
-indent_size = 2
-
-[**.css]
-indent_style = space
-indent_size = 2

package/.travis.yml

@@ -1,10 +0,0 @@
-sudo: required
-os:
-  - linux
-
-language: node_js
-node_js:
-  - "8"
-
-script:
-  - nyc npm test && nyc report --reporter=text-lcov | coveralls

package/CHANGELOG.md

@@ -1,14 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
-
-## 1.1.0 (2021-01-29)
-
-
-### Features
-
-* upgrade dependencies for Node 12+ ([8abb932](https://github.com/arobson/node-flakes/commit/8abb9320805d6b1e559b97c95f15b4f7a3131d5f))
-
-## 1.0.0
-
- initial commit

package/src/index.js

@@ -1,86 +0,0 @@
-const os = require('os');
-const getMac = require('getmac').getMac;
-const jump = require('basejump');
-const farmhash = require('farmhash');
-let instance;
-let instanceCount = 0;
-
-// 128 bit ids can generate up to
-//          1    1    2    2    3    3   3
-//     5    0    5    0    5    0    5   9
-// 340282366920938463463374607431768211456
-// unique ids.
-// By base-62 encoding them, we can shorten the length of the id to 22 places
-
-// via http://stackoverflow.com/questions/8482309/converting-javascript-integer-to-byte-array-and-back
-function longToBytes (long) {
-  // we want to represent the input as a 8-bytes array
-  const byteArray = [0, 0, 0, 0, 0, 0, 0, 0];
-  for (let index = 0; index < byteArray.length; index++) {
-    const byte = long & 0xff;
-    byteArray[index] = byte;
-    long = ((long - byte) / 256);
-  }
-  return byteArray.reverse();
-}
-
-async function getWorkerIdFromEnvironment () {
-  return new Promise(resolve => {
-    getMac((err, address) => {
-      if (err) {
-        address = os.hostname();
-      }
-      const bytes = getNodeBytesFromSeed(address);
-      resolve(bytes);
-    });
-  });
-}
-
-function getNodeBytesFromSeed (seed) {
-  const hash = farmhash.hash32(`${seed.toString()}|${process.pid}`);
-  return longToBytes(hash).splice(2);
-}
-
-const Flake = function (seed) {
-  this.lastMs = Date.now();
-  this.msCounter = 0;
-  this.msBytes = [0, 0];
-  this.index = ++instanceCount;
-  this.seed = seed;
-};
-
-Flake.prototype.create = function () {
-  this.updateTime();
-  const bytes = this.timestamp.concat(this.seed, this.msBytes).reverse();
-  return jump.toBase62(bytes, 22);
-};
-
-Flake.prototype.seedFromEnvironment = async function () {
-  this.seed = await getWorkerIdFromEnvironment();
-};
-
-Flake.prototype.updateTime = function () {
-  const now = Date.now();
-  let change = false;
-  if (now < this.lastMs) {
-    throw new Error('NTP is slewing system time backwards - node-flakes cannot issue ids while this is occurring.');
-  } else if (now > this.lastMs) {
-    change = true;
-    this.msCounter = 0;
-    this.msBytes = [0, 0];
-    this.lastMs = now;
-    this.timestamp = longToBytes(now);
-  } else {
-    this.msCounter++;
-    this.msBytes = [0, 0].concat(longToBytes(this.msCounter)).splice(-2, 2);
-  }
-  return change;
-};
-
-module.exports = function (seed) {
-  if (instance) {
-    return instance;
-  }
-  instance = new Flake(seed);
-  return instance;
-};