@eliware/snowflake 12.0.0 → 13.0.0

package/AGENTS.md

@@ -2,53 +2,33 @@
 
 ## Project
 
-Build a Snowflake ID library with Node.js 26. Use native ESM.
+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.
+Run `npm test`.
+Run `npm run lint`.
+Run `npm run audit`.
+Run `npm run format`.
+Run `npm run format:check`.
 
 ## 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.
+Run focused tests first during development.
+Run one test file with `npm test -- tests/path/to/example.test.mjs`.
+Run multiple test files with `npm test -- tests/path/to/first.test.mjs tests/path/to/second.test.mjs`.
+Prevent repeated full-suite runs during development.
+Run the full `npm test` suite for final validation before a commit, milestone, or release.
 
 ## 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/README.md

@@ -23,19 +23,18 @@ A Node.js Snowflake ID generator with BigInt support and a configurable epoch.
 
 ## Features
 
-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.
+Create time-ordered Snowflake IDs with a custom epoch and worker and process IDs.
+Return decimal strings so JavaScript and JSON preserve each ID exactly.
+The generator keeps IDs ordered when time decreases and reports sequence overflow.
 
 ## Requirements
 
 Use Node.js 26 or later.
-Assign a unique worker and process ID pair to each active generator.
+Use one package instance in each Node.js process.
 
 ## Setup
 
-Install the package:
+Install the package from npm:
 
 ```text
 npm install @eliware/snowflake
@@ -43,7 +42,7 @@ npm install @eliware/snowflake
 
 ## Usage
 
-Create a generator with a unique identity:
+Import the generator factory and set a unique worker and process ID pair:
 
 ```js
 import { createSnowflakeGenerator } from "@eliware/snowflake";
@@ -52,43 +51,49 @@ const generate = createSnowflakeGenerator({ workerId: 3, processId: 7 });
 console.log(generate());
 ```
 
-See [release notes](RELEASE_NOTES.md) for changes by version.
-See the [usage guide](docs/usage.md) for options, ID fields, and limits.
+Each call returns one decimal string.
+
+[Release notes](RELEASE_NOTES.md)
+
+[Specifications](specs/README.md)
 
 ## Development
 
-Read [user documentation](docs/README.md), [examples](examples/README.md), and [specifications](specs/README.md).
+[Documentation](docs/README.md)
+See the [usage guide](docs/usage.md) for generator options and ID fields.
 
 ## 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.
+Run `npm test` from a repository clone to run aggregate validation.
 
 ## Troubleshooting
 
-See [troubleshooting](docs/troubleshooting.md) for error causes and recovery steps.
+Check the options and clock when the generator throws `RangeError`.
+For sequence overflow, retry when the clock returns a timestamp greater than the last timestamp.
+Read the [troubleshooting guide](docs/troubleshooting.md) for error causes and actions.
 
 ## Security
 
-Treat IDs as identifiers, not secrets.
-IDs reveal timestamp and deployment data.
-Do not use IDs as authentication tokens.
+Use IDs as identifiers. Each ID contains its generation time and worker and process values.
+Do not use IDs as secrets or authentication tokens.
+Read the [usage guide](docs/usage.md) for ID fields and storage guidance.
 
 ## API
 
-`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.
+Import `createSnowflakeGenerator` to create a generator with custom options.
+Use `generate`, `snowflake`, or the default export for the default generator.
+Read the [usage guide](docs/usage.md) for the API and option details.
 
 ## Packaging
 
