{"id":26489168,"url":"https://github.com/bur4kbey/snowflake","last_synced_at":"2026-03-10T02:05:02.223Z","repository":{"id":232918257,"uuid":"785451375","full_name":"BUR4KBEY/snowflake","owner":"BUR4KBEY","description":"Easy-to-use Snowflake implementation for generating unique, distributed IDs.","archived":false,"fork":false,"pushed_at":"2024-07-14T01:43:49.000Z","size":116,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-05T13:01:27.830Z","etag":null,"topics":["javascript","nodejs","snowflake","typescript","unique"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/@burakbey/snowflake","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BUR4KBEY.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-04-11T22:57:27.000Z","updated_at":"2024-10-03T22:11:47.000Z","dependencies_parsed_at":"2025-06-02T03:06:45.480Z","dependency_job_id":"f2fec47a-9dd0-468a-b5ac-ea74dcefa9b0","html_url":"https://github.com/BUR4KBEY/snowflake","commit_stats":null,"previous_names":["bur4kbey/snowflake"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/BUR4KBEY/snowflake","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BUR4KBEY%2Fsnowflake","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BUR4KBEY%2Fsnowflake/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BUR4KBEY%2Fsnowflake/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BUR4KBEY%2Fsnowflake/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BUR4KBEY","download_url":"https://codeload.github.com/BUR4KBEY/snowflake/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BUR4KBEY%2Fsnowflake/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30322638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T01:36:58.598Z","status":"online","status_checked_at":"2026-03-10T02:00:06.579Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","nodejs","snowflake","typescript","unique"],"created_at":"2025-03-20T07:20:10.656Z","updated_at":"2026-03-10T02:04:57.214Z","avatar_url":"https://github.com/BUR4KBEY.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![NPM Version](https://img.shields.io/npm/v/%40burakbey%2Fsnowflake?style=for-the-badge\u0026logo=npm\u0026color=blue\u0026cacheSeconds=3600)](https://npmjs.com/package/@burakbey/snowflake)\n[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/bur4kbey/snowflake/test.yml?style=for-the-badge\u0026label=tests\u0026cacheSeconds=3600)](https://github.com/BUR4KBEY/snowflake/actions/workflows/test.yml)\n[![Codecov](https://img.shields.io/codecov/c/github/bur4kbey/snowflake?style=for-the-badge\u0026cacheSeconds=3600)](https://app.codecov.io/gh/BUR4KBEY/snowflake)\n[![GitHub License](https://img.shields.io/github/license/bur4kbey/snowflake?style=for-the-badge)](https://github.com/BUR4KBEY/snowflake/blob/main/LICENSE)\n[![GitHub Repo stars](https://img.shields.io/github/stars/bur4kbey/snowflake?style=for-the-badge\u0026label=%E2%AD%90%20STARS\u0026color=yellow\u0026cacheSeconds=3600)](https://github.com/BUR4KBEY/snowflake)\n\n# ❄️ [@burakbey/snowflake](https://npmjs.com/package/@burakbey/snowflake)\n\nThis library provides an easy-to-use implementation of [Snowflake](https://en.wikipedia.org/wiki/Snowflake_ID) for generating unique, distributed IDs.\n\n## ⚙️ How does it work?\n\nThis library allows you to generate Snowflakes with customizable parameters, ensuring flexibility and reliability in distributed systems:\n\n1. **Set the Epoch**: Determine the starting point in time for your Snowflakes.\n2. **Configure Machine ID Bit Amount**: Define the number of bits allocated for machine IDs to support multiple machines.\n3. **Choose Sequence Number Bit Amount**: Specify the number of bits used for per-machine sequence numbers to ensure uniqueness.\n\nThis library does not produce fixed length Snowflakes (such as only 64 bytes) or allow the generation of Snowflakes with timestamps before the specified epoch. Instead, it enables you to generate Snowflakes according to your specific needs within the constraints of these parameters.\n\nOnce these parameters are set, you can create a `Snowflake` class using the `generateSnowflake` function. After generation, you can generate Snowflakes with this class using the `Snowflake.generate()` method.\n\nRemember to set a unique machine ID for each `Snowflake` class before generating any Snowflakes.\n\nYou can also deconstruct a Snowflake using the `Snowflake.deconstruct()` method to inspect its components based on your Snowflake configuration.\n\n## 🚀 Installation\n\nInstall the package using your preferred package manager. Here's an example using `pnpm`:\n\n```bash\npnpm add @burakbey/snowflake\n```\n\n## 📝 Example Usage\n\nThis example demonstrates usage in TypeScript, but the library is also **compatible** with JavaScript.\n\n```ts\nimport { generateSnowflake } from '@burakbey/snowflake';\n\n// Generate a Snowflake class\n//\n//        flexible                10              12\n// ________________________ + ___________ + _______________\n//        timestamp             machine       per-machine\n//          bits                  id           sequence\n//                               bits         number bits\n//\nconst Snowflake = generateSnowflake({\n  epoch: new Date('2020-01-01T00:00:00.000Z').getTime(),\n  machineIdBitAmount: 10,\n  sequenceNumberBitAmount: 12\n});\n\n// Set a machine id\nSnowflake.setMachineId(0);\n\n// Generate Snowflakes\nconst snowflake1 = Snowflake.generate(); // Uses `Date.now()` by default\nconst snowflake2 = Snowflake.generate(new Date('2022-02-02T22:22:22.222Z')); // Accepts Date objects\nconst snowflake3 = Snowflake.generate(\n  new Date('2023-02-02T22:22:22.222Z').getTime()\n); // Accepts timestamps\n\n// Deconstruct a Snowflake\nconst info = Snowflake.deconstruct(snowflake3);\n\nconsole.log(snowflake1); // 566390217229991936\nconsole.log(snowflake2); // 276839760016703489\nconsole.log(snowflake3); // 409111330960703490\nconsole.log(info); /* {\n                        timestamp: 97539742222,\n                        date: 2023-02-02T22:22:22.222Z,\n                        machineId: 0,\n                        increment: 2,\n                        timestampBits: \"1011010110101110100100101101000001110\",\n                        machineIdBits: \"0000000000\",\n                        incrementBits: \"000000000010\",\n                        allBits: \"10110101101011101001001011010000011100000000000000000000010\",\n                      } */\n```\n\n## 🔑 Minimum Required Bits\n\nTo ensure uniqueness between two generated Snowflakes, it's crucial to reserve **at least one bit for the per-machine sequence number**. However, it's **recommended** to allocate **at least 12 bits** for the sequence number. The more bits allocated, the greater the uniqueness of the Snowflakes.\n\nUsing a small number of bits for the sequence number doesn't guarantee uniqueness. Consider the example below:\n\n```ts\nimport { generateSnowflake } from '@burakbey/snowflake';\n\n// Generate a Snowflake class\nconst Snowflake = generateSnowflake({\n  epoch: new Date('2020-01-01T00:00:00.000Z').getTime(),\n  machineIdBitAmount: 10,\n  sequenceNumberBitAmount: 1 // Example using very few bits for the sequence number\n});\n\n// Set a machine id\nSnowflake.setMachineId(100);\n\n// Generate Snowflakes\nconst s1 = Snowflake.generate();\nconst s2 = Snowflake.generate();\nconst s3 = Snowflake.generate();\n\n// Deconstruct the Snowflakes\nconst i1 = Snowflake.deconstruct(s1);\nconst i2 = Snowflake.deconstruct(s2);\nconst i3 = Snowflake.deconstruct(s3);\n\nconsole.log(`Snowflake: ${s1} | Increment: ${i1.increment}`); // Snowflake: 276703343268040 | Increment: 0\nconsole.log(`Snowflake: ${s2} | Increment: ${i2.increment}`); // Snowflake: 276703343268041 | Increment: 1\nconsole.log(`Snowflake: ${s3} | Increment: ${i3.increment}`); // Snowflake: 276703343268040 | Increment: 0\n```\n\nIn this example, only one bit is reserved for the per-machine sequence number. Generating multiple Snowflakes at the same time on the same machine results in identical Snowflakes being generated. Therefore, it's advisable to reserve a minimum of 12 bits for the sequence number.\n\nOn the other side, you don't have to reserve any bits for the machine id if you work with only one process or replica of your application. It's a common scenario in single-process applications or in cases where there's only one instance of your application running.\n\n```ts\nimport { generateSnowflake } from '@burakbey/snowflake';\n\n// Generate a Snowflake class\nconst Snowflake = generateSnowflake({\n  epoch: new Date('2020-01-01T00:00:00.000Z').getTime(),\n  machineIdBitAmount: 0, // No bits reserved for machine id\n  sequenceNumberBitAmount: 12\n});\n\n// You *must not* use the \"Snowflake.setMachineId()\" method when no bits are reserved for the machine id.\n\n// Generate a Snowflake\nconst snowflake = Snowflake.generate();\n\n// Deconstruct a Snowflake\nconst info = Snowflake.deconstruct(snowflake);\n\nconsole.log(snowflake); // 553408320073728\nconsole.log(info); /* {\n                        timestamp: 135109453143,\n                        date: 2024-04-12T18:24:13.143Z,\n                        machineId: null,\n                        increment: 0,\n                        timestampBits: '1111101110101001001101010010101010111',\n                        machineIdBits: null,\n                        incrementBits: '000000000000',\n                        allBits: '1111101110101001001101010010101010111000000000000'\n                      } */\n```\n\nIn this example, no bits are reserved for the machine id since only one process or replica of the application is being used. Attempting to use the `Snowflake.setMachineId()` method in this scenario would result in an **error**. Instead, you should use the `Snowflake.generate()` method directly to start generating Snowflakes.\n\n## 🧪 Code Coverage and Tests\n\nTests are crucial for ensuring that the library functions as expected. You can review the code coverage reports by visiting [**Codecov**](https://app.codecov.io/gh/BUR4KBEY/snowflake). The primary objective is to achieve complete coverage of the entire codebase through rigorous testing.\n\n## ☕ Support\n\nIf you find this project useful and would like to support [me](https://github.com/BUR4KBEY), you can do so by visiting [my website](https://burakbey.dev).\n\n\u003ca href=\"https://burakbey.dev\" target=\"_blank\"\u003e\u003cimg src=\"https://burakbey.dev/github_support_snippet.png\" style=\"height: 56px !important;width: 200px !important;\" alt=\"Buy me a coffee\"\u003e\u003c/img\u003e\u003c/a\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbur4kbey%2Fsnowflake","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbur4kbey%2Fsnowflake","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbur4kbey%2Fsnowflake/lists"}