Added TTS helper

package.json

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

src/array.ts

@@ -122,6 +122,8 @@ export function sortByProp(prop: string, reverse = false) {
 	return function (a: any, b: any) {
 		const aVal = dotNotation<any>(a, prop);
 		const bVal = dotNotation<any>(b, prop);
+		if(aVal === undefined) return 1;
+		if(bVal === undefined) return -1;
 		if(typeof aVal == 'number' && typeof bVal == 'number')
 			return (reverse ? -1 : 1) * (aVal - bVal);
 		if(aVal > bVal) return reverse ? -1 : 1;

src/errors.ts

@@ -113,6 +113,18 @@ export class NotAcceptableError extends CustomError {
 	}
 }
 
+export class TooManyRequestsError extends CustomError {
+	static code = 429;
+
+	constructor(message: string = 'Rate Limit Reached') {
+		super(message);
+	}
+
+	static instanceof(err: Error) {
+		return (<any>err).constructor.code == this.code;
+	}
+}
+
 export class InternalServerError extends CustomError {
 	static code = 500;
 

src/index.ts

@@ -21,5 +21,6 @@ export * from './search';
 export * from './string';
 export * from './template';
 export * from './time';
+export * from './tts';
 export * from './types';
 export * from 'var-persist';

src/misc.ts

@@ -76,6 +76,23 @@ 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

src/path-events.ts

@@ -65,6 +65,8 @@ export class PathEvent {
 	module!: string;
 	/** Entire path, including the module & name */
 	fullPath!: string;
+	/** Parent directory, excludes module & name */
+	dir!: string;
 	/** Path including the name, excluding the module */
 	path!: string;
 	/** Last segment of path */
@@ -121,6 +123,7 @@ export class PathEvent {
 		if(p === '' || p === undefined || p === '*') {
 			this.module = '';
 			this.path = '';
+			this.dir = '';
 			this.fullPath = '**';
 			this.name = '';
 			this.methods = new ASet<Method>(p === '*' ? ['*'] : <any>method.split(''));
@@ -132,6 +135,7 @@ export class PathEvent {
 		let temp = p.split('/').filter(p => !!p);
 		this.module = temp.splice(0, 1)[0] || '';
 		this.path = temp.join('/');
+		this.dir = temp.length > 2 ? temp.slice(0, -1).join('/') : '';
 		this.fullPath = `${this.module}${this.module && this.path ? '/' : ''}${this.path}`;
 		this.name = temp.pop() || '';
 		this.hasGlob = this.fullPath.includes('*');

src/string.ts

@@ -135,7 +135,15 @@ export function pascalCase(str?: string): string {
 		.join('');
 }
 
-
+/**
+ * Remove all emojis from a string
+ * @param {string} str Input string with emojis
+ * @returns {string} Sanitized string without emojis
+ */
+export function removeEmojis(str: string): string {
+	const emojiRegex = /(?:[\u2700-\u27bf]|(?:\ud83c[\udde6-\uddff]){2}|[\ud83c[\udde6-\uddff]|[\ud83d[\ude00-\ude4f]|[\ud83d[\ude80-\udeff]|[\ud83c[\udd00-\uddff]|[\ud83d[\ude50-\ude7f]|[\u2600-\u26ff]|[\u2700-\u27bf]|[\ud83e[\udd00-\uddff]|[\ud83c[\udf00-\uffff]|[\ud83d[\ude00-\udeff]|[\ud83c[\udde6-\uddff])/g;
+	return str.replace(emojiRegex, '');
+}
 
 /**
  * Generate a random hexadecimal value

src/template.ts

@@ -17,7 +17,7 @@ export function findTemplateVars(html: string): Record<string, any> {
 		excluded.add(index);
 		const arrayVar = loop[2].trim();
 		const root = arrayVar.split('.')[0];
-		if (!excluded.has(root)) {
+		if(!excluded.has(root)) {
 			variables.add(arrayVar);
 			arrays.add(arrayVar);
 		}
@@ -33,7 +33,7 @@ export function findTemplateVars(html: string): Record<string, any> {
 		const vars = cleaned.match(/[a-zA-Z_$][a-zA-Z0-9_$.]+/g) || [];
 		for (const v of vars) {
 			const root = v.split('.')[0];
-			if (!excluded.has(root)) variables.add(v);
+			if(!excluded.has(root)) variables.add(v);
 		}
 	}
 
@@ -49,7 +49,7 @@ export function findTemplateVars(html: string): Record<string, any> {
 		const vars = cleaned.match(/[a-zA-Z_$][a-zA-Z0-9_$.]+/g) || [];
 		for (const v of vars) {
 			const root = v.split('.')[0];
-			if (!excluded.has(root)) variables.add(v);
+			if(!excluded.has(root)) variables.add(v);
 		}
 	}
 
@@ -59,7 +59,7 @@ export function findTemplateVars(html: string): Record<string, any> {
 		let current = result;
 		for (let i = 0; i < parts.length; i++) {
 			const part = parts[i];
-			if (i === parts.length - 1) {
+			if(i === parts.length - 1) {
 				const fullPath = parts.slice(0, i + 1).join('.');
 				current[part] = arrays.has(fullPath) ? [] : '';
 			} else {
@@ -70,10 +70,11 @@ export function findTemplateVars(html: string): Record<string, any> {
 	}
 	return result;
 }
-
 export async function renderTemplate(template: string, data: any, fetch?: (file: string) => Promise<string>) {
-	let content = template, found: any;
+	if(!fetch) fetch = (file) => { throw new TemplateError(`Unable to fetch template: ${file}`); }
-	const now = new Date(), d = {
+
+	const now = new Date();
+	const d = {
 		date: {
 			day: now.getDate(),
 			month: now.toLocaleString('default', { month: 'long' }),
@@ -83,72 +84,158 @@ export async function renderTemplate(template: string, data: any, fetch?: (file:
 		},
 		...(data || {}),
 	};
-	if(!fetch) fetch = (file) => { throw new TemplateError(`Unable to fetch template: ${file}`); }
+
 	const evaluate = (code: string, data: object, fatal = true) => {
 		try {
 			return Function('data', `with(data) { return ${code}; }`)(data);
-		} catch {
+		} catch(err: any) {
-			if(fatal) throw new TemplateError(`Failed to evaluate: ${code}`);
+			if(fatal) throw new TemplateError(`Failed to evaluate: ${code}\n${err.message || err.toString()}`);
-			else return false;
+			return false;
 		}
 	}
 
-	// If Statements - Optimize what we render: `{{ ? javascript }} IF TRUE CONTENT {{ !? javascript }} ELSE-IF CONTENT {{ !? }} ELSE FALSE CONTENT {{ /? }}`
+	async function process(content: string, ctx: object = d): Promise<string> {
-	while(!!(found = /\{\{\s*?\?\s*?(.+?)\s*?}}([\s\S]*?)\{\{\s*?\/\?\s*?}}/g.exec(content))) {
+		let result = content;
-		const nested = matchAll(found[0], /\{\{\s*?\?.+?}}/g).slice(-1)?.[0]?.index;
+
-		if(nested != 0) found = /\{\{\s*?\?\s*?(.+?)\s*?}}([\s\S]*?)\{\{\s*?\/\?\s*?}}/g.exec(content.slice(found.index + nested))
+		// Process extends first (they wrap everything)
-		const parts = found[2].split(/\{\{\s*?!\?\s*?/);
+		const extendsMatch = result.match(/\{\{\s*>\s*(.+?):(.+?)\s*}}([\s\S]*?)\{\{\s*\/>\s*}}/);
-		let result = evaluate(found[1], d, false) ? parts[0] : '';
+		if(extendsMatch) {
-		if (!result) {
+			const parentTemplate = await (<Function>fetch)(extendsMatch[1].trim());
-			for (let i = 1; i < parts.length; i++) {
+			if(!parentTemplate) throw new TemplateError(`Unknown extended template: ${extendsMatch[1].trim()}`);
-				const [cond, body] = parts[i].split(/}}/);
+			const slotName = extendsMatch[2].trim();
-				if (!cond.trim()) {
+			const slotContent = await process(extendsMatch[3], ctx);
-					result = body || '';
+			return process(parentTemplate, {...ctx, [slotName]: slotContent});
-					break;
 		}
-				if (evaluate(cond, d, false)) {
+
-					result = body || '';
+		let changed = true;
+		while(changed) {
+			changed = false;
+			const before = result;
+
+			// Process imports
+			const importMatch = result.match(/\{\{\s*<\s*(.+?)\s*}}/);
+			if(importMatch) {
+				const t = await (<Function>fetch)(importMatch[1].trim());
+				if(!t) throw new TemplateError(`Unknown imported template: ${importMatch[1].trim()}`);
+				const rendered = await process(t, ctx);
+				result = result.replace(importMatch[0], rendered);
+				changed = true;
+				continue;
+			}
+
+			// Process for-loops (innermost first)
+			const forMatch = findInnermostFor(result);
+			if(forMatch) {
+				const { full, vars, array, body, start } = forMatch;
+				const [element, index = 'index'] = vars.split(',').map(v => v.trim());
+				const arr: any[] = <any>dotNotation(ctx, array);
+				if(!arr || typeof arr != 'object') throw new TemplateError(`Cannot iterate: ${array}`);
+				let output = [];
+				for(let i = 0; i < arr.length; i++)
+					output.push(await process(body, {...ctx, [element]: arr[i], [index]: i}));
+				result = result.slice(0, start) + output.join('\n') + result.slice(start + full.length);
+				changed = true;
+				continue;
+			}
+
+			// Process if-statements (innermost first)
+			const ifMatch = findInnermostIf(result);
+			if(ifMatch) {
+				const { full, condition, body, start } = ifMatch;
+				const branches = parseIfBranches(body);
+				let output = '';
+				if(evaluate(condition, ctx, false)) {
+					output = branches.if;
+				} else {
+					for(const branch of branches.elseIf) {
+						if(evaluate(branch.condition, ctx, false)) {
+							output = branch.body;
 							break;
 						}
 					}
+					if(!output && branches.else) output = branches.else;
 				}
-		content = content.replace(found[0], result);
+				result = result.slice(0, start) + output + result.slice(start + full.length);
+				changed = true;
+				continue;
+			}
+			if(before === result) changed = false;
+		}
+		return processVariables(result, ctx);
 	}
 
-	// Imports - We render bottom up: `{{ < file.html }}`
+	function processVariables(content: string, data: object): string {
-	while(!!(found = /\{\{\s*?<\s*?(.+?)\s*?}}/g.exec(content))) {
+		return content.replace(/\{\{\s*([^<>\*\?!/}\s][^{}]*?)\s*}}/g, (match, code) => {
-		const t = await fetch(found[1].trim());
+			return evaluate(code.trim(), data) ?? '';
-		if(!t) throw new TemplateError(`Unknown imported template: ${found[1].trim()}`);
+		});
-		content = content.replace(found[0], await renderTemplate(t, d, fetch));
 	}
 
-	// For Loops: `{{ * (row, index) in invoice }} CONTENT {{ /* }}`
+	function findInnermostIf(content: string) {
-	while(!!(found = /\{\{\s*?\*\s*?(.+?)\s+in\s+(.+?)\s*?}}([\s\S]*?)\{\{\s*?\/\*\s*?}}/g.exec(content))) {
+		const regex = /\{\{\s*\?\s*(.+?)\s*}}/g;
-		const split = found[1].replaceAll(/[()\s]/g, '').split(',');
+		let match, lastMatch = null;
-		const element = split[0];
+		while((match = regex.exec(content)) !== null) {
-		const index = split[1] || 'index';
+			const start = match.index;
-		const array: any[] = <any>dotNotation(d, found[2]);
+			const condition = match[1];
-		if(!array || typeof array != 'object') throw new TemplateError(`Cannot iterate: ${found[2]}`);
+			const bodyStart = match.index + match[0].length;
-		let compiled = [];
+			const end = findMatchingClose(content, bodyStart, /\{\{\s*\?\s*/, /\{\{\s*\/\?\s*}}/);
-		for(let i = 0; i < array.length; i++)
+			if(end === -1) throw new TemplateError(`Unmatched if-statement at position ${start}`);
-			compiled.push(await renderTemplate(found[3], {...d, [element]: array[i], [index]: i}, fetch));
+			const closeTag = content.slice(end).match(/\{\{\s*\/\?\s*}}/);
-		content = content.replace(found[0], compiled.join('\n'));
+			const full = content.slice(start, end + (<any>closeTag)[0].length);
+			const body = content.slice(bodyStart, end);
+			lastMatch = { full, condition, body, start };
+		}
+		return lastMatch;
 	}
 
-	// Evaluate whatever is left - Should come last: `{{ javascript }}`
+	function findInnermostFor(content: string) {
-	while(!!(found = /\{\{\s*([^<>\*\?!/}\s][^}]*?)\s*}}/g.exec(content))) {
+		const regex = /\{\{\s*\*\s*(.+?)\s+in\s+(.+?)\s*}}/g;
-		content = content.replace(found[0], evaluate(found[1].trim(), d) ?? '');
+		let match, lastMatch = null;
+		while((match = regex.exec(content)) !== null) {
+			const start = match.index;
+			const vars = match[1].replaceAll(/[()\s]/g, '');
+			const array = match[2];
+			const bodyStart = match.index + match[0].length;
+			const end = findMatchingClose(content, bodyStart, /\{\{\s*\*\s*/, /\{\{\s*\/\*\s*}}/);
+			if(end === -1) throw new TemplateError(`Unmatched for-loop at position ${start}`);
+			const closeTag = content.slice(end).match(/\{\{\s*\/\*\s*}}/);
+			const full = content.slice(start, end + (<any>closeTag)[0].length);
+			const body = content.slice(bodyStart, end);
+			lastMatch = { full, vars, array, body, start };
+		}
+		return lastMatch;
 	}
 
-	// Extends: `{{ > file.html:property }} CONTENT {{ /> }}`
+	function findMatchingClose(content: string, startIndex: number, openTag: RegExp, closeTag: RegExp): number {
-	while(!!(found = /\{\{\s*?>\s*?(.+?):(.+?)\s*?}}([\s\S]*?)\{\{\s*?\/>\s*?}}/g.exec(content))) {
+		let depth = 1, pos = startIndex;
-		const t = await fetch(found[1].trim());
+		while (depth > 0 && pos < content.length) {
-		if(!t) throw new TemplateError(`Unknown extended templated: ${found[1].trim()}`);
+			const remaining = content.slice(pos);
-		content = content.replace(found[0], await renderTemplate(t, {
+			const nextOpen = remaining.search(openTag);
-			...d,
+			const nextClose = remaining.search(closeTag);
-			[found[2].trim()]: found[3],
+			if(nextClose === -1) return -1;
-		}, fetch));
+			if(nextOpen !== -1 && nextOpen < nextClose) {
+				depth++;
+				pos += nextOpen + 1;
+			} else {
+				depth--;
+				if(depth === 0) return pos + nextClose;
+				pos += nextClose + 1;
+			}
+		}
+		return -1;
 	}
 
-	return content;
+	function parseIfBranches(body: string) {
+		const parts = body.split(/\{\{\s*!\?\s*/);
+		const result = { if: parts[0], elseIf: [] as any[], else: '' };
+		for(let i = 1; i < parts.length; i++) {
+			const closeBrace = parts[i].indexOf('}}');
+			const condition = parts[i].slice(0, closeBrace).trim();
+			const branchBody = parts[i].slice(closeBrace + 2);
+			if(!condition) result.else = branchBody;
+			else result.elseIf.push({ condition, body: branchBody });
+		}
+		return result;
+	}
+
+	return process(template);
 }

src/tts.ts

@@ -0,0 +1,139 @@
+import {removeEmojis} from './string.ts';
+
+export class TTS {
+	private static readonly QUALITY_PATTERNS = ['Google', 'Microsoft', 'Samantha', 'Premium', 'Natural', 'Neural'];
+
+	private _currentUtterance: SpeechSynthesisUtterance | null = null;
+
+	private _rate: number = 1.0;
+	get rate(): number { return this._rate; }
+	set rate(value: number) {
+		this._rate = value;
+		if(this._currentUtterance) this._currentUtterance.rate = value;
+	}
+
+	private _pitch: number = 1.0;
+	get pitch(): number { return this._pitch; }
+	set pitch(value: number) {
+		this._pitch = value;
+		if(this._currentUtterance) this._currentUtterance.pitch = value;
+	}
+
+	private _volume: number = 1.0;
+	get volume(): number { return this._volume; }
+	set volume(value: number) {
+		this._volume = value;
+		if(this._currentUtterance) this._currentUtterance.volume = value;
+	}
+
+	private _voice: SpeechSynthesisVoice | undefined;
+	get voice(): SpeechSynthesisVoice | undefined { return this._voice; }
+	set voice(value: SpeechSynthesisVoice | undefined) {
+		this._voice = value;
+		if(this._currentUtterance && value) this._currentUtterance.voice = value;
+	}
+
+	/** Create a TTS instance with optional configuration */
+	constructor(config?: {rate?: number; pitch?: number; volume?: number; voice?: SpeechSynthesisVoice | null}) {
+		if(config) {
+			if(config.rate !== undefined) this._rate = config.rate;
+			if(config.pitch !== undefined) this._pitch = config.pitch;
+			if(config.volume !== undefined) this._volume = config.volume;
+			this._voice = config.voice === null ? undefined : (config.voice || undefined);
+		}
+	}
+
+	/**
+	 * Selects the best available TTS voice, prioritizing high-quality options
+	 * @param lang Speaking language
+	 * @returns Highest quality voice
+	 */
+	private static bestVoice(lang = 'en'): SpeechSynthesisVoice | undefined {
+		const voices = window.speechSynthesis.getVoices();
+		for (const pattern of this.QUALITY_PATTERNS) {
+			const voice = voices.find(v => v.name.includes(pattern) && v.lang.startsWith(lang));
+			if(voice) return voice;
+		}
+		return voices.find(v => v.lang.startsWith(lang));
+	}
+
+	/** Cleans text for TTS by removing emojis, markdown and code block */
+	private static cleanText(text: string): string {
+		return removeEmojis(text)
+			.replace(/```[\s\S]*?```/g, ' code block ')
+			.replace(/[#*_~`]/g, '');
+	}
+
+	/** Creates a speech utterance with current options */
+	private createUtterance(text: string): SpeechSynthesisUtterance {
+		const cleanedText = TTS.cleanText(text);
+		const utterance = new SpeechSynthesisUtterance(cleanedText);
+		const voice = this._voice || TTS.bestVoice();
+		if(voice) utterance.voice = voice;
+		utterance.rate = this._rate;
+		utterance.pitch = this._pitch;
+		utterance.volume = this._volume;
+		return utterance;
+	}
+
+	/** Speaks text and returns a Promise which resolves once complete */
+	speak(text: string): Promise<void> {
+		if(!text.trim()) return Promise.resolve();
+
+		return new Promise((resolve, reject) => {
+			this._currentUtterance = this.createUtterance(text);
+
+			this._currentUtterance.onend = () => {
+				this._currentUtterance = null;
+				resolve();
+			};
+
+			this._currentUtterance.onerror = (error) => {
+				this._currentUtterance = null;
+				reject(error);
+			};
+
+			window.speechSynthesis.speak(this._currentUtterance);
+		});
+	}
+
+	/** Stops all TTS */
+	stop(): void {
+		window.speechSynthesis.cancel();
+		this._currentUtterance = null;
+	}
+
+	/**
+	 * Initialize a stream that chunks text into sentences and speak them.
+	 *
+	 * @example
+	 * const stream = tts.speakStream();
+	 * stream.next("Hello ");
+	 * stream.next("World. How");
+	 * stream.next(" are you?");
+	 * await stream.done();
+	 *
+	 * @returns Object with next function for passing chunk of streamed text and done for completing the stream
+	 */
+	speakStream(): {next: (text: string) => void, done: () => void} {
+		let buffer = '';
+		const sentenceRegex = /[^.!?\n]+[.!?\n]+/g;
+
+		return {
+			next: (text: string): void => {
+				buffer += text;
+				const sentences = buffer.match(sentenceRegex);
+				if(sentences) {
+					sentences.forEach(sentence => this.speak(sentence.trim()));
+					buffer = buffer.replace(sentenceRegex, '');
+				}
+			},
+			done: async (): Promise<void> => {
+				if(buffer.trim()) {
+					await this.speak(buffer.trim());
+					buffer = '';
+				}
+			}
+		};
+	}
+}

tests/object.spec.ts

@@ -62,6 +62,11 @@ describe('Object utilities', () => {
 			dotNotation(obj, 'd.e.f', 5);
 			expect(obj.d.e.f).toBe(5);
 		});
+		it('undefined', () => {
+			const obj: any = {a: 1};
+			const resp = dotNotation(obj, 'a.b');
+			expect(resp).toBe(undefined);
+		})
 	});
 
 	describe('encodeQuery', () => {

tests/templates.spec.ts

@@ -113,6 +113,39 @@ Total: {{ total }}
 		expect(result).toEqual({ cart: [], total: '' });
 	});
 
+	test('real world template', async () => {
+		const wrapper = `<div> {{body}} </div>`;
+		const tpl = `
+{{ > email:body }}
+	<div style="text-align: center">
+		{{ ? title }}<h1 style="margin: 0">{{ title }}</h1>{{ /? }}
+		{{ ? subject }}<h2 style="margin: 0">{{ subject }}</h2>{{ /? }}
+		{{ ? message }}<p style="margin-top: 1rem">{{ message }}</p>{{ /? }}
+		{{ ? link }}
+			<br>
+			<div style="background: #dedede; padding: 8px 20px; border-radius: 10px; overflow-x: auto;">
+				{{ ? link.startsWith('http') }}
+					<a style="word-break: break-all;" target="_blank" href="{{ link }}">{{ link }}</a>
+				{{ !? }}
+					<p style="margin: 0; word-break: break-all;">{{ link }}</p>
+				{{ /? }}
+			</div>
+		{{ /? }}
+		{{ ? footer }}
+			<br>
+			<p>{{ footer }}</p>
+		{{ /? }}
+	</div>
+{{ /> }}`;
+		console.log(await renderTemplate(tpl, {
+			title: 'test',
+			subject: 'test',
+			message: 'test',
+			link: 'test',
+			footer: 'test',
+		}, async () => wrapper))
+	});
+
 	test('real world invoice template', () => {
 		const tpl = `
 {{ settings.title }}