Added download with progress

# Conflicts:
#	package.json

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ztimson/utils",
-	"version": "0.30.3",
+	"version": "0.30.9",
 	"description": "Utility library",
 	"author": "Zak Timson",
 	"license": "MIT",

src/files.ts

@@ -82,11 +82,11 @@ export function timestampFilename(name?: string, date: Date | number | string =
 }
 
 /**
- * Upload file to URL with progress callback using PromiseProgress
+ * Upload file to URL with progress (size/total/speed/eta/...) via PromiseProgress
  * Works in both browser (with progress) and Node.js (fallback without progress)
  *
  * @param {{url: string, files: File[], headers?: {[p: string]: string}, withCredentials?: boolean}} options
- * @return {PromiseProgress<T>} Promise of request with `onProgress` callback
+ * @return {PromiseProgress<T>} Promise of request with `onProgress` callback & meta getters
  */
 export function uploadWithProgress<T>(options: {
 	url: string;
@@ -102,7 +102,7 @@ export function uploadWithProgress<T>(options: {
 			options.files.forEach(f => formData.append('files', f));
 
 			xhr.withCredentials = !!options.withCredentials;
-			xhr.upload.addEventListener('progress', (event) => event.lengthComputable ? prog(event.loaded / event.total) : null);
+			xhr.upload.addEventListener('progress', (event) => event.lengthComputable ? prog(event.loaded, event.total) : null);
 			xhr.addEventListener('loadend', () => res(<T>JSONAttemptParse(xhr.responseText)));
 			xhr.addEventListener('error', () => rej(JSONAttemptParse(xhr.responseText)));
 			xhr.addEventListener('timeout', () => rej({error: 'Request timed out'}));
@@ -131,3 +131,39 @@ export function uploadWithProgress<T>(options: {
 		}
 	});
 }
+
+/**
+ * Download file from URL with progress (size/total/speed/eta/...) via PromiseProgress
+ * Streams the response body for progress when supported, falls back to a plain blob otherwise
+ *
+ * @param {{url: string, name?: string, headers?: {[p: string]: string}}} options name - if set, triggers a file save via `downloadFile`
+ * @return {PromiseProgress<Blob>} Promise of downloaded blob with `onProgress` callback & meta getters
+ */
+export function downloadWithProgress(options: {url: string; name?: string; headers?: {[key: string]: string}}): PromiseProgress<Blob> {
+	return new PromiseProgress<Blob>(async (res, rej, prog) => {
+		try {
+			const response = await fetch(options.url, {headers: options.headers || {}});
+			if(!response.ok) return rej(JSONAttemptParse(await response.text()));
+			const total = Number(response.headers.get('content-length')) || 0;
+			if(!response.body?.getReader) {
+				const blob = await response.blob();
+				options.name && downloadFile(blob, options.name);
+				return res(blob);
+			}
+			const reader = response.body.getReader();
+			const chunks: Uint8Array[] = [];
+			let size = 0;
+			while(true) {
+				const {done, value} = await reader.read();
+				if(done) break;
+				chunks.push(value);
+				prog(size += value.length, total);
+			}
+			const blob = new Blob(chunks as BlobPart[]);
+			options.name && downloadFile(blob, options.name);
+			res(blob);
+		} catch (error) {
+			rej(error);
+		}
+	});
+}

src/html.ts

@@ -26,6 +26,9 @@ export function decodeHtml(html: string) {
 
 /**
  * Parse markdown headers
+ *
+ * **NOTE: frontmatter parsing only works 2 layers deep**
+ *
  * @param {string} content
  * @returns {{meta: any, content: string} | {meta: {}, content: string}}
  */
@@ -34,12 +37,29 @@ export function parseMarkdown(content: string) {
 	if (!match) return {meta: {}, content};
 
 	const meta: any = {};
-	for (const line of match[1].split('\n')) {
+	let currentParent: string | null = null;
+
+	for (const rawLine of match[1].split('\n')) {
+		if (!rawLine.trim()) continue;
+		const indented = /^\s+/.test(rawLine);
+		const line = rawLine.trim();
 		const colonIdx = line.indexOf(':');
 		if (colonIdx === -1) continue;
+
 		const key = line.slice(0, colonIdx).trim();
 		const value = line.slice(colonIdx + 1).trim();
-		try { meta[key] = JSON.parse(value); } catch { meta[key] = value; }
+
+		let parsed: any = value;
+		try { parsed = JSON.parse(value); } catch {}
+
+		if (!indented) {
+			currentParent = value === '' ? key : null;
+			if (value === '') meta[key] = {};
+			else meta[key] = parsed;
+		} else if (currentParent) {
+			meta[currentParent][key] = parsed;
 		}
+	}
+
 	return {meta, content: match[2].trim()};
 }

src/index.ts

@@ -12,6 +12,7 @@ export * from './errors';
 export * from './files';
 export * from './html';
 export * from './http';
+export * from './ip';
 export * from './json';
 export * from './jwt';
 export * from './logger';

src/ip.ts

@@ -0,0 +1,77 @@
+/**
+ * Check if IP address falls within any of the given CIDR ranges
+ * @param {string} ip IPV4 to check (192.168.0.12)
+ * @param {...string} cidrs IP ranges to check against (example: 192.168.0.0/24)
+ * @returns {boolean} Whether IP address is within any range
+ */
+export function matchesCidr(ip: string, ...cidrs: string[]): boolean {
+	if (!ip) return false;
+	if (!cidrs.length) return true;
+	const ipToInt = (str: string) => str.split('.')
+		.reduce((int, octet) => (int << 8) + parseInt(octet), 0) >>> 0;
+	return cidrs.some(cidr => {
+		if (!cidr) return true;
+		if (!cidr.includes('/')) return ip === cidr; // Single IP
+		const [range, bits] = cidr.split('/');
+		const mask = ~(2 ** (32 - parseInt(bits)) - 1);
+		return (ipToInt(ip) & mask) === (ipToInt(range) & mask);
+	});
+}
+
+/**
+ * Convert IPv6 to v4 because who uses that, NAT4Life
+ * @param {string} ip IPv6 address, e.g. 2001:0db8:85a3:0000:0000:8a2e:0370:7334
+ * @returns {string | null} IPv4 address, e.g. 172.16.58.3
+ */
+export function ipV6ToV4(ip: string) {
+	if(!ip) return null;
+	const ipv4 = ip.split(':').splice(-1)[0];
+	if(ipv4 == '1') return '127.0.0.1';
+	return ipv4;
+}
+
+/**
+ * @deprecated Use isReserved
+ *
+ * Check if IP is reserved, e.g. localhost, private IPs, etc.
+ * @param {string} ip
+ * @returns {boolean}
+ */
+export function reservedIp(ip: string): boolean {
+	if(ip == 'localhost' || ip == '127.0.0.1') return true;
+	return /\b(10\.(?:[0-9]{1,3}\.){2}[0-9]{1,3})\b|\b(172\.(?:1[6-9]|2[0-9]|3[0-1])\.(?:[0-9]{1,3}\.)[0-9]{1,3})\b|\b(192\.168\.(?:[0-9]{1,3}\.)[0-9]{1,3})\b/.test(ip);
+}
+
+/**
+ * Check if IP is within a reserved range
+ * @param {string} ip
+ * @returns {null | 'Invalid' | 'Host' | 'Loopback' | 'Private (Class A)' | 'Private (Class B)' | 'Link-Local' | 'IETF Protocol Assignments' | 'Documentation (TEST-NET-1)' | 'Benchmarking' | 'Documentation (TEST-NET-2)' | 'Documentation (TEST-NET-3)' | 'Multicast' | 'Reserved (Class E)'} null if public, class name if reserved
+ */
+export function isReserved(ip: string): null | 'Invalid' | 'Host' | 'Loopback' | 'Private (Class A)' | 'Private (Class B)' | 'Link-Local' | 'IETF Protocol Assignments' | 'Documentation (TEST-NET-1)' | 'Benchmarking' | 'Documentation (TEST-NET-2)' | 'Documentation (TEST-NET-3)' | 'Multicast' | 'Reserved (Class E)' {
+	const ipToNumber = (ip: string) => {
+		return ip.split('.').reduce((acc: number, octet: string) => (acc << 8) + parseInt(octet, 10), 0) >>> 0;
+	};
+
+	const ipNum = ipToNumber(ip);
+	if (ipNum === null) return 'Invalid';
+
+	const reserved = [
+		{ name: "Host", start: ipToNumber("0.0.0.0"), end: ipToNumber("0.255.255.255") },
+		{ name: "Loopback", start: ipToNumber("127.0.0.0"), end: ipToNumber("127.255.255.255") },
+		{ name: "Private (Class A)", start: ipToNumber("10.0.0.0"), end: ipToNumber("10.255.255.255") },
+		{ name: "CGNAT", start: ipToNumber("100.64.0.0"), end: ipToNumber("100.127.255.255") },
+		{ name: "Private (Class B)", start: ipToNumber("172.16.0.0"), end: ipToNumber("172.31.255.255") },
+		{ name: "Private (Class C)", start: ipToNumber("192.168.0.0"), end: ipToNumber("192.168.255.255") },
+		{ name: "Link-Local", start: ipToNumber("169.254.0.0"), end: ipToNumber("169.254.255.255") },
+		{ name: "IETF Protocol Assignments", start: ipToNumber("192.0.0.0"), end: ipToNumber("192.0.0.255") },
+		{ name: "Documentation (TEST-NET-1)", start: ipToNumber("192.0.2.0"), end: ipToNumber("192.0.2.255") },
+		{ name: "Benchmarking", start: ipToNumber("198.18.0.0"), end: ipToNumber("198.19.255.255") },
+		{ name: "Documentation (TEST-NET-2)", start: ipToNumber("198.51.100.0"), end: ipToNumber("198.51.100.255") },
+		{ name: "Documentation (TEST-NET-3)", start: ipToNumber("203.0.113.0"), end: ipToNumber("203.0.113.255") },
+		{ name: "Multicast", start: ipToNumber("224.0.0.0"), end: ipToNumber("239.255.255.255") },
+		{ name: "Reserved (Class E)", start: ipToNumber("240.0.0.0"), end: ipToNumber("255.255.255.255") }
+	];
+
+	const match = reserved.find(r => ipNum >= r.start && ipNum <= r.end);
+	return match ? <any>match.name : null;
+}

src/misc.ts

@@ -76,46 +76,6 @@ export function gravatar(email: string, def='mp') {
 	return `https://www.gravatar.com/avatar/${md5(email)}?d=${def}`;
 }
 
-/**
- * Check if IP address falls within CIDR range
- * @param {string} ip IPV4 to check (192.168.0.12)
- * @param {string} cidr IP range to check against (example: 192.168.0.0/24)
- * @returns {boolean} Whether IP address is within range
- */
-export function matchesCidr(ip: string, cidr: string): boolean {
-	if(!cidr) return true;
-	if(!ip) return false;
-	if(!cidr?.includes('/')) return ip === cidr; // Single IP
-	const [range, bits] = cidr.split('/');
-	const mask = ~(2 ** (32 - parseInt(bits)) - 1);
-	const ipToInt = (str: string) => str.split('.')
-		.reduce((int, octet) => (int << 8) + parseInt(octet), 0) >>> 0;
-	return (ipToInt(ip) & mask) === (ipToInt(range) & mask);
-}
-
-/**
- * Convert IPv6 to v4 because who uses that, NAT4Life
- * @param {string} ip IPv6 address, e.g. 2001:0db8:85a3:0000:0000:8a2e:0370:7334
- * @returns {string | null} IPv4 address, e.g. 172.16.58.3
- */
-export function ipV6ToV4(ip: string) {
-	if(!ip) return null;
-	const ipv4 = ip.split(':').splice(-1)[0];
-	if(ipv4 == '1') return '127.0.0.1';
-	return ipv4;
-}
-
-/**
- * Check if IP is reserved, e.g. localhost, private IPs, etc.
- * @param {string} ip
- * @returns {boolean}
- */
-export function reservedIp(ip: string): boolean {
-	if(ip == 'localhost' || ip == '127.0.0.1') return true;
-	return /\b(10\.(?:[0-9]{1,3}\.){2}[0-9]{1,3})\b|\b(172\.(?:1[6-9]|2[0-9]|3[0-1])\.(?:[0-9]{1,3}\.)[0-9]{1,3})\b|\b(192\.168\.(?:[0-9]{1,3}\.)[0-9]{1,3})\b/.test(ip);
-}
-
-
 /**
  * Represents a function that listens for events and handles them accordingly.
  *

src/objects.ts

@@ -97,8 +97,10 @@ export function deepCopy<T>(value: T): T {
  * @return {any} The des
  */
 export function deepMerge<T>(target: any, ...sources: any[]): T {
+	const BLOCKED = new Set(['__proto__', 'constructor', 'prototype']);
 	sources.forEach(s => {
 		for(const key in s) {
+			if(BLOCKED.has(key) || !Object.prototype.hasOwnProperty.call(s, key)) continue;
 			if(s[key] && typeof s[key] == 'object' && !Array.isArray(s[key])) {
 				if(!target[key]) target[key] = {};
 				deepMerge(target[key], s[key]);

src/promise-progress.ts

@@ -1,65 +1,83 @@
-export type ProgressCallback = (progress: number) => any;
+export interface ProgressMeta {
+	start: number;
+	end: number | null;
+	elapsed: number; // seconds
+	speed: number;   // bytes/sec
+	progress: number; // 0-1
+	size: number;    // bytes transferred
+	total: number;   // total bytes
+	eta: number | null; // seconds remaining
+}
+
+export type ProgressCallback = (meta: ProgressMeta) => any;
 
 /**
- * A promise that fires the `onProgress` callback on incremental progress
+ * A promise that tracks transfer progress (size/total/speed/eta/elapsed) via `onProgress` callback & direct getters
  *
  * @example
  * ```js
- * const promise = new Promise((resolve, reject, progress) => {
+ * const promise = new PromiseProgress((resolve, reject, progress) => {
- *   const max = 10;
+ *   const total = 100;
- * 	 for(let i = 0; i < max; i++) progress(i / max);
+ * 	 for(let i = 0; i <= total; i++) progress(i, total);
  * 	 resolve(1);
  * });
  *
- * console.log(promise.progress);
+ * console.log(promise.progress, promise.speed, promise.eta);
  *
- * promise.onProgress(console.log)
+ * promise.onProgress(m => console.log(m.progress, m.eta))
  *        .then(console.log)
  *        .catch(console.error)
  *        .finally(...);
- *
  * ```
  */
 export class PromiseProgress<T> extends Promise<T> {
 	private listeners: ProgressCallback[] = [];
+	private _meta: ProgressMeta = {start: Date.now(), end: null, elapsed: 0, speed: 0, progress: 0, size: 0, total: 0, eta: null};
 
-	private _progress = 0;
+	get meta() { return this._meta; }
-	get progress() { return this._progress; }
+	get start() { return this._meta.start; }
-	set progress(p: number) {
+	get end() { return this._meta.end; }
-		if(p == this._progress) return;
+	get elapsed() { return this._meta.elapsed; }
-		this._progress = p;
+	get speed() { return this._meta.speed; }
-		this.listeners.forEach(l => l(p));
+	get progress() { return this._meta.progress; }
+	get size() { return this._meta.size; }
+	get total() { return this._meta.total; }
+	get eta() { return this._meta.eta; }
+
+	private update(size: number, total: number) {
+		const elapsed = (Date.now() - this._meta.start) / 1000;
+		const speed = elapsed ? size / elapsed : 0;
+		const progress = total ? size / total : this._meta.progress;
+		this._meta = {...this._meta, size, total, progress, elapsed, speed, eta: speed && total ? (total - size) / speed : null};
+		(this.listeners ||= []).forEach(l => l(this._meta));
 	}
 
-	constructor(executor: (resolve: (value: T) => any, reject: (reason: any) => void, progress: (progress: number) => any) => void) {
+	constructor(executor: (resolve: (value: T) => any, reject: (reason: any) => void, progress: (size: number, total?: number) => any) => void) {
 		super((resolve, reject) => executor(
-			(value: T) => resolve(value),
+			(value: T) => { this._meta = {...this._meta, end: Date.now()}; resolve(value); },
-			(reason: any) => reject(reason),
+			(reason: any) => { this._meta = {...this._meta, end: Date.now()}; reject(reason); },
-			(progress: number) => this.progress = progress,
+			(size: number, total?: number) => this.update(size, total ?? this._meta.total),
 		));
 	}
 
 	static from<T>(promise: Promise<T>): PromiseProgress<T> {
 		if(promise instanceof PromiseProgress) return promise;
-		return new PromiseProgress<T>((res, rej) => promise
+		return new PromiseProgress<T>((res, rej) => promise.then(res).catch(rej));
-			.then((...args) => res(...args))
-			.catch((...args) => rej(...args)));
 	}
 
 	private from(promise: Promise<T>): PromiseProgress<T> {
 		const newPromise = PromiseProgress.from(promise);
-		this.onProgress(p => newPromise.progress = p);
+		this.onProgress(m => newPromise.update(m.size, m.total));
 		return newPromise;
 	}
 
 	onProgress(callback: ProgressCallback) {
-		this.listeners.push(callback);
+		(this.listeners ||= []).push(callback);
 		return this;
 	}
 
 	then(res?: (v: T) => any, rej?: (err: any) => any): PromiseProgress<any> {
-		const resp = super.then(res, rej);
+		return this.from(super.then(res, rej));
-		return this.from(resp);
 	}
 
 	catch(rej?: (err: any) => any): PromiseProgress<any> {

src/xml.ts

@@ -1,12 +1,12 @@
 /**
- * Parses an XML string into a structured JavaScript object.
+ * Parses an XML string into a plain JavaScript object.
+ * Each tag becomes a key. Attributes and child tags are merged as
+ * sibling properties on that tag's object. Duplicate tag/attribute
+ * names are collapsed into arrays. Text-only tags resolve to their
+ * (optionally numeric) value; if a tag has both text and attributes/
+ * children, the text is kept under a `_text` key.
  * @param {string} xml - The XML string to parse
- * @returns {Object} An object with `tag`, `attributes`, and `children` properties
+ * @returns {Object} The parsed object tree
- */
-/**
- * Parses an XML string into a structured JavaScript object (fast-xml-parser format).
- * @param {string} xml - The XML string to parse
- * @returns {Object} An object with tag names as keys and text content or nested objects as values
  */
 export function fromXml(xml: string) {
 	xml = xml.trim();
@@ -33,11 +33,11 @@ export function fromXml(xml: string) {
 
 		if(xml[pos] === '/' && xml[pos + 1] === '>') {
 			pos += 2; // skip />
-			return { [tagName]: '' };
+			return { [tagName]: Object.keys(attributes).length ? attributes : '' };
 		}
 
 		pos++; // skip >
-		const children: any[] = [];
+		const children: any[] = Object.entries(attributes).map(([k, v]) => ({ [k]: v }));
 		let textContent = '';
 
 		while(pos < xml.length) {
@@ -49,7 +49,6 @@ export function fromXml(xml: string) {
 				pos++; // skip >
 				break;
 			}
-			const startPos = pos;
 			const child = parseNode();
 			if(typeof child === 'string') {
 				textContent += child;
@@ -64,17 +63,18 @@ export function fromXml(xml: string) {
 			return { [tagName]: value };
 		}
 
-		// If only text with no children
+		// If nothing at all
 		if(children.length === 0) {
 			return { [tagName]: '' };
 		}
 
-		// Merge children into object
+		// Merge attributes/children into object
 		const result: any = {};
+		if(textContent) result._text = isNumeric(textContent) ? Number(textContent) : textContent;
 		for(const child of children) {
 			for(const [key, value] of Object.entries(child)) {
 				if(result[key]) {
-					// Convert to array if duplicate tags
+					// Convert to array if duplicate tags/attrs
 					if(!Array.isArray(result[key])) {
 						result[key] = [result[key]];
 					}

tests/xml.spec.ts

@@ -14,10 +14,10 @@ describe('XML Parser', () => {
 			expect(result).toEqual({ item: '' });
 		});
 
-		it('should parse tag with attributes (ignored in fast-xml-parser format)', () => {
+		it('should parse tag with attributes as merged properties', () => {
 			const xml = '<user id="1" name="someone" />';
 			const result = fromXml(xml);
-			expect(result).toEqual({ user: '' });
+			expect(result).toEqual({ user: { id: '1', name: 'someone' } });
 		});
 
 		it('should parse tag with text content', () => {
@@ -94,6 +94,8 @@ describe('XML Parser', () => {
 			expect(result).toEqual({
 				root: {
 					user: {
+						id: '1',
+						name: 'someone',
 						email: 'someone@example.com',
 						active: ''
 					}
@@ -190,7 +192,7 @@ describe('XML Parser', () => {
 	});
 
 	describe('round-trip', () => {
-		it('should parse toXml output back to fast-xml-parser format', () => {
+		it('should parse toXml output back with attributes merged as properties', () => {
 			const obj = {
 				tag: 'root',
 				attributes: { id: '1' },
@@ -202,6 +204,7 @@ describe('XML Parser', () => {
 			const parsed = fromXml(xml);
 			expect(parsed).toEqual({
 				root: {
+					id: '1',
 					child: 'text'
 				}
 			});