{"id":28251209,"url":"https://github.com/nakanoasaservice/uuid58","last_synced_at":"2026-02-01T17:01:06.067Z","repository":{"id":290437951,"uuid":"974363213","full_name":"nakanoasaservice/uuid58","owner":"nakanoasaservice","description":"A tiny, zero-dependency library for generating and converting UUIDs to Base58-encoded strings.","archived":false,"fork":false,"pushed_at":"2026-01-30T15:29:17.000Z","size":86,"stargazers_count":43,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-30T17:52:52.329Z","etag":null,"topics":["base58","uuid"],"latest_commit_sha":null,"homepage":"https://nakanoasaservice.github.io/uuid58-playground/","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/nakanoasaservice.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-28T16:57:12.000Z","updated_at":"2026-01-30T15:28:54.000Z","dependencies_parsed_at":"2025-04-28T20:55:19.455Z","dependency_job_id":"bd833a5e-09bd-4d56-9586-4478e2fc3b42","html_url":"https://github.com/nakanoasaservice/uuid58","commit_stats":null,"previous_names":["nakanoasaservice/uuid58"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/nakanoasaservice/uuid58","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nakanoasaservice%2Fuuid58","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nakanoasaservice%2Fuuid58/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nakanoasaservice%2Fuuid58/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nakanoasaservice%2Fuuid58/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nakanoasaservice","download_url":"https://codeload.github.com/nakanoasaservice/uuid58/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nakanoasaservice%2Fuuid58/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28983424,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T16:29:42.054Z","status":"ssl_error","status_checked_at":"2026-02-01T16:29:41.428Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["base58","uuid"],"created_at":"2025-05-19T15:14:16.272Z","updated_at":"2026-02-01T17:01:06.062Z","avatar_url":"https://github.com/nakanoasaservice.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# uuid58\n\n[![JSR](https://jsr.io/badges/@nakanoaas/uuid58)](https://jsr.io/@nakanoaas/uuid58)\n[![npm](https://badge.fury.io/js/@nakanoaas%2Fuuid58.svg)](https://badge.fury.io/js/@nakanoaas%2Fuuid58)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA tiny, zero-dependency library for generating and converting UUIDs to\nBase58-encoded strings (using Bitcoin-style alphabet). Perfect for creating\nshorter, URL-safe identifiers while maintaining the uniqueness of UUIDs.\n\n## Features\n\n- 🚀 Generate short, URL-safe identifiers (**fixed 22 characters**)\n- 🔄 Bidirectional conversion between UUID and Base58\n- 🪶 Zero dependencies\n- 💪 Type-safe with TypeScript\n- 🔒 Uses native `crypto.getRandomValues()` for secure UUID generation\n- 📦 Supports both ESM and CommonJS\n- 🛡️ Provides safe APIs that return error objects instead of throwing exceptions\n\n## Try it out!\n\n[UUID58 Playground](https://nakanoasaservice.github.io/uuid58-playground/) - Try\ngenerating, encoding, and decoding UUID58 in real-time!\n\n## Installation\n\n### Deno\n\n```bash\ndeno add @nakanoaas/uuid58\n```\n\n### Node.js\n\nUsing npm:\n\n```bash\nnpm install @nakanoaas/uuid58\n```\n\nUsing yarn:\n\n```bash\nyarn add @nakanoaas/uuid58\n```\n\nUsing pnpm:\n\n```bash\npnpm add @nakanoaas/uuid58\n```\n\n## Usage\n\n```typescript\nimport { uuid58, uuid58Decode, uuid58Encode } from \"@nakanoaas/uuid58\";\n\n// Generate a new Base58-encoded UUID (always 22 characters)\nconst id = uuid58();\n// =\u003e \"XDY9dmBbcMBXqcRvYw8xJ2\" (22 characters)\n\n// Convert existing UUID to Base58 (always 22 characters)\nconst encoded = uuid58Encode(\"f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf\");\n// =\u003e \"XDY9dmBbcMBXqcRvYw8xJ2\" (22 characters)\n\n// Convert Base58 back to UUID\nconst decoded = uuid58Decode(\"XDY9dmBbcMBXqcRvYw8xJ2\");\n// =\u003e \"f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf\"\n\nimport {\n  Uuid58DecodeError,\n  uuid58DecodeSafe,\n  Uuid58EncodeError,\n  uuid58EncodeSafe,\n} from \"@nakanoaas/uuid58\";\n\n// Safe encoding: returns error object instead of throwing\nconst encodedSafe = uuid58EncodeSafe(\"f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf\");\nif (encodedSafe instanceof Uuid58EncodeError) {\n  // handle error\n  console.error(encodedSafe.message);\n  return;\n}\n// use encoded string (22 characters)\nconsole.log(encodedSafe);\n\n// Safe decoding: returns error object instead of throwing\nconst decodedSafe = uuid58DecodeSafe(\"XDY9dmBbcMBXqcRvYw8xJ2\");\nif (decodedSafe instanceof Uuid58DecodeError) {\n  // handle error\n  console.error(decodedSafe.message);\n  return;\n}\n// use decoded UUID\nconsole.log(decodedSafe);\n\nimport { isUuid58, UUID58_REGEX } from \"@nakanoaas/uuid58\";\n\n// Validate UUID58 string without decoding\nconst isValid = isUuid58(\"XDY9dmBbcMBXqcRvYw8xJ2\"); // true\nconst isValid2 = isUuid58(\"invalid\"); // false\n\n// Or use regex pattern for validation\nconst isValid3 = UUID58_REGEX.test(\"XDY9dmBbcMBXqcRvYw8xJ2\"); // true\n```\n\n## API Reference\n\n### `uuid58()`\n\nGenerates a new Base58-encoded UUID (always 22 characters).\n\n```typescript\nfunction uuid58(): string; // always returns a 22-character string\n```\n\n### `uuid58Encode(uuid: string)`\n\nConverts a standard UUID string to a 22-character Base58-encoded format.\n\n```typescript\nfunction uuid58Encode(uuid: string): string; // always returns a 22-character string\n```\n\n- **Parameters:**\n  - `uuid`: The UUID string to encode (with or without hyphens)\n- **Returns:** A 22-character Base58-encoded string\n- **Throws:** `Uuid58EncodeError` if the input is not a valid UUID\n\n### `uuid58EncodeSafe(uuid: string)`\n\nConverts a standard UUID string to a 22-character Base58-encoded format, but\ninstead of throwing an error for invalid input, it returns an\n`Uuid58EncodeError` instance.\n\n```typescript\nfunction uuid58EncodeSafe(uuid: string): string | Uuid58EncodeError; // string is always 22 characters\n```\n\n- **Parameters:**\n  - `uuid`: The UUID string to encode (with or without hyphens)\n- **Returns:** A 22-character Base58-encoded string, or an `Uuid58EncodeError`\n  if the input is not a valid UUID\n- **Note:** This function does not throw; it returns the error object instead.\n\n### `uuid58Decode(encoded: string)`\n\nConverts a 22-character Base58-encoded string back to a standard UUID format.\n\n```typescript\nfunction uuid58Decode(uuid58: string): string;\n```\n\n- **Parameters:**\n  - `uuid58`: The 22-character Base58-encoded string to decode\n- **Returns:** A standard UUID string (lowercase, with hyphens)\n- **Throws:** `Uuid58DecodeError` if the input is not a valid 22-character\n  Base58 string\n\n### `uuid58DecodeSafe(encoded: string)`\n\nConverts a 22-character Base58-encoded string back to a standard UUID format,\nbut instead of throwing an error for invalid input, it returns an\n`Uuid58DecodeError` instance.\n\n```typescript\nfunction uuid58DecodeSafe(uuid58: string): string | Uuid58DecodeError;\n```\n\n- **Parameters:**\n  - `uuid58`: The 22-character Base58-encoded string to decode\n- **Returns:** A standard UUID string (lowercase, with hyphens), or an\n  `Uuid58DecodeError` if the input is not a valid 22-character Base58 string\n- **Note:** This function does not throw; it returns the error object instead.\n\n### Error Classes\n\n#### `Uuid58EncodeError`\n\nError thrown when an invalid UUID string is provided for encoding. This includes\nstrings that don't match the standard UUID format (32 hexadecimal characters\nwith optional hyphens).\n\n```typescript\nclass Uuid58EncodeError extends Error;\n```\n\n#### `Uuid58DecodeError`\n\nError thrown when an invalid Base58 string is provided for decoding. This\nincludes strings containing characters not in the Base58 alphabet or strings\nthat are not exactly 22 characters long.\n\n```typescript\nclass Uuid58DecodeError extends Error;\n```\n\n### `isUuid58(uuid58: string)`\n\nChecks if a given string is a valid UUID58-encodable string. This function\nefficiently validates without performing full decoding.\n\n```typescript\nfunction isUuid58(uuid58: string): boolean;\n```\n\n- **Parameters:**\n  - `uuid58`: The string to check\n- **Returns:** `true` if the string is a valid UUID58 string, `false` otherwise\n- **Note:** This function validates:\n  - Length (must be exactly 22 characters)\n  - Base58 alphabet characters only\n  - That the decoded value fits within 128 bits (UUID size)\n\n**Example:**\n\n```typescript\nimport { isUuid58 } from \"@nakanoaas/uuid58\";\n\nisUuid58(\"XDY9dmBbcMBXqcRvYw8xJ2\"); // true\nisUuid58(\"invalid\"); // false\nisUuid58(\"O0lI\"); // false (contains invalid characters)\nisUuid58(\"short\"); // false (too short)\n```\n\n### Alphabet and Utilities\n\n#### `UUID58_ALPHABET`\n\nCharacter set for Base58 encoding (Bitcoin compatible). This alphabet excludes\ncharacters that can be easily confused: `0` (zero) and `O` (capital O), `I`\n(capital i) and `l` (lowercase L). The alphabet consists of 58 characters:\ndigits 1-9 and letters A-Z, a-z (excluding the ambiguous characters mentioned\nabove).\n\n```typescript\nconst UUID58_ALPHABET: string; // \"123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz\"\n```\n\n#### `UUID58_REGEX`\n\nRegular expression pattern for validating UUID58 strings. This regex ensures\nthat a string contains exactly 22 characters and uses only characters from the\nBase58 alphabet.\n\n```typescript\nconst UUID58_REGEX: RegExp; // /^[1-9A-HJ-NP-Za-km-z]{22}$/\n```\n\n**Note:** While `UUID58_REGEX` can validate the format, `isUuid58()` provides\nmore comprehensive validation by also checking that the decoded value fits\nwithin 128 bits. For simple format checks, the regex is sufficient; for complete\nvalidation, use `isUuid58()`.\n\n**Example:**\n\n```typescript\nimport { UUID58_REGEX } from \"@nakanoaas/uuid58\";\n\nconst isValid = UUID58_REGEX.test(\"XDY9dmBbcMBXqcRvYw8xJ2\"); // true\nconst isValid = UUID58_REGEX.test(\"invalid\"); // false\nconst isValid = UUID58_REGEX.test(\"123\"); // false (too short)\n```\n\n## Why uuid58?\n\nStandard UUIDs are 36 characters long (including hyphens), which can be\ncumbersome in URLs or when space is limited. Base58 encoding reduces this to a\nfixed 22 characters while maintaining uniqueness and using only URL-safe\ncharacters. The Base58 alphabet used in this library is the same as Bitcoin's,\nwhich excludes similar-looking characters (0, O, I, l) to prevent visual\nambiguity and confusion.\n\n## License\n\nMIT License - see the [LICENSE](LICENSE) file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnakanoasaservice%2Fuuid58","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnakanoasaservice%2Fuuid58","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnakanoasaservice%2Fuuid58/lists"}