{"_id":"@3-/strhash","name":"@3-/strhash","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.1":{"name":"@3-/strhash","version":"0.1.1","keywords":["hash","md5","base64url","string-hash","shorten"],"description":"Preserve short strings as is, hash long strings to 22-character base64url MD5 / 保留短字符串，长字符串哈希为22位base64url MD5","repository":{"type":"git","url":"git+https://github.com/i18n-site/lib.git"},"homepage":"https://github.com/i18n-site/lib/tree/dev/strhash","author":{"name":"i18n.site@gmail.com"},"license":"MulanPSL-2.0","exports":{".":"./lib.js","./*":"./*"},"devDependencies":{"@3-/utf8":"^0.1.1"},"scripts":{},"type":"module","dependencies":{"@3-/base64url":"^0.1.4"},"gitHead":"f4ff6bc770a76657f1436f080f0560c092615a50","_id":"@3-/strhash@0.1.1","bugs":{"url":"https://github.com/i18n-site/lib/issues"},"_nodeVersion":"26.2.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-XJotg4dx4YFK5Dp+6M1xEojEUDqhJX2Tssh2CD5DMAyR3TnlL7wxQ4JTJzX/sk+aXO8mQcLKGnnfQ8npx6y/TA==","shasum":"bf2a620e408beeb0993fe51a178b579bc3b7d985","tarball":"https://registry.npmjs.org/@3-/strhash/-/strhash-0.1.1.tgz","fileCount":3,"unpackedSize":7762,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHK3lZxgRqH2s0ydAEDowDKRS0Odw3WifrnXKrm01NOzAiBYH1ElDGHJISuPl2v2JLfCBJWtsBF5zZCxK/oWK27Ipg=="}]},"_npmUser":{"name":"i18n-now","email":"i18n.site@gmail.com"},"directories":{},"maintainers":[{"name":"i18n-now","email":"i18n.site@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/strhash_0.1.1_1780438148351_0.5740731881373007"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-02T22:09:08.219Z","0.1.1":"2026-06-02T22:09:08.497Z","modified":"2026-06-02T22:09:08.666Z"},"maintainers":[{"name":"i18n-now","email":"i18n.site@gmail.com"}],"description":"Preserve short strings as is, hash long strings to 22-character base64url MD5 / 保留短字符串，长字符串哈希为22位base64url MD5","homepage":"https://github.com/i18n-site/lib/tree/dev/strhash","keywords":["hash","md5","base64url","string-hash","shorten"],"repository":{"type":"git","url":"git+https://github.com/i18n-site/lib.git"},"author":{"name":"i18n.site@gmail.com"},"bugs":{"url":"https://github.com/i18n-site/lib/issues"},"license":"MulanPSL-2.0","readme":"[English](#en) | [中文](#zh)\n\n---\n\n<a id=\"en\"></a>\n# @3-/strhash : Preserve short strings and hash long strings to 22-character base64url MD5\n\n[Features](#features) | [Installation](#installation) | [Usage](#usage) | [Design Idea](#design-idea) | [Tech Stack](#tech-stack) | [Directory Structure](#directory-structure) | [Historical Background](#historical-background)\n\n## Features\n\nThis package provides a utility to handle string hashing with size limits.\nIf string length is less than 22 characters, the original string returns.\nIf string length is 22 characters or more, it generates a 22-character base64url MD5 hash.\nThis ensures output string length never exceeds 22 characters, which is ideal for key generation, database indexing, and identifier normalization.\n\n## Installation\n\n```bash\nbun add @3-/strhash\n```\n\n## Usage\n\n```javascript\nimport strHash from \"@3-/strhash\";\n\n// Short strings (length < 22) are preserved\nconsole.log(strHash(\"hello\")); // \"hello\"\n\n// Long strings (length >= 22) are hashed to 22 characters\nconsole.log(strHash(\"1234567890123456789012\")); // \"t_O8W6GepO1i9x2K1WjWfw\"\n```\n\n## Design Idea\n\nThe utility compresses inputs exceeding the length limit while leaving shorter inputs readable.\n\n```mermaid\ngraph TD\n    A[Input String] --> B{Length < 22?}\n    B -- Yes --> C[Return Original String]\n    B -- No --> D[Encode String to UTF-8 Bytes]\n    D --> E[Generate MD5 Hash]\n    E --> F[Encode to Base64URL]\n    F --> G[Return 22-character Result]\n```\n\n## Tech Stack\n\n- **Runtime**: Bun\n- **Language**: JavaScript (ES modules)\n- **Dependencies**:\n  - `@3-/utf8`: For UTF-8 byte encoding\n  - `@3-/base64url`: For base64url encoding and MD5 generation\n\n## Directory Structure\n\n```\n.\n├── build.sh         # Build script using mise\n├── package.json     # Project configuration\n├── run.sh           # Test runner and builder script\n├── src\n│   └── lib.js       # Core implementation source code\n├── tests\n│   └── lib.test.js  # Bun test suite\n```\n\n## Historical Background\n\n### The Origin of MD5\nIn 1991, Professor Ronald Rivest from MIT designed the Message-Digest Algorithm 5 (MD5) as a secure replacement for MD4. Over the following decades, researchers discovered cryptographic vulnerabilities, making MD5 unsuitable for security-sensitive purposes. However, due to its speed, 128-bit fixed output length, and low collision rates, it remains a standard choice for non-cryptographic checksums and data partitioning.\n\n### The Rise of Base64url\nStandard Base64 encoding utilizes characters such as `+`, `/`, and `=`, which require percent-encoding in URL contexts or cause folder structure issues in file paths. To address these problems, the IETF standardized Base64url in RFC 4648 (October 2006), substituting `+` with `-`, `/` with `_`, and omitting the padding `=` characters. Today, Base64url serves as the backbone of modern web technologies like JSON Web Tokens (JWT).\n\n---\n\n<a id=\"zh\"></a>\n# @3-/strhash : 保留短字符串并哈希长字符串为22位base64url MD5\n\n[功能介绍](#功能介绍) | [安装方法](#安装方法) | [使用演示](#使用演示) | [设计思路](#设计思路) | [技术堆栈](#技术堆栈) | [目录结构](#目录结构) | [历史背景](#历史背景)\n\n## 功能介绍\n\n提供限制字符串长度的哈希工具。\n输入字符串长度小于 22 时，直接返回原字符串。\n输入字符串长度大于等于 22 时，通过 MD5 计算并进行 base64url 编码，生成 22 位哈希值。\n输出字符长度上限固定为 22，适用于生成数据库主键、索引以及标识符规范化。\n\n## 安装方法\n\n```bash\nbun add @3-/strhash\n```\n\n## 使用演示\n\n```javascript\nimport strHash from \"@3-/strhash\";\n\n// 短字符串（长度小于 22）直接返回\nconsole.log(strHash(\"hello\")); // \"hello\"\n\n// 长字符串（长度大于等于 22）被哈希为 22 位字符\nconsole.log(strHash(\"1234567890123456789012\")); // \"t_O8W6GepO1i9x2K1WjWfw\"\n```\n\n## 设计思路\n\n本工具针对超出长度限制的输入进行压缩，同时保留短输入的原始可读性。\n\n```mermaid\ngraph TD\n    A[输入字符串] --> B{长度 < 22?}\n    B -- 是 --> C[返回原字符串]\n    B -- 否 --> D[转换为 UTF-8 字节流]\n    D --> E[计算 MD5 值]\n    E --> F[进行 Base64URL 编码]\n    F --> G[返回 22 位结果]\n```\n\n## 技术堆栈\n\n- **运行环境**：Bun\n- **开发语言**：JavaScript (ES Modules)\n- **依赖库**：\n  - `@3-/utf8`：用于 UTF-8 字节编码\n  - `@3-/base64url`：用于 MD5 计算及 Base64url 编码\n\n## 目录结构\n\n```\n.\n├── build.sh         # 使用 mise 的构建脚本\n├── package.json     # 项目配置文件\n├── run.sh           # 构建与测试执行脚本\n├── src\n│   └── lib.js       # 核心实现源码\n├── tests\n│   └── lib.test.js  # Bun 测试套件\n```\n\n## 历史背景\n\n### MD5 算法的诞生\n1991年，麻省理工学院（MIT）教授 Ronald Rivest 设计了 MD5（Message-Digest Algorithm 5）算法，用以替代存在安全隐患的 MD4。尽管随着密码学研究发展，MD5 被证实存在碰撞漏洞而不适用于安全加密场景，但凭借出色的计算速度、固定的 128 位输出以及低碰撞率，MD5 在非加密校验和数据分片场景中依旧被广泛采用。\n\n### Base64url 的普及\n传统 Base64 编码中使用的 `+`、`/` 和 `=` 字符，在 URL 传输时需要进行百分号编码，且在文件路径中容易引起混淆。为解决此问题，IETF 在 2006 年 10 月发布的 RFC 4648 中定义了 Base64url 编码，将 `+` 替换为 `-`，`/` 替换为 `_`，并省略末尾占位的 `=`。如今，Base64url 已经成为 JSON Web Token（JWT）等主流 Web 规范的基础底座。\n\n---\n\n## About\n\nThis project is an open-source component of [i18n.site ⋅ Internationalization Solution](https://i18n.site).\n\n* [i18 : MarkDown Command Line Translation Tool](https://i18n.site/i18)\n\n  The translation perfectly maintains the Markdown format.\n\n  It recognizes file changes and only translates the modified files.\n\n  The translated Markdown content is editable; if you modify the original text and translate it again, manually edited translations will not be overwritten (as long as the original text has not been changed).\n\n* [i18n.site : MarkDown Multi-language Static Site Generator](https://i18n.site/i18n.site)\n\n  Optimized for a better reading experience\n\n## 关于\n\n本项目为 [i18n.site ⋅ 国际化解决方案](https://i18n.site) 的开源组件。\n\n* [i18 :  MarkDown命令行翻译工具](https://i18n.site/i18)\n\n  翻译能够完美保持 Markdown 的格式。能识别文件的修改，仅翻译有变动的文件。\n\n  Markdown 翻译内容可编辑；如果你修改原文并再次机器翻译，手动修改过的翻译不会被覆盖（如果这段原文没有被修改）。\n\n* [i18n.site : MarkDown多语言静态站点生成器](https://i18n.site/i18n.site) 为阅读体验而优化。\n","readmeFilename":"README.md","_rev":"1-9a2776709d21be0544083a2a1dc4db3d"}