@eliware/snowflake 13.0.0 → 14.0.0

package/AGENTS.md

@@ -2,15 +2,20 @@
 
 ## Project
 
-Build a Snowflake ID library with Node.js 26.
-Use native ESM.
+Maintain `@eliware/snowflake`, a Snowflake ID library owned by Eliware.
 
 ## Scope and boundaries
 
+Limit this package to Snowflake ID generation.
+
 ## Layout
 
+Use `README.md` and `specs/README.md` to find repository paths.
+
 ## Development
 
+Use Node.js 26 and native ESM for maintained JavaScript.
+
 ## Validation
 
 Run `npm test`.
@@ -21,8 +26,12 @@ Run `npm run format:check`.
 
 ## Security
 
+Keep credentials, private data, and runtime state out of Git.
+
 ## Changes
 
+Update the nearest index when you add a document.
+
 ## Library
 
 Run focused tests first during development.
@@ -32,3 +41,6 @@ Prevent repeated full-suite runs during development.
 Run the full `npm test` suite for final validation before a commit, milestone, or release.
 
 ## npm publication
+
+Run `npm run pack` to check package contents.
+Follow the approved release procedure.

package/README.md

@@ -23,14 +23,13 @@ A Node.js Snowflake ID generator with BigInt support and a configurable epoch.
 
 ## Features
 
-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.
+Create time-ordered Snowflake IDs as decimal strings.
+Set a custom epoch, worker ID, process ID, clock, or logger.
 
 ## Requirements
 
 Use Node.js 26 or later.
-Use one package instance in each Node.js process.
+Use native ECMAScript modules (ESM).
 
 ## Setup
 
@@ -42,7 +41,7 @@ npm install @eliware/snowflake
 
 ## Usage
 
-Import the generator factory and set a unique worker and process ID pair:
+Create a generator with a unique worker and process ID pair:
 
 ```js
 import { createSnowflakeGenerator } from "@eliware/snowflake";
@@ -52,48 +51,53 @@ console.log(generate());
 ```
 
 Each call returns one decimal string.
-
-[Release notes](RELEASE_NOTES.md)
-
-[Specifications](specs/README.md)
+Read the [usage guide](docs/usage.md) for generator options and ID fields.
+Read the [release notes](RELEASE_NOTES.md) for changes by version.
+Read the [specifications index](specs/README.md) for repository requirements.
 
 ## Development
 
-[Documentation](docs/README.md)
-See the [usage guide](docs/usage.md) for generator options and ID fields.
+Read the [documentation index](docs/README.md) for maintained guides.
 
 ## Testing
 
-Run `npm test` from a repository clone to run aggregate validation.
+Run `npm test` from a repository clone for aggregate validation.
 
 ## Troubleshooting
 
-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
 
-Use IDs as identifiers. Each ID contains its generation time and worker and process values.
+Each ID contains its generation time and identity fields.
 Do not use IDs as secrets or authentication tokens.
-Read the [usage guide](docs/usage.md) for ID fields and storage guidance.
 
 ## API
 
 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.
+Import `generate`, `snowflake`, or the default export to use the default generator.
+Import `constants` to read the default epoch and field sizes.
+Read the [usage guide](docs/usage.md) for API details and TypeScript declarations.
 
 ## Packaging
 
-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).
+The package uses native ESM, includes TypeScript declarations, and depends on `@eliware/log`.
+Its root entrypoint is `src/index.mjs` and its declaration file is `src/index.d.ts`.
+The npm package includes these paths from `package.json`:
+
+- `src/`
+- `docs/`
+- `README.md`, `AGENTS.md`, `LICENSE`, and `RELEASE_NOTES.md`
+- `examples/` and `specs/`
+
+Use numeric `MAJOR.MINOR.PATCH` versions.
+Push a matching `v<version>` tag to start validation and npm publication.
+Follow the approved release procedure before you create a release tag.
 
 ## Examples
 
-[Run the native ESM example](examples/example.mjs).
-[Examples](examples/README.md)
+Run `node examples/example.mjs` to create sample IDs.
+Read [examples/README.md](examples/README.md) for the example index.
 
 ## Support
 

package/RELEASE_NOTES.md

@@ -1,5 +1,25 @@
 # Release Notes
 
