@eliware/snowflake 1.1.1 → 1.1.3

package/README.md

@@ -1,128 +1,63 @@
-# [![eliware.org](https://eliware.org/logos/brand.png)](https://discord.gg/M6aTR9eTwN)
+# @eliware/snowflake
 
-## @eliware/snowflake [![npm version](https://img.shields.io/npm/v/@eliware/snowflake.svg)](https://www.npmjs.com/package/@eliware/snowflake)[![license](https://img.shields.io/github/license/eliware/snowflake.svg)](LICENSE)[![build status](https://github.com/eliware/snowflake/actions/workflows/nodejs.yml/badge.svg)](https://github.com/eliware/snowflake/actions)
+[![npm version](https://img.shields.io/npm/v/@eliware/snowflake.svg)](https://www.npmjs.com/package/@eliware/snowflake) [![build status](https://github.com/eliware/snowflake/actions/workflows/nodejs.yml/badge.svg)](https://github.com/eliware/snowflake/actions)
 
-> A snowflake for Node.js (Insert Brief Description)
-
----
-
-## Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Usage](#usage)
-  - [ESM Example](#esm-example)
-  - [CommonJS Example](#commonjs-example)
-- [API](#api)
-- [TypeScript](#typescript)
-- [Testing](#testing)
-- [License](#license)
+A production-ready, BigInt-safe Snowflake ID generator for Node.js. IDs are returned as decimal strings so they remain safe across JSON, databases, and JavaScript runtimes.
 
 ## Features
 
-- Minimal, dependency-light Snowflake ID generator compatible with Discord-style bit layout.
-- BigInt-safe implementation to preserve full 64-bit IDs.
-- Works in both ESM and CommonJS environments.
-- Configurable epoch and worker ID via a factory function.
-- Includes TypeScript declarations and basic tests.
+- Custom epoch; the default is `365662380000n` (`1981-08-03T04:53:00Z`).
+- 42-bit millisecond timestamp, 5-bit worker ID, 5-bit process ID, and 12-bit sequence.
+- Clock rollback protection and sequence overflow handling.
+- Configurable worker/process identity for distributed deployments.
+- Injectable clock for deterministic tests.
+- Range validation and timestamp-capacity checks.
+- Native ESM, TypeScript declarations, and no runtime dependencies.
 
 ## Installation
 
-Install from npm:
-
 ```bash
 npm install @eliware/snowflake
 ```
 
 ## Usage
 
-### ESM Example
-
 ```js
-// ESM (index.mjs)
-import generate, { createSnowflakeGenerator } from './index.mjs';
+import generate, { createSnowflakeGenerator } from '@eliware/snowflake';
 
-// default generator (workerId: 0)
-console.log('id:', generate());
+console.log(generate());
 
-// create a generator for a specific worker ID
-const gen = createSnowflakeGenerator({ workerId: 1 });
-console.log('worker 1 id:', gen());
+// Set a unique worker ID for each replica or node.
+const replicaGenerator = createSnowflakeGenerator({
+  workerId: 3,
+  processId: 7,
+});
+console.log(replicaGenerator());
 ```
 
-### CommonJS Example
-
-```js
-// CommonJS (index.cjs)
-const generate = require('./index.cjs');
-const { createSnowflakeGenerator } = require('./index.cjs');
-
-console.log('id:', generate());
-
-const gen = createSnowflakeGenerator({ workerId: 2 });
-console.log('worker 2 id:', gen());
-```
+For Kubernetes, assign each replica a stable `workerId` from configuration. `processId` defaults to `process.pid % 32`, but should be explicitly configured when process identity must be coordinated across hosts.
 
 ## API
 
-### createSnowflakeGenerator(options?) => () => string
-
-- options.epoch: number | bigint (default: 1420070400000) — base epoch in milliseconds (Discord epoch: 2015-01-01T00:00:00.000Z).
-- options.workerId: number (default: 0) — numeric worker/node ID (10-bit value).
-
-Returns a zero-argument function that generates a new Snowflake ID (as a decimal string) each call.
-
-Behavior notes:
-- Timestamp uses (Date.now() - epoch) shifted left 22 bits.
-- Worker ID occupies 10 bits, sequence counter occupies 12 bits.
-- The generator waits for the next millisecond if more than 4095 IDs are requested in the same millisecond.
-
-### Default export: generate()
+`createSnowflakeGenerator(options?)` returns a function that generates decimal-string IDs.
 
-A ready-to-use generator (workerId 0). It returns a decimal string representation of the Snowflake ID.
+| Option | Default | Description |
+| --- | --- | --- |
+| `epoch` | `365662380000n` | Unix epoch in milliseconds. |
+| `workerId` | `0` | Worker/node ID, from `0` to `31`. |
+| `processId` | `process.pid % 32` | Process ID, from `0` to `31`. |
+| `now` | `Date.now` | Injectable millisecond clock. |
 
-## TypeScript
+The exports `generate` and `snowflake` are ready-to-use default generators. `constants` exposes the bit layout and default epoch.
 
-Type definitions are included (index.d.ts). Example signatures:
-
-```ts
-export function createSnowflakeGenerator(options?: { epoch?: number | bigint; workerId?: number }): () => string;
-export const generate: () => string;
-export default generate;
-```
-
-## Testing
-
-A small Jest test suite is included (index.test.mjs / index.test.cjs) that verifies:
-
-- Generated IDs are numeric strings parseable to BigInt.
-- Consecutive IDs are monotonically increasing.
-- Worker ID bits are encoded correctly.
-- Timestamp portion decodes to a recent time.
-
-Run tests with:
+## Testing and linting
 
 ```bash
 npm test
+npm run test:gaps
+npm run lint
 ```
 
----
-
-## Support
-
-For help, questions, or to chat with the author and community, visit:
-
-[![Discord](https://eliware.org/logos/discord_96.png)](https://discord.gg/M6aTR9eTwN)[![eliware.org](https://eliware.org/logos/eliware_96.png)](https://discord.gg/M6aTR9eTwN)
-
-**[eliware.org on Discord](https://discord.gg/M6aTR9eTwN)**
-
 ## License
 
-[MIT © 2025 Eli Sterling, eliware.org](LICENSE)
-
-## Links
-
-- [Home Page](https://eliware.org)
-- [GitHub](https://github.com/eliware/snowflake)
-- [npm](https://www.npmjs.com/package/@eliware/snowflake)
-- [Discord](https://discord.gg/M6aTR9eTwN)
+MIT © Eli Sterling, eliware.org

package/index.d.ts

@@ -1,3 +1,19 @@
-export function createSnowflakeGenerator(options?: { epoch?: number | bigint; workerId?: number }): () => string;
+export interface SnowflakeGeneratorOptions {
+  epoch?: number | bigint;
+  workerId?: number | bigint;
+  processId?: number | bigint;
+  now?: () => number | bigint;
+}
+
+export interface SnowflakeConstants {
+  readonly epoch: bigint;
+  readonly sequenceBits: bigint;
+  readonly processBits: bigint;
+  readonly workerBits: bigint;
+}
+
+export function createSnowflakeGenerator(options?: SnowflakeGeneratorOptions): () => string;
 export const generate: () => string;
+export const snowflake: typeof generate;
+export const constants: SnowflakeConstants;
 export default generate;

package/index.mjs

@@ -1,34 +1,85 @@
-// Snowflake generator (ESM)
-const DEFAULT_EPOCH = 1420070400000n; // Discord epoch: 2015-01-01T00:00:00.000Z
+/**
+ * BigInt-safe Snowflake ID generation.
+ *
+ * Layout (least significant bit first):
+ *   sequence: 12 bits
+ *   process:    5 bits
+ *   worker:     5 bits
+ *   timestamp: 42 bits
+ */
+const DEFAULT_EPOCH = 365662380000n; // 1981-08-03T04:53:00.000Z (fixed EST input)
+const SEQUENCE_BITS = 12n;
+const PROCESS_BITS = 5n;
+const WORKER_BITS = 5n;
+const PROCESS_MASK = (1n << PROCESS_BITS) - 1n;
+const WORKER_MASK = (1n << WORKER_BITS) - 1n;
+const SEQUENCE_MASK = (1n << SEQUENCE_BITS) - 1n;
+const MAX_TIMESTAMP = (1n << 42n) - 1n;
 
-export function createSnowflakeGenerator({ epoch = DEFAULT_EPOCH, workerId = 0 } = {}) {
-  const _epoch = BigInt(epoch);
-  const _workerId = BigInt(workerId) & 0x3ffn; // 10 bits
-  let lastTimestamp = 0n;
+const defaultNow = () => Date.now();
+
+function validatePart(value, name, mask) {
+  const parsed = BigInt(value);
+  if (parsed < 0n || parsed > mask) {
+    throw new RangeError(`${name} must be between 0 and ${mask}`);
+  }
+  return parsed;
+}
+
+/**
+ * Create a generator. Configure a unique workerId per replica and processId
+ * per process when generating IDs from multiple instances.
+ */
+export function createSnowflakeGenerator({
+  epoch = DEFAULT_EPOCH,
+  workerId = 0,
+  processId = process.pid % 32,
+  now = defaultNow,
+} = {}) {
+  const baseEpoch = BigInt(epoch);
+  const worker = validatePart(workerId, 'workerId', WORKER_MASK);
+  const processNumber = validatePart(processId, 'processId', PROCESS_MASK);
+  if (typeof now !== 'function') throw new TypeError('now must be a function');
+
+  let lastTimestamp = -1n;
   let sequence = 0n;
 
+  function readTime() {
+    const timestamp = BigInt(now());
+    if (timestamp < baseEpoch) throw new RangeError('current time must not be before epoch');
+    return timestamp;
+  }
+
   return function generate() {
-    let now = BigInt(Date.now());
+    let timestamp = readTime();
+    if (timestamp < lastTimestamp) timestamp = lastTimestamp;
 
-    if (now === lastTimestamp) {
-      sequence = (sequence + 1n) & 0xfffn; // 12 bits
+    if (timestamp === lastTimestamp) {
+      sequence = (sequence + 1n) & SEQUENCE_MASK;
       if (sequence === 0n) {
-        // Sequence overflow in the same millisecond — wait for next ms
-        while (now <= lastTimestamp) {
-          now = BigInt(Date.now());
-        }
+        do timestamp = readTime(); while (timestamp <= lastTimestamp);
       }
     } else {
       sequence = 0n;
     }
 
-    lastTimestamp = now;
-
-    const id = ((now - _epoch) << 22n) | (_workerId << 12n) | sequence;
-    return id.toString();
+    const elapsed = timestamp - baseEpoch;
+    if (elapsed > MAX_TIMESTAMP) throw new RangeError('timestamp exceeds Snowflake capacity');
+    lastTimestamp = timestamp;
+    return ((elapsed << (WORKER_BITS + PROCESS_BITS + SEQUENCE_BITS)) |
+      (worker << (PROCESS_BITS + SEQUENCE_BITS)) |
+      (processNumber << SEQUENCE_BITS) |
+      sequence).toString();
   };
 }
 
-// Default generator (workerId 0)
 export const generate = createSnowflakeGenerator();
+export const snowflake = generate;
+export const constants = Object.freeze({
+  epoch: DEFAULT_EPOCH,
+  sequenceBits: SEQUENCE_BITS,
+  processBits: PROCESS_BITS,
+  workerBits: WORKER_BITS,
+});
+
 export default generate;

package/package.json

@@ -1,27 +1,26 @@
 {
     "name": "@eliware/snowflake",
     "type": "module",
-    "version": "1.1.1",
-    "description": "A minimal Node.js Snowflake ID generator (Discord-compatible). Provides BigInt-safe generators for ESM and CommonJS with configurable epoch and worker ID.",
-    "main": "index.cjs",
-    "module": "index.mjs",
+    "version": "1.1.3",
+    "description": "A minimal Node.js Snowflake ID generator (Discord-compatible). Provides BigInt-safe generators with configurable epoch and worker ID.",
+    "main": "index.mjs",
     "types": "index.d.ts",
     "files": [
         "index.mjs",
-        "index.cjs",
         "index.d.ts",
         "README.md",
         "LICENSE"
     ],
     "exports": {
         ".": {
-            "import": "./index.mjs",
-            "require": "./index.cjs",
-            "types": "./index.d.ts"
+            "types": "./index.d.ts",
+            "import": "./index.mjs"
         }
     },
     "scripts": {
-        "test": "npx --node-options=\"--experimental-vm-modules --no-warnings\" jest --detectOpenHandles --silent"
+        "test": "npx --node-options=\"--experimental-vm-modules --no-warnings\" jest --detectOpenHandles --silent --coverage",
+        "test:gaps": "npm test -- --coverageReporters=text 2>&1 | awk '!/100%/'",
+        "lint": "npx oxlint ."
     },
     "repository": {
         "type": "git",
@@ -35,8 +34,7 @@
         "unique-id",
         "bigint",
         "nodejs",
-        "esm",
-        "cjs"
+        "esm"
     ],
     "author": "Eli Sterling, eliware.org <eli@eliware.org>",
     "license": "MIT",
@@ -45,17 +43,16 @@
     },
     "homepage": "https://github.com/eliware/snowflake#readme",
     "devDependencies": {
-        "jest": "^30.0.4"
+        "jest": "^30.4.2"
     },
     "jest": {
         "testEnvironment": "node",
         "testMatch": [
             "**/?(*.)+(spec|test).[jt]s?(x)",
-            "**/?(*.)+(spec|test).mjs",
-            "**/?(*.)+(spec|test).cjs"
+            "**/?(*.)+(spec|test).mjs"
         ]
     },
     "dependencies": {
-        "@eliware/common": "^1.1.1"
+        "@eliware/common": "^1.1.4"
     }
 }

package/index.cjs

@@ -1,37 +0,0 @@
-// Snowflake generator (CommonJS)
-const DEFAULT_EPOCH = 1420070400000n; // Discord epoch: 2015-01-01T00:00:00.000Z
-
-function createSnowflakeGenerator({ epoch = DEFAULT_EPOCH, workerId = 0 } = {}) {
-  const _epoch = BigInt(epoch);
-  const _workerId = BigInt(workerId) & 0x3ffn; // 10 bits
-  let lastTimestamp = 0n;
-  let sequence = 0n;
-
-  return function generate() {
-    let now = BigInt(Date.now());
-
-    if (now === lastTimestamp) {
-      sequence = (sequence + 1n) & 0xfffn; // 12 bits
-      if (sequence === 0n) {
-        // Sequence overflow in the same millisecond — wait for next ms
-        while (now <= lastTimestamp) {
-          now = BigInt(Date.now());
-        }
-      }
-    } else {
-      sequence = 0n;
-    }
-
-    lastTimestamp = now;
-
-    const id = ((now - _epoch) << 22n) | (_workerId << 12n) | sequence;
-    return id.toString();
-  };
-}
-
-// Default generator (workerId 0)
-const generate = createSnowflakeGenerator();
-
-module.exports = generate;
-module.exports.generate = generate;
-module.exports.createSnowflakeGenerator = createSnowflakeGenerator;