vivth 1.1.1 → 1.2.0

package/src/class/FileSafe.mjs

@@ -0,0 +1,124 @@
+// @ts-check
+import { writeFile, mkdir, copyFile, rename, rm } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import { TryAsync } from '../function/TryAsync.mjs';
+
+/**
+ * @description
+ * - collection of static methods of file access with added safety to mkdir before proceeding;
+ */
+export class FileSafe {
+	/**
+	 * @description
+	 * - method to create file safely by recursively mkdir the dirname of the outFile;
+	 * - also returning promise of result & error as value;
+	 * @param {Parameters<writeFile>[0]} outFile
+	 * @param {Parameters<writeFile>[1]} content
+	 * @param {Parameters<writeFile>[2]} [options]
+	 * @returns {ReturnType<typeof TryAsync<void>>}
+	 * @example
+	 * import { join } from 'node:path';
+	 * import { FileSafe, Paths } from 'vivth';
+	 *
+	 * const [, errorWrite] = await FileSafe.write(
+	 * 	join(Paths.root, '/some/path.mjs'),
+	 * 	`console.log("hello-world!!");`,
+	 * 	{ encoding: 'utf-8' }
+	 * );
+	 */
+	static write = async (outFile, content, options) => {
+		return await TryAsync(async () => {
+			const [, errorMkDir] = await FileSafe.mkdir(dirname(outFile.toString()));
+			if (errorMkDir) {
+				throw new Error(`error mkdir, "${dirname(outFile.toString())}"`);
+			}
+			return writeFile(outFile, content, options);
+		});
+	};
+	/**
+	 * @description
+	 * - method to copy file/dir safely by recursively mkdir the dirname of the dest;
+	 * - also returning promise of result & error as value;
+	 * @param {Parameters<typeof copyFile>[0]} sourceFile
+	 * @param {Parameters<typeof copyFile>[1]} destinationFile
+	 * @param {Parameters<typeof copyFile>[2]} mode
+	 * @returns {ReturnType<typeof TryAsync<void>>}
+	 * @example
+	 * import { join } from 'node:path';
+	 * import { FileSafe, Paths } from 'vivth';
+	 *
+	 * const [, errorWrite] = await FileSafe.copy(
+	 * 	join(Paths.root, '/some/path.mjs'),
+	 * 	join(Paths.root, '/other/path.copy.mjs'),
+	 * 	{ encoding: 'utf-8' }
+	 * );
+	 */
+	static copy = async (sourceFile, destinationFile, mode) => {
+		return await TryAsync(async () => {
+			const dest_ = destinationFile.toString();
+			const [, errorMkDir] = await FileSafe.mkdir(dirname(dest_));
+			if (errorMkDir) {
+				throw new Error(`error mkdir, "${dirname(dest_)}"`);
+			}
+			return await copyFile(sourceFile, destinationFile, mode);
+		});
+	};
+	/**
+	 * @description
+	 * - method to rename file/dir safely by recursively mkdir the dirname of the dest;
+	 * - also returning promise of result & error as value;
+	 * @param {Parameters<typeof rename>[0]} oldPath
+	 * @param {Parameters<typeof rename>[0]} newPath
+	 * @returns {ReturnType<typeof TryAsync<void>>}
+	 * @example
+	 * import { join } from 'node:path';
+	 * import { FileSafe, Paths } from 'vivth';
+	 *
+	 * const [, errorRename] = await FileSafe.rename(
+	 * 	join(Paths.root, 'some/path'),
+	 * 	join(Paths.root, 'other/path'),
+	 * );
+	 */
+	static rename = async (oldPath, newPath) => {
+		return await TryAsync(async () => {
+			const dest_ = newPath.toString();
+			const [, errorMkDir] = await FileSafe.mkdir(dirname(dest_));
+			if (errorMkDir) {
+				throw new Error(`error mkdir, "${dirname(dest_)}"`);
+			}
+			return await rename(oldPath, newPath);
+		});
+	};
+	/**
+	 * @description
+	 * - function to remove dir and file;
+	 * - also returning promise of result & error as value;
+	 * @param {Parameters<rm>[0]} path
+	 * @param {Parameters<rm>[1]} [rmOptions]
+	 * @returns {ReturnType<typeof TryAsync<void>>}
+	 */
+	static rm = async (path, rmOptions) => {
+		return await TryAsync(async () => {
+			return await rm(path, rmOptions);
+		});
+	};
+	/**
+	 * @description
+	 * - create directory recursively;
+	 * - also returning promise of result & error as value;
+	 * @param {Parameters<mkdir>[0]} outDir
+	 * - absolute path
+	 * @returns {ReturnType<typeof TryAsync<string>>}
+	 * @example
+	 * import { join } from 'node:path';
+	 * import { FileSafe, Paths } from 'vivth';
+	 *
+	 * const [str, errorMkDir] = await FileSafe.mkdir(join(Paths.root, '/some/path/example'));
+	 */
+	static mkdir = async (outDir) => {
+		return await TryAsync(async () => {
+			return await mkdir(outDir, { recursive: true });
+		});
+	};
+}

