hlsdownloader 5.0.1 → 5.0.3

package/README.md

@@ -74,6 +74,19 @@ const summary = await downloader.startDownload();
 console.log(`Downloaded ${summary.total} segments to ${summary.path}`);
 ```
 
+### Using as CDN Primer
+
+```ts
+import HLSDowloader from 'hlsdownloader';
+
+const downloader = new HLSDownloader({
+  playlistURL: '[https://example.com/stream/master.m3u8](https://example.com/stream/master.m3u8)',
+});
+
+const summary = await downloader.startDownload();
+console.log(`Fetching ${summary.total} segments to Edge servers`);
+```
+
 ### Advanced Usage
 
 ```ts
@@ -81,9 +94,9 @@ import { HLSDownloader } from 'hlsdownloader-ts';
 
 const downloader = new HLSDownloader({
   playlistURL: 'https://example.com/video.m3u8',
-  destination: './output',
-  concurrency: 10, // 10 simultaneous downloads
-  overwrite: true, // Overwrite existing files
+  concurrency: 10, // 10 simultaneous downloads (optional: 1)
+  destination: './output', // path to downlod   (optional: '')
+  overwrite: true, // Overwrite existing files. (optional: false)
 });
 
 const { total, errors } = await downloader.startDownload();
@@ -120,9 +133,9 @@ The library is organized under the `HLSDownloader` module. For full interactive
 
 The main service orchestrator for fetching HLS content.
 
-| Method            | Returns                    | Description                           |
-| ----------------- | -------------------------- | ------------------------------------- |
-| `startDownload()` | `Promise<DownloadSummary>` | Begins parsing and fetching segments. |
+| Method          | Returns                    | Description                           |
+| --------------- | -------------------------- | ------------------------------------- |
+| startDownload() | `Promise<DownloadSummary>` | Begins parsing and fetching segments. |
 
 ### DownloaderOptions (Interface)
 
@@ -139,9 +152,27 @@ The main service orchestrator for fetching HLS content.
 
 | Property | Type              | Description                           | Description                        |
 | -------- | ----------------- | ------------------------------------- | ---------------------------------- |
-| `total`  | `number`          | Count of successfully saved segments. | The absolute URL to the M3U8 file. |
-| `path`   | `string`          | The final output directory.           | Local path to save files.          |
-| `errors` | `DownloadError[]` | Array of detailed failure objects.    | Max parallel network requests.     |
+| total    | `number`          | Count of successfully saved segments. | The absolute URL to the M3U8 file. |
+| path     | `string`          | The final output directory.           | Local path to save files.          |
+| errors   | `DownloadError[]` | Array of detailed failure objects.    | Max parallel network requests.     |
+
+### SegmentDownloadedData (Interface) - `onData` Hook
+
+| Property | Type     | Description                                                                |
+| -------- | -------- | -------------------------------------------------------------------------- |
+| url      | `string` | Original segment URL as referenced in the HLS playlist (`.m3u8`).          |
+| path     | `string` | Local file system path where the segment was saved. Empty if not provided. |
+| total    | `number` | Total number of segments downloaded so far, including this one.            |
+
+---
+
+### SegmentDownloadErrorData (Interface) - `onError` Hook
+
+| Property | Type     | Description                                                |
+| -------- | -------- | ---------------------------------------------------------- |
+| url      | `string` | Original segment URL that failed to download.              |
+| name     | `string` | Error name or type (e.g., `NetworkError`, `TimeoutError`). |
+| message  | `string` | Human-readable error description.                          |
 
 ## Development & Contributing
 
@@ -149,18 +180,18 @@ Contributions are welcome! This project enforces strict quality standards to mai
 
 ### Prerequisites
 
