{"id":21681764,"url":"https://github.com/cbschuld/uuid-base58","last_synced_at":"2025-10-18T01:44:39.196Z","repository":{"id":42893696,"uuid":"253848206","full_name":"cbschuld/uuid-base58","owner":"cbschuld","description":"Generate a RFC4122 compliant v4 UUID and return it encoded in base-58. This is great for creating unique IDs which only consume 22 characters of storage. Also provides base-58 encoding and decoding.","archived":false,"fork":false,"pushed_at":"2023-10-18T15:36:18.000Z","size":426,"stargazers_count":22,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-09T02:38:20.596Z","etag":null,"topics":["base58","typescript","uuid"],"latest_commit_sha":null,"homepage":"","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/cbschuld.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2020-04-07T16:17:38.000Z","updated_at":"2025-04-03T07:52:30.000Z","dependencies_parsed_at":"2024-06-21T12:57:54.956Z","dependency_job_id":"716b8dbe-8fd8-4e1c-a0c5-9b509ae083af","html_url":"https://github.com/cbschuld/uuid-base58","commit_stats":{"total_commits":25,"total_committers":4,"mean_commits":6.25,"dds":0.56,"last_synced_commit":"513841c8d43955a284ef3a298bbb02a7f965e04b"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbschuld%2Fuuid-base58","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbschuld%2Fuuid-base58/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbschuld%2Fuuid-base58/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbschuld%2Fuuid-base58/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cbschuld","download_url":"https://codeload.github.com/cbschuld/uuid-base58/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248530613,"owners_count":21119592,"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":["base58","typescript","uuid"],"created_at":"2024-11-25T15:31:18.809Z","updated_at":"2025-10-18T01:44:39.190Z","avatar_url":"https://github.com/cbschuld.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# uuid-base58\n\n\u003cp\u003e\n  \u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/dw/uuid-base58?style=flat-square\"/\u003e\u003c!-- downloads --\u003e\n  \u003cimg alt=\"license\" src=\"https://img.shields.io/npm/l/uuid-base58?style=flat-square\"/\u003e\u003c!-- license --\u003e\n  \u003cimg alt=\"size\" src=\"https://img.shields.io/bundlephobia/min/uuid-base58\"/\u003e\u003c!-- bundle size --\u003e\n  \u003cimg alt=\"build\" src=\"https://img.shields.io/github/actions/workflow/status/cbschuld/uuid-base58/ci.yml?branch=master\"/\u003e\u003c!-- build --\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square\"/\u003e\u003c!-- PRs welcome --\u003e\n\u003c/p\u003e\n\nGenerate a RFC4122 compliant v4 UUID and return it encoded in base-58. This is great for creating unique IDs which only consume 22 characters of storage (_some encodes are 21 characters_). Also library also provides base-58 encoding, decoding and validation.\n\n## Installation\n\n```sh\nnpm install uuid-base58\n```\n\n## Usage: creating a base58 UUID string\n\n```typescript\nimport { uuid58 } from 'uuid-base58';\n\nconst id = uuid58();\n```\n\n## Usage: validation of a base58 UUID string\n\n```typescript\nimport { strict as assert } from 'assert';\nimport { uuid58, valid } from 'uuid-base58';\n\nconst id = uuid58();\nassert(valid(id)); // true\n```\n\n## API\n\nThe uuid58 package provides the following functions:\n\n- `uuid58` - creates the RFC4122 v4 UUID encoded in base-58\n- `encode(string)` - encodes a base-16 string in base-58\n- `decode(string)` - decodes a string from base-58 to base-16\n- `valid(string)` - returns true if the string is a valid base-58 string\n- `uuidV4NoDash()` - creates a RFC4122 v4 UUID without dashes\n\n## Notes on validation with valid(string)\n\nThe validation is optimistic such that if the encoding will decode into a valid UUID it will return true. The validation will return false if the representative number overflows 128bits or if the base58 number is zero (0). A UUID-based base58 value of `1` is a valid UUID of `00000000-0000-0000-0000-000000000000` and a base58 value of `2` is `00000000-0000-0000-0000-000000000001`. These are valid base58 values that can become valid UUIDs. The `valid()` function will also return false if a character in the base58 is not supported in the encoding hash alphabet which does not include `l` or `0` as an example.\n\n## Testing\n\n```sh\nnpm run test\n```\n\n## Performance\n\n### \u003c= v1.1\n\nThere is finite performance cost to translate a v4 UUID into base58. Testing the overhead for the translation to base58 exposes an additional 25% increase. Three quarters of the runtime was consumed calculating the v4 uuid. Additional work could be done to bring the uuid calculation internal and attempt to increase performance.\n\n![performance graph](https://raw.githubusercontent.com/cbschuld/uuid-base58/master/__tests__/performance.png)\n\n### Performance Update (\u003e=v1.2.0)\n\nIn version =\u003e1.2 additional performance work was completed by removing the validation process from the v4 UUID calculation and the runtime from the amazing [uuid](https://github.com/uuidjs/uuid) project was lifted and placed into `src/uuid` of this project. The package reduction was significant: 340kB to 5kB (18kB unpacked). Unfortunately little to no substantial performance increase although it was noticed v1.2 did consistently score better in realtime results but user+system remained nearly the same over 4M test generations. Additionally, the UUID string management process was updated to not create a traditional dashed uuid and the `uuid` v4 validation process was removed (_which addresses specific user input and does not intersect v4 calculation_). Performance increases are likely at a point of diminishing returns.\n\n![performance graph](https://user-images.githubusercontent.com/231867/111826829-65468080-88a6-11eb-86ad-3f254c017a89.png)\n\n## Package Size\n\nFor version \u003e= 1.2.X the official dependency on the [uuid](https://github.com/uuidjs/uuid) project was removed. The solution and dependency are still in use but only the portion required for a v4 UUID was marshalled over. The runtime was altered slightly and added to the `src/uuid` path. Current sizing is around 5kB (18kB unpacked), down from 340kB.\n\n## Base58 Alphabet\n\nThis solution uses the Bitcoin / IPFS hash alphabet:\n\n```\n123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz\n```\n\n[Additional information on Base-58](https://en.wikipedia.org/wiki/Base58).\n\n## Environment Support\n\n- CommonJS: `const { uuid58 } = require('uuid-base58')`\n- ESM (Node/bundlers): `import { uuid58 } from 'uuid-base58'`\n- Node versions: tested on Node 18/20/22; engines set to `\u003e=14`.\n- Browser: RNG prefers `globalThis.crypto.getRandomValues`. If unavailable (very old browsers), a secure RNG is required and an error is thrown. Most modern browsers support Web Crypto.\n\n### Examples\n\nCommonJS (Node):\n\n```js\n// index.cjs\nconst { uuid58, encode, decode, valid, uuidV4NoDash } = require('uuid-base58');\n\nconst id = uuid58();\nconsole.log('uuid58:', id);\nconsole.log('valid:', valid(id));\n```\n\nESM (Node or bundlers):\n\n```js\n// index.mjs or in a TypeScript file\nimport { uuid58, encode, decode, valid, uuidV4NoDash } from 'uuid-base58';\n\nconst id = uuid58();\nconsole.log('uuid58:', id);\nconsole.log('valid:', valid(id));\n```\n\nBrowser (with bundler):\n\n```ts\n// In a front-end app (Vite, Webpack, etc.)\nimport { uuid58 } from 'uuid-base58';\n\n// Requires Web Crypto (available in modern browsers)\nconst id = uuid58();\ndocument.body.textContent = id;\n```\n\nSee a runnable Vite example in `examples/vite-basic`.\n\n## Migration from v1.x to v2.0\n\n**Breaking Changes:**\n- **Node.js 14+ required** - upgrade Node.js if using older versions\n- **Package exports enforced** - only use documented import paths (`import { uuid58 } from 'uuid-base58'`)\n\n**Non-breaking:**\n- All API functions work identically\n- CommonJS imports unchanged\n- Enhanced browser compatibility\n\n## Contact\n\n**Twitter** - @cbschuld\n\n## Contributing\n\nYes, thank you! Please update the docs and tests and add your name to the package.json file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbschuld%2Fuuid-base58","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcbschuld%2Fuuid-base58","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbschuld%2Fuuid-base58/lists"}