-The package provides native ESM code and TypeScript declarations.
-It has no runtime dependencies.
+The package uses native ESM and includes TypeScript declarations.
+The package has no runtime dependencies.
+Install it from [npm](https://www.npmjs.com/package/@eliware/snowflake).
 
 ## Examples
 
-Run the [native ESM example](examples/example.mjs) with Node.js 26 or later.
+[Run the native ESM example](examples/example.mjs).
+[Examples](examples/README.md)
 
 ## Support
 

package/RELEASE_NOTES.md

@@ -1,5 +1,23 @@
 # Release Notes
 
+## 13.0.0 — 2026-10-19
+
+### Added
+
+- Added the canonical npm publication workflow.
+- Added full Git history to CI.
+
+### Changed
+
+- Updated the package to version 13.0.0 and upgraded `@eliware/test` and npm dependencies.
+- Aligned CI and npm publication workflows with the current templates and checkout action.
+- Updated Knit deployment commands and the repository path.
+- Updated specifications and repository guidance for Convention 13.
+- Expanded user guides with API details, ID limits, timestamp decoding, and storage guidance.
+- Documented the custom epoch for Discord timestamp decoding. It does not create official Discord IDs.
+- Changed the invalid clock source and sequence overflow error messages.
+- Reduced the root README and contributor guidance to convention-required content.
+
 ## 12.0.0 — 2026-10-12
 
 ### Changed
@@ -32,34 +50,3 @@
 ### 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/troubleshooting.md

@@ -2,44 +2,44 @@
 
 ## 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.                         |
+| 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 set 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.     | Retry when the clock returns a greater timestamp.       |
+| `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.
+Retry when the clock returns a timestamp greater than the last timestamp.
 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.
+Give each active generator a unique worker and process ID pair.
 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.
+Set both IDs in deployment configuration when some 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.
+The elapsed time must be 42 bits or less.
 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.
+IDs are decimal strings because JavaScript numbers cannot store every ID exactly.
+Keep the string in JSON and in database fields that store exact decimal values.
 Use `BigInt(id)` for exact integer operations.
 
 ## Node.js version

package/docs/usage.md

@@ -25,7 +25,7 @@ const id = generate();
 console.log(id);
 ```
 
-The program prints one decimal string. The value changes on each call.
+The command prints one decimal string. The value changes on each call.
 
 ## Set generator options
 
@@ -38,20 +38,36 @@ Pass an options object to `createSnowflakeGenerator`.
 | `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.
+`createSnowflakeGenerator(options)` returns a function that creates IDs.
+Each call returns one decimal string.
+Set `epoch` as a safe integer number or a bigint from zero through `(1n << 42n) - 1n`.
+Set `workerId` and `processId` to integer values from `0` through `31`.
+Use the same epoch for all generators in one application.
+
+Give each active generator a unique pair of `workerId` and `processId` values.
+Keep each pair unique while IDs from that pair remain in use.
+Set `processId` when some hosts or processes use the same `workerId`.
 The default process ID can repeat across hosts.
 
+To align timestamp decoding with Discord, set `epoch` to `1420070400000n`.
+This epoch matches Discord's timestamp epoch.
+It does not create an official Discord resource ID.
+
+```js
+const createDiscordTimeGenerator = createSnowflakeGenerator({
+  epoch: 1420070400000n,
+  workerId: 3,
+  processId: 7,
+});
+```
+
 ## 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 sequence starts at zero when the timestamp changes.
 The default epoch is `365662380000n`, or `1981-08-03T04:53:00Z`.
+The timestamp field sorts before the worker, process, and sequence fields.
 
 The generator combines the fields as follows:
 
@@ -60,14 +76,34 @@ The generator combines the fields as follows:
 ```
 
 The maximum elapsed timestamp is `(1n << 42n) - 1n` milliseconds.
-IDs can exceed JavaScript's safe integer range.
+IDs can be greater than JavaScript's safe integer limit.
 
 ## 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.
+Create a custom generator to set a different identity, epoch, or clock.
+
+The `constants` export has `epoch`, `sequenceBits`, `processBits`, and `workerBits` fields.
+Each field has a `bigint` value.
+The sequence, process, and worker fields use 12, 5, and 5 bits.
+The `constants` object is frozen.
+
+## Decode an ID timestamp
+
+Convert the ID string to a `bigint` before you read its timestamp field.
+Move the value right by 22 bits to read elapsed milliseconds.
+Add the configured epoch to get Unix time in milliseconds.
+Convert that value to a JavaScript `Date` to get its ISO 8601 value.
+
+```js
+const epoch = 365662380000n;
+const timestamp = new Date(Number((BigInt(id) >> 22n) + epoch));
+console.log(timestamp.toISOString());
+```
+
+Use the same epoch that the generator used to create the ID.
 
 ## Use a custom clock
 
@@ -76,29 +112,33 @@ 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
+## Time and sequence limits
+
+The generator uses the last timestamp when the clock returns a lower value.
+The generator sets the sequence to zero when the timestamp changes.
+The generator increments the sequence while the timestamp stays the same.
 
-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.
+Each generator can create 4096 IDs in one millisecond.
+The generator throws `RangeError` after that limit.
+Retry when the clock returns a timestamp greater than the last timestamp.
+The generator throws `RangeError` for a timestamp before the epoch or greater than its 42-bit limit.
 
-## Store and transfer IDs
+## Store and share IDs
 
 Keep each ID as a decimal string in JavaScript and JSON.
 Do not convert an ID to `number`.
+JSON cannot encode a `bigint` value without custom code.
 Use a text field or an unsigned 64-bit field in a database.
-Use `BigInt(id)` when you need exact integer math in JavaScript.
+Use `BigInt(id)` for exact integer math in JavaScript.
 
 ## Run the example
 
-Use Node.js 26 or later. Run this command from the repository root:
+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.
+The example writes no files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eliware/snowflake",
-  "version": "12.0.0",
+  "version": "13.0.0",
   "type": "module",
   "description": "A Node.js Snowflake ID generator with BigInt support and a configurable epoch.",
   "keywords": [
@@ -42,7 +42,7 @@
     "node": ">=26"
   },
   "devDependencies": {
-    "@eliware/test": "^12.0.0",
+    "@eliware/test": "^13.0.0",
     "typescript": "^7.0.2"
   },
   "jest": {

package/specs/directives.yaml

@@ -1,25 +1,23 @@
-version: "12.0"
+version: "13.0"
 description: Defines behavior and limits for the Snowflake ID generator.
-requires: []
-conflicts: []
 directives:
   - id: E-106.0
     dos:
-      - Generate time-ordered Snowflake IDs.
+      - Create 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.
+      - Do not show 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.
+          - Do not use identity values outside the supported bit range.
       - id: E-106.0.1
         dos:
-          - Protect generation from clock rollback.
+          - Keep IDs unique when the clock returns a lower value.
           - Report sequence overflow before an ID can repeat.
         donts:
           - Do not return an ID when the sequence overflows.

package/specs/out-of-scope.yaml

@@ -1,7 +1,5 @@
-version: "12.0"
+version: "13.0"
 description: Defines work outside the Snowflake ID library scope.
-requires: []
-conflicts: []
 directives:
   - id: E-106.2
     dos:

package/specs/requirements.yaml

@@ -1,13 +1,11 @@
-version: "12.0"
+version: "13.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.
+      - Keep credentials and private data private.
+      - Pass repository validation before inspection.
     donts:
       - Do not use IDs as secrets or authentication tokens.

package/src/generator-options.mjs

@@ -15,7 +15,7 @@ export function validateGeneratorOptions({
   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");
+  if (typeof now !== "function") throw new TypeError("clock source must be a function");
 
   return { baseEpoch, ...identity, now };
 }

package/src/generator.mjs

@@ -28,7 +28,9 @@ export function createGenerator(options = {}) {
     let nextSequence;
     if (timestamp === lastTimestamp) {
       if (sequence === SEQUENCE_MASK)
-        throw new RangeError("sequence overflow; clock must advance before retrying");
+        throw new RangeError(
+          "sequence overflow. Retry when the clock returns a greater timestamp.",
+        );
       nextSequence = sequence + 1n;
     } else {
       nextSequence = 0n;