justget 0.1.7 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/README.browser.md +227 -0
  2. package/README.en.md +39 -12
  3. package/README.md +43 -15
  4. package/dist/browser/core/downloader.d.ts +31 -0
  5. package/dist/browser/core/downloader.d.ts.map +1 -0
  6. package/dist/browser/core/downloader.js +332 -0
  7. package/dist/browser/core/downloader.js.map +1 -0
  8. package/dist/browser/core/http.d.ts +38 -0
  9. package/dist/browser/core/http.d.ts.map +1 -0
  10. package/dist/browser/core/http.js +106 -0
  11. package/dist/browser/core/http.js.map +1 -0
  12. package/dist/browser/index.d.ts +18 -0
  13. package/dist/browser/index.d.ts.map +1 -0
  14. package/dist/browser/index.js +16 -0
  15. package/dist/browser/index.js.map +1 -0
  16. package/dist/browser/utils/buffer.d.ts +11 -0
  17. package/dist/browser/utils/buffer.d.ts.map +1 -0
  18. package/dist/browser/utils/buffer.js +30 -0
  19. package/dist/browser/utils/buffer.js.map +1 -0
  20. package/dist/browser/utils/cache.d.ts +37 -0
  21. package/dist/browser/utils/cache.d.ts.map +1 -0
  22. package/dist/browser/utils/cache.js +102 -0
  23. package/dist/browser/utils/cache.js.map +1 -0
  24. package/dist/browser/utils/hash.d.ts +22 -0
  25. package/dist/browser/utils/hash.d.ts.map +1 -0
  26. package/dist/browser/utils/hash.js +136 -0
  27. package/dist/browser/utils/hash.js.map +1 -0
  28. package/dist/cli.d.ts +2 -9
  29. package/dist/cli.d.ts.map +1 -1
  30. package/dist/cli.js +66 -72
  31. package/dist/cli.js.map +1 -1
  32. package/dist/config.d.ts +2 -2
  33. package/dist/config.d.ts.map +1 -1
  34. package/dist/config.js +24 -21
  35. package/dist/config.js.map +1 -1
  36. package/dist/core/downloader.d.ts +18 -9
  37. package/dist/core/downloader.d.ts.map +1 -1
  38. package/dist/core/downloader.js +478 -258
  39. package/dist/core/downloader.js.map +1 -1
  40. package/dist/core/http.d.ts +19 -18
  41. package/dist/core/http.d.ts.map +1 -1
  42. package/dist/core/http.js +41 -39
  43. package/dist/core/http.js.map +1 -1
  44. package/dist/core/temp.d.ts +23 -19
  45. package/dist/core/temp.d.ts.map +1 -1
  46. package/dist/core/temp.js +29 -29
  47. package/dist/core/temp.js.map +1 -1
  48. package/dist/format.d.ts +16 -0
  49. package/dist/format.d.ts.map +1 -0
  50. package/dist/format.js +47 -0
  51. package/dist/format.js.map +1 -0
  52. package/dist/i18n.d.ts +21 -0
  53. package/dist/i18n.d.ts.map +1 -0
  54. package/dist/i18n.js +109 -0
  55. package/dist/i18n.js.map +1 -0
  56. package/dist/index.d.ts +5 -2
  57. package/dist/index.d.ts.map +1 -1
  58. package/dist/index.js +10 -7
  59. package/dist/index.js.map +1 -1
  60. package/dist/render.d.ts +85 -0
  61. package/dist/render.d.ts.map +1 -0
  62. package/dist/render.js +221 -0
  63. package/dist/render.js.map +1 -0
  64. package/dist/types.d.ts +30 -7
  65. package/dist/types.d.ts.map +1 -1
  66. package/dist/utils/hash.d.ts +13 -2
  67. package/dist/utils/hash.d.ts.map +1 -1
  68. package/dist/utils/hash.js +35 -4
  69. package/dist/utils/hash.js.map +1 -1
  70. package/package.json +15 -7
  71. package/dist/downloader.d.ts +0 -22
  72. package/dist/downloader.d.ts.map +0 -1
  73. package/dist/downloader.js +0 -564
  74. package/dist/downloader.js.map +0 -1
