{"_id":"@1-/github_cdn","_rev":"3-9fba39402d37d9353c39387f0d7077ce","name":"@1-/github_cdn","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@1-/github_cdn","version":"0.1.0","keywords":["cdn","github","jsdelivr","sharding","storage"],"author":{"name":"x-at-01@googlegroups.com"},"license":"MulanPSL-2.0","_id":"@1-/github_cdn@0.1.0","maintainers":[{"name":"i18n-now","email":"i18n.site@gmail.com"}],"homepage":"https://github.com/webc-site/npm/tree/main/github_cdn","bugs":{"url":"https://github.com/webc-site/npm/issues"},"dist":{"shasum":"304093cc08a5a37bb0e14b0a5fd253baeadf85ee","tarball":"https://registry.npmjs.org/@1-/github_cdn/-/github_cdn-0.1.0.tgz","fileCount":11,"integrity":"sha512-JV7uJvn6z/9fO8rsAgdUUnENaDPACLA/hWiyN/5iV28i1SnvB6vcvUOmdlKjvrvt/CZ5MWx/WvvaYp3Kq9W/Aw==","signatures":[{"sig":"MEUCIQCYgrhNoV9eTiWWOZ4vJCMfheqZjM0VLy5ia/5wTUPjFwIgJENFeeWsqzP9ID+Jn7EH5Ptr98s1POIJLO5aantQsf0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":10421},"type":"module","exports":{".":"./_.js","./*":"./*"},"_npmUser":{"name":"i18n-now","email":"i18n.site@gmail.com"},"repository":{"url":"git+https://github.com/webc-site/npm.git","type":"git"},"_npmVersion":"11.13.0","description":"Branch-sharded file CDN storage based on GitHub and jsDelivr / 基于 GitHub 与 jsDelivr 分支分片的文件 CDN 存储方案","directories":{},"_nodeVersion":"26.2.0","_hasShrinkwrap":false,"peerDependencies":{"@3-/req":"^0.1.18","@1-/url_exist":"^0.1.0","@3-/base64url":"^0.1.4"},"_npmOperationalInternal":{"tmp":"tmp/github_cdn_0.1.0_1781019607995_0.5436770494818581","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@1-/github_cdn","version":"0.1.1","keywords":["cdn","github","jsdelivr","sharding","storage"],"author":{"name":"x-at-01@googlegroups.com"},"license":"MulanPSL-2.0","_id":"@1-/github_cdn@0.1.1","maintainers":[{"name":"i18n-now","email":"i18n.site@gmail.com"}],"homepage":"https://github.com/webc-site/npm/tree/main/github_cdn","bugs":{"url":"https://github.com/webc-site/npm/issues"},"dist":{"shasum":"9977a76dc8bc324a31d8be91c475e3a3a1829b77","tarball":"https://registry.npmjs.org/@1-/github_cdn/-/github_cdn-0.1.1.tgz","fileCount":11,"integrity":"sha512-EO70jnbFX/5EZPFGd7J10Bq5tyZ8BXxZBuJiHDFaCMIVtTjvgiI3w6QmB6jKainlGPB9MVa0hOfWhihhLFqhVg==","signatures":[{"sig":"MEYCIQCCpCn05+P8lCZ/o4VlddRJ0m/CgzDccMw8bN8EwxU4dQIhANo+CEGx54Uwr7XaSrSJ0A3wOXFVS2FaQ3g35/8vkYzg","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":11879},"type":"module","exports":{".":"./_.js","./*":"./*"},"_npmUser":{"name":"i18n-now","email":"i18n.site@gmail.com"},"repository":{"url":"git+https://github.com/webc-site/npm.git","type":"git"},"_npmVersion":"11.16.0","description":"Branch-sharded file CDN storage based on GitHub and jsDelivr / 基于 GitHub 与 jsDelivr 分支分片的文件 CDN 存储方案","directories":{},"_nodeVersion":"26.2.0","dependencies":{"@3-/req":"^0.1.18","@1-/url_exist":"^0.1.1","@3-/base64url":"^0.1.4"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/github_cdn_0.1.1_1783692759884_0.12844945264416596","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@1-/github_cdn","version":"0.1.2","description":"Branch-sharded file CDN storage based on GitHub and jsDelivr / 基于 GitHub 与 jsDelivr 分支分片的文件 CDN 存储方案","keywords":["cdn","github","jsdelivr","sharding","storage"],"homepage":"https://github.com/webc-site/npm/tree/main/github_cdn","license":"MulanPSL-2.0","author":{"name":"x-at-01@googlegroups.com"},"repository":{"type":"git","url":"git+https://github.com/webc-site/npm.git"},"type":"module","exports":{".":"./_.js","./*":"./*"},"dependencies":{"@1-/url_exist":"^0.1.1","@3-/base64url":"^0.1.4","@3-/req":"^0.1.18"},"_id":"@1-/github_cdn@0.1.2","bugs":{"url":"https://github.com/webc-site/npm/issues"},"_nodeVersion":"26.7.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-5tACJm4pCgTRgvLDoTD04VwmVr6+HWRViC8VpB6l4K2gUSxILPrBe/xWVpPgsBEl8qvjGgWLxLjsMEX6a/xK7g==","shasum":"107a1e33b954ac6962657dc6a5938301c045ac1f","tarball":"https://registry.npmjs.org/@1-/github_cdn/-/github_cdn-0.1.2.tgz","fileCount":11,"unpackedSize":13553,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDpKqPFnwRWhXlvSD9A1JSlY7zQ6NnxMtzAgtdCxJk+cAIgMG7NZJmtWZ/9QlPAs7cOM7ZZNA94X2wGbSCCyRI+L4o="}]},"_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/github_cdn_0.1.2_1788234458072_0.23659124331476322"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-09T15:40:07.863Z","modified":"2026-09-01T03:47:38.402Z","0.1.0":"2026-06-09T15:40:08.136Z","0.1.1":"2026-07-10T14:12:40.008Z","0.1.2":"2026-09-01T03:47:38.207Z"},"bugs":{"url":"https://github.com/webc-site/npm/issues"},"author":{"name":"x-at-01@googlegroups.com"},"license":"MulanPSL-2.0","homepage":"https://github.com/webc-site/npm/tree/main/github_cdn","keywords":["cdn","github","jsdelivr","sharding","storage"],"repository":{"type":"git","url":"git+https://github.com/webc-site/npm.git"},"description":"Branch-sharded file CDN storage based on GitHub and jsDelivr / 基于 GitHub 与 jsDelivr 分支分片的文件 CDN 存储方案","maintainers":[{"name":"i18n-now","email":"i18n.site@gmail.com"}],"readme":"[English](#en) | [中文](#zh)\n\n---\n\n\n# @1-/github_cdn : Branch-sharded static resource CDN storage based on GitHub and jsDelivr\n\n- [@1-/github_cdn : Branch-sharded static resource CDN storage based on GitHub and jsDelivr](#1-github_cdn-branch-sharded-static-resource-cdn-storage-based-on-github-and-jsdelivr)\n - [Features](#features)\n - [Usage](#usage)\n - [Design Concept](#design-concept)\n - [技术栈](#技术栈)\n - [Code Structure](#code-structure)\n - [History Story](#history-story)\n - [About](#about)\n\n## Features\n\nThis module provides deduplicated, highly available static resource distribution using GitHub repositories and multiple CDN mirrors.\n\n- **Content-Addressed Deduplication**: Uses MD5 Base64url hash as a unique identifier; skips upload if the resource already exists.\n- **Branch-Sharded Storage**: First two characters of the hash form the GitHub branch name; the remainder plus extension forms the file path. Distributes files across 256 lightweight branches to bypass single-branch performance and capacity limits.\n- **Intelligent Branch Management**: Automatically creates the target branch from the main branch's latest commit if missing. Falls back to detecting the repository's default branch and creating a \"main\" branch if `main` is absent.\n- **Multi-CDN Probing & Warm-up**: Built-in multi-CDN generator (prioritizing `jsdmirror.cn`, including `fastly.jsdelivr.net`, `cdn.jsdelivr.net`, `cdn.jsdmirror.com`, `gcore.jsdelivr.net`, `testingcf.jsdelivr.net`) checks and warms up mirrors in order, returning the first available CDN URL.\n\n## Usage\n\n```bash\nnpm install @1-/github_cdn\n```\n\n```javascript\nimport cdnUpload from \"@1-/github_cdn\";\n\n// Initialize the upload function\nconst upload = cdnUpload(process.env.GITHUB_TOKEN, \"owner/repo\");\n\n// Upload data\nconst buf = Buffer.from(\"hello world\");\nconst url = await upload(buf, \"txt\");\n\nconsole.log(url);\n// Output: //jsdmirror.cn/gh/owner/repo@39/bW84b3JpZ2luYWw.txt\n```\n\n## Design Concept\n\nThe system uses Git branches as isolation units and file content hashes as routing keys, enabling stateless, horizontally scalable static asset hosting and multi-CDN fallback.\n\n\n\n## 技术栈\n\n- **Runtime**: Bun\n- **CDN**: JSDMirror (`jsdmirror.cn`), jsDelivr (`fastly.jsdelivr.net`, `cdn.jsdelivr.net`, `cdn.jsdmirror.com`, `gcore.jsdelivr.net`, `testingcf.jsdelivr.net`)\n- **API**: GitHub REST API (`/repos/{owner}/{repo}/contents/{path}`, `/repos/{owner}/{repo}/git/refs`, `/repos/{owner}/{repo}`)\n- **Core Dependencies**:\n - `@3-/base64url`: Secure hashing and encoding\n - `@1-/url_exist`: CDN resource liveness detection\n - `@3-/req`: Lightweight HTTP request wrapper\n\n## Code Structure\n\n```\nsrc/\n├── _.js # Main upload flow: hashing, pre-check, writing, branch fallback, warmup probing\n├── CDN.js # Multi-CDN URL generator (Generator)\n├── createBranch.js# GitHub branch creation logic\n├── ensureMain.js # Main branch detection and fallback creation\n├── ifElse.js # Unified error handling and control flow wrapper\n├── putContent.js # GitHub file content write encapsulation\n└── req.js # GitHub API request context initialization\n```\n\n## History Story\n\nGitHub enforces strict limits on repository size (typically 1–5 GB) and file count per directory. Early developers committing large numbers of images or build artifacts directly to the `main` branch experienced severe Git performance degradation, failed clones, and official GitHub warnings.\n\nThis solution employs branch sharding: each file's hash deterministically maps to a dedicated branch. Because Git branches are lightweight pointers and histories are fully decoupled, this design eliminates single-point bottlenecks without increasing storage overhead—providing open-source projects with a stable, infinite-capacity static asset hosting infrastructure.\n\n## About\n\nThis library is developed by [WebC.site](https://webc.site).\n\n[WebC.site](https://webc.site): A new paradigm of web development for AI\n\n\n---\n\n\n# @1-/github_cdn : Branch-sharded static resource CDN storage based on GitHub and jsDelivr\n\n- [@1-/github_cdn : Branch-sharded static resource CDN storage based on GitHub and jsDelivr](#1-github_cdn-branch-sharded-static-resource-cdn-storage-based-on-github-and-jsdelivr)\n - [功能介绍](#功能介绍)\n - [使用演示](#使用演示)\n - [设计思路](#设计思路)\n - [技术栈](#技术栈)\n - [代码结构](#代码结构)\n - [历史故事](#历史故事)\n - [关于](#关于)\n\n## 功能介绍\n\n本模块提供基于 GitHub 仓库与多 CDN 镜像的去重、预热与高可用静态资源分发服务。\n\n- **内容寻址去重**：使用 MD5 Base64url 散列值作为唯一标识，自动跳过已存在的资源。\n- **分支分片存储**：散列值前两位作为 GitHub 分支名，剩余部分与后缀组成文件路径，将文件均匀分布至 256 个轻量分支，规避单分支性能瓶颈与容量限制。\n- **智能分支管理**：上传时若目标分支不存在，自动基于主分支最新提交创建；主分支缺失时，自动探测仓库默认分支并创建 \"main\" 分支。\n- **多 CDN 预热探测**：内置多 CDN 镜像生成器（优先 `jsdmirror.cn`，并包含 `fastly.jsdelivr.net`、`cdn.jsdelivr.net`、`cdn.jsdmirror.com`、`gcore.jsdelivr.net`、`testingcf.jsdelivr.net`），按序检查与预热缓存，返回首个可用 CDN 链接。\n\n## 使用演示\n\n```bash\nnpm install @1-/github_cdn\n```\n\n```javascript\nimport cdnUpload from \"@1-/github_cdn\";\n\n// 初始化上传函数\nconst upload = cdnUpload(process.env.GITHUB_TOKEN, \"owner/repo\");\n\n// 上传数据\nconst buf = Buffer.from(\"hello world\");\nconst url = await upload(buf, \"txt\");\n\nconsole.log(url);\n// 输出: //jsdmirror.cn/gh/owner/repo@39/bW84b3JpZ2luYWw.txt\n```\n\n## 设计思路\n\n系统以 Git 分支为隔离单元，以文件内容散列为路由键，实现无状态、可水平扩展的静态资源托管与多源 CDN 探测。\n\n\n\n## 技术栈\n\n- **Runtime**: Bun\n- **CDN**: JSDMirror (`jsdmirror.cn`), jsDelivr (`fastly.jsdelivr.net`, `cdn.jsdelivr.net`, `cdn.jsdmirror.com`, `gcore.jsdelivr.net`, `testingcf.jsdelivr.net`)\n- **API**: GitHub REST API (`/repos/{owner}/{repo}/contents/{path}`, `/repos/{owner}/{repo}/git/refs`, `/repos/{owner}/{repo}`)\n- **核心依赖**:\n - `@3-/base64url`: 安全散列与编码\n - `@1-/url_exist`: CDN 资源在线性检测\n - `@3-/req`: 轻量级 HTTP 请求封装\n\n## 代码结构\n\n```\nsrc/\n├── _.js # 上传主流程：散列、预检、写入、分支容错、预热探测\n├── CDN.js # 多 CDN 镜像 URL 生成器 (Generator)\n├── createBranch.js# GitHub 分支创建逻辑\n├── ensureMain.js # 主分支探测与兜底创建\n├── ifElse.js # 统一错误处理与流程分支包装\n├── putContent.js # GitHub 文件内容写入封装\n└── req.js # GitHub API 请求上下文初始化\n```\n\n## 历史故事\n\nGitHub 对单仓库大小（通常 1–5 GB）和单目录文件数量有严格限制。早期开发者直接将大量图片或构建产物提交至 `main` 分支，导致 Git 操作缓慢、克隆失败，甚至收到 GitHub 官方警告。\n\n本方案采用分支分片（branch sharding）策略，将每个文件散列映射至独立分支。由于 Git 分支仅为轻量指针，且各分支历史完全解耦，此设计在不增加存储开销的前提下，彻底消除了单点性能瓶颈，为开源项目提供了稳定、无限容量的静态资源托管基础设施。\n\n## 关于\n\n本库由 [WebC.site](https://webc.site) 开发。\n\n[WebC.site](https://webc.site) : 面向人工智能的网站开发新范式\n\n","readmeFilename":"README.md"}