vivth 1.3.5 → 1.3.7

package/README.md

@@ -73,11 +73,13 @@ npm i vivth
 - [SafeExit](#safeexit)
 - [Setup](#setup)
 - [Signal](#signal)
+- [WalkThrough](#walkthrough)
 - [WorkerMainThread](#workermainthread)
 - [WorkerResult](#workerresult)
 - [WorkerThread](#workerthread)
 - [Base64URL](#base64url)
 - [Base64URLFromFile](#base64urlfromfile)
+- [CreateStringID](#createstringid)
 - [Dev](#dev)
 - [EventNameSpace](#eventnamespace)
 - [Trace](#trace)
@@ -666,12 +668,13 @@ const effect = new Effect(async ({ isLastCalled }) => {
 
 #### reference:`Effect_instance.options.subscribe`
 
+- subscribe to `Signal_instance`;
 - normally it's passed as argument to constructor, however it is also accessible from `options` property;
 
 ```js
 /**
  * @template V
- * @param {Signal<V>} signal
+ * @param {Signal<V>} signalInstance
  * @returns {Signal<V>}
  */
 ```
@@ -708,6 +711,33 @@ const effect = new Effect(async () => {
 effect.options.removeEffect();
 ```
 
+#### reference:`Effect_instance.removeSignal`
+
+- remove inputed signal from this `Effect_instance`;
+- if effect signal has no other `Signal_instance` to listen to, it will then completely rendered non reactive;
+- normally it's passed as argument to constructor, however it is also accessible from `options` property;
+
+```js
+/**
+ * @param {Signal<any>} signalInstance
+ * @returns {void}
+ */
+```
+
+- <i>example</i>:
+
+```js
+import { Effect, Signal } from "vivth";
+
+const count = new Signal(0);
+const effect = new Effect(async ({ subscribe }) => {
+  console.log(subscribe(count).value); // will subscribe  count changes;
+});
+count.value++; // will increase the count and trigger effect;
+effect.options.removeSignal(count);
+count.value++; // will increase the count but will no longer trigger effect;
+```
+
 #### reference:`new Effect`
 
 ```js
@@ -1100,7 +1130,7 @@ eventSignal_instance.remove.ref();
 import { join } from "node:path";
 import { FileSafe, Paths } from "vivth";
 
-const [, error] = await FileSafe.write(join(Paths.root, "/some/path.mjs"));
+const [, error] = await FileSafe.exist(join(Paths.root, "/some/path.mjs"));
 if (!error) {
   // file exists
 } else {
@@ -1871,7 +1901,7 @@ resume();
 /**
  * @template RESULT
  * @param {()=>Promise<RESULT>} asyncCallback
- * @returns {Promise<[RESULT|undefined, Error|undefined]>}
+ * @returns {ReturnType<typeof TryAsync<RESULT>>}
  */
 ```
 
@@ -2347,6 +2377,108 @@ count.value = 9;
 
 \*) <sub>[go to list of exported API and typehelpers](#list-of-exported-api-and-typehelpers)</sub>
 
+<h2 id="walkthrough">WalkThrough</h2>
+
+#### reference:`WalkThrough`
+
+- collection of static `methods` to walktrhough things, instead of regular looping;
+- usefull to iterator that might be modified during iteration;
+- mostlikely to be less performant, but with better result clarity;
+
+#### reference:`WalkThrough.set`
+
+- method helper to WalkThrough `Set`;
+
+```js
+/**
+ * @template VAL
+ * @param {Set<VAL>} setInstance
+ * @param {(value:VAL)=>void} callback
+ * @returns {void}
+ */
+```
+
+- <i>example</i>:
+
+```js
+import { WalkThrough } from "vivth";
+
+WalkThrough.set(setOfSomething, (value) => {
+  // code
+});
+```
+
+#### reference:`WalkThrough.map`
+
+- method helper to WalkThrough `Map`;
+
+```js
+/**
+ * @template KEY, VAL
+ * @param {Map<KEY, VAL>} mapInstance
+ * @param {(res:[key: KEY, value: VAL]) => void} callback
+ * @returns {void}
+ */
+```
+
+- <i>example</i>:
+
+```js
+import { WalkThrough } from "vivth";
+
+WalkThrough.map(mapOfSomething, ([key, value]) => {
+  // code
+});
+```
+
+#### reference:`WalkThrough.array`
+
+- method helper to WalkThrough `Array`;
+
+```js
+/**
+ * @template VAL
+ * @param {VAL[]} arrayInstance
+ * @param {(res:[value: VAL, index: number]) => void} callback
+ * @returns {void}
+ */
+```
+
+- <i>example</i>:
+
+```js
+import { WalkThrough } from "vivth";
+
+WalkThrough.array(arrayOfSomething, ([value, index]) => {
+  // code
+});
+```
+
+#### reference:`WalkThrough.generator`
+
+- method helper to WalkThrough `Generator`;
+
+```js
+/**
+ * @template T
+ * @param {Generator<T, any, any>} generatorInstance
+ * @param {(value: T) => void} callback
+ * @returns {void}
+ */
+```
+
+- <i>example</i>:
+
+```js
+import { WalkThrough } from "vivth";
+
+WalkThrough.generator(generatorOfSomething, (value) => {
+  // code
+});
+```
+
+\*) <sub>[go to list of exported API and typehelpers](#list-of-exported-api-and-typehelpers)</sub>
+
 <h2 id="workermainthread">WorkerMainThread</h2>
 
 #### reference:`WorkerMainThread`
@@ -2681,6 +2813,37 @@ await Base64URLFromFile(join(Paths.root, "/path/to/file"));
 
 \*) <sub>[go to list of exported API and typehelpers](#list-of-exported-api-and-typehelpers)</sub>
 
+<h2 id="createstringid">CreateStringID</h2>
+
+#### reference:`CreateStringID`
+
+- function helper to generate absolute unique ID;
+- the asynchrounous nature is to prevent race condition that might resulting same Id being generated;
+  > - queued using QChannel;
+
+```js
+/**
+ * @param {string} [prefix]
+ * @returns {ReturnType<typeof TryAsync<string>>}
+ */
+```
+
+- <i>example</i>:
+
+```js
+import { CreateStringID } from "vivth";
+
+(async () => {
+  const [myUniqueID, errorCreatingUniqueID] = await CreateStringID("myPrefix");
+  if (errorCreatingUniqueID) {
+    return;
+  }
+  Console.log(myUniqueID); // `myPrefix${Date.now()}`
+})();
+```
+
+\*) <sub>[go to list of exported API and typehelpers](#list-of-exported-api-and-typehelpers)</sub>
+
 <h2 id="dev">Dev</h2>
 
 #### reference:`Dev`
@@ -3134,13 +3297,13 @@ test();
 import { Try } from "vivth";
 
 const [[key, result], error] = await Try({
-  someRuntime: async (prevError) => {
+  someRuntime: async ({ prevError }) => {
     // asuming on this one doesn't naturally throw error,
     // yet you need to continue to next key,
     // instead of returning,
     // you should throw new Error(something);
   },
-  browser: async (prevError) => {
+  browser: async ({ prevError }) => {
     return location?.origin;
     // if no error, stop other key function from running;
     // key = 'browser'
@@ -3149,7 +3312,7 @@ const [[key, result], error] = await Try({
     // if error;
     // run nodeOrBun;
   },
-  nodeOrBun: async (prevError) => {
+  nodeOrBun: async ({ prevError }) => {
     return process?.env?.INIT_CWD ?? process?.cwd();
     // if no error;
     // key = 'nodeOrBun'

package/index.mjs

@@ -26,11 +26,13 @@ export { QChannel } from './src/class/QChannel.mjs';
 export { SafeExit } from './src/class/SafeExit.mjs';
 export { Setup } from './src/class/Setup.mjs';
 export { Signal } from './src/class/Signal.mjs';
+export { WalkThrough } from './src/class/WalkThrough.mjs';
 export { WorkerMainThread } from './src/class/WorkerMainThread.mjs';
 export { WorkerResult } from './src/class/WorkerResult.mjs';
 export { WorkerThread } from './src/class/WorkerThread.mjs';
 export { Base64URL } from './src/common/Base64URL.mjs';
 export { Base64URLFromFile } from './src/common/Base64URLFromFile.mjs';
+export { CreateStringID } from './src/common/CreateStringID.mjs';
 export { Dev } from './src/common/Dev.mjs';
 export { EventNameSpace } from './src/common/EventNameSpace.mjs';
 export { Trace } from './src/common/Trace.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "vivth",
-	"version": "1.3.5",
+	"version": "1.3.7",
 	"description": "library primitives",
 	"main": "index.mjs",
 	"types": "./types/index.d.mts",

package/src/class/Effect.mjs

@@ -1,6 +1,7 @@
 // @ts-check
 
 import { unwrapLazy } from '../common/lazie.mjs';
+import { WalkThrough } from './WalkThrough.mjs';
 import { LazyFactory } from '../function/LazyFactory.mjs';
 import { Timeout } from '../function/Timeout.mjs';
 import { TryAsync } from '../function/TryAsync.mjs';
@@ -8,9 +9,9 @@ import { Console } from './Console.mjs';
 import { Signal } from './Signal.mjs';
 
 /**
- * @type {Set<Effect>}
+ * @type {Map<Effect, Set<Signal<any>>>}
  */
-export const setOfEffects = new Set();
+export const mapOfEffects = new Map();
 
 /**
  * @description
@@ -68,9 +69,10 @@ export class Effect {
 			/**
 			 * @instance options
 			 * @description
+			 * - subscribe to `Signal_instance`;
 			 * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
 			 * @template V
-			 * @param {Signal<V>} signal
+			 * @param {Signal<V>} signalInstance
 			 * @returns {Signal<V>}
 			 * @example
 			 * import { Effect } from 'vivth';
@@ -80,13 +82,13 @@ export class Effect {
 			 * })
 			 * effect.options.subscribe(signalInstance);
 			 */
-			subscribe: (signal) => {
-				if (signal instanceof Signal === false) {
+			subscribe: (signalInstance) => {
+				if (signalInstance instanceof Signal === false) {
 					// @ts-expect-error
-					signal = signal[unwrapLazy]();
+					signalInstance = signalInstance[unwrapLazy]();
 				}
-				signal.subscribers.setOf.add(this_);
-				return signal;
+				signalInstance.subscribers.setOf.add(this_);
+				return signalInstance;
 			},
 			/**
 			 * @instance options
@@ -102,7 +104,44 @@ export class Effect {
 			 * effect.options.removeEffect();
 			 */
 			removeEffect: () => {
-				setOfEffects.delete(this);
+				const setOfSignal = mapOfEffects.get(this);
+				if (!setOfSignal) {
+					return;
+				}
+				WalkThrough.set(setOfSignal, (signalInstance) => {
+					this.options.removeSignal(signalInstance);
+				});
+				mapOfEffects.delete(this);
+			},
+			/**
+			 * @description
+			 * - remove inputed signal from this `Effect_instance`;
+			 * - if effect signal has no other `Signal_instance` to listen to, it will then completely rendered non reactive;
+			 * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
+			 * @param {Signal<any>} signalInstance
+			 * @returns {void}
+			 * @example
+			 * import { Effect, Signal } from 'vivth';
+			 *
+			 * const count = new Signal(0);
+			 * const effect = new Effect(async ({ subscribe }) => {
+			 * 	console.log(subscribe(count).value); // will subscribe  count changes;
+			 * })
+			 * count.value++; // will increase the count and trigger effect;
+			 * effect.options.removeSignal(count);
+			 * count.value++; // will increase the count but will no longer trigger effect;
+			 */
+			removeSignal: (signalInstance) => {
+				signalInstance.subscribers.setOf.delete(this);
+				const setOfSignal = mapOfEffects.get(this);
+				if (!setOfSignal) {
+					return;
+				}
+				setOfSignal.delete(signalInstance);
+				if (setOfSignal.size) {
+					return;
+				}
+				mapOfEffects.delete(this);
 			},
 		};
 	});
@@ -130,7 +169,7 @@ export class Effect {
 	 */
 	constructor(effect) {
 		this.#effect = effect;
-		setOfEffects.add(this);
+		mapOfEffects.set(this, new Set());
 		this.run();
 	}
 	/**
@@ -156,6 +195,13 @@ export class Effect {
 	 */
 	run = () => {
 		TryAsync(async () => {
+			if (
+				//
+				!mapOfEffects.has(this)
+			) {
+				this.options.removeEffect();
+				return;
+			}
 			await this.#effect(this.options[unwrapLazy]());
 		}).then(([, error]) => {
 			if (error === undefined) {

package/src/class/EventSignal.mjs

@@ -27,7 +27,7 @@ export class EventSignal {
 	/**
 	 * @type {QChannel<string>}
 	 */
-	static #qChannelEventSignal = new QChannel('EventSignal');
+	static #qChannelEventSignal = LazyFactory(() => new QChannel('EventSignal'));
 	/**
 	 * @description
 	 * - the constructor it self is set to `private`;
@@ -114,6 +114,7 @@ export class EventSignal {
 	 */
 	listen = LazyFactory(() => {
 		const dispatch = this.dispatch;
+		// @ts-expect-error
 		const _ = dispatch.value;
 		if (this.#isList) {
 			return new ListDerived(async ({ subscribe }) => {

package/src/class/FileSafe.mjs

@@ -22,7 +22,7 @@ export class FileSafe {
 	 * import { join } from 'node:path';
 	 * import { FileSafe, Paths } from 'vivth';
 	 *
-	 * const [, error] = await FileSafe.write(
+	 * const [, error] = await FileSafe.exist(
 	 * 	join(Paths.root, '/some/path.mjs'),
 	 * );
 	 * if (!error) {

package/src/class/LitExp.mjs

@@ -209,11 +209,6 @@ export class LitExp {
 			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;

package/src/class/QChannel.mjs

@@ -114,7 +114,7 @@ export class QChannel {
 			 * - blocks execution for subsequent calls until the current one finishes.
 			 * @template RESULT
 			 * @param {()=>Promise<RESULT>} asyncCallback
-			 * @returns {Promise<[RESULT|undefined, Error|undefined]>}
+			 * @returns {ReturnType<typeof TryAsync<RESULT>>}
 			 * @example
 			 * const [result, error] = await QChannel.fifo.callback(async () = > {
 			 * 	// code

package/src/class/SafeExit.mjs

@@ -2,8 +2,9 @@
 
 import { TryAsync } from '../function/TryAsync.mjs';
 import { TrySync } from '../function/TrySync.mjs';
+import { WalkThrough } from './WalkThrough.mjs';
 import { Console } from './Console.mjs';
-import { Effect, setOfEffects } from './Effect.mjs';
+import { Effect, mapOfEffects } from './Effect.mjs';
 import { EnvSignal } from './EnvSignal.mjs';
 import { setOFSignals } from './Signal.mjs';
 
@@ -150,6 +151,7 @@ export class SafeExit {
 	 * @type {()=>void}
 	 */
 	#exit = () => {};
+	// @ts-expect-error
 	#autoCleanUp = new Effect(async ({ subscribe }) => {
 		if (
 			//
@@ -157,10 +159,10 @@ export class SafeExit {
 		) {
 			return;
 		}
-		setOFSignals.forEach((signal) => {
+		WalkThrough.set(setOFSignals, (signal) => {
 			signal.remove.ref();
 		});
-		setOfEffects.forEach((effect) => {
+		WalkThrough.map(mapOfEffects, ([effect, _]) => {
 			effect.options.removeEffect();
 		});
 		for await (const cleanup of safeCleanUpCBs) {

package/src/class/Signal.mjs

@@ -1,10 +1,11 @@
 // @ts-check
 
+import { WalkThrough } from './WalkThrough.mjs';
 import { LazyFactory } from '../function/LazyFactory.mjs';
 import { TryAsync } from '../function/TryAsync.mjs';
 import { TrySync } from '../function/TrySync.mjs';
 import { Console } from './Console.mjs';
-import { Effect, setOfEffects } from './Effect.mjs';
+import { Effect, mapOfEffects } from './Effect.mjs';
 
 /**
  * @type {Set<Signal<any>>}
@@ -65,7 +66,7 @@ export class Signal {
 		 */
 		notify: (callback = undefined) => {
 			if (callback === undefined) {
-				Signal.#notify(this.subscribers.setOf);
+				Signal.#notify(this);
 				return;
 			}
 			TryAsync(async () => {
@@ -75,25 +76,27 @@ export class Signal {
 					Console.error({ message: 'unable to run callback', callback, error });
 					return;
 				}
-				Signal.#notify(this.subscribers.setOf);
+				Signal.#notify(this);
 			});
 		},
 	}));
 	/**
-	 * @param {Set<Effect>} setOfSubscribers
+	 * @param {Signal<any>} signalInstance
 	 */
-	static #notify = (setOfSubscribers) => {
+	static #notify = (signalInstance) => {
 		const [, error] = TrySync(() => {
-			const effects = setOfSubscribers;
-			effects.forEach((effect) => {
-				if (setOfEffects.has(effect) === false) {
-					effects.delete(effect);
+			WalkThrough.set(signalInstance.subscribers.setOf, (effectInstance) => {
+				if (
+					//
+					!mapOfEffects.has(effectInstance)
+				) {
+					effectInstance.options.removeSignal(signalInstance);
 					return;
 				}
 				/**
-				 * effect.run is already TryAsync
+				 * effect.run is already wrapped with TryAsync
 				 */
-				effect.run();
+				effectInstance.run();
 			});
 		});
 		if (error === undefined) {
@@ -118,7 +121,7 @@ export class Signal {
 			 * this part is not needed, as the effect might need to react to other signals
 			// effectInstance.options.removeEffect();
 			 */
-			this.subscribers.setOf.delete(effectInstance);
+			effectInstance.options.removeSignal(this);
 		},
 		/**
 		 * @instance remove
@@ -127,8 +130,9 @@ export class Signal {
 		 * @type {()=>void}
 		 */
 		allSubscribers: () => {
-			const $ = this.subscribers.setOf;
-			$.forEach(this.remove.subscriber);
+			WalkThrough.set(this.subscribers.setOf, (effectInstance) => {
+				this.remove.subscriber(effectInstance);
+			});
 		},
 		/**
 		 * @instance remove

package/src/class/WalkThrough.mjs

@@ -0,0 +1,90 @@
+// @ts-check
+
+/**
+ * @description
+ * - collection of static `methods` to walktrhough things, instead of regular looping;
+ * - usefull to iterator that might be modified during iteration;
+ * - mostlikely to be less performant, but with better result clarity;
+ */
+export class WalkThrough {
+	/**
+	 * @param {Iterator<any, any, any>} iterator
+	 * @param {(...any:any[])=>void} callback
+	 * @returns {void}
+	 */
+	static #handler = (iterator, callback) => {
+		let result = iterator.next();
+		while (!result.done) {
+			callback(result.value);
+			result = iterator.next();
+		}
+	};
+	/**
+	 * @description
+	 * - method helper to WalkThrough `Set`;
+	 * @template VAL
+	 * @param {Set<VAL>} setInstance
+	 * @param {(value:VAL)=>void} callback
+	 * @returns {void}
+	 * @example
+	 * import { WalkThrough } from 'vivth';
+	 *
+	 * WalkThrough.set(setOfSomething, (value) => {
+	 * 	// code
+	 * })
+	 */
+	static set(setInstance, callback) {
+		WalkThrough.#handler(setInstance.values(), callback);
+	};
+	/**
+	 * @description
+	 * - method helper to WalkThrough `Map`;
+	 * @template KEY, VAL
+	 * @param {Map<KEY, VAL>} mapInstance
+	 * @param {(res:[key: KEY, value: VAL]) => void} callback
+	 * @returns {void}
+	 * @example
+	 * import { WalkThrough } from 'vivth';
+	 *
+	 * WalkThrough.map(mapOfSomething, ([key, value]) => {
+	 * 	// code
+	 * })
+	 */
+	static map(mapInstance, callback) {
+		WalkThrough.#handler(mapInstance.entries(), callback);
+	};
+	/**
+	 * @description
+	 * - method helper to WalkThrough `Array`;
+	 * @template VAL
+	 * @param {VAL[]} arrayInstance
+	 * @param {(res:[value: VAL, index: number]) => void} callback
+	 * @returns {void}
+	 * @example
+	 * import { WalkThrough } from 'vivth';
+	 *
+	 * WalkThrough.array(arrayOfSomething, ([value, index]) => {
+	 * 	// code
+	 * })
+	 */
+	static array(arrayInstance, callback) {
+		WalkThrough.#handler(arrayInstance.values(), callback);
+	};
+	/**
+	 * @description
+	 * - method helper to WalkThrough `Generator`;
+	 * @template T
+	 * @param {Generator<T, any, any>} generatorInstance
+	 * @param {(value: T) => void} callback
+	 * @returns {void}
+	 * @example
+	 * import { WalkThrough } from 'vivth';
+	 *
+	 * WalkThrough.generator(generatorOfSomething, (value) => {
+	 * 	// code
+	 * })
+	 */
+	static generator(generatorInstance, callback) {
+		WalkThrough.#handler(generatorInstance, callback);
+	};
+}

package/src/common/CreateStringID.mjs

@@ -0,0 +1,33 @@
+// @ts-check
+
+import { QChannel } from '../class/QChannel.mjs';
+import { LazyFactory } from '../function/LazyFactory.mjs';
+import { Timeout } from '../function/Timeout.mjs';
+import { TryAsync } from '../function/TryAsync.mjs';
+
+const qchannel = LazyFactory(() => new QChannel('CreateStringID'));
+
+/**
+ * @description
+ * - function helper to generate absolute unique ID;
+ * - the asynchrounous nature is to prevent race condition that might resulting same Id being generated;
+ * >- queued using QChannel;
+ * @param {string} [prefix]
+ * @returns {ReturnType<typeof TryAsync<string>>}
+ * @example
+ * import { CreateStringID } from 'vivth';
+ *
+ * (async () => {
+ * 	const [myUniqueID, errorCreatingUniqueID] = await CreateStringID('myPrefix');
+ * 	if(errorCreatingUniqueID) {
+ * 		return;
+ * 	}
+ * 	Console.log(myUniqueID); // `myPrefix${Date.now()}`
+ * })()
+ */
+export async function CreateStringID(prefix = '') {
+	return await qchannel.callback('newStringID', async () => {
+		await Timeout(1);
+		return `${prefix}${Date.now()}`;
+	});
+}

package/src/doc/JSautoDOC.mjs

@@ -186,6 +186,7 @@ export class JSautoDOC {
 	 * @type {Signal<string>}
 	 */
 	#readMESRCContent = LazyFactory(() => new Signal(''));
+	// @ts-expect-error
 	#generatedREADME_md = new Effect(async ({ subscribe, isLastCalled }) => {
 		const contentSRC = subscribe(this.#readMESRCContent).value;
 		const filepaths = subscribe(this.#filePaths).value;

package/src/function/EventObject.mjs

@@ -1,4 +1,5 @@
 // @ts-check
+
 import { EventNameSpace } from '../common/EventNameSpace.mjs';
 
 /**

package/src/function/GetNamedImportAlias.mjs

@@ -1,7 +1,5 @@
 // @ts-check
 
-import { Console } from '../class/Console.mjs';
-
 /**
  * @description
  * - regex helper for:

package/src/function/Try.mjs

@@ -1,6 +1,5 @@
 // @ts-check
 
-import { Console } from '../class/Console.mjs';
 import { TryAsync } from './TryAsync.mjs';
 
 /**
@@ -25,13 +24,13 @@ import { TryAsync } from './TryAsync.mjs';
  * import { Try } from 'vivth';
  *
  * const [[key, result], error] = await Try({
- * 	someRuntime: async ( prevError ) => {
+ * 	someRuntime: async ({ prevError }) => {
  * 		// asuming on this one doesn't naturally throw error,
  * 		// yet you need to continue to next key,
  * 		// instead of returning,
  * 		// you should throw new Error(something);
  * 	},
- * 	browser: async ( prevError ) => {
+ * 	browser: async ({ prevError }) => {
  * 		return location?.origin;
  * 		// if no error, stop other key function from running;
  * 		// key = 'browser'
@@ -40,7 +39,7 @@ import { TryAsync } from './TryAsync.mjs';
  * 		// if error;
  * 		// run nodeOrBun;
  * 	},
- * 	nodeOrBun: async ( prevError ) => {
+ * 	nodeOrBun: async ({ prevError }) => {
  * 		return process?.env?.INIT_CWD ?? process?.cwd();
  * 		// if no error;
  * 		// key = 'nodeOrBun'

package/tsconfig.json

@@ -28,7 +28,7 @@
 		"noImplicitOverride": true,
 
 		// Some stricter flags (disabled by default)
-		"noUnusedLocals": false,
+		"noUnusedLocals": true,
 		"noUnusedParameters": false,
 		"noPropertyAccessFromIndexSignature": false
 	},

package/types/index.d.mts

@@ -18,11 +18,13 @@ export { QChannel } from "./src/class/QChannel.mjs";
 export { SafeExit } from "./src/class/SafeExit.mjs";
 export { Setup } from "./src/class/Setup.mjs";
 export { Signal } from "./src/class/Signal.mjs";
+export { WalkThrough } from "./src/class/WalkThrough.mjs";
 export { WorkerMainThread } from "./src/class/WorkerMainThread.mjs";
 export { WorkerResult } from "./src/class/WorkerResult.mjs";
 export { WorkerThread } from "./src/class/WorkerThread.mjs";
 export { Base64URL } from "./src/common/Base64URL.mjs";
 export { Base64URLFromFile } from "./src/common/Base64URLFromFile.mjs";
+export { CreateStringID } from "./src/common/CreateStringID.mjs";
 export { Dev } from "./src/common/Dev.mjs";
 export { EventNameSpace } from "./src/common/EventNameSpace.mjs";
 export { Trace } from "./src/common/Trace.mjs";

package/types/src/class/Effect.d.mts

@@ -1,7 +1,7 @@
 /**
- * @type {Set<Effect>}
+ * @type {Map<Effect, Set<Signal<any>>>}
  */
-export const setOfEffects: Set<Effect>;
+export const mapOfEffects: Map<Effect, Set<Signal<any>>>;
 /**
  * @description
  * - a class for creating effect;
@@ -70,9 +70,10 @@ export class Effect {
         /**
          * @instance options
          * @description
+         * - subscribe to `Signal_instance`;
          * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
          * @template V
-         * @param {Signal<V>} signal
+         * @param {Signal<V>} signalInstance
          * @returns {Signal<V>}
          * @example
          * import { Effect } from 'vivth';
@@ -82,7 +83,7 @@ export class Effect {
          * })
          * effect.options.subscribe(signalInstance);
          */
-        subscribe: <V>(signal: Signal<V>) => Signal<V>;
+        subscribe: <V>(signalInstance: Signal<V>) => Signal<V>;
         /**
          * @instance options
          * @description
@@ -97,6 +98,25 @@ export class Effect {
          * effect.options.removeEffect();
          */
         removeEffect: () => void;
+        /**
+         * @description
+         * - remove inputed signal from this `Effect_instance`;
+         * - if effect signal has no other `Signal_instance` to listen to, it will then completely rendered non reactive;
+         * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
+         * @param {Signal<any>} signalInstance
+         * @returns {void}
+         * @example
+         * import { Effect, Signal } from 'vivth';
+         *
+         * const count = new Signal(0);
+         * const effect = new Effect(async ({ subscribe }) => {
+         * 	console.log(subscribe(count).value); // will subscribe  count changes;
+         * })
+         * count.value++; // will increase the count and trigger effect;
+         * effect.options.removeSignal(count);
+         * count.value++; // will increase the count but will no longer trigger effect;
+         */
+        removeSignal: (signalInstance: Signal<any>) => void;
     } & {
         "vivth:unwrapLazy;": () => {
             /**
@@ -126,9 +146,10 @@ export class Effect {
             /**
              * @instance options
              * @description
+             * - subscribe to `Signal_instance`;
              * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
              * @template V
-             * @param {Signal<V>} signal
+             * @param {Signal<V>} signalInstance
              * @returns {Signal<V>}
              * @example
              * import { Effect } from 'vivth';
@@ -138,7 +159,7 @@ export class Effect {
              * })
              * effect.options.subscribe(signalInstance);
              */
-            subscribe: <V>(signal: Signal<V>) => Signal<V>;
+            subscribe: <V>(signalInstance: Signal<V>) => Signal<V>;
             /**
              * @instance options
              * @description
@@ -153,6 +174,25 @@ export class Effect {
              * effect.options.removeEffect();
              */
             removeEffect: () => void;
+            /**
+             * @description
+             * - remove inputed signal from this `Effect_instance`;
+             * - if effect signal has no other `Signal_instance` to listen to, it will then completely rendered non reactive;
+             * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
+             * @param {Signal<any>} signalInstance
+             * @returns {void}
+             * @example
+             * import { Effect, Signal } from 'vivth';
+             *
+             * const count = new Signal(0);
+             * const effect = new Effect(async ({ subscribe }) => {
+             * 	console.log(subscribe(count).value); // will subscribe  count changes;
+             * })
+             * count.value++; // will increase the count and trigger effect;
+             * effect.options.removeSignal(count);
+             * count.value++; // will increase the count but will no longer trigger effect;
+             */
+            removeSignal: (signalInstance: Signal<any>) => void;
         };
     };
     /**

package/types/src/class/FileSafe.d.mts

@@ -14,7 +14,7 @@ export class FileSafe {
      * import { join } from 'node:path';
      * import { FileSafe, Paths } from 'vivth';
      *
-     * const [, error] = await FileSafe.write(
+     * const [, error] = await FileSafe.exist(
      * 	join(Paths.root, '/some/path.mjs'),
      * );
      * if (!error) {

package/types/src/class/LitExp.d.mts

@@ -90,11 +90,6 @@ export class LitExp<KEYS extends import("../types/LitExpKeyType.mjs").LitExpKeyT
      * @param {...(keyof KEYS)} values
      */
     private constructor();
-    /**
-     * @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;

package/types/src/class/QChannel.d.mts

@@ -56,13 +56,13 @@ export class QChannel<DEFINEDANY extends import("../types/AnyButUndefined.mjs").
          * - blocks execution for subsequent calls until the current one finishes.
          * @template RESULT
          * @param {()=>Promise<RESULT>} asyncCallback
-         * @returns {Promise<[RESULT|undefined, Error|undefined]>}
+         * @returns {ReturnType<typeof TryAsync<RESULT>>}
          * @example
          * const [result, error] = await QChannel.fifo.callback(async () = > {
          * 	// code
          * })
          */
-        callback: <RESULT>(asyncCallback: () => Promise<RESULT>) => Promise<[RESULT | undefined, Error | undefined]>;
+        callback: <RESULT>(asyncCallback: () => Promise<RESULT>) => ReturnType<typeof TryAsync<RESULT>>;
     } & {
         "vivth:unwrapLazy;": () => {
             /**
@@ -82,13 +82,13 @@ export class QChannel<DEFINEDANY extends import("../types/AnyButUndefined.mjs").
              * - blocks execution for subsequent calls until the current one finishes.
              * @template RESULT
              * @param {()=>Promise<RESULT>} asyncCallback
-             * @returns {Promise<[RESULT|undefined, Error|undefined]>}
+             * @returns {ReturnType<typeof TryAsync<RESULT>>}
              * @example
              * const [result, error] = await QChannel.fifo.callback(async () = > {
              * 	// code
              * })
              */
-            callback: <RESULT>(asyncCallback: () => Promise<RESULT>) => Promise<[RESULT | undefined, Error | undefined]>;
+            callback: <RESULT>(asyncCallback: () => Promise<RESULT>) => ReturnType<typeof TryAsync<RESULT>>;
         };
     };
     /**

package/types/src/class/Signal.d.mts

@@ -9,9 +9,9 @@ export const setOFSignals: Set<Signal<any>>;
  */
 export class Signal<VALUE> {
     /**
-     * @param {Set<Effect>} setOfSubscribers
+     * @param {Signal<any>} signalInstance
      */
-    static #notify: (setOfSubscribers: Set<Effect>) => void;
+    static #notify: (signalInstance: Signal<any>) => void;
     /**
      * @description
      * - create a `Signal`;

package/types/src/class/WalkThrough.d.mts

@@ -0,0 +1,74 @@
+/**
+ * @description
+ * - collection of static `methods` to walktrhough things, instead of regular looping;
+ * - usefull to iterator that might be modified during iteration;
+ * - mostlikely to be less performant, but with better result clarity;
+ */
+export class WalkThrough {
+    /**
+     * @param {Iterator<any, any, any>} iterator
+     * @param {(...any:any[])=>void} callback
+     * @returns {void}
+     */
+    static #handler: (iterator: Iterator<any, any, any>, callback: (...any: any[]) => void) => void;
+    /**
+     * @description
+     * - method helper to WalkThrough `Set`;
+     * @template VAL
+     * @param {Set<VAL>} setInstance
+     * @param {(value:VAL)=>void} callback
+     * @returns {void}
+     * @example
+     * import { WalkThrough } from 'vivth';
+     *
+     * WalkThrough.set(setOfSomething, (value) => {
+     * 	// code
+     * })
+     */
+    static set<VAL>(setInstance: Set<VAL>, callback: (value: VAL) => void): void;
+    /**
+     * @description
+     * - method helper to WalkThrough `Map`;
+     * @template KEY, VAL
+     * @param {Map<KEY, VAL>} mapInstance
+     * @param {(res:[key: KEY, value: VAL]) => void} callback
+     * @returns {void}
+     * @example
+     * import { WalkThrough } from 'vivth';
+     *
+     * WalkThrough.map(mapOfSomething, ([key, value]) => {
+     * 	// code
+     * })
+     */
+    static map<KEY, VAL>(mapInstance: Map<KEY, VAL>, callback: (res: [key: KEY, value: VAL]) => void): void;
+    /**
+     * @description
+     * - method helper to WalkThrough `Array`;
+     * @template VAL
+     * @param {VAL[]} arrayInstance
+     * @param {(res:[value: VAL, index: number]) => void} callback
+     * @returns {void}
+     * @example
+     * import { WalkThrough } from 'vivth';
+     *
+     * WalkThrough.array(arrayOfSomething, ([value, index]) => {
+     * 	// code
+     * })
+     */
+    static array<VAL>(arrayInstance: VAL[], callback: (res: [value: VAL, index: number]) => void): void;
+    /**
+     * @description
+     * - method helper to WalkThrough `Generator`;
+     * @template T
+     * @param {Generator<T, any, any>} generatorInstance
+     * @param {(value: T) => void} callback
+     * @returns {void}
+     * @example
+     * import { WalkThrough } from 'vivth';
+     *
+     * WalkThrough.generator(generatorOfSomething, (value) => {
+     * 	// code
+     * })
+     */
+    static generator<T>(generatorInstance: Generator<T, any, any>, callback: (value: T) => void): void;
+}

package/types/src/common/CreateStringID.d.mts

@@ -0,0 +1,20 @@
+/**
+ * @description
+ * - function helper to generate absolute unique ID;
+ * - the asynchrounous nature is to prevent race condition that might resulting same Id being generated;
+ * >- queued using QChannel;
+ * @param {string} [prefix]
+ * @returns {ReturnType<typeof TryAsync<string>>}
+ * @example
+ * import { CreateStringID } from 'vivth';
+ *
+ * (async () => {
+ * 	const [myUniqueID, errorCreatingUniqueID] = await CreateStringID('myPrefix');
+ * 	if(errorCreatingUniqueID) {
+ * 		return;
+ * 	}
+ * 	Console.log(myUniqueID); // `myPrefix${Date.now()}`
+ * })()
+ */
+export function CreateStringID(prefix?: string): ReturnType<typeof TryAsync<string>>;
+import { TryAsync } from '../function/TryAsync.mjs';

package/types/src/function/Try.d.mts

@@ -20,13 +20,13 @@
  * import { Try } from 'vivth';
  *
  * const [[key, result], error] = await Try({
- * 	someRuntime: async ( prevError ) => {
+ * 	someRuntime: async ({ prevError }) => {
  * 		// asuming on this one doesn't naturally throw error,
  * 		// yet you need to continue to next key,
  * 		// instead of returning,
  * 		// you should throw new Error(something);
  * 	},
- * 	browser: async ( prevError ) => {
+ * 	browser: async ({ prevError }) => {
  * 		return location?.origin;
  * 		// if no error, stop other key function from running;
  * 		// key = 'browser'
@@ -35,7 +35,7 @@
  * 		// if error;
  * 		// run nodeOrBun;
  * 	},
- * 	nodeOrBun: async ( prevError ) => {
+ * 	nodeOrBun: async ({ prevError }) => {
  * 		return process?.env?.INIT_CWD ?? process?.cwd();
  * 		// if no error;
  * 		// key = 'nodeOrBun'

package/types/dev/fsInline.d.mts

@@ -1 +0,0 @@
-export {};

package/types/dev/index.d.mts

@@ -1 +0,0 @@
-export {};

package/types/dev/test.d.mts

@@ -1 +0,0 @@
-export {};

package/types/dev/testWorker.d.mts

@@ -1,7 +0,0 @@
-/**
- * @type {WorkerThread<{a:number}, number>}
- */
-export const testWorker: WorkerThread<{
-    a: number;
-}, number>;
-import { WorkerThread } from '../index.mjs';

package/types/dev/testbundle.d.mts

@@ -1 +0,0 @@
-export {};

package/types/dev/workerThreadClass.d.mts

@@ -1,13 +0,0 @@
-/**
- * @description
- * `workerThreadClass` description placeholder;
- */
-export const workerThreadClass: {
-    new (handler: (ev: any, isLastOnQ: () => boolean) => any): WorkerThread<any, any>;
-    #refs: Parameters<(typeof WorkerThread)["setup"]>[0] | undefined;
-    setup<RECEIVE, POST>(refs: {
-        parentPort: typeof import("worker_threads")["parentPort"];
-    }): typeof WorkerThread<RECEIVE, POST>;
-    #isCloseWorkerEvent: (ev: any) => boolean;
-};
-import { WorkerThread } from '../index.mjs';

package/types/src/function/WithDefer.d.mts

@@ -1,10 +0,0 @@
-/**
- * Description
- * @param {(
- * this:{defer:(tobeDefered:()=>Promise<void>)=>void}
- * )=>Promise<void>} cb
- * @returns {void}
- */
-export function WithDefer(cb: (this: {
-    defer: (tobeDefered: () => Promise<void>) => void;
-}) => Promise<void>): void;

package/types/src/types/IsDevCBStringType.d.mts

@@ -1,4 +0,0 @@
-/**
- * - closing helper for `Dev.IsDevCB`;
- */
-export type IsDevCBStringType = "IsDevCB";