@@ -0,0 +1,227 @@
1
+ # justget/browser — 浏览器端竞速下载
2
+
3
+ `justget/browser` 是 `justget` 的浏览器端版本,通过 `import { download } from 'justget/browser'` 使用。
4
+
5
+ ## 设计思路
6
+
7
+ ### 核心差异(与 Node.js 版)
8
+
9
+ | 特性 | Node.js `justget` | 浏览器 `justget/browser` |
10
+ |---|---|---|
11
+ | **分块 Range** | 分块并行下载 | ❌ 不分块,整文件下载 |
12
+ | **浏览器缓存** | 不利用 | ✅ 整文件请求 → 浏览器 HTTP 缓存自然生效 |
13
+ | **镜像策略** | 预热后全部启动 | ✅ 逐步释放,一次一个,按需启动 |
14
+ | **镜像记忆** | 无 | ✅ localStorage 学习型缓存,下次提为主站 |
15
+ | **存储** | 临时文件(fs) | ✅ 内存(Uint8Array[]) |
16
+ | **返回** | 文件路径 | ✅ Blob / Uint8Array |
17
+ | **哈希** | Node crypto | ✅ Web Crypto API |
18
+ | **依赖** | node-fetch, commander, progress | ✅ 零依赖 |
19
+ | **竞速** | 分块竞速 | ✅ 整文件竞速,先完成胜出 |
20
+ | **慢源替换** | 有 | ✅ 保留,慢于最快源 1/3 则 abort |
21
+
22
+ ### 竞速策略
23
+
24
+ ```
25
+ 主源启动 → 预热(5s)
26
+ ├─ 速度达标(>2MB/s) → 单源完成,浏览器缓存
27
+ └─ 速度不达标(<500KB/s) → 启动 mirror-1
28
+ ├─ 现在最快源达标 → 等它完成
29
+ └─ 仍不达标 → 启动 mirror-2
30
+ └─ 仍不达标 → 启动 mirror-3 ...
31
+ └─ 任一完成 → 胜出,abort 其余
32
+ ```
33
+
34
+ ### 学习型缓存(localStorage)
35
+
36
+ ```
37
+ 第1次:主站(慢) → 启动 mirror-1(成功) → 记到 localStorage
38
+ 第2次:查 localStorage → mirror-1 提为主站 → 直接下载,秒开
39
+ ```
40
+
41
+ - key: `justget:cache:{资源URL的FNV哈希}`
42
+ - value: `{ bestUrl, timestamp, successCount }`
43
+ - 7 天自动过期
44
+
45
+ ## 快速开始
46
+
47
+ ```bash
48
+ npm install justget
49
+ ```
50
+
51
+ ```typescript
52
+ import { download } from 'justget/browser';
53
+
54
+ // 基本下载 → 返回 Blob
55
+ const result = await download({
56
+ url: 'https://example.com/models/face-detection.bin',
57
+ });
58
+
59
+ // result.data 是 Blob,可直接用于 createObjectURL
60
+ const url = URL.createObjectURL(result.data as Blob);
61
+ ```
62
+
63
+ ### 带镜像回退
64
+
65
+ ```typescript
66
+ const result = await download({
67
+ url: 'https://github.com/xxx/models/face.bin',
68
+ mirrors: [
69
+ 'https://gh-proxy.com/...',
70
+ 'https://mirror.example.com/...',
71
+ ],
72
+ });
73
+ // 如果 mirror 成功,下次它自动当主站
74
+ ```
75
+
76
+ ### 带进度条
77
+
78
+ ```typescript
79
+ const result = await download({
80
+ url: 'https://example.com/models/large-model.onnx',
81
+ options: {
82
+ onProgress: (p) => {
83
+ console.log(`${p.percentage.toFixed(1)}% | ${(p.speed/1024).toFixed(0)} KB/s`);
84
+ },
85
+ },
86
+ });
87
+ ```
88
+
89
+ ### 获取 Uint8Array(直接喂给 face-api / WebAssembly)
90
+
91
+ ```typescript
92
+ const result = await download({
93
+ url: 'https://example.com/model.bin',
94
+ options: { responseType: 'uint8array' },
95
+ });
96
+ // result.data 是 Uint8Array
97
+ const bytes = result.data as Uint8Array;
98
+ ```
99
+
100
+ ### 校验 checksum
101
+
102
+ ```typescript
103
+ const result = await download({
104
+ url: 'https://example.com/model.bin',
105
+ options: {
106
+ checksum: 'b413e420d6840b2775fba32008db6f3cddb07d485967fb42cfcf379c16a8c589',
107
+ checksumAlgorithm: 'sha256',
108
+ },
109
+ });
110
+ ```
111
+
112
+ ## 与 face-api 集成示例
113
+
114
+ ```typescript
115
+ import { download } from 'justget/browser';
116
+ import * as faceapi from '@vladmandic/face-api';
117
+
118
+ // 下载模型文件(竞速 + SHA-256 校验;不匹配自动剔除该源重跑竞速)
119
+ const modelResult = await download({
120
+ url: 'https://cdn.jsdelivr.net/npm/@vladmandic/face-api@1.7.15/model/face_recognition_model.bin',
121
+ mirrors: [
122
+ 'https://unpkg.com/@vladmandic/face-api@1.7.15/model/face_recognition_model.bin',
123
+ 'https://gitee.com/justdb-mirrors/face-models/releases/download/face-api-1.7.15/face_recognition_model.bin',
124
+ ],
125
+ options: {
126
+ checksum: 'b413e420d6840b2775fba32008db6f3cddb07d485967fb42cfcf379c16a8c589',
127
+ responseType: 'uint8array',
128
+ onProgress: (p) => updateProgressBar(p.percentage),
129
+ },
130
+ });
131
+ const modelBytes = modelResult.data as Uint8Array;
132
+
133
+ // 喂给 face-api:face-api 的 load() 只收 URI 或 Float32Array,没有
134
+ // loadFromBuffer —— 用 fetch 拦截把已下载(已校验)的字节喂给
135
+ // loadFromUri,避免它再从网络拉一遍:
136
+ const MODEL_URL = 'https://cdn.jsdelivr.net/npm/@vladmandic/face-api@1.7.15/model/';
137
+ const origFetch = window.fetch;
138
+ window.fetch = async (input, init) => {
139
+ const u = typeof input === 'string' ? input : (input as Request).url;
140
+ if (u.startsWith(MODEL_URL)) {
141
+ return new Response(modelBytes, {
142
+ headers: { 'Content-Type': 'application/octet-stream' },
143
+ });
144
+ }
145
+ return origFetch(input, init);
146
+ };
147
+ try {
148
+ await faceapi.nets.faceRecognitionNet.loadFromUri(MODEL_URL);
149
+ } finally {
150
+ window.fetch = origFetch; // 用完即还原,不污染全局 fetch
151
+ }
152
+ ```
153
+
154
+ > 注:需要一并拦截/替换 manifest JSON(`loadFromUri` 会先拉
155
+ > `*-weights_manifest.json` 再拉 `.bin`),逐文件下载时把 manifest
156
+ > 也走 download() 校验后一并拦截即可。
157
+
158
+ ## API
159
+
160
+ ### `download(options: DownloadOptions): Promise<DownloadResult>`
161
+
162
+ | 参数 | 类型 | 默认 | 说明 |
163
+ |---|---|---|---|
164
+ | `url` | `string` | — | 主站 URL(必填) |
165
+ | `mirrors` | `string[]` | `[]` | 镜像 URL 列表 |
166
+ | `options.primaryWarmupTime` | `number` | `5000` | 主站预热 ms |
167
+ | `options.speedThreshold` | `number` | `512000` | 速度阈值 B/s,低于此值启动镜像 |
168
+ | `options.fastPrimaryThreshold` | `number` | `2048000` | 快速阈值 B/s,高于此值不启动镜像 |
169
+ | `options.sizeThreshold` | `number` | `1048576` | 文件大小阈值 B |
170
+ | `options.minReplaceTime` | `number` | `30000` | 慢源替换最短等待 ms |
171
+ | `options.replaceCheckInterval` | `number` | `10000` | 检查间隔 ms |
172
+ | `options.retries` | `number` | `3` | 重试次数 |
173
+ | `options.timeout` | `number` | `300000` | 下载超时 ms |
174
+ | `options.connectTimeout` | `number` | `10000` | 连接超时 ms |
175
+ | `options.checksum` | `string` | — | 预期校验和 |
176
+ | `options.checksumAlgorithm` | `'md5'\|'sha1'\|'sha256'\|'sha512'` | `'sha256'` | 校验算法(md5 不受 Web Crypto 支持,会抛错) |
177
+
178
+ **checksum 降级语义**:胜出源校验不匹配不会直接失败——库会在**本次调用内**剔除该源并
179
+ 用剩余源重跑竞速,直至校验通过或源穷尽(穷尽时抛最后一个
180
+ `ChecksumMismatchError`,含 `expected` / `actual` / `badUrl`,调用方可据此
181
+ 自行处理污染源)。镜像清单是调用方意图,库**不跨调用持久化“坏源”**。
182
+ 注意:重跑竞速会重新计耗时与进度回调,`onComplete` 只在最终成功后触发。
183
+ | `options.responseType` | `'blob'\|'uint8array'` | `'blob'` | 返回类型 |
184
+ | `options.onProgress` | `(p: ProgressInfo) => void` | — | 进度回调 |
185
+ | `options.onComplete` | `(r: DownloadResult) => void` | — | 完成回调 |
186
+
187
+ ### 返回 `DownloadResult`
188
+
189
+ ```typescript
190
+ interface DownloadResult {
191
+ data: Blob | Uint8Array; // 下载的数据
192
+ bytes: number; // 总字节数
193
+ duration: number; // 耗时 ms
194
+ averageSpeed: number; // 平均速度 B/s
195
+ sources: SourceResult[]; // 各源结果
196
+ mimeType: string; // MIME 类型
197
+ }
198
+ ```
199
+
200
+ ## 缓存 API(独立使用)
201
+
202
+ ```typescript
203
+ import { saveBestSource, loadBestSource, prioritizeMirrors, recordSuccess } from 'justget/browser';
204
+
205
+ // 手动记录
206
+ saveBestSource('https://example.com/model.bin', 'https://mirror.example.com/model.bin');
207
+
208
+ // 手动读取
209
+ const best = loadBestSource('https://example.com/model.bin');
210
+ // → 'https://mirror.example.com/model.bin'
211
+
212
+ // 重排镜像列表(把缓存的最优源提到主站)
213
+ const { primaryUrl, mirrors } = prioritizeMirrors(
214
+ 'https://example.com/model.bin',
215
+ ['https://mirror1.com/...', 'https://mirror2.com/...'],
216
+ 'https://example.com/model.bin'
217
+ );
218
+ ```
219
+
220
+ ## 开发
221
+
222
+ ```bash
223
+ npm run build # 构建 Node.js + 浏览器版
224
+ npm run build:browser # 仅构建浏览器版
225
+ npm run build:node # 仅构建 Node.js 版
226
+ npm test # 测试
227
+ ```
package/README.en.md CHANGED
@@ -47,6 +47,29 @@ Verified scenarios:
47
47
 