+## 14.0.0 — 2026-10-21
+
+### Added
+
+- Added optional structured logging through `@eliware/log` with a custom logger option.
+- Added tests for logger records and the full elapsed timestamp range with the maximum epoch.
+
+### Changed
+
+- Updated the package to version 14.0.0 and aligned its specifications with Eliware Test 14.
+- Clarified the authoritative rule for first timestamps and later pre-epoch rollbacks.
+- Updated npm dependencies and added `@eliware/log` as a direct dependency.
+- Expanded the user guides with logging, API, decoding, timestamp limits, identity, and storage details.
+- Reduced `README.md` and `AGENTS.md` to convention-required content.
+
+### Fixed
+
+- Kept the full elapsed timestamp range available when the configured epoch is at its maximum.
+- Kept IDs increasing when the clock returns a time before the epoch after the first valid ID.
+
 ## 13.0.0 — 2026-10-19
 
 ### Added

package/docs/README.md

@@ -1,4 +1,13 @@
 # Documentation
 
-- [Usage](usage.md)
-- [Troubleshooting](troubleshooting.md)
+Use these guides to install the package, create IDs, and resolve common errors.
+
+## Guides
+
+- [Usage](usage.md) explains installation, generator options, ID fields, decoding, logging, and storage.
+- [Troubleshooting](troubleshooting.md) explains validation errors, sequence limits, and duplicate IDs.
+
+## Requirements
+
+Use Node.js 26 or later.
+Use native ECMAScript modules (ESM).

package/docs/troubleshooting.md

@@ -2,16 +2,17 @@
 
 ## 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 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.                 |
+| 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.          |
+| `TypeError` for `logger`                      | The logger lacks a required level method.            | Pass a logger with `error`, `warn`, `info`, and `debug` methods. |
+| `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 first time before epoch      | The first 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
 
@@ -28,11 +29,23 @@ The default worker ID is `0`.
 The default process ID is `process.pid % 32` and can repeat across hosts.
 Set both IDs in deployment configuration when some hosts create IDs.
 
+Do not create multiple generators with the same pair while their IDs can overlap in time.
+Each generator starts its sequence at zero.
+Use one generator instance for each pair in a process.
+
+## Clock rollback
+
+The generator keeps IDs in increasing order when its clock returns an earlier time.
+It uses the last valid timestamp and advances the sequence.
+It logs a warning when you provide a logger.
+The first clock value must be at or after the configured epoch.
+After the first ID, a clock value lower than the epoch uses rollback handling.
+
 ## 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 first timestamp must be at or after the configured epoch.
 The elapsed time must be 42 bits or less.
 Check the clock and epoch values when timestamp validation fails.
 

package/docs/usage.md

@@ -3,7 +3,8 @@
 ## Requirements
 
 Use Node.js 26 or later.
-Use one package instance in each Node.js process.
+Use native ECMAScript modules (ESM).
+Give each active generator a unique worker and process ID pair.
 
 ## Install
 
@@ -27,6 +28,10 @@ console.log(id);
 
 The command prints one decimal string. The value changes on each call.
 
+The package exports `createSnowflakeGenerator`, `generate`, `snowflake`, `constants`, and a default generator.
+The `generate`, `snowflake`, and default exports use the same generator instance.
+Use `createSnowflakeGenerator()` to set an epoch, identity, clock, or logger.
+
 ## Set generator options
 
 Pass an options object to `createSnowflakeGenerator`.
@@ -37,6 +42,7 @@ Pass an options object to `createSnowflakeGenerator`.
 | `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. |
+| `logger`    | logger           | none               | Optional structured logger for generator events. |
 
 `createSnowflakeGenerator(options)` returns a function that creates IDs.
 Each call returns one decimal string.
@@ -46,8 +52,9 @@ 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.
+The fields allow 32 worker values and 32 process values, for 1,024 pairs.
+The default process ID is `process.pid % 32` and can repeat across hosts.
+Set both values in deployment configuration when different hosts can create IDs at the same time.
 
 To align timestamp decoding with Discord, set `epoch` to `1420070400000n`.
 This epoch matches Discord's timestamp epoch.
@@ -68,6 +75,7 @@ The timestamp stores milliseconds since the configured epoch.
 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 complete ID has 64 bits.
 
 The generator combines the fields as follows:
 