package/src/class/ListDerived.mjs

@@ -7,16 +7,19 @@ import { Effect } from './Effect.mjs';
  * - class to create `dervivedList` that satisfy `Array<Record<string, string>>`;
  * - usefull for `derivedLoops`, e.g. temporary search values;
  * - is a `Derived` instance;
- * @template {ListArg} LA
- * @extends {Derived<LA[]>}
+ * @template {ListArg} LISTARG
+ * @extends {Derived<LISTARG[]>}
  */
 export class ListDerived extends Derived {
 	/**
 	 * @typedef {import('../types/ListArg.mjs').ListArg} ListArg
+	 * @typedef {import('../common/lazie.mjs').unwrapLazy} unwrapLazy
 	 */
 	/**
 	 * @description
-	 * @param {(effectInstanceOptions:Effect["options"])=>Promise<LA[]>} derivedFunction
+	 * @param {(effectInstanceOptions:Omit<Effect["options"],
+	 * unwrapLazy>)=>
+	 * Promise<LISTARG[]>} derivedFunction
 	 * @example
 	 * import { ListSignal, ListDerived } from 'vivth';
 	 *

package/src/class/ListSignal.mjs

@@ -11,8 +11,8 @@ import { Signal } from './Signal.mjs';
 /**
  * @description
  * - class to create list that satisfy `Array<Record<string, string>>`.
- * @template {import('../types/ListArg.mjs').ListArg} LA
- * @extends {Signal<LA[]>}
+ * @template {import('../types/ListArg.mjs').ListArg} LISTARG
+ * @extends {Signal<LISTARG[]>}
  */
 export class ListSignal extends Signal {
 	/**
@@ -41,7 +41,7 @@ export class ListSignal extends Signal {
 	/**
 	 * @description
 	 * - usefull for `loops`;
-	 * @param {LA[]} [value]
+	 * @param {LISTARG[]} [value]
 	 * @example
 	 * import { ListSignal } from 'vivth';
 	 *
@@ -56,7 +56,7 @@ export class ListSignal extends Signal {
 	/**
 	 * @description
 	 * - reference to original inputed `value`;
-	 * @type {LA[]}
+	 * @returns {LISTARG[]}
 	 */
 	get value() {
 		return super.value;
@@ -65,7 +65,7 @@ export class ListSignal extends Signal {
 	 * @description
 	 * - you cannot mannually set`value` `ListSignal_instance`;
 	 * @private
-	 * @type {LA[]}
+	 * @type {LISTARG[]}
 	 */
 	set value(_) {
 		Console.error('`List.value` `setter` are not available outside the class or instance');
@@ -82,7 +82,7 @@ export class ListSignal extends Signal {
 			 * @description
 			 * - reference to structuredClone elements of `value`;
 			 * - calling doesn't notify
-			 * @type {Array<LA>}
+			 * @returns {Array<LISTARG>}
 			 */
 			get structuredClone() {
 				return structuredClone(super.value);
@@ -91,7 +91,7 @@ export class ListSignal extends Signal {
 			 * @instance arrayMethods
 			 * @description
 			 * - appends new elements to the end;
-			 * @param {...LA} listArg
+			 * @param {...LISTARG} listArg
 			 * @returns {void}
 			 */
 			push: (...listArg) => {
@@ -112,7 +112,7 @@ export class ListSignal extends Signal {
 			 * @instance arrayMethods
 			 * @description
 			 * - inserts new element at the start;
-			 * @param  {...LA} listArg
+			 * @param  {...LISTARG} listArg
 			 * @returns {void}
 			 */
 			unshift: (...listArg) => {
@@ -137,7 +137,7 @@ export class ListSignal extends Signal {
 			 * @instance arrayMethods
 			 * @description
 			 * - replace whole `List` data with new array.
-			 * @param {LA[]} listArgs
+			 * @param {LISTARG[]} listArgs
 			 * - new array in place of the deleted array.
 			 * @returns {void}
 			 */
@@ -152,7 +152,7 @@ export class ListSignal extends Signal {
 			 * - The zero-based location in the data from which to start removing elements.
 			 * @param {number} deleteCount
 			 * -The number of elements to remove.
-			 * @param {...LA} listArg
+			 * @param {...LISTARG} listArg
 			 * - new data in place of the deleted data.
 			 * @returns {void}
 			 */
@@ -184,7 +184,7 @@ export class ListSignal extends Signal {
 			 * @description
 			 * - modify `List` element at specific index;
 			 * @param {number} index
-			 * @param {Partial<LA>} listArg
+			 * @param {Partial<LISTARG>} listArg
 			 * @returns {void}
 			 */
 			modify: (index, listArg) => {

package/src/class/LitExp.mjs

@@ -0,0 +1,405 @@
+// @ts-check
+
+import { LazyFactory } from '../function/LazyFactory.mjs';
+import { TrySync } from '../function/TrySync.mjs';
+
+/**
+ * @description
+ * - class helper to created opionated regex helper;
+ * - named capture uses `es6+` feature, you might need to add polyfill to target extremely old browser;
+ * - class name refer to `Literal Expression`;
+ * - please be patient when using this class;
+ * >- destructuring is meant for extensive typehelper;
+ * >- and destructuring can lead to unhandled error here and there;
+ * >- therefore error as value is introduced to help to prevent error on runtime;
+ * @template {LitExpKeyType} KEYS
+ */
+export class LitExp {
+	/**
+	 * @typedef {import("../types/LitExpKeyType.mjs").LitExpKeyType} LitExpKeyType
+	 */
+	/**
+	 * @description
+	 * - constructor helper;
+	 * - under the hood it is an abstraction of `RegExp`, with more template literal touch;
+	 * >- you can apply inline `RegExp` features on the string template literal(as constructor RegExp arg0);
+	 * >>- by doing so you are opting in to make:
+	 * >>>- your regex detection more robust; but
+	 * >>>- `litExp_instance.make.string` to be `unusable`;
+	 * >>- also mind the needs of escape for special characters;
+	 * @template {LitExpKeyType} KEYS
+	 * @param {KEYS} keysAndDefaultValuePair
+	 * - keys and whether to override regex detection;
+	 * >- example:
+	 * ```js
+	 *  myKey: /myCustomCapture/ // all flags will be stripped;
+	 * ```
+	 * - default value === `false` is "[\\s\\S]*?", as in whiteSpace and nonWhiteSpace 0 to more occurence;
+	 * @returns {ReturnType<typeof TrySync<(templateStringArray:TemplateStringsArray,
+	 * ...values:(keyof KEYS)[]
+	 * )=>LitExp<KEYS>>>}
+	 * - placement of `key` will determine the named capture group will be placed in the template literal;
+	 * - it is recomended to not end template literal with any of the `key`s as the regex detection might failed to detects the boundary of the end of matched string of that capture group;
+	 * @example
+	 * import { LitExp } from 'vivth';
+	 *
+	 * (()=>{
+	 * 	const [liteal, errorPrep] = LitExp.prepare({
+	 * 		myKey: /myCustomCapture/, // is placed on (?<myKey>myCustomCapture)
+	 * 		// use false to place "[\\s\\S]\*?" instead;
+	 * 		...keyCaptureLogicPair
+	 * 	})
+	 * 	if (errorPrep) {
+	 * 		console.error(error);
+	 * 		return;
+	 * 	}
+	 * 	 const litExp_instance = liteal`templateLiteral:${'myKey'};`
+	 * 	// recommended to end the template literal with any string but `key`;
+	 * })()
+	 */
+	static prepare = (keysAndDefaultValuePair) => {
+		return TrySync(() => {
+			for (const key in keysAndDefaultValuePair) {
+				const regex = keysAndDefaultValuePair[key];
+				const capture = !regex ? `[\\s\\S]*?` : regex.source;
+				if (capture.match(/\(\<\w+\>[\s\S]*?\)/g)) {
+					throw Error('trying to add named capture');
+				}
+			}
+			return (templateStringArray, ...values) =>
+				new LitExp(keysAndDefaultValuePair, templateStringArray, ...values);
+		});
+	};
+	/**
+	 * @private
+	 * @param {KEYS} keys
+	 * @param {TemplateStringsArray} templateStringArray
+	 * @param {...(keyof KEYS)} values
+	 */
+	constructor(keys, templateStringArray, ...values) {
+		this.#templateStringArray = templateStringArray;
+		this.#keyRules = keys;
+		this.#values = values;
+	}
+	/**
+	 * @type {KEYS}
+	 */
+	#keyRules;
+	/**
+	 * @type {TemplateStringsArray}
+	 */
+	#templateStringArray;
+	/**
+	 * @type {(keyof KEYS)[]}
+	 */
+	#values;
+	/**
+	 * @template {LitExpKeyType} KEYS
+	 * @param {KEYS} instance_rules
+	 * @param {(keyof KEYS)[]} intance_values
+	 * @param {(value:keyof KEYS, regex:RegExp|false)=>ReturnType<typeof TrySync<string>>} valueHandler
+	 * @param {TemplateStringsArray} strings
+	 * @returns {ReturnType<typeof TrySync<string[]>>}
+	 */
+	static #processTemplate = (instance_rules, intance_values, valueHandler, strings) => {
+		return TrySync(() => {
+			const result = [];
+			const values = intance_values;
+			const stringsLength = strings.length;
+			for (let i = 0; i < stringsLength; i++) {
+				const string = strings[i];
+				if (i + 1 == stringsLength && string === '') {
+					result.push('(?:\\s*?|$)');
+				} else {
+					result.push(string);
+				}
+				if (i < values.length) {
+					const value = values[i];
+					const [valueHandled, errorValue] = valueHandler(value, instance_rules[value]);
+					if (errorValue || !valueHandled) {
+						throw errorValue;
+					}
+					result.push(valueHandled);
+				}
+			}
+			return result;
+		});
+	};
+	/**
+	 * @param {Parameters<LitExp<KEYS>["evaluate"]["execGroups"]>[1] &
+	 * { absoluteLeadAndFollowing: boolean }} options
+	 * @returns {ReturnType<typeof TrySync<RegExp>>}
+	 */
+	#regExp = ({ flags, whiteSpaceSensitive, absoluteLeadAndFollowing }) => {
+		return TrySync(() => {
+			let regExpStringCache;
+			if (!this.#regExpStringCache) {
+				const [regExpStringCache, error] = LitExp.#processTemplate(
+					this.#keyRules,
+					this.#values,
+					LitExp.#namedChapture,
+					this.#templateStringArray
+				);
+				if (error) {
+					throw error;
+				}
+				this.#regExpStringCache = regExpStringCache.join('');
+			}
+			if (!whiteSpaceSensitive) {
+				regExpStringCache = this.#regExpStringCache.replace(/\s+/g, `\\s+`);
+			} else {
+				regExpStringCache = this.#regExpStringCache;
+			}
+			return new RegExp(
+				absoluteLeadAndFollowing ? `\^${regExpStringCache}\$` : regExpStringCache,
+				flags
+			);
+		});
+	};
+	/**
+	 * @param {Parameters<LitExp<KEYS>["evaluate"]["matchedAllAndGrouped"]>[1]} options
+	 * @returns {ReturnType<typeof TrySync<RegExp>>}
+	 */
+	#regexToMatchAll = ({ flags, whiteSpaceSensitive }) => {
+		return TrySync(() => {
+			let regExpToMatchStringCache;
+			if (!this.#regExpToMatchStringCache) {
+				const [regExpToMatchStringCache, error] = LitExp.#processTemplate(
+					this.#keyRules,
+					this.#values,
+					LitExp.#namedChapture,
+					this.#templateStringArray
+				);
+				if (error) {
+					throw error;
+				}
+				this.#regExpToMatchStringCache = regExpToMatchStringCache.join('');
+			}
+			if (!whiteSpaceSensitive) {
+				regExpToMatchStringCache = this.#regExpToMatchStringCache.replace(/\s+/g, `\\s+`);
+			} else {
+				regExpToMatchStringCache = this.#regExpToMatchStringCache;
+			}
+			return new RegExp(`\(${regExpToMatchStringCache}\)`, flags);
+		});
+	};
+
+	/**
+	 * @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];
+		},
+	}));
+	/**
+	 * @type {string}
+	 */
+	#regExpStringCache;
+	/**
+	 * @template {LitExpKeyType} KEYS
+	 * @param {RegExp|false} regex
+	 * @param {keyof KEYS} value
+	 * @returns {ReturnType<typeof TrySync<string>>}
+	 */
+	static #namedChapture = (value, regex) => {
+		return TrySync(() => {
+			const capture = !regex ? `[\\s\\S]*?` : regex.source;
+			return `(?<${value.toString()}>${capture})`;
+		});
+	};
+	/**
+	 * @type {string}
+	 */
+	#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) {
+						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 };
+			});
+		},
+	}));
+}