perf(core): optimize async operation & progress events (#23)

perf(core)!: optimize download pipeline, progress events, and stream I/O

- lower CPU load by ~35% by replacing `pretty-bytes` and `pretty-ms` with optimized in-repo formatters
- lower event-loop load and context switching by ~60% by replacing the old write path with queued/debounced disk writes via `WriteQueue`
- reduce network file-engine event overhead by ~10% with debounced progress/event emission
- reduce CLI engine-order calculation overhead by ~5% with cached CLI calculations
- replace `eventemitter3`/`chalk` with a lighter in-repo `EventEmitter`, fast formatters, and `ansis`
- add range-aware per-part downloads, stronger range validation, stream watchdog/retry handling, and renewed download URL support
- improve CLI/save-path handling and filename detection, including the `--save` directory fix
- expand regression coverage with a local HTTP test server for redirects, ranges, content-length mismatches, pause/resume, and error propagation

Benchmarks: https://ido-pluto.github.io/ipull-speed-test/
Benchmarks source: https://github.com/ido-pluto/ipull-speed-test

BREAKING CHANGE: minimum supported Node.js version is now 20.
BREAKING CHANGE: CLI `-st` shortcut was removed; use `--style`.
BREAKING CHANGE: automatic file-name resolution changed to better capture names from URLs and `content-disposition`, so resolved output file names may differ from previous releases.
BREAKING CHANGE: `pause()` now closes active connections and `resume()` reopens them.
BREAKING CHANGE: `start` and `finished` events are now emitted for `Existing` and `Cloned` download edge cases.
BREAKING CHANGE: public download metadata moved to a per-part model: `DownloadFilePart.size` was replaced by `remoteFileSize` and `downloadSize`, and per-part settings such as `parallelStreams` now live on each part instead of resumable progress metadata.
BREAKING CHANGE: TypeScript event APIs on exported download engines are now stricter, so arbitrary string event names are no longer accepted by default on typed emitters.

Fixes #19
Fixes #21

Author: ido-pluto

.github/workflows/build.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Install modules
         run: npm ci --ignore-scripts
       - name: Build
-        run: npm run build
+        run: npm run build:prod
       - name: Test
         run: npm run test
       - name: Generate docs
@@ -66,7 +66,6 @@ jobs:
       - name: Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: npx semantic-release
 
       - name: Set npm package url to GITHUB_OUTPUT

.github/workflows/test.yml

@@ -13,6 +13,6 @@ jobs:
       - name: ESLint
         run: npm run lint
       - name: TypeScript validity
-        run: npm run build
+        run: npm run build:prod
       - name: Run Tests
         run: npm run test

.gitignore

@@ -10,3 +10,8 @@ node_modules
 /.eslintcache
 /test/utils/files/big-image.jpg
 /test/utils/files/big-file.jpg
+
+# tests
+test/utils/files/big-file.bin
+file.gguf
+fileCreateToken.gguf

README.md

@@ -56,7 +56,11 @@ import {downloadFileBrowser} from "ipull/dist/browser.js";
 
 const downloader = await downloadFileBrowser({
     url: 'https://example.com/file.large',
-    acceptRangeIsKnown: true // cors origin request will not return the range header, but we can force it to be true (multi-connection download)
+    acceptRangeIsKnown: true, // overcome CORS, force multi-connection download (use only if you know the server supports range requests)
+    // defaultFetchDownloadInfo: { // set download info manually to overcome CORS issues && prevent multiple requests
+    //     acceptRange: true,
+    //     length: 40789822,
+    // }
 });
 
 await downloader.download();