@eliware/snowflake 1.1.5 → 12.0.0

package/AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS.md
+
+## Project
+
+Build a Snowflake ID library with Node.js 26. Use native ESM.
+
+## Scope and boundaries
+
+Keep this package focused on Snowflake ID generation.
+Do not use validation to publish, deploy, or change external systems.
+
+## Layout
+
+Keep implementation modules under `src/` and matching tests under `tests/`.
+Keep user guides under `docs/`, examples under `examples/`, and rules under `specs/`.
+
+## Development
+
+Keep each module focused on one purpose.
+Keep TypeScript declarations beside their matching ESM modules.
+
+## Validation
+
+Use Node.js 26 and native ESM.
+Run `npm test` for aggregate validation.
+Run `npm run lint` for lint checks.
+Run `npm run audit` for dependency checks.
+Run `npm run format` to format files.
+Run `npm run format:check` to check file format.
+Run `npm run typecheck` to check TypeScript declarations.
+Run `npm run pack` to check package contents.
+
+## Security
+
+Protect credentials, tokens, secrets, private data, and machine-specific values.
+Treat Snowflake IDs as identifiers, not secrets.
+
+## Changes
+
+Keep docs current and direct.
+Follow the Eliware Operations approval process for release changes.
+Do not treat validation as release approval.
+
+## Library
+
+Export the public generator API from `src/index.mjs`.
+Return each generated ID as a decimal string.
+Keep declarations in `src/` beside their matching ESM modules.
+
+## npm publication
+
+Publish the `@eliware/snowflake` package only after release approval.
+Use `package.json.version` as the package version.
+Run package validation before publication review.

package/LICENSE

@@ -1,6 +1,6 @@
-# MIT License
+MIT License
 
-Copyright (c) 2025 Eli Sterling, eliware.org
+Copyright (c) 2026 Eliware
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,81 +1,112 @@
-# @eliware/snowflake
+# [![eliware.org](https://eliware.org/logos/brand.png)](https://discord.gg/M6aTR9eTwN)
 
