@eliware/snowflake 1.1.4 → 2.0.0

package/README.md

@@ -9,11 +9,16 @@ A production-ready, BigInt-safe Snowflake ID generator for Node.js. IDs are retu
 - 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.
+- Sequence overflow fails fast; callers can retry after the clock advances.
 - 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.
 
+## Requirements
+
+- Node.js 26 or newer
+
 ## Installation
 
 ```bash
@@ -35,7 +40,11 @@ const replicaGenerator = createSnowflakeGenerator({
 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.
+For Kubernetes or other distributed deployments, assign each replica a stable
+`workerId` and coordinate `processId` values so that no two active generators
+share the same worker/process pair. `processId` defaults to `process.pid % 32`,
+but should be explicitly configured when process identity must be coordinated
+across hosts.
 
 ## API
 
@@ -48,16 +57,45 @@ For Kubernetes, assign each replica a stable `workerId` from configuration. `pro
 | `processId` | `process.pid % 32` | Process ID, from `0` to `31`. |
 | `now` | `Date.now` | Injectable millisecond clock. |
 
-The exports `generate` and `snowflake` are ready-to-use default generators. `constants` exposes the bit layout and default epoch.
+The exports `generate` and `snowflake` are ready-to-use default generators;
+both refer to the same generator. `constants` exposes the bit layout and
+default epoch. IDs are unique only when the configured worker/process identity
+is unique and the system clock is not permanently stalled.
+
+## TypeScript
+
+TypeScript declarations are included for all public exports and options.
+
+## Errors / Troubleshooting
+
+Configuration values outside the supported ranges throw `RangeError`; a
+non-function clock throws `TypeError`; timestamps before the epoch or beyond
+Snowflake capacity throw `RangeError`. If more than 4096 IDs are requested in
+one millisecond, generation throws a `RangeError`; retry after the clock has
+advanced. Configure unique `workerId` and `processId` values across distributed
+generators.
 
 ## Testing and linting
 
 ```bash
 npm test
-npm run test:gaps
 npm run lint
+npm run typecheck
+npm run audit
+npm run pack
 ```
 
+## Operations
+
+Use the same `epoch`, `workerId`, and `processId` configuration consistently
+for each generator instance. Persist IDs as decimal strings because Snowflake
+values can exceed JavaScript's safe integer range. The generator performs no
+filesystem or network I/O and does not require shutdown handling.
+
+## Security
+
+Snowflake IDs are unique identifiers, not secrets. Do not use them as authentication tokens or assume they conceal timestamp and deployment information.
+
 ## License
 
 MIT © Eli Sterling, eliware.org

package/RELEASE_NOTES.md

@@ -0,0 +1,57 @@
+# Release Notes
+
+## 2.0.0 — August 28, 2026
+
+- Adopted the shared `@eliware/test` harness for testing and linting with
+  strict 100×4 coverage enforcement.
+- Modernized package metadata, documentation, package contents, and CI for
+  Node.js `>=26`, including cross-platform validation and tag-only publishing.
+- Added production dependency auditing and repository-owned Knit validation.
+- Added fail-fast sequence-overflow handling and expanded BigInt, boundary, and
+  rollback coverage.
+- Removed obsolete Jest-result ignore configuration and added shared project
+  working rules.
+- Breaking: the standard `test` and `lint` scripts now delegate to
+  `@eliware/test`.
+
+## 1.1.5 — August 7, 2026
+
+- Aligned repository layout, scripts, CI, documentation, and package contents with Eliware library conventions.
+- Added TypeScript declaration checking and standardized package validation.
+- Moved tests under `tests/` and included a runnable `examples/` file in the package.
+- Removed the legacy `main` metadata from this ESM-only package.
+- Verification: tests, coverage, gap checks, lint, typecheck, smoke test, and package dry-run pass.
+
+## 1.1.4 — August 7, 2026
+
+### Changed
+
+- Removed the unused `@eliware/common` runtime dependency.
+- Reduced the installed dependency tree and regenerated the npm lockfile.
+- Added manual GitHub Actions workflow dispatch support.
+
+### Verification
+
+- npm audit: 0 vulnerabilities.
+
+## 1.1.2
+
+### Added
+
+- Rebuilt the generator around a configurable, BigInt-safe Snowflake implementation.
+- Added the custom Eliware epoch: `365662380000n` (`1981-08-03T04:53:00Z`).
+- Added worker ID and process ID fields for distributed deployments.
+- Added clock rollback protection and sequence overflow handling.
+- Added injectable clocks, range validation, and timestamp-capacity validation.
+- Added TypeScript declarations for all public options and exports.
+
+### Changed
+
+- Removed CommonJS entrypoints and tests; the package is ESM-only.
+- Expanded documentation with deployment and bit-layout guidance.
+- Added complete generator behavior tests.
+
+### Verification
+
+- Jest coverage: 100% statements, branches, functions, and lines.
+- Oxlint: 0 warnings and errors.

package/examples/example.mjs

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

package/index.mjs

@@ -57,7 +57,7 @@ export function createSnowflakeGenerator({
     if (timestamp === lastTimestamp) {
       sequence = (sequence + 1n) & SEQUENCE_MASK;
       if (sequence === 0n) {
-        do timestamp = readTime(); while (timestamp <= lastTimestamp);
+        throw new RangeError('sequence overflow; clock must advance before retrying');
       }
     } else {
       sequence = 0n;

package/package.json

@@ -1,16 +1,23 @@
 {
     "name": "@eliware/snowflake",
     "type": "module",
-    "version": "1.1.4",
+    "version": "2.0.0",
     "description": "A minimal Node.js Snowflake ID generator (Discord-compatible). Provides BigInt-safe generators with configurable epoch and worker ID.",
-    "main": "index.mjs",
+    "engines": {
+        "node": ">=26"
+    },
     "types": "index.d.ts",
     "files": [
         "index.mjs",
         "index.d.ts",
         "README.md",
-        "LICENSE"
+        "LICENSE",
+        "RELEASE_NOTES.md",
+        "examples"
     ],
+    "publishConfig": {
+        "access": "public"
+    },
     "exports": {
         ".": {
             "types": "./index.d.ts",
@@ -18,9 +25,11 @@
         }
     },
     "scripts": {
-        "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 ."
+        "test": "eliware-test",
+        "lint": "eliware-test --lint",
+        "audit": "npm audit --omit=dev --audit-level=moderate",
+        "typecheck": "tsc --project tsconfig.json",
+        "pack": "npm pack --dry-run"
     },
     "repository": {
         "type": "git",
@@ -43,13 +52,7 @@
     },
     "homepage": "https://github.com/eliware/snowflake#readme",
     "devDependencies": {
-        "jest": "^30.4.2"
-    },
-    "jest": {
-        "testEnvironment": "node",
-        "testMatch": [
-            "**/?(*.)+(spec|test).[jt]s?(x)",
-            "**/?(*.)+(spec|test).mjs"
-        ]
+        "@eliware/test": "^2.0.0",
+        "typescript": "^7.0.2"
     }
 }