-- Node.js >= 20.0.0
-- npm >= 10.0.0
+- [Node.js](https://nodejs.org/) >= 20.0.0
+- [npm](https://github.com/npm/cli) >= 10.0.0
 
 ### Workflow
 
 Fork & Clone: Get the repo locally.
 
-- Install: `npm install`
-- Lint: `npm run lint` (Must pass without warnings)
-- Test: `npm run test:cov` (Must maintain 100% coverage)
-- Build: `npm run build` (Generates `./dist` and bundled types)
-- Docs: `npm run docs` (Generates TypeDoc HTML)
+- `Install`: `npm install`
+- `Lint`: `npm run lint` (Must pass without warnings)
+- `Test`: `npm run test:coverage` (Must maintain 100% coverage)
+- `Build`: `npm run build` (Generates `./dist` and bundled types)
+- `Docs`: `npm run docs` (Generates TypeDoc HTML)
 
 ### Guidelines
 

package/dist/index.d.ts

@@ -5,21 +5,23 @@ export interface DownloadError {
 	name: string;
 	message: string;
 }
+export interface SegmentDownloadedData {
+	url: string;
+	path?: string;
+	total: number;
+}
+export interface SegmentDownloadErrorData {
+	url: string;
+	name: string;
+	message: string;
+}
 export interface DownloaderOptions {
 	playlistURL: string;
 	destination?: string;
 	overwrite?: boolean;
 	concurrency?: number;
-	onData?: (data: {
-		url: string;
-		path?: string;
-		total: number;
-	}) => void;
-	onError?: (error: {
-		url: string;
-		name: string;
-		message: string;
-	}) => void;
+	onData?: (data: SegmentDownloadedData) => void;
+	onError?: (error: SegmentDownloadErrorData) => void;
 	[key: string]: any;
 }
 export interface DownloadSummary {

package/dist/index.js

@@ -1 +1 @@
-import{cpus as k}from"node:os";import F from"p-limit";import{URL as w}from"node:url";var m=class s extends Error{constructor(t){super(t),this.name=this.constructor.name,Object.setPrototypeOf(this,s.prototype),Error.captureStackTrace&&Error.captureStackTrace(this,this.constructor)}},g=m;var o=class{static isValidUrl(t,r=["http:","https:","ftp:","sftp:"]){let{protocol:e}=new w(t);if(e&&!r.includes(e))throw new g(`${e} is not supported. Supported protocols are ${r.join(", ")}`);return!0}static stripFirstSlash(t){return t.startsWith("/")?t.substring(1):t}static isValidPlaylist(t){return/^#EXTM3U/im.test(t)}static parseUrl(t){return new w(t)}static omit(t,...r){let e=new Set(r.flat());return Object.fromEntries(Object.entries(t).filter(([a])=>!e.has(a)))}static isNotFunction(t){return typeof t!="function"}};import{constants as L,createWriteStream as U}from"node:fs";import*as n from"node:fs/promises";import S from"node:path";import{Readable as R}from"node:stream";import{pipeline as T}from"node:stream/promises";var h=class{destination;overwrite;constructor(t,r=!1){this.destination=t,this.overwrite=r}async getTargetPath(t){let{pathname:r}=o.parseUrl(t);return S.join(this.destination,o.stripFirstSlash(r))}async prepareDirectory(t){let r=await this.getTargetPath(t),e=S.dirname(r);return await n.mkdir(e,{recursive:!0}),r}async canWrite(t){try{let r=await this.getTargetPath(t);return await n.access(r,L.F_OK),this.overwrite}catch(r){if(r.code==="ENOENT")return!0;throw r}}async saveStream(t,r){let e=R.fromWeb(t),a=U(r);try{await T(e,a)}catch(i){throw await n.unlink(r).catch(()=>{}),i}}},v=h;import E from"ky";var u=class s extends Error{constructor(t){super(t),this.name=this.constructor.name,Object.setPrototypeOf(this,s.prototype),Error.captureStackTrace&&Error.captureStackTrace(this,this.constructor)}},D=u;var d=class s{options;static defaultKyOptions={retry:{limit:0}};static unSupportedOptions=["uri","url","json","form","body","method","setHost","isStream","parseJson","prefixUrl","cookieJar","playlistURL","concurrency","allowGetBody","stringifyJson","methodRewriting"];constructor(t={}){this.options=Object.assign({},s.defaultKyOptions,o.omit(t,...s.unSupportedOptions))}async fetchText(t){let r=await E.get(t,{...this.options}).text();if(!o.isValidPlaylist(r))throw new D("Invalid playlist");return r}async getStream(t){let r=await E.get(t,{...this.options});if(!r.body)throw new Error("Response body is null");return r.body}},P=d;import{URL as x}from"node:url";var y=class s{static HLS_PLAYLIST_EXT=".m3u8";parse(t,r){return r.replace(/^#[\s\S].*/gim,"").split(/\r?\n/).filter(e=>e.trim()!=="").map(e=>new x(e,t).href)}isPlaylist(t){return t.toLowerCase().endsWith(s.HLS_PLAYLIST_EXT)}},c=new y;var f=class{constructor(t){this.options=t;let{onData:r,onError:e,destination:a="",playlistURL:i="",overwrite:p=!1,concurrency:l=Math.max(1,k().length-1),...O}=t||{};this.onData=r,this.onError=e,this.playlistURL=i,this.pool=F(l),this.concurrency=l,this.http=new P(O),this.fileService=new v(a,p),this.items=[i]}playlistURL;onData;onError;pool;http;fileService;items;errors=[];concurrency=1;async startDownload(){try{o.isValidUrl(this.playlistURL);let t=await this.http.fetchText(this.playlistURL),r=c.parse(this.playlistURL,t);this.items.push(...r);let e=r.filter(i=>c.isPlaylist(i));return(await Promise.allSettled(e.map(i=>this.http.fetchText(i)))).forEach((i,p)=>{if(i.status==="fulfilled"){let l=c.parse(e[p],i.value);this.items.push(...l)}}),await this.processQueue(),this.generateSummary()}catch(t){return this.handleError(this.playlistURL,t),this.generateSummary()}}async processQueue(){if(this.fileService.destination){if(!await this.fileService.canWrite(this.playlistURL))throw new Error("Directory already exists and overwrite is disabled");let r=this.items.map(e=>this.pool(()=>this.downloadFile(e)));return Promise.allSettled(r)}let t=this.items.map(r=>this.pool(async()=>{try{let e=await this.http.getStream(r);return this.onData&&this.onData({url:r,total:this.items.length}),e}catch(e){this.handleError(r,e)}}));return Promise.allSettled(t)}async downloadFile(t){try{let r=await this.http.getStream(t),e=await this.fileService.prepareDirectory(t);await this.fileService.saveStream(r,e),this.onData&&this.onData({url:t,path:e,total:this.items.length})}catch(r){this.handleError(t,r)}}handleError(t,r){let e={url:t,name:r.name,message:r.message};this.errors.push(e),this.onError&&this.onError(e)}generateSummary(){return{errors:this.errors,total:this.items.length,message:this.errors.length>0?"Download ended with errors":"Downloaded successfully"}}},b=f;var ct=b;export{b as HLSDownloader,ct as default};
+import{cpus as k}from"node:os";import F from"p-limit";import{URL as w}from"node:url";var m=class s extends Error{constructor(t){super(t),this.name=this.constructor.name,Object.setPrototypeOf(this,s.prototype),Error.captureStackTrace&&Error.captureStackTrace(this,this.constructor)}},f=m;var a=class{static isValidUrl(t,r=["http:","https:","ftp:","sftp:"]){let{protocol:e}=new w(t);if(e&&!r.includes(e))throw new f(`${e} is not supported. Supported protocols are ${r.join(", ")}`);return!0}static stripFirstSlash(t){return t.startsWith("/")?t.substring(1):t}static isValidPlaylist(t){return/^#EXTM3U/im.test(t)}static parseUrl(t){return new w(t)}static omit(t,...r){let e=new Set(r.flat());return Object.fromEntries(Object.entries(t).filter(([o])=>!e.has(o)))}static isNotFunction(t){return typeof t!="function"}};import{constants as L,createWriteStream as U}from"node:fs";import*as n from"node:fs/promises";import S from"node:path";import{Readable as R}from"node:stream";import{pipeline as T}from"node:stream/promises";var h=class{destination;overwrite;constructor(t,r=!1){this.destination=t,this.overwrite=r}async getTargetPath(t){let{pathname:r}=a.parseUrl(t);return S.join(this.destination,a.stripFirstSlash(r))}async prepareDirectory(t){let r=await this.getTargetPath(t),e=S.dirname(r);return await n.mkdir(e,{recursive:!0}),r}async canWrite(t){try{let r=await this.getTargetPath(t);return await n.access(r,L.F_OK),this.overwrite}catch(r){if(r.code==="ENOENT")return!0;throw r}}async saveStream(t,r){let e=R.fromWeb(t),o=U(r);try{await T(e,o)}catch(i){throw await n.unlink(r).catch(()=>{}),i}}},D=h;import E from"ky";var d=class s extends Error{constructor(t){super(t),this.name=this.constructor.name,Object.setPrototypeOf(this,s.prototype),Error.captureStackTrace&&Error.captureStackTrace(this,this.constructor)}},v=d;var u=class s{options;static defaultKyOptions={retry:{limit:0}};static unSupportedOptions=["uri","url","json","form","body","method","setHost","isStream","parseJson","prefixUrl","cookieJar","playlistURL","concurrency","allowGetBody","stringifyJson","methodRewriting"];constructor(t={}){this.options=Object.assign({},s.defaultKyOptions,a.omit(t,...s.unSupportedOptions))}async fetchText(t){let r=await E.get(t,{...this.options}).text();if(!a.isValidPlaylist(r))throw new v("Invalid playlist");return r}async getStream(t){let r=await E.get(t,{...this.options});if(!r.body)throw new Error("Response body is null");return r.body}},P=u;import{URL as x}from"node:url";var g=class s{static HLS_PLAYLIST_EXT=".m3u8";parse(t,r){return r.replace(/^#[\s\S].*/gim,"").split(/\r?\n/).filter(e=>e.trim()!=="").map(e=>new x(e,t).href)}isPlaylist(t){return t.toLowerCase().endsWith(s.HLS_PLAYLIST_EXT)}},c=new g;var y=class{constructor(t){this.options=t;let{onData:r,onError:e,destination:o="",playlistURL:i="",overwrite:p=!1,concurrency:l=Math.max(1,k().length-1),...O}=t||{};this.onData=r,this.onError=e,this.playlistURL=i,this.pool=F(l),this.concurrency=l,this.http=new P(O),this.fileService=new D(o,p),this.items=[i]}playlistURL;onData;onError;pool;http;fileService;items;errors=[];concurrency=1;async startDownload(){try{a.isValidUrl(this.playlistURL);let t=await this.http.fetchText(this.playlistURL),r=c.parse(this.playlistURL,t);this.items.push(...r);let e=r.filter(i=>c.isPlaylist(i));return(await Promise.allSettled(e.map(i=>this.http.fetchText(i)))).forEach((i,p)=>{if(i.status==="fulfilled"){let l=c.parse(e[p],i.value);this.items.push(...l)}}),await this.processQueue(),this.generateSummary()}catch(t){return this.handleError(this.playlistURL,t),this.generateSummary()}}async processQueue(){let t=this.items.length;if(this.fileService.destination){if(!await this.fileService.canWrite(this.playlistURL))throw new Error("Directory already exists and overwrite is disabled");let e=this.items.map(o=>this.pool(()=>this.downloadFile(o)));return Promise.allSettled(e)}let r=this.items.map(e=>this.pool(async()=>{try{let o=await this.http.getStream(e);return this.onData&&this.onData({url:e,total:t}),o}catch(o){this.handleError(e,o)}}));return Promise.allSettled(r)}async downloadFile(t){try{let r=await this.http.getStream(t),e=await this.fileService.prepareDirectory(t);await this.fileService.saveStream(r,e),this.onData&&this.onData({url:t,path:e,total:this.items.length})}catch(r){this.handleError(t,r)}}handleError(t,r){let e={url:t,name:r.name,message:r.message};this.errors.push(e),this.onError&&this.onError(e)}generateSummary(){return{errors:this.errors,total:this.items.length,message:this.errors.length>0?"Download ended with errors":"Downloaded successfully"}}},b=y;var mt=b;export{b as HLSDownloader,mt as default};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hlsdownloader",
-  "version": "5.0.1",
+  "version": "5.0.3",
   "description": "Downloads HLS Playlist file and TS chunks",
   "snyk": true,
   "main": "./dist/index.js",
@@ -26,7 +26,7 @@
     "build:types": "echo '🏷️ Generating Types' && dts-bundle-generator -o dist/index.d.ts src/index.ts --no-check --silent",
     "docs": "rimraf -fr ./docs && echo '🧹 All documentation has been cleaned.' && echo '📝 Generating documentation...' && jsdoc -c jsdoc.json",
     "build:bundle": "esbuild src/index.ts --bundle --packages=external --platform=node --format=esm --target=node20 --minify --tree-shaking=true --outfile=dist/index.js",
-    "build": "echo '🏗️ Compile: Bundles ESM source and generates minified distribution files.' && npm run typecheck && rimraf -fr ./dist && npm run build:types && npm run build:bundle",
+    "build": "echo '📦 Bundles ESM source and generates minified distribution files.' && npm run typecheck && rimraf -fr ./dist && npm run build:types && npm run build:bundle",
     "test:coverage": "rimraf -fr ./coverage && echo '🧹 All test coverage reports has been cleaned.' && c8 npm test && echo '📊 Coverage: Validates 100% code coverage across all source files successfully.'"
   },
   "dependencies": {
@@ -36,25 +36,25 @@
   "devDependencies": {
     "@babel/core": "^7.29.0",
     "@babel/preset-typescript": "^7.28.5",
-    "@commitlint/cli": "^20.4.1",
-    "@commitlint/config-conventional": "^20.4.1",
-    "@eslint/js": "^9.39.2",
-    "@types/node": "^25.2.3",
-    "@types/web": "^0.0.331",
-    "c8": "^10.1.3",
+    "@commitlint/cli": "^20.4.2",
+    "@commitlint/config-conventional": "^20.4.2",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.3.0",
+    "@types/web": "^0.0.338",
+    "c8": "^11.0.0",
     "clean-jsdoc-theme": "^4.3.0",
     "cz-conventional-changelog": "^3.3.0",
     "dts-bundle-generator": "^9.5.1",
-    "eslint": "^9.39.2",
-    "eslint-plugin-jsdoc": "^62.5.4",
+    "eslint": "^10.0.1",
+    "eslint-plugin-jsdoc": "^62.7.0",
     "jsdoc": "^4.0.5",
     "jsdoc-babel": "^0.5.0",
-    "lefthook": "^2.1.0",
-    "rimraf": "^6.1.2",
+    "lefthook": "^2.1.1",
+    "rimraf": "^6.1.3",
     "semantic-release": "^25.0.3",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.55.0"
+    "typescript-eslint": "^8.56.1"
   },
   "engines": {
     "node": ">=20.0.0",