-[![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)
+## @eliware/snowflake [![npm](https://img.shields.io/npm/v/@eliware/snowflake)](https://www.npmjs.com/package/@eliware/snowflake) [![License](https://img.shields.io/github/license/eliware/snowflake)](https://github.com/eliware/snowflake/blob/main/LICENSE) [![CI](https://github.com/eliware/snowflake/actions/workflows/ci.yaml/badge.svg)](https://github.com/eliware/snowflake/actions/workflows/ci.yaml)
 
-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.
+A Node.js Snowflake ID generator with BigInt support and a configurable epoch.
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Setup](#setup)
+- [Usage](#usage)
+- [Development](#development)
+- [Testing](#testing)
+- [Troubleshooting](#troubleshooting)
+- [Security](#security)
+- [API](#api)
+- [Packaging](#packaging)
+- [Examples](#examples)
+- [Support](#support)
+- [Links](#links)
+- [License](#license)
 
 ## Features
 
-- 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.
+Create time-ordered IDs with a custom epoch and unique worker and process IDs.
+The IDs use the Discord Snowflake bit layout.
+Receive decimal strings that preserve every ID bit in JavaScript and JSON.
+The generator handles clock rollback and reports sequence overflow.
 
 ## Requirements
 
-- Node.js 26 or newer
+Use Node.js 26 or later.
+Assign a unique worker and process ID pair to each active generator.
 
-## Installation
+## Setup
 
-```bash
+Install the package:
+
+```text
 npm install @eliware/snowflake
 ```
 
 ## Usage
 
+Create a generator with a unique identity:
+
 ```js
-import generate, { createSnowflakeGenerator } from '@eliware/snowflake';
+import { createSnowflakeGenerator } from "@eliware/snowflake";
 
+const generate = createSnowflakeGenerator({ workerId: 3, processId: 7 });
 console.log(generate());
-
-// Set a unique worker ID for each replica or node.
-const replicaGenerator = createSnowflakeGenerator({
-  workerId: 3,
-  processId: 7,
-});
-console.log(replicaGenerator());
 ```
 
-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.
+See [release notes](RELEASE_NOTES.md) for changes by version.
+See the [usage guide](docs/usage.md) for options, ID fields, and limits.
+
+## Development
+
+Read [user documentation](docs/README.md), [examples](examples/README.md), and [specifications](specs/README.md).
+
+## Testing
+
+Run `npm test` for all required checks.
+Run `npm run lint`, `npm run format:check`, `npm run audit`, `npm run typecheck`, or `npm run pack` for focused checks.
+
+## Troubleshooting
+
+See [troubleshooting](docs/troubleshooting.md) for error causes and recovery steps.
+
+## Security
+
+Treat IDs as identifiers, not secrets.
+IDs reveal timestamp and deployment data.
+Do not use IDs as authentication tokens.
 
 ## API
 
-`createSnowflakeGenerator(options?)` returns a function that generates decimal-string IDs.
+`createSnowflakeGenerator(options)` returns a function that creates decimal-string IDs.
+Options set the epoch, worker ID, process ID, and clock.
+The default generator is `generate`, `snowflake`, and the default export.
+The `constants` export provides the default epoch and bit sizes.
 
-| 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. |
+## Packaging
 
-The exports `generate` and `snowflake` are ready-to-use default generators. `constants` exposes the bit layout and default epoch.
+The package provides native ESM code and TypeScript declarations.
+It has no runtime dependencies.
 
-## TypeScript
+## Examples
 
-TypeScript declarations are included for all public exports and options.
+Run the [native ESM example](examples/example.mjs) with Node.js 26 or later.
 
-## Errors / Troubleshooting
+## Support
 
-Configuration values outside the supported ranges throw `RangeError`; a non-function clock throws `TypeError`; timestamps before the epoch or beyond Snowflake capacity throw `RangeError`. Configure unique `workerId` and `processId` values across distributed generators.
+For help, questions, or to chat with the author and community, visit:
 
-## Testing and linting
+[![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)
 
-```bash
-npm test
-npm run test:gaps
-npm run lint
-npm run typecheck
-npm run pack
-```
+**[eliware.org on Discord](https://discord.gg/M6aTR9eTwN)**
 
-## Security
+## Links
 
-Snowflake IDs are unique identifiers, not secrets. Do not use them as authentication tokens or assume they conceal timestamp and deployment information.
+- [Home Page](https://eliware.org)
+- [GitHub Org](https://github.com/eliware)
+- [GitHub Repo](https://github.com/eliware/snowflake)
+- [Bug Reports](https://github.com/eliware/snowflake/issues)
+- [npm](https://www.npmjs.com/package/@eliware/snowflake)
+- [Discord](https://discord.gg/M6aTR9eTwN)
 
 ## License
 
-MIT © Eli Sterling, eliware.org
+[MIT © Eliware](LICENSE)

package/RELEASE_NOTES.md

@@ -0,0 +1,65 @@
+# Release Notes
+
+## 12.0.0 — 2026-10-12
+
+### Changed
+
+- Moved library code to `src/` and added matching tests under `tests/`.
+- Added user guides, navigation indexes, repository rules, and a runnable example index.
+- Expanded user guides with option defaults, ID fields, identity rules, limits, and error actions.
+- Updated package metadata, version, contents, license, and dependency lock.
+- Added repository ID metadata and v12 specification files.
+- Updated ignore rules and removed obsolete Jest result settings.
+- Updated validation scripts and the shared test harness to version 12.
+- Replaced the CI workflow and added an npm publication workflow with provenance.
+- Updated Knit commands and its repository path.
+- Updated README and contributor rules to match the v12 conventions.
+- Kept the public API and decimal string output unchanged.
+
+## 2.0.0 — 2026-08-28
+
+### Added
+
+- Added fail-fast sequence overflow handling and expanded boundary coverage.
+- Added TypeScript declarations for public exports and options.
+
+### Changed
+
+- Adopted `@eliware/test` for tests and lint checks.
+- Updated package metadata, documentation, and CI for Node.js 26 or newer.
+- Reorganized production modules under `src/` and tests under `tests/`.
+
+### Breaking changes
+
+- Changed the `test` and `lint` scripts to use `@eliware/test`.
+
+## 1.1.5 — 2026-08-07
+
+### Changed
+
+- Aligned the repository layout, scripts, documentation, and package contents.
+- Added TypeScript declaration checks and package validation.
+- Moved tests under `tests/` and added a runnable native ESM example.
+- Removed the legacy CommonJS package entry point.
+
+## 1.1.4 — 2026-08-07
+
+### Changed
+
+- Removed the unused `@eliware/common` runtime dependency.
+- Added manual GitHub Actions workflow dispatch support.
+
+## 1.1.2 — 2026-08-06
+
+### Added
+
+- Added a configurable BigInt-safe Snowflake ID generator.
+- Added the Eliware epoch, worker IDs, and process IDs.
+- Added clock rollback protection and sequence overflow handling.
+- Added injectable clocks, range checks, and timestamp capacity checks.
+- Added TypeScript declarations for public options and exports.
+
+### Changed
+
+- Removed CommonJS entry points and tests. The package now uses native ESM.
+- Expanded deployment and bit layout guidance.

package/docs/README.md

@@ -0,0 +1,4 @@
+# Documentation
+
+- [Usage](usage.md)
+- [Troubleshooting](troubleshooting.md)

package/docs/troubleshooting.md

@@ -0,0 +1,48 @@
+# Troubleshooting
+
+## Error reference
+
+| Error                                         | Cause                                                | Action                                                          |
+| --------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------- |
+| `RangeError` for `workerId` or `processId`    | The value is outside `0` through `31`.               | Set an integer from `0` through `31`.                           |
+| `TypeError` for `now`                         | The option is not a function.                        | Pass a function that returns Unix time in milliseconds.         |
+| `RangeError` for `epoch`                      | The epoch is outside the supported range.            | Set the epoch from zero through the timestamp limit.            |
+| `RangeError` for invalid clock number         | The clock returned a fractional or unsafe number.    | Return a safe integer number or a bigint.                       |
+| `RangeError` for time before epoch            | The clock value is lower than `epoch`.               | Set the correct epoch or fix the clock source.                  |
+| `RangeError` for timestamp capacity           | Elapsed time is greater than the 42-bit limit.       | Use a valid epoch for the required date range.                  |
+| `RangeError` for sequence overflow            | The generator created 4096 IDs at one timestamp.     | Wait until the clock moves past the last timestamp, then retry. |
+| `TypeError` or `RangeError` during conversion | An option or clock value cannot convert to `BigInt`. | Pass an integer number or bigint value.                         |
+
+## Sequence overflow
+
+The generator does not wait for the clock.
+It fails when one timestamp reaches the 4096-ID limit.
+Wait until the clock moves past the last timestamp before you retry.
+If the clock stalls, check the system clock or the `now` function.
+
+## Duplicate IDs
+
+Assign a unique worker and process ID pair to each active generator.
+Use the same epoch for each generator in one application.
+The default worker ID is `0`.
+The default process ID is `process.pid % 32` and can repeat across hosts.
+Set both IDs through deployment configuration when several hosts create IDs.
+
+## Invalid timestamps
+
+The clock must return a safe integer number or a bigint.
+The value must be Unix time in milliseconds.
+The timestamp must be at or after the configured epoch.
+The elapsed time must fit in 42 bits.
+Check the clock and epoch values when timestamp validation fails.
+
+## Large ID values
+
+IDs are decimal strings because JavaScript numbers cannot represent every ID exactly.
+Keep the string in JSON and in database fields that preserve exact decimal values.
+Use `BigInt(id)` for exact integer operations.
+
+## Node.js version
+
+Use Node.js 26 or later.
+Check the active version with `node --version`.

package/docs/usage.md

@@ -0,0 +1,104 @@
+# Use Snowflake IDs
+
+## Requirements
+
+Use Node.js 26 or later.
+Use one package instance in each Node.js process.
+
+## Install
+
+Install the package from npm:
+
+```text
+npm install @eliware/snowflake
+```
+
+## Create a generator
+
+Import the generator factory and set a unique worker and process ID pair:
+
+```js
+import { createSnowflakeGenerator } from "@eliware/snowflake";
+
+const generate = createSnowflakeGenerator({ workerId: 3, processId: 7 });
+const id = generate();
+console.log(id);
+```
+
+The program prints one decimal string. The value changes on each call.
+
+## Set generator options
+
+Pass an options object to `createSnowflakeGenerator`.
+
+| Option      | Type             | Default            | Meaning                                          |
+| ----------- | ---------------- | ------------------ | ------------------------------------------------ |
+| `epoch`     | number or bigint | `365662380000n`    | Unix epoch in milliseconds.                      |
+| `workerId`  | number or bigint | `0`                | Worker value from `0` through `31`.              |
+| `processId` | number or bigint | `process.pid % 32` | Process value from `0` through `31`.             |
+| `now`       | function         | `Date.now`         | Function that returns Unix time in milliseconds. |
+
+Use the same epoch for all generators that create IDs for one application.
+Set the epoch from zero through the timestamp limit.
+Pass it as a safe integer number or a bigint.
+Set `epoch` to `1420070400000n` to decode timestamps with Discord's epoch.
+Assign a unique worker and process ID pair to each active generator.
+Set `processId` when several hosts or processes share worker IDs.
+The default process ID can repeat across hosts.
+
+## Understand the ID fields
+
+Each ID has a 42-bit timestamp, a 5-bit worker ID, a 5-bit process ID, and a 12-bit sequence.
+The timestamp stores milliseconds since the configured epoch.
+The sequence starts at zero when the timestamp advances.
+The default epoch is `365662380000n`, or `1981-08-03T04:53:00Z`.
+
+The generator combines the fields as follows:
+
+```text
+((time - epoch) << 22) | (workerId << 17) | (processId << 12) | sequence
+```
+
+The maximum elapsed timestamp is `(1n << 42n) - 1n` milliseconds.
+IDs can exceed JavaScript's safe integer range.
+
+## Use the default generator
+
+Use `generate`, `snowflake`, or the default export to create IDs.
+These exports refer to the same generator instance.
+The default generator uses worker ID `0` and process ID `process.pid % 32`.
+Create a custom generator when you need a different identity, epoch, or clock.
+
+## Use a custom clock
+
+Pass `now` to set the clock source.
+Return a safe integer number or a bigint from that function.
+The value must be Unix time in milliseconds.
+Use this option for deterministic tests or a controlled clock source.
+
+## Handle time and sequence limits
+
+The generator uses the last timestamp when the clock moves backward.
+It increments the sequence while that timestamp remains active.
+Each generator can create up to 4096 IDs for one millisecond.
+The next call throws `RangeError` until the clock advances past the last timestamp.
+Wait for the clock to advance before retry.
+The generator throws `RangeError` for a timestamp before the epoch or beyond its 42-bit limit.
+
+## Store and transfer IDs
+
+Keep each ID as a decimal string in JavaScript and JSON.
+Do not convert an ID to `number`.
+Use a text field or an unsigned 64-bit field in a database.
+Use `BigInt(id)` when you need exact integer math in JavaScript.
+
+## Run the example
+
+Use Node.js 26 or later. Run this command from the repository root:
+
+```text
+node examples/example.mjs
+```
+
+The command prints two decimal strings. The values depend on the current time and process ID.
+You do not need cleanup.

package/examples/README.md

@@ -0,0 +1,3 @@
+# Examples
+
+- [Native ESM example](example.mjs)

package/examples/example.mjs

@@ -1,10 +1,10 @@
 // ESM example: example.mjs
-import generate, { createSnowflakeGenerator } from './index.mjs';
+import generate, { createSnowflakeGenerator } from "@eliware/snowflake";
 
-console.log('Default generate():', generate());
+console.log("Default generate():", generate());
 
 const genWorker1 = createSnowflakeGenerator({ workerId: 1 });
-console.log('Worker 1 generate():', genWorker1());
+console.log("Worker 1 generate():", genWorker1());
 
 // Exported generator can be used anywhere in your app to create unique IDs
 export default generate;

package/package.json

@@ -1,58 +1,109 @@
 {
-    "name": "@eliware/snowflake",
-    "type": "module",
-    "version": "1.1.5",
-    "description": "A minimal Node.js Snowflake ID generator (Discord-compatible). Provides BigInt-safe generators with configurable epoch and worker ID.",
-    "types": "index.d.ts",
-    "files": [
-        "index.mjs",
-        "index.d.ts",
-        "README.md",
-        "LICENSE",
-        "examples"
+  "name": "@eliware/snowflake",
+  "version": "12.0.0",
+  "type": "module",
+  "description": "A Node.js Snowflake ID generator with BigInt support and a configurable epoch.",
+  "keywords": [
+    "snowflake",
+    "snowflake-id",
+    "id-generator",
+    "discord",
+    "unique-id",
+    "bigint",
+    "nodejs",
+    "esm"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "main": "./src/index.mjs",
+  "files": [
+    "src/",
+    "docs/",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE",
+    "RELEASE_NOTES.md",
+    "examples/",
+    "specs/"
+  ],
+  "scripts": {
+    "test": "eliware-test",
+    "lint": "eliware-test --lint",
+    "audit": "eliware-test --audit",
+    "format": "eliware-test --format",
+    "format:check": "eliware-test --format-check",
+    "typecheck": "tsc --project tsconfig.json",
+    "pack": "eliware-test --pack"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "devDependencies": {
+    "@eliware/test": "^12.0.0",
+    "typescript": "^7.0.2"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/tests/**/*.test.mjs"
     ],
-    "exports": {
-        ".": {
-            "types": "./index.d.ts",
-            "import": "./index.mjs"
-        }
-    },
-    "scripts": {
-        "test": "npx --node-options=\"--experimental-vm-modules --no-warnings\" jest --detectOpenHandles --silent --coverage",
-        "test:gaps": "npm test 2>&1 | grep '|' | grep -vF '|     100 |      100 |     100 |     100 |'",
-        "lint": "npx oxlint .",
-        "typecheck": "tsc --project tsconfig.json",
-        "pack": "npm pack --dry-run"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/eliware/snowflake.git"
-    },
-    "keywords": [
-        "snowflake",
-        "snowflake-id",
-        "id-generator",
-        "discord",
-        "unique-id",
-        "bigint",
-        "nodejs",
-        "esm"
+    "collectCoverageFrom": [
+      "src/**/*.mjs"
     ],
-    "author": "Eli Sterling, eliware.org <eli@eliware.org>",
-    "license": "MIT",
-    "bugs": {
-        "url": "https://github.com/eliware/snowflake/issues"
-    },
-    "homepage": "https://github.com/eliware/snowflake#readme",
-    "devDependencies": {
-        "jest": "^30.4.2",
-        "typescript": "^7.0.2"
-    },
-    "jest": {
-        "testEnvironment": "node",
-        "testMatch": [
-            "**/?(*.)+(spec|test).[jt]s?(x)",
-            "**/?(*.)+(spec|test).mjs"
-        ]
+    "coverageReporters": [
+      "text",
+      "json-summary"
+    ],
+    "coverageThreshold": {
+      "global": {
+        "branches": 100,
+        "functions": 100,
+        "lines": 100,
+        "statements": 100
+      }
+    }
+  },
+  "prettier": {
+    "printWidth": 100,
+    "tabWidth": 2,
+    "useTabs": false,
+    "semi": true,
+    "singleQuote": false,
+    "quoteProps": "as-needed",
+    "jsxSingleQuote": false,
+    "trailingComma": "all",
+    "bracketSpacing": true,
+    "bracketSameLine": false,
+    "arrowParens": "always",
+    "proseWrap": "preserve",
+    "endOfLine": "lf"
+  },
+  "author": "Eliware <eliware@eliware.org>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eliware/snowflake.git"
+  },
+  "homepage": "https://github.com/eliware/snowflake#readme",
+  "bugs": {
+    "url": "https://github.com/eliware/snowflake/issues"
+  },
+  "eliware": {
+    "id": "E-106",
+    "apply": [
+      "general",
+      "library",
+      "npm-published"
+    ]
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs"
     }
-}
+  },
+  "types": "./src/index.d.ts"
+}

package/specs/README.md

@@ -0,0 +1,5 @@
+# Specifications
+
+- [Directives](directives.yaml)
+- [Out of scope](out-of-scope.yaml)
+- [Requirements](requirements.yaml)

package/specs/directives.yaml

@@ -0,0 +1,25 @@
+version: "12.0"
+description: Defines behavior and limits for the Snowflake ID generator.
+requires: []
+conflicts: []
+directives:
+  - id: E-106.0
+    dos:
+      - Generate time-ordered Snowflake IDs.
+      - Return each ID as a decimal string.
+      - Use configurable epoch and identity values.
+    donts:
+      - Do not present generated IDs as secrets.
+    children:
+      - id: E-106.0.0
+        dos:
+          - Validate worker and process IDs before generation.
+          - Reject timestamps before the configured epoch.
+        donts:
+          - Do not permit identity values outside the supported bit range.
+      - id: E-106.0.1
+        dos:
+          - Protect generation from clock rollback.
+          - Report sequence overflow before an ID can repeat.
+        donts:
+          - Do not return an ID when the sequence overflows.

package/specs/out-of-scope.yaml

@@ -0,0 +1,12 @@
+version: "12.0"
+description: Defines work outside the Snowflake ID library scope.
+requires: []
+conflicts: []
+directives:
+  - id: E-106.2
+    dos:
+      - Keep warehouse deployment procedures outside this library.
+      - Keep private release procedures outside this library.
+      - Keep host-specific operational commands outside this library.
+    donts:
+      - Do not store secrets in this repository.

package/specs/requirements.yaml

@@ -0,0 +1,13 @@
+version: "12.0"
+description: Defines repository requirements for the Snowflake ID library.
+requires: []
+conflicts: []
+directives:
+  - id: E-106.1
+    dos:
+      - Preserve the documented Snowflake ID behavior.
+      - Return IDs as decimal strings.
+      - Protect credentials and private data.
+      - Pass the repository validation commands before review.
+    donts:
+      - Do not use IDs as secrets or authentication tokens.

package/src/constants.mjs

@@ -0,0 +1,15 @@
+export const DEFAULT_EPOCH = 365662380000n;
+export const SEQUENCE_BITS = 12n;
+export const PROCESS_BITS = 5n;
+export const WORKER_BITS = 5n;
+export const PROCESS_MASK = (1n << PROCESS_BITS) - 1n;
+export const WORKER_MASK = (1n << WORKER_BITS) - 1n;
+export const SEQUENCE_MASK = (1n << SEQUENCE_BITS) - 1n;
+export const MAX_TIMESTAMP = (1n << 42n) - 1n;
+
+export const constants = Object.freeze({
+  epoch: DEFAULT_EPOCH,
+  sequenceBits: SEQUENCE_BITS,
+  processBits: PROCESS_BITS,
+  workerBits: WORKER_BITS,
+});

package/src/generator-options.mjs

@@ -0,0 +1,21 @@
+import { DEFAULT_EPOCH, MAX_TIMESTAMP } from "./constants.mjs";
+import { validateIdentity } from "./validation.mjs";
+
+const defaultNow = () => Date.now();
+
+export function validateGeneratorOptions({
+  epoch = DEFAULT_EPOCH,
+  workerId = 0,
+  processId = process.pid % 32,
+  now = defaultNow,
+} = {}) {
+  if (typeof epoch === "number" && !Number.isSafeInteger(epoch))
+    throw new RangeError("epoch must be between 0 and the timestamp limit");
+  const baseEpoch = BigInt(epoch);
+  if (baseEpoch < 0n || baseEpoch > MAX_TIMESTAMP)
+    throw new RangeError("epoch must be between 0 and the timestamp limit");
+  const identity = validateIdentity(workerId, processId);
+  if (typeof now !== "function") throw new TypeError("now must be a function");
+
+  return { baseEpoch, ...identity, now };
+}

package/src/generator.mjs

@@ -0,0 +1,47 @@
+import {
+  MAX_TIMESTAMP,
+  PROCESS_BITS,
+  SEQUENCE_BITS,
+  SEQUENCE_MASK,
+  WORKER_BITS,
+} from "./constants.mjs";
+import { validateGeneratorOptions } from "./generator-options.mjs";
+
+export function createGenerator(options = {}) {
+  const { baseEpoch, worker, processNumber, now } = validateGeneratorOptions(options);
+
+  let lastTimestamp = -1n;
+  let sequence = 0n;
+
+  function readTime() {
+    const clockValue = now();
+    if (typeof clockValue === "number" && !Number.isSafeInteger(clockValue))
+      throw new RangeError("current time must be a safe integer or bigint");
+    const timestamp = BigInt(clockValue);
+    if (timestamp < baseEpoch) throw new RangeError("current time must not be before epoch");
+    return timestamp;
+  }
+
+  return function generate() {
+    let timestamp = readTime();
+    if (timestamp < lastTimestamp) timestamp = lastTimestamp;
+    let nextSequence;
+    if (timestamp === lastTimestamp) {
+      if (sequence === SEQUENCE_MASK)
+        throw new RangeError("sequence overflow; clock must advance before retrying");
+      nextSequence = sequence + 1n;
+    } else {
+      nextSequence = 0n;
+    }
+    const elapsed = timestamp - baseEpoch;
+    if (elapsed > MAX_TIMESTAMP) throw new RangeError("timestamp exceeds Snowflake capacity");
+    lastTimestamp = timestamp;
+    sequence = nextSequence;
+    return (
+      (elapsed << (WORKER_BITS + PROCESS_BITS + SEQUENCE_BITS)) |
+      (worker << (PROCESS_BITS + SEQUENCE_BITS)) |
+      (processNumber << SEQUENCE_BITS) |
+      nextSequence
+    ).toString();
+  };
+}

package/{index.d.ts → src/index.d.ts}

@@ -13,7 +13,7 @@ export interface SnowflakeConstants {
 }
 
 export function createSnowflakeGenerator(options?: SnowflakeGeneratorOptions): () => string;
-export const generate: () => string;
-export const snowflake: typeof generate;
-export const constants: SnowflakeConstants;
+export declare const generate: () => string;
+export declare const snowflake: typeof generate;
+export declare const constants: SnowflakeConstants;
 export default generate;

package/src/index.mjs

@@ -0,0 +1,8 @@
+import { constants } from "./constants.mjs";
+import { createGenerator } from "./generator.mjs";
+
+export const createSnowflakeGenerator = createGenerator;
+export const generate = createGenerator();
+export const snowflake = generate;
+export { constants };
+export default generate;

package/src/validation.mjs

@@ -0,0 +1,16 @@
+import { PROCESS_MASK, WORKER_MASK } from "./constants.mjs";
+
+export 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;
+}
+
+export function validateIdentity(workerId, processId) {
+  return {
+    worker: validatePart(workerId, "workerId", WORKER_MASK),
+    processNumber: validatePart(processId, "processId", PROCESS_MASK),
+  };
+}

package/index.mjs

@@ -1,85 +0,0 @@
-/**
- * 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;
-
-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 timestamp = readTime();
-    if (timestamp < lastTimestamp) timestamp = lastTimestamp;
-
-    if (timestamp === lastTimestamp) {
-      sequence = (sequence + 1n) & SEQUENCE_MASK;
-      if (sequence === 0n) {
-        do timestamp = readTime(); while (timestamp <= lastTimestamp);
-      }
-    } else {
-      sequence = 0n;
-    }
-
-    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();
-  };
-}
-
-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;