vivth 1.4.10 → 1.5.1

package/src/class/FileSafe.mjs

@@ -1,10 +1,10 @@
 // @ts-check
 
-import { writeFile, mkdir, copyFile, rename, rm, access } from 'node:fs/promises';
+import { writeFile, mkdir, copyFile, rename, rm, readFile, stat } from 'node:fs/promises';
 import { dirname } from 'node:path';
-import { constants } from 'node:fs';
 
 import { TryAsync } from '../function/TryAsync.mjs';
+import { Console } from './Console.mjs';
 
 /**
  * @description
@@ -14,29 +14,59 @@ export class FileSafe {
 	/**
 	 * @description
 	 * - method to safely detects whether filePaths exist;
-	 * - uses fs/promises access under the hood;
+	 * - uses `'node:fs/promises'.access` under the hood;
 	 * - also returning promise of result & error as value;
 	 * @param {string} filePath
-	 * @returns {ReturnType<typeof TryAsync<true>>}
+	 * @returns {Promise<boolean>}
 	 * @example
 	 * import { join } from 'node:path';
-	 * import { FileSafe, Paths } from 'vivth';
+	 * import { FileSafe } from 'vivth/node';
+	 * import { Paths } from 'vivth/neutral';
 	 *
-	 * const [, error] = await FileSafe.exist(
+	 * const isExist = await FileSafe.exist(
 	 * 	join(Paths.root, '/some/path.mjs'),
 	 * );
-	 * if (!error) {
-	 * 	// file exists
-	 * } else {
-	 * 	// file not exists
-	 * }
 	 */
 	static exist = async (filePath) => {
-		// @ts-expect-error
-		return await TryAsync(async () => {
-			await access(filePath, constants.F_OK);
-			return true;
+		const [, error] = await TryAsync(async () => {
+			const stats = await stat(filePath);
+			// Optional: verification that it is a file, not a directory
+			return stats.isFile() || stats.isDirectory();
 		});
+		return !error;
+	};
+	/**
+	 * @param { Parameters<writeFile>[1] } string
+	 * @returns { string }
+	 */
+	static #normalize = (string) => {
+		return string.toString().replace(/\s+/, ' ');
+	};
+	/**
+	 * @param {Parameters<FileSafe.write>[0]} outFile
+	 * @param {Parameters<FileSafe.write>[1]} content
+	 * @param {Parameters<FileSafe.write>[2]} [options]
+	 * @param {Parameters<FileSafe.write>[3]} [checkFuzySame]
+	 * @returns {Promise<boolean>}
+	 */
+	static #validToOverWrite = async (outFile, content, options, checkFuzySame = true) => {
+		const [isExist, [isSame]] = await Promise.all([
+			FileSafe.exist(outFile.toString()),
+			TryAsync(async () => {
+				if (!checkFuzySame) {
+					// code
+					return (await readFile(outFile.toString(), options)) === content;
+				}
+				return (
+					FileSafe.#normalize(await readFile(outFile.toString(), options)) ===
+					FileSafe.#normalize(content)
+				);
+			}),
+		]);
+		if (isExist && isSame) {
+			return false;
+		}
+		return true;
 	};
 	/**
 	 * @description
@@ -45,10 +75,14 @@ export class FileSafe {
 	 * @param {Parameters<writeFile>[0]} outFile
 	 * @param {Parameters<writeFile>[1]} content
 	 * @param {Parameters<writeFile>[2]} [options]
+	 * @param {boolean} [checkFuzySame]
+	 * - true: check while normalize consecutive whitespace into singel white space;
+	 * - false(default): check absolute value;
 	 * @returns {ReturnType<typeof TryAsync<void>>}
 	 * @example
 	 * import { join } from 'node:path';
-	 * import { FileSafe, Paths } from 'vivth';
+	 * import { FileSafe } from 'vivth/node';
+	 * import { Paths } from 'vivth/neutral';
 	 *
 	 * const [, errorWrite] = await FileSafe.write(
 	 * 	join(Paths.root, '/some/path.mjs'),
@@ -56,13 +90,24 @@ export class FileSafe {
 	 * 	{ encoding: 'utf-8' }
 	 * );
 	 */
