@eliware/snowflake 2.0.0 → 13.0.0

package/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md
+
+## Project
+
+Build a Snowflake ID library with Node.js 26.
+Use native ESM.
+
+## Scope and boundaries
+
+## Layout
+
+## Development
+
+## Validation
+
+Run `npm test`.
+Run `npm run lint`.
+Run `npm run audit`.
+Run `npm run format`.
+Run `npm run format:check`.
+
+## Security
+
+## Changes
+
+## Library
+
+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

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,101 +1,117 @@
-# @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.
-- 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.
+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
 
-- Node.js 26 or newer
+Use Node.js 26 or later.
+Use one package instance in each Node.js process.
+
+## Setup
 
-## Installation
+Install the package from npm:
 
-```bash
+```text
 npm install @eliware/snowflake
 ```
 
 ## Usage
 
+Import the generator factory and set a unique worker and process ID pair:
+
 ```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 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.
+Each call returns one decimal string.
 
-## API
+[Release notes](RELEASE_NOTES.md)
+
+[Specifications](specs/README.md)
 
-`createSnowflakeGenerator(options?)` returns a function that generates decimal-string IDs.
+## Development
 
-| 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. |
+[Documentation](docs/README.md)
+See the [usage guide](docs/usage.md) for generator options and ID fields.
 
-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.
+## Testing
 
-## TypeScript
+Run `npm test` from a repository clone to run aggregate validation.
 
-TypeScript declarations are included for all public exports and options.
+## Troubleshooting
 
-## Errors / 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.
 
-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.
+## Security
 
-## Testing and linting
+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.
 
-```bash
-npm test
-npm run lint
-npm run typecheck
-npm run audit
-npm run pack
-```
+## API
 
-## Operations
+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.
 
-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.
+## Packaging
 
-## Security
+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).
+[Examples](examples/README.md)
+
+## 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)**
+
+## 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

@@ -1,57 +1,52 @@
 # 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
+## 13.0.0 — 2026-10-19
+
+### Added
+
+- Added the canonical npm publication workflow.
+- Added full Git history to CI.
 
 ### 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.
+- 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.
 
-### Verification
+## 12.0.0 — 2026-10-12
+
+### Changed
 
-- npm audit: 0 vulnerabilities.
+- 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.
 
-## 1.1.2
+## 2.0.0 — 2026-08-28
 
 ### 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.
+- Added fail-fast sequence overflow handling and expanded boundary coverage.
+- Added TypeScript declarations for public exports and options.
 
 ### Changed
 
-- Removed CommonJS entrypoints and tests; the package is ESM-only.
-- Expanded documentation with deployment and bit-layout guidance.
-- Added complete generator behavior tests.
+- 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/`.
 
-### Verification
+### Breaking changes
 
-- Jest coverage: 100% statements, branches, functions, and lines.
-- Oxlint: 0 warnings and errors.
+- Changed the `test` and `lint` scripts to use `@eliware/test`.

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 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.
+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
+
+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 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 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 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
+
+Use Node.js 26 or later.
+Check the active version with `node --version`.

package/docs/usage.md

@@ -0,0 +1,144 @@
+# 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 command 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. |
+
+`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 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:
+
+```text
+((time - epoch) << 22) | (workerId << 17) | (processId << 12) | sequence
+```
+
+The maximum elapsed timestamp is `(1n << 42n) - 1n` milliseconds.
+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 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
+
+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.
+
+## 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.
+
+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 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)` for 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.
+The example writes no files.

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": "2.0.0",
-    "description": "A minimal Node.js Snowflake ID generator (Discord-compatible). Provides BigInt-safe generators with configurable epoch and worker ID.",
-    "engines": {
-        "node": ">=26"
-    },
-    "types": "index.d.ts",
-    "files": [
-        "index.mjs",
-        "index.d.ts",
-        "README.md",
-        "LICENSE",
-        "RELEASE_NOTES.md",
-        "examples"
+  "name": "@eliware/snowflake",
+  "version": "13.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": "^13.0.0",
+    "typescript": "^7.0.2"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/tests/**/*.test.mjs"
     ],
-    "publishConfig": {
-        "access": "public"
-    },
-    "exports": {
-        ".": {
-            "types": "./index.d.ts",
-            "import": "./index.mjs"
-        }
-    },
-    "scripts": {
-        "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",
-        "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": {
-        "@eliware/test": "^2.0.0",
-        "typescript": "^7.0.2"
+    "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,23 @@
+version: "13.0"
+description: Defines behavior and limits for the Snowflake ID generator.
+directives:
+  - id: E-106.0
+    dos:
+      - Create time-ordered Snowflake IDs.
+      - Return each ID as a decimal string.
+      - Use configurable epoch and identity values.
+    donts:
+      - 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 use identity values outside the supported bit range.
+      - id: E-106.0.1
+        dos:
+          - 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

@@ -0,0 +1,10 @@
+version: "13.0"
+description: Defines work outside the Snowflake ID library scope.
+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,11 @@
+version: "13.0"
+description: Defines repository requirements for the Snowflake ID library.
+directives:
+  - id: E-106.1
+    dos:
+      - Preserve the documented Snowflake ID behavior.
+      - Return IDs as decimal strings.
+      - Keep credentials and private data private.
+      - Pass repository validation before inspection.
+    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("clock source must be a function");
+
+  return { baseEpoch, ...identity, now };
+}

package/src/generator.mjs

@@ -0,0 +1,49 @@
+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. 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;
+    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) {
-        throw new RangeError('sequence overflow; clock must advance before retrying');
-      }
-    } 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;