{"id":14013,"library":"simple-flakeid","title":"Simple Flake ID Generator","description":"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.","status":"active","version":"0.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/zhupengfeivip/simple-flakeId","tags":["javascript","typescript"],"install":[{"cmd":"npm install simple-flakeid","lang":"bash","label":"npm"},{"cmd":"yarn add simple-flakeid","lang":"bash","label":"yarn"},{"cmd":"pnpm add simple-flakeid","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Main class for instantiating the ID generator. The package ships with TypeScript types.","wrong":"const { SnowflakeIdv1 } = require('simple-flakeid')","symbol":"SnowflakeIdv1","correct":"import { SnowflakeIdv1 } from 'simple-flakeid'"},{"note":"The constructor expects an object with configuration properties, not just a worker ID number directly.","wrong":"new SnowflakeIdv1(1)","symbol":"SnowflakeIdv1 constructor","correct":"new SnowflakeIdv1({ workerId: 1 })"},{"note":"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.","symbol":"ID Generation Methods","correct":"generator.NextId()\ngenerator.NextNumber()\ngenerator.NextBigId()"}],"quickstart":{"code":"import { SnowflakeIdv1 } from 'simple-flakeid';\n\nconst workerId = parseInt(process.env.WORKER_ID ?? '1', 10);\n\n// Initialize the generator with a worker ID\nconst generator = new SnowflakeIdv1({ workerId });\n\nconsole.log(`Generating 10 IDs with workerId: ${workerId}`);\n\nfor (let i = 0; i < 10; i++) {\n    // NextId() dynamically returns number or bigint based on length\n    let id = generator.NextId();\n    console.log(`${i}. ID: ${id} (Type: ${typeof id}, Length: ${id.toString().length})`);\n}\n\n// Example of forcing BigInt output\nfor (let i = 0; i < 3; i++) {\n    let bigId = generator.NextBigId();\n    console.log(`BigInt ID ${i}. ID: ${bigId} (Type: ${typeof bigId})`);\n}\n","lang":"typescript","description":"Initializes a SnowflakeIdv1 generator and demonstrates generating IDs using NextId() and NextBigId() methods, showing dynamic type handling."},"warnings":[{"fix":"Use `NextId()` which dynamically returns `number` or `BigInt`, or `NextBigId()` to always get a `BigInt` for potentially larger IDs.","message":"The `NextNumber()` method will throw an error if the generated ID exceeds JavaScript's `Number.MAX_SAFE_INTEGER` (9007199254740991).","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Always use `BIGINT` (or equivalent large integer type) for ID columns in your database schema to prevent data truncation or overflow errors.","message":"When 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).","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Pin your dependency to a specific patch version (`\"simple-flakeid\": \"0.0.5\"`) or thoroughly test updates before deploying to production.","message":"This 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.","severity":"gotcha","affected_versions":"<1.0.0"}],"env_vars":null,"search_vec":"'0.0.5':23 'activ':101 'aim':29 'algorithm':84 'automat':113 'base':74 'bigint':65,73 'cadenc':93 'care':36 'common':122 'configur':81 'consider':37 'continu':103 'control':111 'core':83 'current':20 'deriv':86 'develop':28,104 'differenti':107 'dynam':69 'earli':27 'error':59 'exceed':61 'explicit':91,110 'flake':2 'flakeid':7 'found':123 'generat':4,13,34,49 'handl':114 'id':3,19,33,50,77,116,129 'indic':100 'integ':43,64,128 'issu':121 'javascript':39,125,130 'javascript/typescript':10 'key':106 'larg':127 'librari':11 'limit':44 'low':98 'magnitud':79 'method':47 'number':53,71 'number.max':41,62 'offer':46 'order':17 'overflow':120 'prevent':119 'provid':31 'recent':97 'releas':92 'robust':32 'safe':42,63 'simpl':1,6 'simple-flakeid':5 'snowflak':18 'standard':52 'state':95 'throw':57 'time':16 'time-ord':15 'type':54,66,70,117 'typescript':131 'uniqu':14 'version':22,99 'yitter/idgenerator':88","created_at":"2026-04-20T01:57:28.951779+00:00","updated_at":"2026-04-20T01:57:28.951779+00:00","problems":[{"fix":"Replace `generator.NextNumber()` with `generator.NextId()` (for dynamic type handling) or `generator.NextBigId()` (to always receive a BigInt).","cause":"Attempting to generate an ID using `NextNumber()` when the calculated ID value is larger than JavaScript's maximum safe integer (9007199254740991).","error":"Error: the ID exceeds Number.MAX_SAFE_INTEGER"},{"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.","cause":"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`.","error":"Type 'bigint' is not assignable to type 'number'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/zhupengfeivip/simple-flakeId","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/simple-flakeid","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}