-	static write = async (outFile, content, options) => {
+	static write = async (outFile, content, options, checkFuzySame = true) => {
 		return await TryAsync(async () => {
 			const [, errorMkDir] = await FileSafe.mkdir(dirname(outFile.toString()));
 			if (errorMkDir) {
-				throw new Error(`error mkdir, "${dirname(outFile.toString())}"`);
+				throw `error mkdir, "${dirname(outFile.toString())}"`;
+			}
+			if (!(await FileSafe.#validToOverWrite(outFile, content, options, checkFuzySame))) {
+				Console.warn(
+					{
+						[FileSafe.name]: `write file '${outFile}' is canceled, old file are ${checkFuzySame ? 'almost ' : ''}identical`,
+					},
+					{
+						now: true,
+					},
+				);
+				return;
 			}
-			return writeFile(outFile, content, options);
+			return await writeFile(outFile, content, options);
 		});
 	};
 	/**
@@ -75,7 +120,8 @@ export class FileSafe {
 	 * @returns {ReturnType<typeof TryAsync<void>>}
 	 * @example
 	 * import { join } from 'node:path';
-	 * import { FileSafe, Paths } from 'vivth';
+	 * import { FileSafe } from 'vivth/node';
+	 * import { Paths } from 'vivth/neutral';
 	 *
 	 * const [, errorWrite] = await FileSafe.copy(
 	 * 	join(Paths.root, '/some/path.mjs'),
@@ -88,7 +134,7 @@ export class FileSafe {
 			const dest_ = destinationFile.toString();
 			const [, errorMkDir] = await FileSafe.mkdir(dirname(dest_));
 			if (errorMkDir) {
-				throw new Error(`error mkdir, "${dirname(dest_)}"`);
+				throw `error mkdir, "${dirname(dest_)}"`;
 			}
 			return await copyFile(sourceFile, destinationFile, mode);
 		});
@@ -102,7 +148,8 @@ export class FileSafe {
 	 * @returns {ReturnType<typeof TryAsync<void>>}
 	 * @example
 	 * import { join } from 'node:path';
-	 * import { FileSafe, Paths } from 'vivth';
+	 * import { FileSafe} from 'vivth/node';
+	 * import { Paths } from 'vivth/neutral';
 	 *
 	 * const [, errorRename] = await FileSafe.rename(
 	 * 	join(Paths.root, 'some/path'),
@@ -114,7 +161,7 @@ export class FileSafe {
 			const dest_ = newPath.toString();
 			const [, errorMkDir] = await FileSafe.mkdir(dirname(dest_));
 			if (errorMkDir) {
-				throw new Error(`error mkdir, "${dirname(dest_)}"`);
+				throw `error mkdir, "${dirname(dest_)}"`;
 			}
 			return await rename(oldPath, newPath);
 		});
@@ -141,7 +188,8 @@ export class FileSafe {
 	 * @returns {ReturnType<typeof TryAsync<string|undefined>>}
 	 * @example
 	 * import { join } from 'node:path';
-	 * import { FileSafe, Paths } from 'vivth';
+	 * import { FileSafe } from 'vivth/node';
+	 * import { Paths } from 'vivth/neutral';
 	 *
 	 * const [str, errorMkDir] = await FileSafe.mkdir(join(Paths.root, '/some/path/example'));
 	 */

package/src/class/ForEach.mjs

@@ -0,0 +1,78 @@
+// @ts-check
+
+import { TrySync } from '../function/TrySync.mjs';
+
+/**
+ * @description
+ * - is collections of safe `.forEach` wrapper;
+ * >- via [TrySync](#trysync);
+ */
+export class ForEach {
+	// @ts-expect-error
+	static #handler = (iter, handler) => {
+		// @ts-expect-error
+		const results = [];
+		// @ts-expect-error
+		iter.forEach((...args) => {
+			results.push(TrySync(() => handler(...args))[0]);
+		});
+		// @ts-expect-error
+		return results;
+	};
+	/**
+	 * @description
+	 * - static method helper for `array` to be iterate safely;
+	 * @template T, R
+	 * @param {T[]} array
+	 * @param {(value: T, index: number, array: T[]) => R} handler
+	 * @returns {Array<ReturnType<typeof TrySync<R>>>}
+	 * @example
+	 * import { Foreach } from 'vivth/neutral';
+	 *
+	 * const arr = ['a','b'];
+	 * ForEach(arr, (string, i, arr_)=>{
+	 * 	// unsafe Code
+	 * });
+	 */
+	static array(array, handler) {
+		return ForEach.#handler(array, handler);
+	}
+
+	/**
+	 * @description
+	 * - static method helper for `set` to be iterate safely;
+	 * @template T, R
+	 * @param {Set<T>} set
+	 * @param {(value: T, value2: T, set: Set<T>) => R} handler
+	 * @returns {Array<ReturnType<typeof TrySync<R>>>}
+	 * @example
+	 * import { Foreach } from 'vivth/neutral';
+	 *
+	 * const set = new Set();
+	 * ForEach(set, (value, value2, set_)=>{
+	 * 	// unsafe Code
+	 * });
+	 */
+	static set(set, handler) {
+		return ForEach.#handler(set, handler);
+	}
+
+	/**
+	 * @description
+	 * - static method helper for `map` to be iterate safely;
+	 * @template K, V, R
+	 * @param {Map<K,V>} map
+	 * @param {(value: V, key: K, map: Map<K,V>) => R} handler
+	 * @returns {Array<ReturnType<typeof TrySync<R>>>}
+	 * @example
+	 * import { Foreach } from 'vivth/neutral';
+	 *
+	 * const map = new Map();
+	 * ForEach(map, (value, key, map_)=>{
+	 * 	// unsafe Code
+	 * });
+	 */
+	static map(map, handler) {
+		return ForEach.#handler(map, handler);
+	}
+}

package/src/class/ForSignal.mjs

@@ -0,0 +1,115 @@
+// @ts-check
+
+import { TryAsync } from '../function/TryAsync.mjs';
+import { Console } from './Console.mjs';
+import { Effect } from './Effect.mjs';
+import { Signal } from './Signal.mjs';
+
+/**
+ * @typedef {import('../typehints/VivthCleanup.mjs').VivthCleanup} VivthCleanup
+ */
+
+/**
+ * @description
+ * - this class extends `Signal`;
+ * - `ForSignal_instance.runCleanUp` still needs to be manually called, when cleaning up this instance;
+ * @template {any} TYPE
+ * @implements {VivthCleanup}
+ * @extends {Signal<Array<TYPE|undefined>>}
+ */
+export class ForSignal extends Signal {
+	/**
+	 * @description
+	 * @param {(
+	 *	this: ForSignal<TYPE>,
+	 *	arg:{
+	 *		index:number,
+	 *		value:{ value:TYPE, isValueDefined:true, }|
+	 *			{ value:undefined, isValueDefined:false, },
+	 *		prev:{ prev:TYPE, isPrevDefined:true, }|
+	 * 			{ prev:undefined, isPrevDefined:false, },
+	 * 	})=>void
+	 * } loopCallback
+	 * - the diffence of `current` and `prev` or `isValueDefined` and `isPrevDefined` can be used for sideEffect, such as;
+	 * >- `adding/removing/modifiying` `childNode`s on a parent element;
+	 * >- `adding/removing/modifiying` `Signal` instances;
+	 * @param {()=>void} [additionalCleanUp]
+	 * - additional callback to be run when runCleanUp is called;
+	 * @example
+	 * import { ForSignal } from 'vivth/neutral';
+	 *
+	 * const myLoop = new ForSignal(
+	 * 	function ({ index, value: {value, isValueDefined}, prev:{ prev, isPrevDefined} }) {
+	 * 		// code
+	 * 	},
+	 * 	() => {
+	 * 	 // additional cleanup code
+	 * 	}
+	 * )
+	 * // myLoop.runCleanUp(); // need to be called manually when the instance are to out of scope;
+	 */
+	constructor(loopCallback, additionalCleanUp) {
+		super([]);
+		new Effect(async ({ subscribe, isLastCalled, removeEffect }) => {
+			const { value: currentValues, prev: prevValues = [] } = subscribe(this);
+			if (!(await isLastCalled())) {
+				return;
+			}
+			const length = Math.max(currentValues.length, prevValues?.length ?? 0);
+			const isCleanUpRun = this.#isCleanUpRun;
+			/**
+			 * @type {Array<ReturnType<typeof TryAsync<void>>>}
+			 */
+			const promises = [];
+			for (let index = 0; index < length; index++) {
+				promises.push(
+					TryAsync(async () => {
+						const current = currentValues[index];
+						const prev = prevValues[index];
+						if (current === prev) {
+							return;
+						}
+						try {
+							await loopCallback.call(this, {
+								index,
+								// @ts-expect-error
+								value: { value: current, isValueDefined: current !== undefined },
+								// @ts-expect-error
+								prev: { prev, isPrevDefined: prev !== undefined },
+							});
+						} catch (errorHandlingForSignal) {
+							Console.error({ errorHandlingForSignal, index });
+						}
+					}),
+				);
+			}
+			await Promise.all(promises);
+			if (!isCleanUpRun) {
+				return;
+			}
+			/**
+			 * - the actual cleanup code;
+			 */
+			removeEffect();
+			this.remove.ref();
+			if (!additionalCleanUp) {
+				return;
+			}
+			additionalCleanUp();
+		});
+	}
+	/**
+	 * @type {boolean}
+	 */
+	#isCleanUpRun = false;
+	/**
+	 * @description
+	 * - need to be manually called when disposing/cleaning up this instance;
+	 * @type {()=>Promise<void>}
+	 * @override
+	 */
+	vivthCleanup = async () => {
+		this.#isCleanUpRun = true;
+		this.value = [];
+	};
+}

package/src/class/GetterSetter.mjs

@@ -0,0 +1,40 @@
+// @ts-check
+
+/**
+ * @description
+ * - create getter setter in one place;
+ * @template {any} RET
+ * @template {((...any:any[])=>RET)} TG
+ * @template {((...any:any[])=>void)} TS
+ * @example
+ * import { GetterSetter } from 'vivth/neutral';
+ *
+ * const localA = new GetterSetter({
+ * 	get:() => {
+ * 		return localStorage.getItem('myAValue');
+ * 	},
+ * 	set:(newValue) => {
+ * 		return localStorage.setItem('myAValue', newValue);
+ * 	},
+ * });
+ * localA.get(); // null;
+ * localA.set('my new value');
+ * localA.get(); // 'my new value'
+ */
+export class GetterSetter {
+	/**
+	 * @param {{ get?: TG, set?: TS }} options
+	 */
+	constructor({ get, set }) {
+		this.get = get;
+		this.set = set;
+	}
+	/**
+	 * @type {ConstructorParameters<typeof GetterSetter<RET,TG,TS>>[0]["get"]}
+	 */
+	get;
+	/**
+	 * @type {ConstructorParameters<typeof GetterSetter<RET,TG,TS>>[0]["set"]}
+	 */
+	set;
+}

package/src/class/JSONFileHandler.mjs

@@ -0,0 +1,90 @@
+// @ts-check
+
+import { readFile } from 'node:fs/promises';
+import prettier from 'prettier';
+import stripJsonComments from 'strip-json-comments';
+
+import { TryAsync } from '../function/TryAsync.mjs';
+import { FileSafe } from './FileSafe.mjs';
+import { Preferrence } from '../common/Preferrence.mjs';
+import { Paths } from './Paths.mjs';
+
+/**
+ * @description
+ * - class helper to handle `.json` file;
+ * - this class assume, `Paths` already instantiated;
+ */
+export class JSONFileHandler {
+	/**
+	 * @param {string} path
+	 * - `relative`(to `Paths.root`) OR `absolute`, both are accepted;
+	 */
+	constructor(path) {
+		this.#path = Paths.diskAbsolute(path);
+	}
+	/**
+	 * @type {ConstructorParameters<typeof JSONFileHandler>[0]}
+	 */
+	#path;
+	/**
+	 * @description
+	 * @returns {ReturnType<typeof TryAsync<Object>>}
+	 * @example
+	 * import { JSONFileHandler } from "vivth/node";
+	 *
+	 * const packageJSONHandler = new JSONFileHandler('/package.json');
+	 * const [content, error] = await packageJSONHandler.read();
+	 */
+	read = async () => {
+		return await TryAsync(async () => {
+			const strippedContent = stripJsonComments(
+				await readFile(this.#path, { encoding: Preferrence.encoding }),
+			);
+			return JSON.parse(strippedContent);
+		});
+	};
+	/**
+	 * @description
+	 * @param {Object} newObj
+	 * @return { ReturnType<typeof TryAsync<void>> }
+	 * @example
+	 * import { this.writeJSONFileHandler } from "vivth/node";
+	 *
+	 * const packageJSONHandler = new JSONFileHandler('/package.json');
+	 * const [, error] = await packageJSONHandler.write({
+	 *  ...object,
+	 * });
+	 */
+	write = async (newObj) => {
+		const pretified = await prettier.format(JSON.stringify(newObj), { parser: 'json-stringify' });
+		return await FileSafe.write(this.#path, pretified, {
+			encoding: Preferrence.encoding,
+		});
+	};
+	/**
+	 * @description
+	 * @param {Object} object
+	 * @return { ReturnType<typeof TryAsync<void>> }
+	 * @example
+	 * import { JSONFileHandler } from "vivth/node";
+	 *
+	 * const packageJSONHandler = new JSONFileHandler('/package.json');
+	 * const [, error] = await packageJSONHandler.assign({
+	 *  ...object,
+	 * });
+	 */
+	assign = async (object) => {
+		return await TryAsync(async () => {
+			const [jsonFileObject, errorReadJSONFileHandler] = await this.read();
+			if (errorReadJSONFileHandler) {
+				throw { errorReadJSONFileHandler };
+			}
+			Object.assign(jsonFileObject, object);
+			const [, errorWriteJSONFileHandler] = await this.write(jsonFileObject);
+			if (!errorWriteJSONFileHandler) {
+				return;
+			}
+			throw { errorWriteJSONFileHandler };
+		});
+	};
+}