{"id":21531897,"url":"https://github.com/matrixai/js-id","last_synced_at":"2025-04-10T00:28:55.176Z","repository":{"id":43716271,"uuid":"413671301","full_name":"MatrixAI/js-id","owner":"MatrixAI","description":"ID generation for JavaScript \u0026 TypeScript Applications","archived":false,"fork":false,"pushed_at":"2025-03-31T22:25:45.000Z","size":1051,"stargazers_count":11,"open_issues_count":8,"forks_count":1,"subscribers_count":5,"default_branch":"staging","last_synced_at":"2025-03-31T23:26:47.498Z","etag":null,"topics":["id","monotonic","random","uuid","uuid-generator"],"latest_commit_sha":null,"homepage":"https://polykey.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MatrixAI.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}},"created_at":"2021-10-05T04:19:52.000Z","updated_at":"2025-03-31T22:25:49.000Z","dependencies_parsed_at":"2024-06-21T14:18:28.232Z","dependency_job_id":"262a2bb1-ae1a-4b29-9a74-349cdeab074d","html_url":"https://github.com/MatrixAI/js-id","commit_stats":{"total_commits":57,"total_committers":4,"mean_commits":14.25,"dds":"0.14035087719298245","last_synced_commit":"b508247f05a5948038f1c2ff248e4f1d7ef164ae"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2Fjs-id","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2Fjs-id/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2Fjs-id/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2Fjs-id/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MatrixAI","download_url":"https://codeload.github.com/MatrixAI/js-id/tar.gz/refs/heads/staging","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248133832,"owners_count":21053330,"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","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","monotonic","random","uuid","uuid-generator"],"created_at":"2024-11-24T02:18:05.270Z","updated_at":"2025-04-10T00:28:55.163Z","avatar_url":"https://github.com/MatrixAI.png","language":"TypeScript","readme":"# js-id\n\nID generation for JavaScript \u0026 TypeScript applications.\n\nExample Usage:\n\n```ts\nimport { IdRandom, IdDeterministic, IdSortable, utils } from '@matrixai/id';\n\n// Random ids, equivalent to UUIDv4\n\nconst randGen = new IdRandom();\n\nconst randIds = [...utils.take(randGen, 3)];\nconsole.log(randIds.map((b) =\u003e utils.toUUID(b)));\n\n// Deterministic ids, equivalent to UUIDv5\n\nconst deteGen = new IdDeterministic({\n  namespace: 'foo'\n});\n\nconst deteId1 = deteGen.get();\nconst deteId2 = deteGen.get('bar');\nconst deteId3 = deteGen.get('bar');\n\nconsole.log(utils.toUUID(deteId1));\nconsole.log(utils.toMultibase(deteId2, 'base32hex'));\n\n// Will be cast to string index\nconst recordOfDeteIds = {};\nrecordOfDeteIds[deteId1] = 1;\nrecordOfDeteIds[deteId2] = 1;\nconsole.log(recordOfDeteIds[deteId1]);\n\n// Can be checked for equality\nconsole.log(deteId2.equals(deteId3));\n// Binary string form can be checked for equality\nconsole.log(deteId2.toString() === deteId3.toString());\n\n// Strictly monotonic sortable ids, equivalent to UUIDv7\n\nlet lastId = new Uint8Array(\n  [\n    0x06, 0x16, 0x3e, 0xf5, 0x6d, 0x8d, 0x70, 0x00,\n    0x87, 0xc4, 0x65, 0xd5, 0x21, 0x9b, 0x03, 0xd4,\n  ]\n);\n\nconst sortGen = new IdSortable({ lastId });\n\nconst sortId1 = sortGen.get();\nconst sortId2 = sortGen.get();\nconst sortId3 = sortGen.get();\n\nconst sortIds = [\n  utils.toBuffer(sortId2),\n  utils.toBuffer(sortId3),\n  utils.toBuffer(sortId1),\n];\n\nsortIds.sort(Buffer.compare);\n\nconsole.log(sortIds);\n\n// Save the last id to ensure strict monotonicity across process restarts\nlastId = sortGen.lastId;\n\n// Ids can also be compared in order\nconsole.log(sortId1 \u003c sortId2);\nconsole.log(sortId2 \u003c sortId3);\n```\n\n**Base Encoding and Lexicographic Order**\n\nIt is important to realise that not all base-encodings preserve lexicographic sort order. The UUID (hex-encoding) and `base32hex` does, but `base58btc` and `base64` does not. Make sure to pick an appropriate base encoding if you are expecting to compare the `IdSortable` as base-encoded strings.\n\nOut of all the multibase encodings, the only ones that preserve sort order are:\n\n```\nbase2\nbase8\nbase16\nbase16upper\nbase32hex\nbase32hexupper\nbase32hexpad\nbase32hexpadupper\n```\n\nIn addition to this, JS binary string encoding through `id.toString()` also preserves sort order.\n\n## Installation\n\n```sh\nnpm install --save @matrixai/id\n```\n\n## Development\n\nRun `nix develop`, and once you're inside, you can use:\n\n```sh\n# install (or reinstall packages from package.json)\nnpm install\n# build the dist\nnpm run build\n# run the repl (this allows you to import from ./src)\nnpm run tsx\n# run the tests\nnpm run test\n# lint the source code\nnpm run lint\n# automatically fix the source\nnpm run lintfix\n```\n\n### Docs Generation\n\n```sh\nnpm run docs\n```\n\nSee the docs at: https://matrixai.github.io/js-id/\n\n### Publishing\n\nPublishing is handled automatically by the staging pipeline.\n\nPrerelease:\n\n```sh\n# npm login\nnpm version prepatch --preid alpha # premajor/preminor/prepatch\ngit push --follow-tags\n```\n\nRelease:\n\n```sh\n# npm login\nnpm version patch # major/minor/patch\ngit push --follow-tags\n```\n\nManually:\n\n```sh\n# npm login\nnpm version patch # major/minor/patch\nnpm run build\nnpm publish --access public\ngit push\ngit push --tags\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrixai%2Fjs-id","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrixai%2Fjs-id","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrixai%2Fjs-id/lists"}