{"id":15809965,"url":"https://github.com/theedoran/uuidv7-js","last_synced_at":"2025-11-10T10:03:43.313Z","repository":{"id":236155691,"uuid":"792062391","full_name":"TheEdoRan/uuidv7-js","owner":"TheEdoRan","description":"UUIDv7 generator library for JavaScript, RFC 9562 compliant. Supports encoding/decoding UUIDs to custom alphabets.","archived":false,"fork":false,"pushed_at":"2024-07-04T23:26:53.000Z","size":99,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-16T18:37:23.925Z","etag":null,"topics":["id","id-gen","rfc-9562","uuid","uuidv7"],"latest_commit_sha":null,"homepage":"https://npmjs.com/uuidv7-js","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/TheEdoRan.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},"funding":{"github":["TheEdoRan"]}},"created_at":"2024-04-25T22:47:43.000Z","updated_at":"2025-01-13T09:46:26.000Z","dependencies_parsed_at":"2024-05-19T00:23:13.432Z","dependency_job_id":"c20b234b-b4df-44f2-a1be-e9710784d249","html_url":"https://github.com/TheEdoRan/uuidv7-js","commit_stats":null,"previous_names":["theedoran/uuidv7-js"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/TheEdoRan/uuidv7-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheEdoRan%2Fuuidv7-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheEdoRan%2Fuuidv7-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheEdoRan%2Fuuidv7-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheEdoRan%2Fuuidv7-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheEdoRan","download_url":"https://codeload.github.com/TheEdoRan/uuidv7-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheEdoRan%2Fuuidv7-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271448361,"owners_count":24761434,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"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":["id","id-gen","rfc-9562","uuid","uuidv7"],"created_at":"2024-10-05T03:41:49.894Z","updated_at":"2025-11-10T10:03:38.271Z","avatar_url":"https://github.com/TheEdoRan.png","language":"TypeScript","funding_links":["https://github.com/sponsors/TheEdoRan"],"categories":[],"sub_categories":[],"readme":"# [uuidv7-js](https://github.com/TheEdoRan/uuidv7-js)\n\nUUIDv7 generator library for JavaScript, [RFC 9562](https://datatracker.ietf.org/doc/html/rfc9562) compliant. Supports encoding/decoding UUIDs to custom alphabets.\n\n## Installation\n\n```sh\nnpm i uuidv7-js\n```\n\n## Usage\n\n```typescript\nimport { UUIDv7, uuidv7, encodeUUIDv7, decodeUUIDv7 } from \"uuidv7-js\";\n\n// Initialize a new UUIDv7 generator.\n// You can pass a custom encoding alphabet here.\nconst uuid = new UUIDv7();\n\nconst id = uuid.gen(); // 018ef3e8-90e2-7be4-b4ea-4be3bf8803b7\nconst encoded = uuid.encode(id); // CANANjseoigQthQMd1VwC\nconst decoded = uuid.decode(encoded); // 018ef3e8-90e2-7be4-b4ea-4be3bf8803b7\nconst isValid = UUIDv7.isValid(id); // true\nconst timestamp = UUIDv7.timestamp(id); // 1713489088738\nconst date = UUIDv7.date(id); // 2024-04-19T01:11:28.738Z\n\n// You can also use convenient function aliases if you don't need to use a custom alphabet.\nconst id = uuidv7(); // 018ef3e8-90e2-7be4-b4ea-4be3bf8803b7\nconst encoded = encodeUUIDv7(id); // CANANjseoigQthQMd1VwC\nconst decoded = decodeUUIDv7(encoded); // // 018ef3e8-90e2-7be4-b4ea-4be3bf8803b7\n```\n\n## Create a new instance\n\n```typescript\nconst uuid = new UUIDv7(opts?: { encodeAlphabet?: string })\n```\n\nCreates a new `UUIDv7` instance. By default it uses the [Base58](https://www.cs.utexas.edu/users/moore/acl2/manuals/current/manual/index-seo.php/BITCOIN_____A2BASE58-CHARACTERS_A2) alphabet to `encode` and `decode` UUIDs, but you can pass a custom alphabet (16-64 characters).\n\n### Instance methods\n\n#### `gen`\n\n```typescript\ngen(customTimestamp?: number) =\u003e string\n```\n\nGenerates a new UUIDv7. You can provide a custom timestamp to be used instead of the current one.\n\n#### `genMany`\n\n```typescript\ngenMany(amount: number, customTimestamp?: number) =\u003e string[]\n```\n\nGenerates a custom amount of UUIDv7s. You can provide a custom timestamp to be used instead of the current one.\n\n#### `encode`\n\n```typescript\nencode(id: string) =\u003e string\n```\n\nEncodes a UUIDv7 using the alphabet passed to the constructor or the default one.\n\n#### `decode`\n\n```typescript\ndecode(encodedId: string) =\u003e string | null\n```\n\nDecodes an encoded UUIDv7 using the alphabet passed to the constuctor or the default one. If the UUIDv7 is not valid, `null` is returned.\n\n#### `decodeOrThrow`\n\n```typescript\ndecodeOrThrow(encodedId: string) =\u003e string\n```\n\nDecodes an encoded UUIDv7 using the alphabet passed to the constuctor or the default one. If the UUIDv7 is not valid, an error is thrown.\n\n### Static methods\n\n#### `UUIDv7.isValid`\n\n```typescript\nUUIDv7.isValid(id: string) =\u003e boolean\n```\n\nChecks if the UUIDv7 is valid.\n\n#### `UUIDv7.timestamp`\n\n```typescript\nUUIDv7.timestamp(id: string) =\u003e number | null\n```\n\nReturns the timestamp part of the UUIDv7. If the UUIDv7 is not valid, `null` is returned.\n\n#### `UUIDv7.date`\n\n```typescript\nUUIDv7.date(id: string) =\u003e Date | null\n```\n\nReturns the timestamp part of the UUIDv7 converted to `Date`. If the UUIDv7 is not valid, `null` is returned.\n\n### Function aliases\n\nThe library provides a few function aliases for convenience. You can use them without creating a new `UUIDv7` instance:\n\n| Function name         | Instance method | Description                                                                                   |\n| --------------------- | --------------- | --------------------------------------------------------------------------------------------- |\n| `uuidv7`              | `gen`           | Generates a new UUIDv7.                                                                       |\n| `encodeUUIDv7`        | `encode`        | Encodes a UUIDv7 with the default Base58 alphabet.                                            |\n| `decodeUUIDv7`        | `decode`        | Decodes an encoded UUIDv7 from Base58 alphabet. Returns null if the encoded ID is invalid.    |\n| `decodeOrThrowUUIDv7` | `decodeOrThrow` | Decodes an encoded UUIDv7 from Base58 alphabet. Throws an error if the encoded ID is invalid. |\n\n## Implementation details\n\nThis library implements the [RFC 9562](https://datatracker.ietf.org/doc/html/rfc9562#name-uuid-version-7) spec to generate UUIDv7s:\n\n- if the current timestamp is ahead of the last stored one, it generates new `rand_a` and `rand_b` parts;\n- if the current timestamp is behind the last stored one, it waits for the next valid timestamp to return a UUIDv7 with newly generated `rand_a` and `rand_b` parts;\n- if the current timestamp is the same as the last stored one:\n  - it uses `rand_b` and then `rand_a` as randomly seeded counters, in that order. `rand_b` is the primary counter, and `rand_a` is used as the secondary one, when `rand_b` overflows its 62 bits (rare case). When used as a counter, `rand_b` increments its previous random value by a random integer between 1 and 4,294,967,296 (2^32), and `rand_a` increments its previous random value by 1, while generating a new `rand_b` part.\n  - if both counters overflow their bit sizes, the generation function waits for the next millisecond to return a UUIDv7 with newly generated random parts.\n\nThis approach follows the [method 2](https://datatracker.ietf.org/doc/html/rfc9562#monotonicity_counters) of the \"Monotonicity and Counters\" section of the spec. It guarantees monotonicity and uniqueness per instance, and always keeps timestamp the same as `Date.now()` value.\n\nIf you provide a custom timestamp, it will be used instead of the current one. Generation works differently in this case:\n\n- if the custom timestamp is different from the last custom stored one, it generates new `rand_a` and `rand_b` parts;\n- if the custom timestamp is the same as the last custom stored one, it uses `rand_b` and then `rand_a` as randomly seeded counters, in that order, just like the normal generation method. If both `rand_a` and `rand_b` overflow, though, the generator creates new `rand_a` and `rand_b` parts. This breaks monotonicity per instance with custom timestamp, but ensures that a valid UUIDv7 is always returned. Keep in mind that this is an extremely rare case and should really never happen.\n\n## Field and Bit Layout\n\nThis is the UUIDv7 Field and Bit Layout, took from the spec linked above:\n\n```\n 0                   1                   2                   3\n 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|                           unix_ts_ms                          |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|          unix_ts_ms           |  ver  |       rand_a          |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|var|                        rand_b                             |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|                            rand_b                             |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n```\n\n### Description\n\n#### unix_ts_ms\n\n48 bit big-endian unsigned number of Unix epoch timestamp in milliseconds as per [Section 6.1](https://datatracker.ietf.org/doc/html/rfc9562#timestamp_considerations). Occupies bits 0 through 47 (octets 0-5).\n\n#### ver\n\nThe 4 bit version field as defined by [Section 4.2](https://datatracker.ietf.org/doc/html/rfc9562#version_field), set to 0b0111 (7). Occupies bits 48 through 51 of octet 6.\n\n#### rand_a\n\n12 bits pseudo-random data to provide uniqueness as per [Section 6.9](https://datatracker.ietf.org/doc/html/rfc9562#unguessability) and/or optional constructs to guarantee additional monotonicity as per [Section 6.2](https://datatracker.ietf.org/doc/html/rfc9562#monotonicity_counters). Occupies bits 52 through 63 (octets 6-7).\n\n#### var\n\nThe 2 bit variant field as defined by [Section 4.1](https://datatracker.ietf.org/doc/html/rfc9562#variant_field), set to 0b10. Occupies bits 64 and 65 of octet 8.\n\n#### rand_b\n\nThe final 62 bits of pseudo-random data to provide uniqueness as per [Section 6.9](https://datatracker.ietf.org/doc/html/rfc9562#unguessability) and/or an optional counter to guarantee additional monotonicity as per [Section 6.2](https://datatracker.ietf.org/doc/html/rfc9562#monotonicity_counters). Occupies bits 66 through 127 (octets 8-15).\n\n## Feedback\n\nIf you found a bug in the implementation, please open a new [issue](https://github.com/TheEdoRan/uuidv7-js/issues/new).\n\n## Alternatives\n\n- [uuidv7](https://www.npmjs.com/package/uuidv7) by [LiosK](https://github.com/LiosK)\n\n## License\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheedoran%2Fuuidv7-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheedoran%2Fuuidv7-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheedoran%2Fuuidv7-js/lists"}