@@ -75,7 +83,10 @@ The generator combines the fields as follows:
 ((time - epoch) << 22) | (workerId << 17) | (processId << 12) | sequence
 ```
 
-The maximum elapsed timestamp is `(1n << 42n) - 1n` milliseconds.
+The epoch option accepts values through `(1n << 42n) - 1n` milliseconds.
+The timestamp field separately stores a maximum of `(1n << 42n) - 1n` elapsed milliseconds.
+The epoch limit applies to the configured epoch, not the final Unix time.
+The maximum supported Unix time equals the epoch plus the maximum elapsed timestamp.
 IDs can be greater than JavaScript's safe integer limit.
 
 ## Use the default generator
@@ -105,6 +116,18 @@ console.log(timestamp.toISOString());
 
 Use the same epoch that the generator used to create the ID.
 
+Read the worker, process, and sequence fields with bit shifts and masks:
+
+```js
+const value = BigInt(id);
+const workerId = (value >> 17n) & 31n;
+const processId = (value >> 12n) & 31n;
+const sequence = value & 4095n;
+```
+
+The package does not export a decoder.
+Use the same field layout and epoch that the generator used to create the ID.
+
 ## Use a custom clock
 
 Pass `now` to set the clock source.
@@ -112,6 +135,35 @@ 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.
 
+The first clock value must be at or after the configured epoch.
+After the first ID, an earlier clock value uses the last valid timestamp.
+The generator increments the sequence during that rollback.
+
+## Add structured logging
+
+Install `@eliware/log` to create a logger. Pass the logger to the generator with the `logger` option.
+The generator writes records only when you provide a logger.
+
+```js
+import { createLogger } from "@eliware/log";
+import { createSnowflakeGenerator } from "@eliware/snowflake";
+
+const logger = createLogger({ level: "debug", format: "json" });
+const generate = createSnowflakeGenerator({ logger });
+const id = generate();
+```
+
+The generator writes `info` when it starts, `debug` when it creates an ID, and `warn` when its clock returns an earlier time.
+It writes `error` when ID generation fails.
+Records do not include generated IDs, credentials, tokens, or error messages.
+
+Records include the operation, component, and related timestamp or identity fields.
+The logger supports the `error`, `warn`, `info`, `http`, `verbose`, `debug`, and `silly` levels.
+The generator uses only levels that apply to its operations.
+Set the logger level to control which records it writes.
+The `logger` option requires `error`, `warn`, `info`, and `debug` methods.
+The `LoggerWithConfiguredLevels` TypeScript type describes the supported logger interface.
+
 ## Time and sequence limits
 
 The generator uses the last timestamp when the clock returns a lower value.
@@ -131,6 +183,24 @@ 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)` for exact integer math in JavaScript.
 
+Each ID contains its generation time, worker ID, process ID, and sequence.
+Do not use an ID as a password, credential, or authentication token.
+
+## Use TypeScript
+
+The package includes TypeScript declarations for its public API.
+Import `SnowflakeGeneratorOptions`, `SnowflakeConstants`, and `LoggerWithConfiguredLevels` as types.
+
+```ts
+import { createSnowflakeGenerator, constants } from "@eliware/snowflake";
+import type { SnowflakeGeneratorOptions } from "@eliware/snowflake";
+
+const options: SnowflakeGeneratorOptions = { workerId: 3, processId: 7 };
+const generate = createSnowflakeGenerator(options);
+const id: string = generate();
+const epoch: bigint = constants.epoch;
+```
+
 ## Run the example
 
 Use Node.js 26 or later.

package/package.json

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

package/specs/directives.yaml

@@ -1,4 +1,4 @@
-version: "13.0"
+version: "14.0"
 description: Defines behavior and limits for the Snowflake ID generator.
 directives:
   - id: E-106.0
@@ -12,8 +12,11 @@ directives:
       - id: E-106.0.0
         dos:
           - Validate worker and process IDs before generation.
-          - Reject timestamps before the configured epoch.
+          - Reject the first clock value when it is before the configured epoch.
+          - Apply rollback handling to a later clock value before the configured epoch.
+          - Use the last valid timestamp after a rollback.
         donts:
+          - Do not create an ID from a timestamp before the configured epoch.
           - Do not use identity values outside the supported bit range.
       - id: E-106.0.1
         dos:

