{"id":22081743,"url":"https://github.com/ryasmi/baseroo","last_synced_at":"2025-07-24T14:32:57.890Z","repository":{"id":65175556,"uuid":"585613970","full_name":"ryasmi/baseroo","owner":"ryasmi","description":"🦘 Converts positive \u0026 negative float values from one base to another between 2-64. Started in 2015. Published in 2023.","archived":false,"fork":false,"pushed_at":"2025-07-24T02:32:55.000Z","size":3158,"stargazers_count":8,"open_issues_count":6,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-07-24T05:50:37.639Z","etag":null,"topics":["base64","javascript","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/baseroo","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/ryasmi.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-01-05T16:10:18.000Z","updated_at":"2025-07-24T02:32:58.000Z","dependencies_parsed_at":"2023-09-09T04:22:05.562Z","dependency_job_id":"9552b4cc-8fe9-47e0-9a91-c843956fb288","html_url":"https://github.com/ryasmi/baseroo","commit_stats":null,"previous_names":["ryasmi/baseroo","ryansmith94/baseroo"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/ryasmi/baseroo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryasmi%2Fbaseroo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryasmi%2Fbaseroo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryasmi%2Fbaseroo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryasmi%2Fbaseroo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryasmi","download_url":"https://codeload.github.com/ryasmi/baseroo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryasmi%2Fbaseroo/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266855943,"owners_count":23995587,"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-07-24T02:00:09.469Z","response_time":99,"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":["base64","javascript","typescript"],"created_at":"2024-11-30T23:25:16.169Z","updated_at":"2025-07-24T14:32:57.873Z","avatar_url":"https://github.com/ryasmi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e🦘\u003c/br\u003ebaseroo\u003c/h1\u003e\n\t\u003cp\u003eConverts positive \u0026 negative float values from one base to another between bases 2-64, with support for custom alphabets\u003c/p\u003e\n\t\u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-d9207b.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/semantic-release/semantic-release\"\u003e\u003cimg src=\"https://img.shields.io/badge/%F0%9F%93%A6%F0%9F%9A%80%20-semantic%20release-d9207b.svg\" alt=\"Uses Semantic Release to correctly bump versions especially for breaking changes\"\u003e\u003c/a\u003e\n\t\u003ca href=\"https://renovatebot.com/\"\u003e\u003cimg src=\"https://img.shields.io/badge/%F0%9F%94%84%F0%9F%A4%96%20-renovate%20bot-d9207b.svg\" alt=\"Uses Renovate to keep dependencies updated\"\u003e\u003c/a\u003e\n\t\u003ca href=\"https://codecov.io/gh/ryasmi/baseroo\"\u003e\u003cimg alt=\"Main branch coverage percentage from Codecov\" src=\"https://codecov.io/gh/ryasmi/baseroo/branch/main/graph/badge.svg\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://bundlephobia.com/result?p=baseroo\"\u003e\u003cimg alt=\"Package size from BundlePhobia\" src=\"https://img.shields.io/bundlephobia/minzip/baseroo.svg\" /\u003e\u003c/a\u003e\n\t\u003cdiv\u003e\n\t\u003c/div\u003e\n\u003c/div\u003e\n\n## Quick Start\n\n```ts\n// Install it with `npm i baseroo`\nimport { convertBase } from 'baseroo'\n\n// Basic numeric base conversion\nconst base16Value = '8f.3333333333'\nconst base10Value = convertBase(base16Value, 16, 10) // '143.1999999999'\n\n// Custom alphabet conversion (new feature!)\nconst customBinary = convertBase('255', 10, 'AB') // 'BBBBBBBB' (using A=0, B=1)\nconst urlSafe = convertBase(\n\t'hello',\n\t'abcdefghijklmnopqrstuvwxyz',\n\t'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'\n)\n```\n\n## Features\n\n- ✅ **Standard base conversion** between bases 2-64\n- ✅ **Custom alphabets** for specialized encoding needs\n- ✅ **Floating-point precision** up to 10 decimal places\n- ✅ **Negative number support**\n- ✅ **BigInt support** for large numbers\n- ✅ **TypeScript support** with full type safety\n- ✅ **Zero dependencies** and lightweight\n- ✅ **100% test coverage**\n\n## API Documentation\n\n### convertBase(value, fromBase, toBase)\n\nConverts a numeric string from one base to another.\n\n**Parameters:**\n\n- `value: string` - The number to convert as a string\n- `fromBase: number | string` - Source base (2-64) or custom alphabet string\n- `toBase: number | string` - Target base (2-64) or custom alphabet string\n\n**Returns:** `string` - The converted number\n\n**Throws:**\n\n- `InvalidBaseError` - When base is invalid (\u003c 2 for numeric, \u003c 2 characters for custom)\n- `InvalidDigitError` - When input contains characters not in the source alphabet\n\n## Basic Usage\n\n### Standard Numeric Bases\n\n```ts\nimport { convertBase } from 'baseroo'\n\n// Hexadecimal to decimal\nconvertBase('ff', 16, 10) // '255'\n\n// Binary to hexadecimal\nconvertBase('1010', 2, 16) // 'a'\n\n// Decimal to binary\nconvertBase('255', 10, 2) // '11111111'\n\n// Floating-point numbers\nconvertBase('10.5', 10, 2) // '1010.1'\nconvertBase('3.14', 10, 16) // '3.23d70a3d70a4'\n\n// Negative numbers\nconvertBase('-255', 10, 16) // '-ff'\nconvertBase('-10.5', 10, 2) // '-1010.1'\n```\n\n## Custom Alphabets (New Feature!)\n\nCustom alphabets allow you to define your own character sets for specialized encoding needs.\n\n### Basic Custom Alphabets\n\n```ts\n// Custom binary using different characters\nconvertBase('1010', 2, 'AB') // 'BABA' (A=0, B=1)\nconvertBase('BABA', 'AB', 10) // '10'\n\n// Custom base 12 (duodecimal)\nconst customBase12 = 'QWERTYUIOPAS'\nconvertBase('255', 10, customBase12) // 'QWP'\nconvertBase('QWP', customBase12, 10) // '255'\n```\n\n### Practical Use Cases\n\n#### URL-Safe Base64 Alternative\n\n```ts\nconst urlSafe = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'\nconvertBase('12345', 10, urlSafe) // 'dNh'\n```\n\n#### Avoiding Confusing Characters\n\n```ts\n// Remove confusing characters: 0, O, 1, I, l\nconst clearAlphabet = '23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'\nconvertBase('12345', 10, clearAlphabet) // '7Ah'\n```\n\n#### Gaming/Display Applications\n\n```ts\n// Use symbols for visual appeal\nconst symbols = '♠♣♥♦★☆♪♫'\nconvertBase('100', 10, symbols) // '♠♣★♦'\n```\n\n#### Case-Sensitive Encoding\n\n```ts\n// 62-character alphabet (case-sensitive)\nconst base62 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'\nconvertBase('123456789', 10, base62) // '8M0kX'\n```\n\n### Advanced Examples\n\n#### Round-trip Conversion\n\n```ts\nconst original = '123456789'\nconst alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'\n\nconst encoded = convertBase(original, 10, alphabet) // 'FXSHRXW'\nconst decoded = convertBase(encoded, alphabet, 10) // '123456789'\n```\n\n#### Floating-Point with Custom Alphabets\n\n```ts\n// Binary fractions with custom alphabet\nconvertBase('3.25', 10, 'AB') // 'BB.AB' (11.01 in binary)\nconvertBase('BB.AB', 'AB', 10) // '3.25'\n\n// Precision is maintained\nconvertBase('0.1', 10, 'AB') // 'A.AAAABABABB' (limited to 10 decimal places)\n```\n\n#### Negative Numbers with Custom Alphabets\n\n```ts\nconvertBase('-255', 10, 'XY') // '-YYYYYYYY'\nconvertBase('-YYYYYYYY', 'XY', 10) // '-255'\n```\n\n## Union Type Behavior\n\nThe library accepts both numeric and string parameters for bases:\n\n```ts\n// These are equivalent:\nconvertBase('ff', 16, 10) // Numeric base\nconvertBase('ff', '0123456789abcdef', 10) // Custom alphabet equivalent\n\n// Type safety in TypeScript:\nfunction myConverter(value: string, from: number | string, to: number | string) {\n\treturn convertBase(value, from, to) // ✅ Type-safe\n}\n```\n\n## Error Handling\n\n```ts\ntry {\n\t// Invalid character for base\n\tconvertBase('G', 16, 10)\n} catch (error) {\n\tconsole.log(error.message) // \"Invalid digit 'G' for base 16.\"\n}\n\ntry {\n\t// Custom alphabet too short\n\tconvertBase('1', 'A', 10)\n} catch (error) {\n\tconsole.log(error.message) // \"'fromBase' must be between 2 and 9007199254740991 not '1'.\"\n}\n\ntry {\n\t// Character not in custom alphabet\n\tconvertBase('C', 'AB', 10)\n} catch (error) {\n\tconsole.log(error.message) // \"Invalid digit 'C' for base 2.\"\n}\n```\n\n## Performance\n\nCustom alphabets maintain excellent performance with minimal overhead compared to numeric bases:\n\n```ts\n// Both of these perform similarly:\nconvertBase('12345.6789', 10, 16) // ~0.1ms\nconvertBase('12345.6789', 10, '0123456789ABCDEF') // ~0.1ms\n\n// Large numbers are handled efficiently with BigInt:\nconvertBase('123456789012345678901234567890', 10, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ') // \u003c1ms\n```\n\n## Compatibility\n\n- **Node.js**: 18.x, 20.x, 22.x (LTS versions)\n- **TypeScript**: 4.x, 5.x\n- **ES Modules**: Full support\n- **CommonJS**: Full support\n- **Browsers**: Modern browsers with BigInt support\n\n## Background\n\nBaseroo was created from a [2015 Stack Overflow Answer](https://stackoverflow.com/a/32480941/1221906) from a question asking \"How do you convert numbers between different bases in JavaScript?\". This answer and [the Gist code snippet](https://gist.github.com/ryasmi/91d7fd30710264affeb9) received some comments requesting some changes, so it was converted to a package with tests and documentation in January 2023 to continue its development and make it easier to use as bug fixes and improvements are made.\n\nThe custom alphabet feature was added to support specialized encoding requirements while maintaining backward compatibility with all existing numeric base operations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryasmi%2Fbaseroo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryasmi%2Fbaseroo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryasmi%2Fbaseroo/lists"}