vivth 1.2.3 → 1.3.0

package/src/class/LitExp.mjs

@@ -18,6 +18,22 @@ export class LitExp {
 	/**
 	 * @typedef {import("../types/LitExpKeyType.mjs").LitExpKeyType} LitExpKeyType
 	 */
+
+	/**
+	 * @description
+	 * - to escape special chars from string literal;
+	 * - returned value can be used to create instance of RegExp;
+	 * @param {string} string
+	 * @returns {string}
+	 * @example
+	 * import { LitExp } from 'vivt';
+	 *
+	 * const escapedLiteral = LitExp.escape(`something[][;alerk325]`);
+	 * new RegExp(escapedLiteral, 'g');
+	 */
+	static escape = (string) => {
+		return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+	};
 	/**
 	 * @description
 	 * - constructor helper;
@@ -57,7 +73,7 @@ export class LitExp {
 	 * 	// recommended to end the template literal with any string but `key`;
 	 * })()
 	 */
-	static prepare = (keysAndDefaultValuePair) => {
+	static prepare(keysAndDefaultValuePair) {
 		return TrySync(() => {
 			for (const key in keysAndDefaultValuePair) {
 				const regex = keysAndDefaultValuePair[key];
@@ -69,7 +85,7 @@ export class LitExp {
 			return (templateStringArray, ...values) =>
 				new LitExp(keysAndDefaultValuePair, templateStringArray, ...values);
 		});
-	};
+	}
 	/**
 	 * @private
 	 * @param {KEYS} keys
@@ -101,22 +117,31 @@ export class LitExp {
 	 * @param {TemplateStringsArray} strings
 	 * @returns {ReturnType<typeof TrySync<string[]>>}
 	 */
-	static #processTemplate = (instance_rules, intance_values, valueHandler, strings) => {
+	static #processTemplate(instance_rules, intance_values, valueHandler, strings) {
 		return TrySync(() => {
+			/**
+			 * @type {string[]}
+			 */
 			const result = [];
 			const values = intance_values;
 			const stringsLength = strings.length;
 			for (let i = 0; i < stringsLength; i++) {
 				const string = strings[i];
+				if (string === undefined) {
+					throw new Error('string undefined');
+				}
 				if (i + 1 == stringsLength && string === '') {
-					result.push('(?:\\s*?|$)');
+					result.push('(?:\\s+?|$)');
 				} else {
-					result.push(string);
+					result.push(LitExp.escape(string));
 				}
 				if (i < values.length) {
 					const value = values[i];
+					if (value === undefined || instance_rules[value] === undefined) {
+						continue;
+					}
 					const [valueHandled, errorValue] = valueHandler(value, instance_rules[value]);
-					if (errorValue || !valueHandled) {
+					if (errorValue || valueHandled === '') {
 						throw errorValue;
 					}
 					result.push(valueHandled);
@@ -124,7 +149,7 @@ export class LitExp {
 			}
 			return result;
 		});
-	};
+	}
 	/**
 	 * @param {Parameters<LitExp<KEYS>["evaluate"]["execGroups"]>[1] &
 	 * { absoluteLeadAndFollowing: boolean }} options
@@ -133,7 +158,7 @@ export class LitExp {
 	#regExp = ({ flags, whiteSpaceSensitive, absoluteLeadAndFollowing }) => {
 		return TrySync(() => {
 			let regExpStringCache;
-			if (!this.#regExpStringCache) {
+			if (this.#regExpStringCache === undefined) {
 				const [regExpStringCache, error] = LitExp.#processTemplate(
 					this.#keyRules,
 					this.#values,
@@ -145,10 +170,10 @@ export class LitExp {
 				}
 				this.#regExpStringCache = regExpStringCache.join('');
 			}
-			if (!whiteSpaceSensitive) {
-				regExpStringCache = this.#regExpStringCache.replace(/\s+/g, `\\s+`);
-			} else {
+			if (whiteSpaceSensitive) {
 				regExpStringCache = this.#regExpStringCache;
+			} else {
+				regExpStringCache = this.#regExpStringCache.replace(/\s+/g, `\\s+`);
 			}
 			return new RegExp(
 				absoluteLeadAndFollowing ? `\^${regExpStringCache}\$` : regExpStringCache,
@@ -163,75 +188,83 @@ export class LitExp {
 	#regexToMatchAll = ({ flags, whiteSpaceSensitive }) => {
 		return TrySync(() => {
 			let regExpToMatchStringCache;
-			if (!this.#regExpToMatchStringCache) {
+			if (this.#regExpToMatchStringCache === undefined) {
 				const [regExpToMatchStringCache, error] = LitExp.#processTemplate(
 					this.#keyRules,
 					this.#values,
 					LitExp.#namedChapture,
 					this.#templateStringArray
 				);
-				if (error) {
+				if (error || regExpToMatchStringCache === undefined) {
 					throw error;
 				}
 				this.#regExpToMatchStringCache = regExpToMatchStringCache.join('');
 			}
-			if (!whiteSpaceSensitive) {
-				regExpToMatchStringCache = this.#regExpToMatchStringCache.replace(/\s+/g, `\\s+`);
-			} else {
+			if (whiteSpaceSensitive) {
 				regExpToMatchStringCache = this.#regExpToMatchStringCache;
+			} else {
+				regExpToMatchStringCache = this.#regExpToMatchStringCache.replace(/\s+/g, `\\s+`);
 			}
 			return new RegExp(`\(${regExpToMatchStringCache}\)`, flags);
 		});
 	};
-
+	/**
+	 * @typedef {ReturnType<LitExp<KEYS>["evaluate"]["execGroups"]>} ExecGroups
+	 * @typedef {ExecGroups extends [infer First, ...any] ? First : undefined} FirstGroup
+	 * @typedef {FirstGroup extends { result: any } ? Partial<FirstGroup["result"]> : undefined} Overrides
+	 */
 	/**
 	 * @description
 	 * - instance methods for generating things;
 	 */
-	make = LazyFactory(() => ({
-		/**
-		 * @instance make
-		 * @description
-		 * - to make string based on the template literal;
-		 * @param {Partial<ReturnType<LitExp<KEYS>["evaluate"]["execGroups"]>>[0]["result"]} overrides
-		 * @returns {string}
-		 * @example
-		 * import { LitExp } from 'vivth';
-		 *
-		 * const [literal, errorPreparing] = LitExp.prepare({
-		 * 	myKey: false,
-		 * 	...keyCaptureLogicPair
-		 * })
-		 *
-		 * // asuming no error
-		 * litExp_instance = `templateLiteral:${'myKey'};`;
-		 * const [result, error] = litExp_instance.make.string({
-		 * 	myKey: 'actualvalue',
-		 * });
-		 *
-		 * console.log(result); // "templateLiteral:actualvalue;"
-		 */
-		string: (overrides) => {
-			return TrySync(() => {
-				const [res, error] = LitExp.#processTemplate(
-					this.#keyRules,
-					this.#values,
-					(key) => {
-						return TrySync(() => {
-							return overrides[key.toString()] ?? '';
-						});
-					},
-					this.#templateStringArray
-				);
-				if (error || !res) {
-					throw error;
-				}
-				return res.join('');
-			})[0];
-		},
-	}));
+	make = LazyFactory(() => {
+		const this_ = this;
+		return {
+			/**
+			 * @instance make
+			 * @description
+			 * - to make string based on the template literal;
+			 * @param {Partial<{ [K in keyof KEYS]?: string }>} overrides
+			 * @returns {string|undefined}
+			 * @example
+			 * import { LitExp } from 'vivth';
+			 *
+			 * const [literal, errorPreparing] = LitExp.prepare({
+			 * 	myKey: false,
+			 * 	...keyCaptureLogicPair
+			 * })
+			 *
+			 * // asuming no error
+			 * litExp_instance = `templateLiteral:${'myKey'};`;
+			 * const [result, error] = litExp_instance.make.string({
+			 * 	myKey: 'actualvalue',
+			 * });
+			 *
+			 * console.log(result); // "templateLiteral:actualvalue;"
+			 */
+			string: (overrides) => {
+				return TrySync(() => {
+					const [res, error] = LitExp.#processTemplate(
+						this_.#keyRules,
+						this_.#values,
+						// @ts-expect-error
+						(key) => {
+							return TrySync(() => {
+								return overrides[key];
+							});
+						},
+						this_.#templateStringArray
+					);
+					if (error) {
+						throw error;
+					}
+					return res.join('');
+				})[0];
+			},
+		};
+	});
 	/**
-	 * @type {string}
+	 * @type {string|undefined}
 	 */
 	#regExpStringCache;
 	/**
@@ -240,152 +273,81 @@ export class LitExp {
 	 * @param {keyof KEYS} value
 	 * @returns {ReturnType<typeof TrySync<string>>}
 	 */
-	static #namedChapture = (value, regex) => {
+	static #namedChapture(value, regex) {
 		return TrySync(() => {
-			const capture = !regex ? `[\\s\\S]*?` : regex.source;
+			const capture = regex === false ? `[\\s\\S]*?` : regex.source;
 			return `(?<${value.toString()}>${capture})`;
 		});
-	};
+	}
 	/**
-	 * @type {string}
+	 * @type {string|undefined}
 	 */
 	#regExpToMatchStringCache;
 	/**
 	 * @description
 	 * - methods collections to evaluate string with `Literal Expression`;
 	 */
