@caoyang7394/base62

一个轻量级、高性能的 Base62 编码/解码库，支持将数字转换为 Base62 字符串，适用于短链接生成、ID 编码等场景。

✨ 特性

• 🚀 轻量级 - 体积小，无外部依赖
• ⚡ 高性能 - 使用预计算字典，编码解码速度快
• 🔒 类型安全 - 完整的 TypeScript 类型定义
• ✅ 输入验证 - 完善的错误处理和边界情况处理
• 📦 多格式支持 - 支持 ES Module、UMD、IIFE 多种格式
• 🎯 零配置 - 开箱即用，无需额外配置

📦 安装

npm install @caoyang7394/base62

或使用 yarn：

yarn add @caoyang7394/base62

或使用 pnpm：

pnpm add @caoyang7394/base62

🚀 快速开始

ES Module

import { base62Encode, base62Decode } from '@caoyang7394/base62';

// 编码数字为 Base62 字符串 const encoded = base62Encode(123456789); console.log(encoded); // '8M0kX'

// 解码 Base62 字符串为数字 const decoded = base62Decode('8M0kX'); console.log(decoded); // 123456789

### CommonJS

```javascript
const { base62Encode, base62Decode } = require('@caoyang7394/base62');

const encoded = base62Encode(123);
console.log(encoded); // '1Z'

const decoded = base62Decode('1Z');
console.log(decoded); // 123

浏览器 (UMD)

<script src="https://unpkg.com/@caoyang7394/base62/dist/node/caoyBase62.umd.js"></script>
<script>
  const encoded = caoyBase62.base62Encode(123456);
  console.log(encoded); // 'w7e'
  
  const decoded = caoyBase62.base62Decode('w7e');
  console.log(decoded); // 123456
</script>

📖 API 文档

base62Encode(number: number): string

将非负整数编码为 Base62 字符串。

参数：

• number (number): 要编码的非负整数

返回值：

• string: Base62 编码后的字符串

异常：

• TypeError: 当输入不是数字或不是整数时抛出
• RangeError: 当输入为负数时抛出

示例：

base62Encode(0);        // '0'
base62Encode(123);      // '1Z'
base62Encode(123456789); // '8M0kX'
base62Encode(999999999); // '15FTGf'

base62Decode(encodedString: string): number

将 Base62 字符串解码为数字。

参数：

• encodedString (string): Base62 编码的字符串

返回值：

• number: 解码后的数字

异常：

• TypeError: 当输入不是字符串时抛出
• Error: 当输入为空字符串或包含无效的 Base62 字符时抛出

示例：

base62Decode('0');      // 0
base62Decode('1Z');     // 123
base62Decode('8M0kX');  // 123456789
base62Decode('15FTGf'); // 999999999

💡 使用场景

短链接生成

import { base62Encode } from '@caoyang7394/base62';

// 将数据库 ID 转换为短链接
function generateShortUrl(databaseId) {
  const encoded = base62Encode(databaseId);
  return `https://example.com/${encoded}`;
}

const shortUrl = generateShortUrl(123456789);
console.log(shortUrl); // 'https://example.com/8M0kX'

ID 编码

import { base62Encode, base62Decode } from '@caoyang7394/base62';

// 编码用户 ID const userId = 1001; const encodedId = base62Encode(userId); console.log(encodedId); // 'g9'

// 解码用户 ID const decodedId = base62Decode(encodedId); console.log(decodedId); // 1001

### 双向转换验证

import { base62Encode, base62Decode } from '@caoyang7394/base62';

function testRoundTrip(number) {
  const encoded = base62Encode(number);
  const decoded = base62Decode(encoded);
  console.log(`${number} -> ${encoded} -> ${decoded}`);
  return number === decoded;
}

testRoundTrip(123456789); // true
testRoundTrip(0);         // true
testRoundTrip(999999);    // true

⚠️ 错误处理

库提供了完善的错误处理机制：

import { base62Encode, base62Decode } from '@caoyang7394/base62';

try { // 无效输入：负数 base62Encode(-1); } catch (error) { console.error(error.message); // Expected a non-negative number, but got -1 }

try { // 无效输入：非整数 base62Encode(123.45); } catch (error) { console.error(error.message); // Expected an integer, but got 123.45 }

try { // 无效输入：无效字符 base62Decode('abc@123'); } catch (error) { console.error(error.message); // Invalid Base62 character "@" at position 3. Valid characters are: 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ }

## 🔧 Base62 字符集

Base62 使用以下 62 个字符：
- 数字：`0-9` (10 个字符)
- 小写字母：`a-z` (26 个字符)
- 大写字母：`A-Z` (26 个字符)

字符集顺序：`0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ`

## 📊 性能

- 编码/解码操作时间复杂度：O(n)，其中 n 为字符串长度
- 字典预计算，避免重复初始化
- 无外部依赖，体积小

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## 🔗 相关链接

- [GitHub 仓库](https://github.com/cy7394/caoy-base62)
- [npm 包](https://www.npmjs.com/package/@caoyang7394/base62)

---

Made with ❤️ by [cy7394](https://github.com/cy7394)