Registry / serialization / simple-flakeid

simple-flakeid

library0.0.5jsnpmunverified

simple-flakeid is a JavaScript/TypeScript library for generating unique, time-ordered Snowflake IDs. Currently at version 0.0.5, it's in early development, aiming to provide robust ID generation with careful consideration for JavaScript's `Number.MAX_SAFE_INTEGER` limitation. It offers methods to generate IDs as standard `number` types (which can throw an error if exceeding `Number.MAX_SAFE_INTEGER`), `BigInt` types, or a dynamic type (`number` or `BigInt`) based on the ID's magnitude and configuration. The core algorithm is derived from yitter/idgenerator. While no explicit release cadence is stated, its recent low version indicates active and continuous development. A key differentiator is the explicit control and automatic handling of ID types to prevent overflow issues commonly found in JavaScript with large integer IDs.

serialization database

npm install simple-flakeid

github ↗package ↗

INSTALL

IMPORT

SIG · SIMPLE-FLAKEID

simple-flakeid

serializationjavascriptv0.0.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SnowflakeIdv1

✓ import { SnowflakeIdv1 } from 'simple-flakeid'

✗ const { SnowflakeIdv1 } = require('simple-flakeid')

Main class for instantiating the ID generator. The package ships with TypeScript types.

SnowflakeIdv1 constructor

✓ new SnowflakeIdv1({ workerId: 1 })

✗ new SnowflakeIdv1(1)

The constructor expects an object with configuration properties, not just a worker ID number directly.

ID Generation Methods

✓ generator.NextId() generator.NextNumber() generator.NextBigId()

These methods are called on an instance of SnowflakeIdv1. NextId() returns number or BigInt, NextNumber() always returns number (throws on overflow), and NextBigId() always returns BigInt.

Initializes a SnowflakeIdv1 generator and demonstrates generating IDs using NextId() and NextBigId() methods, showing dynamic type handling.

import { SnowflakeIdv1 } from 'simple-flakeid'; const workerId = parseInt(process.env.WORKER_ID ?? '1', 10); // Initialize the generator with a worker ID const generator = new SnowflakeIdv1({ workerId }); console.log(`Generating 10 IDs with workerId: ${workerId}`); for (let i = 0; i < 10; i++) { // NextId() dynamically returns number or bigint based on length let id = generator.NextId(); console.log(`${i}. ID: ${id} (Type: ${typeof id}, Length: ${id.toString().length})`); } // Example of forcing BigInt output for (let i = 0; i < 3; i++) { let bigId = generator.NextBigId(); console.log(`BigInt ID ${i}. ID: ${bigId} (Type: ${typeof bigId})`); }

Debug

Known issues

gotchaThe `NextNumber()` method will throw an error if the generated ID exceeds JavaScript's `Number.MAX_SAFE_INTEGER` (9007199254740991).

fix

Use `NextId()` which dynamically returns `number` or `BigInt`, or `NextBigId()` to always get a `BigInt` for potentially larger IDs.

affects: >=0.0.1

gotchaWhen storing generated IDs in databases like MySQL, ensure the column type is `BIGINT` as the default generated IDs (even `number` types in JS) can exceed the maximum value for a standard `INT` column (typically 10 digits vs. 15-19 digits for Flake IDs).

fix

Always use `BIGINT` (or equivalent large integer type) for ID columns in your database schema to prevent data truncation or overflow errors.

affects: >=0.0.1

gotchaThe `NextId()` method's return type is conditional (`number | BigInt`). Ensure your code handles both possible types, especially when performing arithmetic operations or strict type checks, to avoid runtime errors.

fix

Use type guards (`typeof id === 'bigint'`) or explicitly convert `BigInt` to `number` (with caution for precision) or `string` before use if your consuming code expects a specific type.

affects: >=0.0.1

gotchaThis package is currently at version 0.0.5, indicating it is in early development. While functional, API stability may not be fully guaranteed, and minor versions might introduce breaking changes without a major version bump.

fix

Pin your dependency to a specific patch version (`"simple-flakeid": "0.0.5"`) or thoroughly test updates before deploying to production.

affects: <1.0.0

Errors

Common errors & fixes

Error: the ID exceeds Number.MAX_SAFE_INTEGER

Attempting to generate an ID using `NextNumber()` when the calculated ID value is larger than JavaScript's maximum safe integer (9007199254740991).

fix

Replace `generator.NextNumber()` with `generator.NextId()` (for dynamic type handling) or `generator.NextBigId()` (to always receive a BigInt).

Type 'bigint' is not assignable to type 'number'.

This TypeScript error occurs when a `BigInt` value (e.g., from `NextBigId()` or `NextId()` when it returns a `BigInt`) is assigned to a variable or used in a context expecting a `number`.

fix

Change the variable type to `bigint` or `number | bigint`. If you need a `number`, ensure the ID is within `Number.MAX_SAFE_INTEGER` and consider `Number(bigIntValue)` for explicit (and potentially lossy) conversion, or `.toString()` for string representation.

Upgrade

Version history

0.0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Anthropic

Resources

githubhttps://github.com/zhupengfeivip/simple-flakeId ↗

packagehttps://www.npmjs.com/package/simple-flakeid ↗