-	evaluate = LazyFactory(() => ({
-		/**
-		 * @instance evaluate
-		 * @description
-		 * - to exec and grouped based on `key`;
-		 * @param {string} string
-		 * @param {Object} options
-		 * @param {ConstructorParameters<typeof RegExp>[1]} options.flags
-		 * @param {boolean} options.whiteSpaceSensitive
-		 * - true: leave any whitespace as is to be used as regex detection;
-		 * - false: convert all whitespace to `\s+`;
-		 * @param {boolean} options.absoluteLeadAndFollowing
-		 * - false: standard capture;
-		 * - true: add `^` and `$` to capture definition:
-		 * >- meaning string will have to match starting and end of line from capture definition;
-		 * @returns {ReturnType<typeof TrySync<{
-		 * result:{ whole:string, named: Record<keyof KEYS, string>},
-		 * regexp:RegExp}>>
-		 * }
-		 * @example
-		 * import { LitExp } from 'vivth';
-		 *
-		 * const [literal, errorPreparing] = LitExp.prepare({
-		 * 	myKey: false,
-		 * 	...keyCaptureLogicPair
-		 * })
-		 *
-		 * // asuming no eror
-		 * const litExp_instance = literal`templateLiteral:${'myKey'};`
-		 *
-		 * const [{
-		 * 		result:{ // asuming there's no error
-		 * 			named: { myKey },
-		 * 			whole,
-		 * 		},
-		 * 		regex, // for reference
-		 * 	}, error] = litExp_instance.evaluate.execGroups(
-		 * 	`templateLiteral:Something;`,
-		 * 	{ ...options }
-		 * )
-		 *
-		 * console.log(whole); // "templateLiteral:Something;"
-		 * console.log(myKey); // "Something"
-		 */
-		execGroups: (string, options) => {
-			// @ts-expect-error
-			return TrySync(() => {
-				const [regexp, error] = this.#regExp(options);
-				if (error || !regexp) {
-					throw error;
-				}
-				const execResult = regexp.exec(string);
-				const whole = execResult[1];
-				const named = execResult?.groups;
-				const result = { named, whole };
-				if (!named) {
-					throw new Error(
-						JSON.stringify({
-							regexpSource: regexp.source,
-							message: 'no match is found',
-							sugestion: 'make sure all `keys` values will capture any scenario',
-						})
-					);
-				}
-				return { result, regexp };
-			});
-		},
-		/**
-		 * @instance evaluate
-		 * @description
-		 * - to match all and grouped based on `key`;
-		 * @param {Parameters<LitExp<KEYS>["evaluate"]["execGroups"]>[0]} string
-		 * @param {Omit<Parameters<LitExp<KEYS>["evaluate"]["execGroups"]>[1], 'absoluteLeadAndFollowing'>} options
-		 * @returns {ReturnType<typeof TrySync<{result:{whole:string[], named:Array<Record<keyof KEYS, string>>},
-		 * regexp: RegExp}>>
-		 * }
-		 * @example
-		 * import { LitExp, Console } from 'vivth';
-		 *
-		 * const [literal, errorPreparing] = LitExp.prepare({
-		 * 	myKey: false,
-		 * 	...keyCaptureLogicPair
-		 * })
-		 *
-		 * // asuming no error;
-		 * litExp_instance = literal`templateLiteral:${'myKey'};`
-		 *
-		 * const [resultOfMatchedAllAndGrouped, error] = litExp_instance.evaluate.matchedAllAndGrouped(
-		 * 	`templateLiteral:Something;
-		 * 	templateLiteral:SomethingElse;`,
-		 * 	{ ...options }
-		 * )
-		 * (()=>{
-		 * 	if (error) {
-		 * 		Console.error(error);
-		 * 		return;
-		 * 	}
-		 * 	const {
-		 * 		result: {
-		 * 				whole: [whole0, whole1],
-		 * 				named: [
-		 * 					{ myKey: myKeyExec0, },
-		 * 					{ myKey: myKeyExec1, },
-		 * 				],
-		 * 			},
-		 * 		regexp
-		 * 	} = resultOfMatchedAllAndGrouped;
-		 *
-		 * 	console.log(whole0); // "templateLiteral:Something;"
-		 * 	console.log(whole1); // "templateLiteral:SomethingElse;"
-		 * 	console.log(myKeyExec0); // "Something"
-		 * 	console.log(myKeyExec1); // "SomethingElse"
-		 * })()
-		 */
-		matchedAllAndGrouped: (string, options) => {
-			return TrySync(() => {
-				const [regexp, error] = this.#regexToMatchAll(options);
-				if (error || !regexp) {
-					throw error;
-				}
-				/**
-				 * @type {Array<Record<keyof KEYS, string>>}
-				 */
-				const named = [];
-				const whole = [];
-				/**
-				 * @type {{whole:string[], named:Array<Record<keyof KEYS, string>>}}
-				 */
-				const result = { named, whole };
-				const matchedAll = string.matchAll(regexp);
-				for (const match of matchedAll) {
-					if (!match.groups) {
+	evaluate = LazyFactory(() => {
+		const this_ = this;
+		return {
+			/**
+			 * @instance evaluate
+			 * @description
+			 * - to exec and grouped based on `key`;
+			 * @param {string} string
+			 * @param {Object} options
+			 * @param {ConstructorParameters<typeof RegExp>[1]} options.flags
+			 * @param {boolean} options.whiteSpaceSensitive
+			 * - true: leave any whitespace as is to be used as regex detection;
+			 * - false: convert all whitespace to `\s+`;
+			 * @param {boolean} options.absoluteLeadAndFollowing
+			 * - false: standard capture;
+			 * - true: add `^` and `$` to capture definition:
+			 * >- meaning string will have to match starting and end of line from capture definition;
+			 * @returns {ReturnType<typeof TrySync<{
+			 * result:{ whole:string, named: Record<keyof KEYS, string>},
+			 * regexp:RegExp}>>
+			 * }
+			 * @example
+			 * import { LitExp } from 'vivth';
+			 *
+			 * const [literal, errorPreparing] = LitExp.prepare({
+			 * 	myKey: false,
+			 * 	...keyCaptureLogicPair
+			 * })
+			 *
+			 * // asuming no eror
+			 * const litExp_instance = literal`templateLiteral:${'myKey'};`
+			 *
+			 * const [{
+			 * 		result:{ // asuming there's no error
+			 * 			named: { myKey },
+			 * 			whole,
+			 * 		},
+			 * 		regex, // for reference
+			 * 	}, error] = litExp_instance.evaluate.execGroups(
+			 * 	`templateLiteral:Something;`,
+			 * 	{ ...options }
+			 * )
+			 *
+			 * console.log(whole); // "templateLiteral:Something;"
+			 * console.log(myKey); // "Something"
+			 */
+			execGroups(string, options) {
+				// @ts-expect-error
+				return TrySync(() => {
+					const [regexp, error] = this_.#regExp(options);
+					if (error) {
+						throw error;
+					}
+					const execResult = regexp.exec(string);
+					if (execResult === null) {
+						return undefined;
+					}
+					const whole = execResult[1];
+					const named = execResult?.groups;
+					const result = { named, whole };
+					if (named === undefined) {
 						throw new Error(
 							JSON.stringify({
 								regexpSource: regexp.source,
@@ -394,12 +356,87 @@ export class LitExp {
 							})
 						);
 					}
-					whole.push(match[1]);
-					// @ts-expect-error
-					named.push(match.groups);
-				}
-				return { result, regexp };
-			});
-		},
-	}));
+					return { result, regexp };
+				});
+			},
+			/**
+			 * @instance evaluate
+			 * @description
+			 * - to match all and grouped based on `key`;
+			 * @param {Parameters<LitExp<KEYS>["evaluate"]["execGroups"]>[0]} string
+			 * @param {Omit<Parameters<LitExp<KEYS>["evaluate"]["execGroups"]>[1], 'absoluteLeadAndFollowing'>} options
+			 * @returns {ReturnType<typeof TrySync<import('../types/LitExpResultType.mjs').LitExpResultType<KEYS>>>
+			 * }
+			 * @example
+			 * import { LitExp, Console } from 'vivth';
+			 *
+			 * const [literal, errorPreparing] = LitExp.prepare({
+			 * 	myKey: false,
+			 * 	...keyCaptureLogicPair
+			 * })
+			 *
+			 * // asuming no error;
+			 * litExp_instance = literal`templateLiteral:${'myKey'};`
+			 *
+			 * const [resultOfMatchedAllAndGrouped, error] = litExp_instance.evaluate.matchedAllAndGrouped(
+			 * 	`templateLiteral:Something;
+			 * 	templateLiteral:SomethingElse;`,
+			 * 	{ ...options }
+			 * )
+			 * (()=>{
+			 * 	if (error) {
+			 * 		Console.error(error);
+			 * 		return;
+			 * 	}
+			 * 	const {
+			 * 		result: { whole, named },
+			 * 		regexp
+			 * 	} = resultOfMatchedAllAndGrouped;
+			 *
+			 *	named.foreach(({myKey})=>{
+			 *		// code
+			 *	})
+			 *	whole.foreach((capturedString)=>{
+			 *		// code
+			 *	})
+			 * })()
+			 */
+			matchedAllAndGrouped: (string, options) => {
+				return TrySync(() => {
+					const [regexp, error] = this.#regexToMatchAll(options);
+					if (error) {
+						throw error;
+					}
+					/**
+					 * @type {Array<Record<keyof KEYS, string>>}
+					 */
+					const named = [];
+					/**
+					 * @type {Array<string>}
+					 */
+					const whole = [];
+					/**
+					 * @type {{whole:string[], named:Array<Record<keyof KEYS, string>>}}
+					 */
+					const result = { named, whole };
+					const matchedAll = string.matchAll(regexp);
+					for (const match of matchedAll) {
+						if (match.groups === undefined) {
+							throw new Error(
+								JSON.stringify({
+									regexpSource: regexp.source,
+									message: 'no match is found',
+									sugestion: 'make sure all `keys` values will capture any scenario',
+								})
+							);
+						}
+						whole.push(match[1] ?? '');
+						// @ts-expect-error
+						named.push(match.groups);
+					}
+					return { result, regexp };
+				});
+			},
+		};
+	});
 }

package/src/class/Paths.mjs

@@ -12,9 +12,9 @@ import { Console } from './Console.mjs';
  */
 export class Paths {
 	/**
-	 * @type {Paths}
+	 * @type {Paths|undefined}
 	 */
-	static #instance = undefined;
+	static #instance;
 	/**
 	 * @description
 	 * @param {Object} options
@@ -51,19 +51,19 @@ export class Paths {
 		this.#root = root;
 	}
 	/**
-	 * @type {string}
+	 * @type {string|undefined}
 	 */
-	#root = undefined;
+	#root;
 	/**
 	 * @description
 	 * - reference for rootPath
 	 * - `Paths` needed to be instantiated via:
 	 * >- `Paths` constructor;
 	 * >- `Setup.paths` constructor;
-	 * @type {string}
+	 * @type {string|undefined}
 	 */
 	static get root() {
-		if (!Paths.#instance.#root) {
+		if (Paths.#instance === undefined) {
 			Console.error({
 				error: 'Paths.instance.#root is undefined',
 				solutions: 'instantiate `Paths` or instantiate `Setup`',
@@ -82,7 +82,9 @@ export class Paths {
 	 *
 	 * Paths.normalize('file:\\D:\\myFile.mjs'); //  "file://D://myFile.mjs"
 	 */
-	static normalize = (path_) => path_.replace(/\\/g, '/');
+	static normalize = (path_) => {
+		return path_.replace(/\\/g, '/');
+	};
 	/**
 	 * @description
 	 * - normalize path separator to forward slash `/`;
@@ -96,7 +98,7 @@ export class Paths {
 	 */
 	static normalizesForRoot = (path_) => {
 		let normalized = Paths.normalize(path_);
-		if (!normalized.startsWith('/')) {
+		if (normalized.startsWith('/') === false) {
 			normalized = `/${normalized}`;
 		}
 		// @ts-expect-error

package/src/class/QChannel.mjs

@@ -48,17 +48,18 @@ export class QChannel {
 	 * - ensures that each id has only one task running at a time.
 	 * - calls with the same id will wait for the previous call to finish.
 	 * @param {AnyButUndefined} id
-	 * @param {QChannel} instance
+	 * @param {QChannel<any>} instance
 	 * @returns {Promise<QCBReturn>} Resolves when it's safe to proceed for the given id, returning a cleanup function
 	 */
 	static #uniqueCB = async (id, instance) => {
 		const existing = QChannel.#uniquePromiser.get(id);
+		// @ts-expect-error
 		let resolveFn;
 		const nextPromise = new Promise((resolve) => {
 			resolveFn = resolve;
 		});
 		const context = {};
-		if (!existing) {
+		if (existing === undefined) {
 			QChannel.#uniquePromiser.set(id, [nextPromise, context]);
 			await Promise.resolve();
 		} else {
@@ -67,15 +68,17 @@ export class QChannel {
 			QChannel.#uniquePromiser.set(id, [nextPromise, context]);
 		}
 		const resume = () => {
+			// @ts-expect-error
 			resolveFn();
 			QChannel.#uniquePromiser.delete(id);
 		};
 		return {
 			resume,
 			isLastOnQ: () => {
-				if (!QChannel.#uniquePromiser.has(id)) {
+				if (QChannel.#uniquePromiser.has(id) === false) {
 					return false;
 				}
+				// @ts-expect-error
 				const [, lastContext] = QChannel.#uniquePromiser.get(id);
 				return instance.#shouldRun && lastContext === context;
 			},
@@ -140,13 +143,13 @@ export class QChannel {
 	/**
 	 * @type {boolean}
 	 */
-	#shouldRun_;
+	#shouldRun_ = true;
 	/**
 	 * @returns {boolean}
 	 */
 	get #shouldRun() {
 		const shoulRun = this.#shouldRun_;
-		if (!shoulRun) {
+		if (shoulRun === false) {
 			Console.warn({ qChannel_name: this.name, message: 'is closed' });
 		}
 		return shoulRun;
@@ -197,11 +200,15 @@ export class QChannel {
 	key = async (keyID) => {
 		const { resume } = await QChannel.#uniqueCB(this, this);
 		const mapped = this.#mapped;
-		if (!mapped.has(keyID)) {
+		if (mapped.has(keyID) === false) {
 			mapped.set(keyID, {});
 		}
 		resume();
-		return await QChannel.#uniqueCB(mapped.get(keyID), this);
+		return await QChannel.#uniqueCB(
+			// @ts-expect-error
+			mapped.get(keyID),
+			this
+		);
 	};
 	/**
 	 * @description