48
48
  ## 📦 Install
49
49
 
50
+ > Published on npm: <https://www.npmjs.com/package/justget> (current version `0.1.7`)
51
+
52
+ Requires Node.js ≥ 18.
53
+
54
+ ### Option 1: Global install (use as CLI)
55
+
56
+ ```bash
57
+ npm install -g justget
58
+ # or
59
+ yarn global add justget
60
+ # or
61
+ pnpm add -g justget
62
+ ```
63
+
64
+ Then use it directly from the command line:
65
+
66
+ ```bash
67
+ justget --version
68
+ justget <url> -o file.zip
69
+ ```
70
+
71
+ ### Option 2: Install into your project (use as a library)
72
+
50
73
  ```bash
51
74
  npm install justget
52
75
  # or
@@ -55,7 +78,9 @@ yarn add justget
55
78
  pnpm add justget
56
79
  ```
57
80
 
58
- Requires Node.js ≥ 18.
81
+ ```typescript
82
+ import { download } from 'justget';
83
+ ```
59
84
 
60
85
  ---
61
86
 
@@ -108,12 +133,12 @@ Main entry point. Resolves with the download result; rejects on failure (includi
108
133
  | `options.primaryWarmupTime` | `number` | `5000` | Primary warmup in ms (observe only, no mirrors during this period) |
109
134
  | `options.speedThreshold` | `number` | `512000` | Speed threshold B/s; below this, consider starting mirrors |
110
135
  | `options.fastPrimaryThreshold` | `number` | `2048000` | Fast-primary threshold B/s; above this, skip mirrors |
111
- | `options.sizeThreshold` | `number` | `52428800` | File size threshold B; below this, skip mirrors |
136
+ | `options.sizeThreshold` | `number` | `1048576` | File size threshold B; below this, skip mirrors |
112
137
  | `options.minReplaceTime` | `number` | `30000` | Minimum time before replacing a slow source (ms) |
113
138
  | `options.replaceCheckInterval` | `number` | `10000` | Source replacement check interval (ms) |
114
- | `options.chunks` | `number \| 'auto'` | `'auto'` | Chunk count |
115
- | `options.chunkSize` | `number \| 'auto'` | `'auto'` | Chunk size in bytes |
116
- | `options.minChunkSize` | `number` | `1048576` | Minimum chunk size in bytes |
139
+ | `options.chunks` | `number \| 'auto'` | `'auto'` | Max lease (range) count |
140
+ | `options.minSliceSize` | `number` | `4194304` | Min slice size in bytes; also the takeover threshold |
141
+ | `options.overtakeSpeedRatio` | `number` | `0.5` | Overtake when the other's speed < mine × ratio |
117
142
  | `options.retries` | `number` | `3` | Retry count per source |
118
143
  | `options.retryDelay` | `number` | `2000` | Retry delay (ms) |
119
144
  | `options.timeout` | `number` | `300000` | Download timeout (ms) |
@@ -182,12 +207,13 @@ justget <url> [options]
182
207
  | `--warmup <ms>` | number | `5000` | Primary warmup |
183
208
  | `--min-speed <bytes/s>` | number | `512000` | Speed threshold; below this, start mirrors |
184
209
  | `--fast-primary-threshold <bytes/s>` | number | `2048000` | Above this primary speed, skip mirrors |
185
- | `--min-size <bytes>` | number | `52428800` | Below this file size, skip mirrors |
210
+ | `--min-size <bytes>` | number | `1048576` | Below this file size, skip mirrors |
186
211
  | `--min-replace-time <ms>` | number | `30000` | Min time before replacing a slow source |
187
212
  | `--replace-check-interval <ms>` | number | `10000` | Replacement check interval |
188
- | `--chunks <n>` | number\|auto | `auto` | Chunk count |
189
- | `--chunk-size <bytes>` | number\|auto | `auto` | Chunk size |
190
- | `--min-chunk-size <bytes>` | number | `1048576` | Min chunk size |
213
+ | `--chunks <n>` | number\|auto | `auto` | Max lease count |
214
+ | `--chunk-size <bytes>` | number\|auto | `auto` | Min slice size |
215
+ | `--no-progress` | — | — | Disable progress display |
216
+ | `-q, --quiet` | — | — | Quiet mode: no progress or source summary |
191
217
  | `--retries <n>` | number | `3` | Retries per source |
192
218
  | `--retry-delay <ms>` | number | `2000` | Retry delay |
193
219
  | `--timeout <ms>` | number | `300000` | Download timeout |
@@ -231,8 +257,9 @@ warmup to start mirrors + mirrors sources verify,
231
257
  ```
232
258
 
233
259
  - **When mirrors start**: primary speed below `speedThreshold`, file larger than `sizeThreshold`, and primary speed below `fastPrimaryThreshold`; on immediate primary failure (4xx/5xx or network error), mirrors start unconditionally and early.
234
- - **Chunk allocation**: the primary source takes chunks from the head of the pool, mirrors from the tail (primary keeps the leading part); merge concatenates by index order.
235
- - **Slow-source replacement**: after `minReplaceTime`, every `replaceCheckInterval` the sources are evaluated; a source consistently below 1/3 of the fastest speed for `slowChecks` consecutive checks is aborted and its unfinished chunks are returned to the pool.
260
+ - **Lease splitting**: the primary issues a single Range request for the whole file; when a mirror joins, the second half of the slowest-ETA lease's remaining range is carved out for it (the split point follows the actual written position, so downloaded prefixes are never re-fetched). Merge is ordered by position and verifies seamless coverage.
261
+ - **Overtake**: when a source finishes its own lease, a much slower right neighbor (speed < mine × `overtakeSpeedRatio`, written < `minSliceSize`) is aborted and its lease is taken over, resuming from its cursor; otherwise take a free lease; otherwise idle until everything is done.
262
+ - **Slow-source replacement**: after `minReplaceTime`, every `replaceCheckInterval` holders are evaluated; a source consistently below 1/3 of the fastest for `slowChecks` consecutive checks is aborted, its lease (with the partial file) goes to the free pool and the fastest source resumes from its cursor.
236
263
  - **No Range support**: primary and mirrors download the whole file concurrently; first to finish wins.
237
264
  - **Validation**: when `checksum` is set, the merged file is verified.
238
265
 
@@ -240,7 +267,7 @@ warmup to start mirrors + mirrors sources verify,
240
267
 
241
268
  ## 🗂️ Temporary Files
242
269
 
243
- Naming: `.justget-{basename}-{hash}-{source}-{chunk}.{ext}`
270
+ Naming: `.justget-{basename}-{hash}-r{start}.{ext}` (keyed by range start)
244
271
 
245
272
  - Cleaned automatically after completion
246
273
  - Resume supported after an interrupted download (≥90% complete)
package/README.md CHANGED
@@ -9,7 +9,7 @@
9
9
 
10
10
  </div>
11
11
 
12
- **简体中文** · [English](./README.en.md)
12
+ **简体中文** · [English](./README.en.md) · [浏览器版 Browser](./README.browser.md)
13
13
 
14
14
  ---
15
15
 
@@ -35,7 +35,8 @@ justget https://github.com/xxx/releases/download/v1.0/file.zip \
35
35
  ## ✨ 特性 / Features
36
36
 
37
37
  - 🔀 **多源竞速** / Multi-source racing — 主站 + 多镜像同时下载,自动选择最快源
38
- - 🧩 **分块下载** / Chunked download — 大文件分块并行,充分利用带宽
38
+ - 🧩 **租约式动态切分** / Lease-based dynamic splitting — 主源一次请求全文件,副本加入时从最慢源切走剩余区间后半;连接数少、不重下已有数据
39
+ - 📊 **实时进度** / Live progress — 终端多行进度:编号源、按文件位置渲染的进度条(仅 TTY,`--quiet` 可静音)
39
40
  - 📊 **智能调度** / Intelligent scheduling — 按速度、文件大小动态调整策略
40
41
  - 🛡️ **容错机制** / Fault tolerance — 单源失败不影响整体下载
41
42
  - 🧮 **平滑测速** / EWMA speed — 指数加权移动平均,速度估计更稳定
@@ -49,7 +50,7 @@ justget https://github.com/xxx/releases/download/v1.0/file.zip \
49
50
  | 分块策略(chunk size / ranges) | ✅ 已完成 |
50
51
  | 速度监控(EWMA / 瞬时 / 平均 / 峰值) | ✅ 已完成 |
51
52
  | 临时文件命名、文件校验(checksum) | ✅ 已完成 |
52
- | **核心下载器 `download()`**(探测→分块→预热→决策→竞速→替换→合并→校验) | ✅ 已完成(真实下载验证通过) |
53
+ | **核心下载器 `download()`**(探测→初始租约→预热→决策→切分/接管→替换→合并→校验) | ✅ 已完成(真实下载验证通过) |
53
54
  | CLI 接入 `download()` | ✅ 已完成 |
54
55
 
55
56
  已通过的验证场景 / Verified scenarios:
@@ -64,6 +65,29 @@ justget https://github.com/xxx/releases/download/v1.0/file.zip \
64
65
 
65
66
  ## 📦 安装 / Install
66
67
 
68
+ > 已发布到 npm:<https://www.npmjs.com/package/justget>(当前版本 `0.1.7`)
69
+
70
+ 需要 Node.js ≥ 18。
71
+
72
+ ### 方式一:作为 CLI 全局安装(命令行使用)
73
+
74
+ ```bash
75
+ npm install -g justget
76
+ # 或 / or
77
+ yarn global add justget
78
+ # 或 / or
79
+ pnpm add -g justget
80
+ ```
81
+
82
+ 安装后即可直接使用命令:
83
+
84
+ ```bash
85
+ justget --version
86
+ justget <url> -o file.zip
87
+ ```
88
+
89
+ ### 方式二:作为库安装到项目(代码调用)
90
+
67
91
  ```bash
68
92
  npm install justget
69
93
  # 或 / or
@@ -72,7 +96,9 @@ yarn add justget
72
96
  pnpm add justget
73
97
  ```
74
98
 
75
- 需要 Node.js ≥ 18。
99
+ ```typescript
100
+ import { download } from 'justget';
101
+ ```
76
102
 
77
103
  ---
78
104
 
@@ -125,12 +151,12 @@ await download({
125
151
  | `options.primaryWarmupTime` | `number` | `5000` | 主站预热时间 ms(期间只观察不启动镜像)/ Primary warmup |
126
152
  | `options.speedThreshold` | `number` | `512000` | 速度阈值 B/s,低于此值考虑启动镜像 / Slow threshold |
127
153
  | `options.fastPrimaryThreshold` | `number` | `2048000` | 快速主站阈值 B/s,主站高于此值则跳过镜像 / Fast-primary threshold |
128
- | `options.sizeThreshold` | `number` | `52428800` | 文件大小阈值 B,小于此值不启动镜像 / Size threshold |
154
+ | `options.sizeThreshold` | `number` | `1048576` | 文件大小阈值 B,小于此值不启动镜像 / Size threshold |
129
155
  | `options.minReplaceTime` | `number` | `30000` | 慢源替换最短等待时间 ms / Min time before replacement |
130
156
  | `options.replaceCheckInterval` | `number` | `10000` | 源替换检查间隔 ms / Replacement check interval |
131
- | `options.chunks` | `number \| 'auto'` | `'auto'` | 分块数量 / Chunk count |
132
- | `options.chunkSize` | `number \| 'auto'` | `'auto'` | 分块大小 B / Chunk size |
133
- | `options.minChunkSize` | `number` | `1048576` | 最小分块大小 B / Min chunk size |
157
+ | `options.chunks` | `number \| 'auto'` | `'auto'` | 最大租约(区间)数上限 / Max lease count |
158
+ | `options.minSliceSize` | `number` | `4194304` | 最小切分粒度 B,兼接管阈值 / Min slice size & takeover threshold |
159
+ | `options.overtakeSpeedRatio` | `number` | `0.5` | 碾过判定:对方速度 < 本方 × 该比例时接管 / Overtake speed ratio |
134
160
  | `options.retries` | `number` | `3` | 每源重试次数 / Retries per source |
135
161
  | `options.retryDelay` | `number` | `2000` | 重试间隔 ms / Retry delay |
136
162
  | `options.timeout` | `number` | `300000` | 下载超时 ms / Download timeout |
@@ -199,12 +225,13 @@ justget <url> [options]
199
225
  | `--warmup <ms>` | number | `5000` | 主站预热时间 / Primary warmup |
200
226
  | `--min-speed <bytes/s>` | number | `512000` | 速度阈值,低于此值启动镜像 / Slow threshold |
201
227
  | `--fast-primary-threshold <bytes/s>` | number | `2048000` | 主站超过此速度则跳过镜像 / Fast-primary threshold |
202
- | `--min-size <bytes>` | number | `52428800` | 文件小于此大小不启动镜像 / Size threshold |
228
+ | `--min-size <bytes>` | number | `1048576` | 文件小于此大小不启动镜像 / Size threshold |
203
229
  | `--min-replace-time <ms>` | number | `30000` | 慢源替换最短等待 / Min replace time |
204
230
  | `--replace-check-interval <ms>` | number | `10000` | 替换检查间隔 / Check interval |
205
- | `--chunks <n>` | number\|auto | `auto` | 分块数量 / Chunk count |
206
- | `--chunk-size <bytes>` | number\|auto | `auto` | 分块大小 / Chunk size |
207
- | `--min-chunk-size <bytes>` | number | `1048576` | 最小分块大小 / Min chunk size |
231
+ | `--chunks <n>` | number\|auto | `auto` | 最大区间数 / Max lease count |
232
+ | `--chunk-size <bytes>` | number\|auto | `auto` | 最小切分粒度 / Min slice size |
233
+ | `--no-progress` | — | — | 关闭进度显示 / Disable progress |
234
+ | `-q, --quiet` | — | — | 静音模式:不显示进度与源汇总 / Quiet mode |
208
235
  | `--retries <n>` | number | `3` | 每源重试次数 / Retries |
209
236
  | `--retry-delay <ms>` | number | `2000` | 重试间隔 / Retry delay |
210
237
  | `--timeout <ms>` | number | `300000` | 下载超时 / Timeout |
@@ -248,8 +275,9 @@ warmup to start + mirrors sources verify, clean
248
275
  ```
249
276
 
250
277
  - **启动镜像条件 / When mirrors start**:主站速度低于 `speedThreshold`,且文件大于 `sizeThreshold`,且主站速度低于 `fastPrimaryThreshold`;主站立即失败(4xx/5xx 或网络错误)时无条件提前启动镜像。
251
- - **分块分配 / Chunk allocation**:主源从分块池头部取块、镜像从尾部取块(主源优先持有前段),合并时按 index 顺序拼接。
252
- - **慢源替换 / Slow-source replacement**:下载超过 `minReplaceTime` 后每 `replaceCheckInterval` 评估一次,连续 `slowChecks` 次低于快源 1/3 速度的慢源被中止、其未完成分块交还池子。
278
+ - **租约切分 / Lease splitting**:主源一次 Range 请求整个文件;副本加入时,从「预计完成最晚」租约的剩余区间后半切一段给新副本(切分点按实际写入位置计算,不重下已有前缀)。合并时按位置排序并校验区间连续覆盖。
279
+ - **右邻碾过 / Overtake**:源写完自己的区间后,若右邻明显慢(速度 < 本方 × `overtakeSpeedRatio`)且已写不足 `minSliceSize`,直接中止右邻并从其已写位置接管续写;否则领取空闲区间;否则休眠等待。
280
+ - **慢源替换 / Slow-source replacement**:下载超过 `minReplaceTime` 后每 `replaceCheckInterval` 评估一次,连续 `slowChecks` 次低于最快源 1/3 速度的慢源被中止,其区间(含已写部分文件)进入空闲池,快源完成后无缝接管续写。
253
281
  - **不支持 Range 时 / No Range support**:主站与镜像整文件同时下载,先完成者胜出。
254
282
  - **校验 / Validation**:指定 `checksum` 时,合并后校验整个文件。
255
283
 
@@ -257,7 +285,7 @@ warmup to start + mirrors sources verify, clean
257
285
 
258
286
  ## 🗂️ 临时文件 / Temporary Files
259
287
 
260
- 命名格式 / Naming: `.justget-{basename}-{hash}-{source}-{chunk}.{ext}`
288
+ 命名格式 / Naming: `.justget-{basename}-{hash}-r{start}.{ext}`(按区间起点 / keyed by range start)
261
289
 
262
290
  - 下载完成后自动清理 / cleaned after completion
263
291
  - 异常中断可断点续传(>=90% 完整时)/ resume support
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Core downloader (browser): whole-file racing + mirror learning cache, in-memory
3
+ * Browser downloader: full-file racing + learning cache, in-memory
4
+ *
5
+ * Design notes:
6
+ * 1. No Range chunking; whole-file downloads are browser-cache friendly
7
+ * 2. Primary starts first; if slow after warmup, mirrors are released one by one
8
+ * 3. First to finish wins; the rest are aborted
9
+ * 4. Fully in-memory storage (Uint8Array[]), no temp files
10
+ * 5. Checksum validation via the Web Crypto API
11
+ * 6. Learning cache (localStorage): remembers which mirror succeeded and promotes it next time
12
+ */
13
+ import type { DownloadOptions, DownloadResult } from '../../types.js';
14
+ /** Checksum mismatch: recoverable error (drop the winner and re-race) */
15
+ export declare class ChecksumMismatchError extends Error {
16
+ readonly expected: string;
17
+ readonly actual: string;
18
+ readonly badUrl: string;
19
+ constructor(expected: string, actual: string, badUrl: string);
20
+ }
21
+ /**
22
+ * Multi-source whole-file racing (browser).
23
+ * Primary -> mirrors released one by one when slow -> first to finish wins.
24
+ */
25
+ export declare function download(options: DownloadOptions): Promise<DownloadResult>;
26
+ export declare class Downloader {
27
+ private options;
28
+ constructor(options: DownloadOptions);
29
+ start(): Promise<DownloadResult>;
30
+ }
31
+ //# sourceMappingURL=downloader.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"downloader.d.ts","sourceRoot":"","sources":["../../../src/browser/core/downloader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EAIf,MAAM,gBAAgB,CAAC;AAmCxB,yEAAyE;AACzE,qBAAa,qBAAsB,SAAQ,KAAK;aAE5B,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM;aACd,MAAM,EAAE,MAAM;gBAFd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM;CAKjC;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAiChF;AAiQD,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAkB;gBACrB,OAAO,EAAE,eAAe;IACpC,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC;CACjC"}