package/specs/out-of-scope.yaml

@@ -1,4 +1,4 @@
-version: "13.0"
+version: "14.0"
 description: Defines work outside the Snowflake ID library scope.
 directives:
   - id: E-106.2

package/specs/requirements.yaml

@@ -1,4 +1,4 @@
-version: "13.0"
+version: "14.0"
 description: Defines repository requirements for the Snowflake ID library.
 directives:
   - id: E-106.1

package/src/generator-options.mjs

@@ -8,6 +8,7 @@ export function validateGeneratorOptions({
   workerId = 0,
   processId = process.pid % 32,
   now = defaultNow,
+  logger,
 } = {}) {
   if (typeof epoch === "number" && !Number.isSafeInteger(epoch))
     throw new RangeError("epoch must be between 0 and the timestamp limit");
@@ -16,6 +17,12 @@ export function validateGeneratorOptions({
     throw new RangeError("epoch must be between 0 and the timestamp limit");
   const identity = validateIdentity(workerId, processId);
   if (typeof now !== "function") throw new TypeError("clock source must be a function");
+  if (
+    logger !== undefined &&
+    (!logger ||
+      ["error", "warn", "info", "debug"].some((level) => typeof logger[level] !== "function"))
+  )
+    throw new TypeError("logger must provide error, warn, info, and debug methods");
 
-  return { baseEpoch, ...identity, now };
+  return { baseEpoch, ...identity, now, logger };
 }

package/src/generator.mjs

@@ -8,42 +8,76 @@ import {
 import { validateGeneratorOptions } from "./generator-options.mjs";
 
 export function createGenerator(options = {}) {
-  const { baseEpoch, worker, processNumber, now } = validateGeneratorOptions(options);
+  const { baseEpoch, worker, processNumber, now, logger } = validateGeneratorOptions(options);
 
   let lastTimestamp = -1n;
   let sequence = 0n;
 
+  logger?.info("Snowflake generator created", {
+    component: "snowflake",
+    operation: "create-generator",
+    epoch: baseEpoch.toString(),
+    workerId: worker.toString(),
+    processId: processNumber.toString(),
+  });
+
   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");
+    if (timestamp < baseEpoch && lastTimestamp < 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. Retry when the clock returns a greater timestamp.",
-        );
-      nextSequence = sequence + 1n;
-    } else {
-      nextSequence = 0n;
+    try {
+      let timestamp = readTime();
+      if (timestamp < lastTimestamp) {
+        logger?.warn("Snowflake clock moved backward", {
+          component: "snowflake",
+          operation: "generate",
+          event: "clock-rollback",
+          timestamp: timestamp.toString(),
+          lastTimestamp: lastTimestamp.toString(),
+        });
+        timestamp = lastTimestamp;
+      }
+      let nextSequence;
+      if (timestamp === lastTimestamp) {
+        if (sequence === SEQUENCE_MASK)
+          throw new RangeError(
+            "sequence overflow. Retry when the clock returns a greater timestamp.",
+          );
+        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;
+      const id = (
+        (elapsed << (WORKER_BITS + PROCESS_BITS + SEQUENCE_BITS)) |
+        (worker << (PROCESS_BITS + SEQUENCE_BITS)) |
+        (processNumber << SEQUENCE_BITS) |
+        nextSequence
+      ).toString();
+      logger?.debug("Snowflake ID generated", {
+        component: "snowflake",
+        operation: "generate",
+        timestamp: timestamp.toString(),
+        sequence: nextSequence.toString(),
+      });
+      return id;
+    } catch (error) {
+      logger?.error("Snowflake ID generation failed", {
+        component: "snowflake",
+        operation: "generate",
+        errorType: error.name,
+      });
+      throw error;
     }
-    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/src/index.d.ts

@@ -1,10 +1,15 @@
+import type { LoggerWithConfiguredLevels } from "@eliware/log";
+
 export interface SnowflakeGeneratorOptions {
   epoch?: number | bigint;
   workerId?: number | bigint;
   processId?: number | bigint;
   now?: () => number | bigint;
+  logger?: LoggerWithConfiguredLevels;
 }
 
+export type { LoggerWithConfiguredLevels } from "@eliware/log";
+
 export interface SnowflakeConstants {
   readonly epoch: bigint;
   readonly sequenceBits: bigint;