@eliware/snowflake 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2025 Eli Sterling, eliware.org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# [![eliware.org](https://eliware.org/logos/brand.png)](https://discord.gg/M6aTR9eTwN)
+
+## @eliware/snowflake [![npm version](https://img.shields.io/npm/v/@eliware/snowflake.svg)](https://www.npmjs.com/package/@eliware/snowflake)[![license](https://img.shields.io/github/license/eliware/snowflake.svg)](LICENSE)[![build status](https://github.com/eliware/snowflake/actions/workflows/nodejs.yml/badge.svg)](https://github.com/eliware/snowflake/actions)
+
+> A snowflake for Node.js (Insert Brief Description)
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [ESM Example](#esm-example)
+  - [CommonJS Example](#commonjs-example)
+- [API](#api)
+- [TypeScript](#typescript)
+- [Testing](#testing)
+- [License](#license)
+
+## Features
+
+- Minimal, dependency-light Snowflake ID generator compatible with Discord-style bit layout.
+- BigInt-safe implementation to preserve full 64-bit IDs.
+- Works in both ESM and CommonJS environments.
+- Configurable epoch and worker ID via a factory function.
+- Includes TypeScript declarations and basic tests.
+
+## Installation
+
+Install from npm:
+
+```bash
+npm install @eliware/snowflake
+```
+
+## Usage
+
+### ESM Example
+
+```js
+// ESM (index.mjs)
+import generate, { createSnowflakeGenerator } from './index.mjs';
+
+// default generator (workerId: 0)
+console.log('id:', generate());
+
+// create a generator for a specific worker ID
+const gen = createSnowflakeGenerator({ workerId: 1 });
+console.log('worker 1 id:', gen());
+```
+
+### CommonJS Example
+
+```js
+// CommonJS (index.cjs)
+const generate = require('./index.cjs');
+const { createSnowflakeGenerator } = require('./index.cjs');
+
+console.log('id:', generate());
+
+const gen = createSnowflakeGenerator({ workerId: 2 });
+console.log('worker 2 id:', gen());
+```
+
+## API
+
+### createSnowflakeGenerator(options?) => () => string
+
+- options.epoch: number | bigint (default: 1420070400000) — base epoch in milliseconds (Discord epoch: 2015-01-01T00:00:00.000Z).
+- options.workerId: number (default: 0) — numeric worker/node ID (10-bit value).
+
+Returns a zero-argument function that generates a new Snowflake ID (as a decimal string) each call.
+
+Behavior notes:
+- Timestamp uses (Date.now() - epoch) shifted left 22 bits.
+- Worker ID occupies 10 bits, sequence counter occupies 12 bits.
+- The generator waits for the next millisecond if more than 4095 IDs are requested in the same millisecond.
+
+### Default export: generate()
+
+A ready-to-use generator (workerId 0). It returns a decimal string representation of the Snowflake ID.
+
+## TypeScript
+
+Type definitions are included (index.d.ts). Example signatures:
+
+```ts
+export function createSnowflakeGenerator(options?: { epoch?: number | bigint; workerId?: number }): () => string;
+export const generate: () => string;
+export default generate;
+```
+
+## Testing
+
+A small Jest test suite is included (index.test.mjs / index.test.cjs) that verifies:
+
+- Generated IDs are numeric strings parseable to BigInt.
+- Consecutive IDs are monotonically increasing.
+- Worker ID bits are encoded correctly.
+- Timestamp portion decodes to a recent time.
+
+Run tests with:
+
+```bash
+npm test
+```
+
+---
+
+## 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)**
+
+## License
+
+[MIT © 2025 Eli Sterling, eliware.org](LICENSE)
+
+## Links
+
+- [Home Page](https://eliware.org)
+- [GitHub](https://github.com/eliware/snowflake)
+- [npm](https://www.npmjs.com/package/@eliware/snowflake)
+- [Discord](https://discord.gg/M6aTR9eTwN)

package/index.cjs

@@ -0,0 +1,37 @@
+// Snowflake generator (CommonJS)
+const DEFAULT_EPOCH = 1420070400000n; // Discord epoch: 2015-01-01T00:00:00.000Z
+
+function createSnowflakeGenerator({ epoch = DEFAULT_EPOCH, workerId = 0 } = {}) {
+  const _epoch = BigInt(epoch);
+  const _workerId = BigInt(workerId) & 0x3ffn; // 10 bits
+  let lastTimestamp = 0n;
+  let sequence = 0n;
+
+  return function generate() {
+    let now = BigInt(Date.now());
+
+    if (now === lastTimestamp) {
+      sequence = (sequence + 1n) & 0xfffn; // 12 bits
+      if (sequence === 0n) {
+        // Sequence overflow in the same millisecond — wait for next ms
+        while (now <= lastTimestamp) {
+          now = BigInt(Date.now());
+        }
+      }
+    } else {
+      sequence = 0n;
+    }
+
+    lastTimestamp = now;
+
+    const id = ((now - _epoch) << 22n) | (_workerId << 12n) | sequence;
+    return id.toString();
+  };
+}
+
+// Default generator (workerId 0)
+const generate = createSnowflakeGenerator();
+
+module.exports = generate;
+module.exports.generate = generate;
+module.exports.createSnowflakeGenerator = createSnowflakeGenerator;

package/index.d.ts

@@ -0,0 +1,3 @@
+export function createSnowflakeGenerator(options?: { epoch?: number | bigint; workerId?: number }): () => string;
+export const generate: () => string;
+export default generate;

package/index.mjs

@@ -0,0 +1,34 @@
+// Snowflake generator (ESM)
+const DEFAULT_EPOCH = 1420070400000n; // Discord epoch: 2015-01-01T00:00:00.000Z
+
+export function createSnowflakeGenerator({ epoch = DEFAULT_EPOCH, workerId = 0 } = {}) {
+  const _epoch = BigInt(epoch);
+  const _workerId = BigInt(workerId) & 0x3ffn; // 10 bits
+  let lastTimestamp = 0n;
+  let sequence = 0n;
+
+  return function generate() {
+    let now = BigInt(Date.now());
+
+    if (now === lastTimestamp) {
+      sequence = (sequence + 1n) & 0xfffn; // 12 bits
+      if (sequence === 0n) {
+        // Sequence overflow in the same millisecond — wait for next ms
+        while (now <= lastTimestamp) {
+          now = BigInt(Date.now());
+        }
+      }
+    } else {
+      sequence = 0n;
+    }
+
+    lastTimestamp = now;
+
+    const id = ((now - _epoch) << 22n) | (_workerId << 12n) | sequence;
+    return id.toString();
+  };
+}
+
+// Default generator (workerId 0)
+export const generate = createSnowflakeGenerator();
+export default generate;

package/package.json

@@ -0,0 +1,61 @@
+{
+    "name": "@eliware/snowflake",
+    "type": "module",
+    "version": "1.1.1",
+    "description": "A minimal Node.js Snowflake ID generator (Discord-compatible). Provides BigInt-safe generators for ESM and CommonJS with configurable epoch and worker ID.",
+    "main": "index.cjs",
+    "module": "index.mjs",
+    "types": "index.d.ts",
+    "files": [
+        "index.mjs",
+        "index.cjs",
+        "index.d.ts",
+        "README.md",
+        "LICENSE"
+    ],
+    "exports": {
+        ".": {
+            "import": "./index.mjs",
+            "require": "./index.cjs",
+            "types": "./index.d.ts"
+        }
+    },
+    "scripts": {
+        "test": "npx --node-options=\"--experimental-vm-modules --no-warnings\" jest --detectOpenHandles --silent"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/eliware/snowflake.git"
+    },
+    "keywords": [
+        "snowflake",
+        "snowflake-id",
+        "id-generator",
+        "discord",
+        "unique-id",
+        "bigint",
+        "nodejs",
+        "esm",
+        "cjs"
+    ],
+    "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.0.4"
+    },
+    "jest": {
+        "testEnvironment": "node",
+        "testMatch": [
+            "**/?(*.)+(spec|test).[jt]s?(x)",
+            "**/?(*.)+(spec|test).mjs",
+            "**/?(*.)+(spec|test).cjs"
+        ]
+    },
+    "dependencies": {
+        "@eliware/common": "^1.1.1"
+    }
+}