vivth 1.4.10 → 1.5.0

package/src/class/Setup.mjs

@@ -4,6 +4,8 @@ import { SafeExit } from './SafeExit.mjs';
 import { Paths } from './Paths.mjs';
 import { WorkerMainThread } from './WorkerMainThread.mjs';
 import { WorkerThread } from './WorkerThread.mjs';
+import { EnvMode } from '../common/EnvMode.mjs';
+import { Preferrence } from '../common/Preferrence.mjs';
 
 /**
  * @description
@@ -14,27 +16,16 @@ export class Setup {
 	 * @description
 	 * - proxy `SafeExit_instance` for Setup
 	 * @example
-	 * import { Setup, Console } from 'vivth';
+	 * import { Setup } from 'vivth/node';
 	 *
-	 * new Setup.safeExit({
-	 * 	// eventNames are blank by default, you need to manually name them all;
-	 * 	// 'exit' will be omited, as it might cause async callbacks failed to execute;
-	 * 	eventNames: ['SIGINT', 'SIGTERM', ...eventNames],
-	 * 	terminator : () => process.exit(0),
-	 * 	listener : (eventName) => {
-	 * 			process.once(eventName, function () {
-	 * 				SafeExit.instance?.exiting.correction(true);
-	 * 				Console.log(`safe exit via "${eventName}"`);
-	 * 			});
-	 * 	}
-	 * });
+	 * new Setup.safeExit('SIGINT', 'SIGTERM', ...eventNames);
 	 */
 	static safeExit = SafeExit;
 	/**
 	 * @description
 	 * - proxy `Paths_instance` for Setup;
 	 * @example
-	 * import { Setup } from 'vivth';
+	 * import { Setup } from 'vivth/node';
 	 *
 	 * new Setup.paths({
 	 * 	root: location.origin, // browser example
@@ -45,7 +36,7 @@ export class Setup {
 	 * @description
 	 * - proxy `WorkerMainThread_instance` for Setup;
 	 * @example
-	 * import { Setup } from 'vivth';
+	 * import { Setup } from 'vivth/node';
 	 * import { Worker } from 'node:worker_threads';
 	 *
 	 * Setup.workerMain({
@@ -64,7 +55,7 @@ export class Setup {
 	 * - correct `parentPort` reference when needed;
 	 * - export to create new reference to be use to create new WorkerThread instance;
 	 * @example
-	 * import { Setup } from 'vivth';
+	 * import { Setup } from 'vivth/node';
 	 * import { parentPort } from 'node:worker_threads';
 	 *
 	 * export const MyWorkerThreadRef = Setup.workerThread({parentPort});
@@ -72,4 +63,25 @@ export class Setup {
 	 * // you need to call this method;
 	 */
 	static workerThread = WorkerThread.setup;
+	/**
+	 * @description
+	 * - setup envMode into `developement`('default') or `production`;
+	 * @example
+	 * import { Setup } from 'vivth/node';
+	 *
+	 * Setup.enforceEnvMode('prod');
+	 *
+	 * // default behaviour, technically only need to be call for reactive functionality;
+	 * Setup.enforceEnvMode('dev');
+	 */
+	static enforceEnvMode = EnvMode.enforce;
+	/**
+	 * @description
+	 * - setup `vivth `preffered encoding;
+	 * @example
+	 * import { Setup } from 'vivth/node';
+	 *
+	 * Setup.preferrence({ encoding: 'utf-8' });
+	 */
+	static preferrence = Preferrence.setup;
 }

package/src/class/Signal.mjs

@@ -6,6 +6,11 @@ import { TryAsync } from '../function/TryAsync.mjs';
 import { TrySync } from '../function/TrySync.mjs';
 import { Console } from './Console.mjs';
 import { Effect, mapOfEffects } from './Effect.mjs';
+import { DataLog } from './DataLog.mjs';
+
+/**
+ * @typedef { import('../typehints/VivthCleanup.mjs').VivthCleanup } VivthCleanup
+ */
 
 /**
  * @type {Set<Signal<any>>}
@@ -16,21 +21,33 @@ export const setOFSignals = new Set();
  * @description
  * - a class for creating effect to signals;
  * @template VALUE
+ * @implements {VivthCleanup}
  */
 export class Signal {
+	vivthCleanup = async () => {
+		this.remove.ref();
+	};
 	/**
 	 * @description
 	 * - create a `Signal`;
 	 * @param {VALUE} value
+	 * @param {(data:DataLog<VALUE>)=>void} [performanceChangesReport]
+	 * - callback independent from effect;
+	 * >- it will always be called when there's value change;
 	 * @example
-	 * import { Signal, Effect } from  'vivth';
+	 * import { Signal, Effect } from 'vivth/neutral';
 	 *
 	 * const count = new Signal(0);
 	 */
-	constructor(value) {
+	constructor(value, performanceChangesReport = undefined) {
 		this.#value = value;
+		this.#performanceChangesReport = performanceChangesReport;
 		setOFSignals.add(this);
 	}
+	/**
+	 * @type {ConstructorParameters<typeof Signal<VALUE>>[1]}
+	 */
+	#performanceChangesReport;
 	/**
 	 * @description
 	 * - subsrcibers reference of this instance;
@@ -48,9 +65,10 @@ export class Signal {
 		 * @description
 		 * - manually notify on non primitive value or value that have depths;
 		 * @param {(options:{signalInstance:Signal<VALUE>})=>Promise<void>} [callback]
-		 * @returns {void}
+		 * @param {(error:Error|undefined)=>Promise<void>} [afterCompletion]
+		 * @returns {Promise<void>}
 		 * @example
-		 * import { Signal } from 'vivth';
+		 * import { Signal } from 'vivth/neutral';
 		 *
 		 * // for deep signal like array or object you can:
 		 * const arraySignal = new Signal([1,2]);
@@ -64,32 +82,41 @@ export class Signal {
 		 * 	signalInstance.value['d'] = 'testd';
 		 * });
 		 */
-		notify: (callback = undefined) => {
+		notify: async (callback = undefined, afterCompletion = undefined) => {
+			if (this.#performanceChangesReport) {
+				this.#performanceChangesReport(new DataLog(this.#value));
+			}
 			if (callback === undefined) {
-				Signal.#notify(this);
+				await Signal.#notify(this, afterCompletion);
 				return;
 			}
-			TryAsync(async () => {
+			const [, errorRunningCallback] = await TryAsync(async () => {
 				await callback({ signalInstance: this });
-			}).then(([, error]) => {
-				if (error) {
-					Console.error({ message: 'unable to run callback', callback, error });
-					return;
-				}
-				Signal.#notify(this);
 			});
+			if (errorRunningCallback) {
+				Console.error({ errorRunningCallback });
+				return;
+			}
+			await Signal.#notify(this, afterCompletion);
 		},
 	}));
 	/**
 	 * @param {Signal<any>} signalInstance
+	 * @param {(error:Error|undefined)=>void} [afterCompletion]
+	 * @returns {Promise<void>}
 	 */
-	static #notify = (signalInstance) => {
-		const [, error] = TrySync(() => {
+	static #notify = async (
+		signalInstance,
+		afterCompletion = async (error) => {
+			if (error === undefined) {
+				return;
+			}
+			Console.error(error);
+		},
+	) => {
+		const [, errorRunningWalkThrough] = TrySync(() => {
 			WalkThrough.set(signalInstance.subscribers.setOf, (effectInstance) => {
-				if (
-					//
-					!mapOfEffects.has(effectInstance)
-				) {
+				if (!mapOfEffects.has(effectInstance)) {
 					effectInstance.options.removeSignal(signalInstance);
 					return;
 				}
@@ -99,10 +126,7 @@ export class Signal {
 				effectInstance.run();
 			});
 		});
-		if (error === undefined) {
-			return;
-		}
-		Console.error(error);
+		afterCompletion(errorRunningWalkThrough);
 	};
 	/**
 	 * @description
@@ -147,7 +171,6 @@ export class Signal {
 			setOFSignals.delete(this);
 		},
 	}));
-
 	/**
 	 * @type {VALUE|undefined}
 	 */
@@ -169,7 +192,7 @@ export class Signal {
 	 * - value after change;
 	 * @returns {VALUE}
 	 * @example
-	 * import { Signal, Effect, Derived } from  'vivth';
+	 * import { Signal, Effect, Derived } from 'vivth/neutral';
 	 *
 	 * const count = new Signal(0);
 	 * count.value; // not reactive
@@ -177,7 +200,7 @@ export class Signal {
 	 * new Effect(async ({ subscribe }) =>{
 	 * 	const countValue = subscribe(count).value; // reactive
 	 * })
-	 * const oneMoreThanCount = new Derived(async ({ subscribe }) =>{
+	 * const oneMoreThanCount = new Derived(async function({ subscribe }){
 	 * 	return subscribe(count).value + 1; // reactive
 	 * })
 	 */
@@ -189,7 +212,7 @@ export class Signal {
 	 * - assign new value then automatically notify all subscribers;
 	 * @type {VALUE}
 	 * @example
-	 * import { Signal } from  'vivth';
+	 * import { Signal } from 'vivth/neutral';
 	 *
 	 * const count = new Signal(0);
 	 * count.value++;

package/src/class/SignalCollection.mjs

@@ -0,0 +1,130 @@
+// @ts-check
+
+import { ForInSync } from '../function/ForInSync.mjs';
+
+/**
+ * @typedef {import('../typehints/VivthCleanup.mjs').VivthCleanup} VivthCleanup
+ */
+
+/**
+ * @description
+ * - class helper for creating Collection of `Signals` for Object of Signals to be subscribed to(on `Effect`/`Derived`) collectively as signals;
+ * >- uses as `Facade` Pattern;
+ * @template {Record<string, import('./Signal.mjs').Signal<any>>} SIGNALS
+ * @implements {VivthCleanup}
+ */
+export class SignalCollection {
+	vivthCleanup = async () => {
+		this.forInSignals((_key, signal) => {
+			signal.remove.ref();
+		});
+	};
+	/**
+	 * @description
+	 * - creates instance of `SignalCollection`, by referencing to named Signal;
+	 * @param {SIGNALS} signalsObject
+	 * @example
+	 * import { Signal, Derived, SignalCollection } from 'vivth/neutral';
+	 *
+	 * const a = new Signal('a');
+	 * const b = new Signal('b');
+	 * const c = new Derived(async ({ subscribe }) => {
+	 * 	return `${subscribe(b).value}_b`;
+	 * });
+	 *
+	 * const f = new SignalCollection({ a, c });
+	 */
+	constructor(signalsObject) {
+		this.#signals = signalsObject;
+	}
+	/**
+	 * @type {SIGNALS}
+	 */
+	#signals;
+	/**
+	 * @description
+	 * - accessor for signals, to be subscribed to;
+	 * @param {import('./Effect.mjs').Effect["options"]["subscribe"]} [subscribe]
+	 * @returns {SIGNALS}
+	 * @example
+	 * import { Signal, Derived, Effect, SignalCollection } from 'vivth/neutral';
+	 *
+	 * const a = new Signal('a');
+	 * const b = new Signal('b');
+	 * const c = new Derived(async ({ subscribe }) => {
+	 * 	return `${subscribe(b).value}_b`;
+	 * });
+	 *
+	 * const f = new SignalCollection({ a, c });
+	 *
+	 * new Effect(async ({ subscribe, isLastCalled }) => {
+	 * 	const {
+	 * 		a: { value: aa }, // aa is safely desctructured and auto subscribed
+	 * 		c: { value: cc }, // cc is safely desctructured and auto subscribed
+	 * 	} = f.signals(subscribe);
+	 * 	if(!await isLastCalled(100)) {
+	 * 		return; // impertaive debounce
+	 * 	}
+	 * });
+	 *
+	 * const d = new Derived(async function({ subscribe, isLastCalled }) {
+	 * 	const {
+	 * 		a: { value: aa }, // aa is safely desctructured and auto subscribed
+	 * 		c: { value: cc }, // cc is safely desctructured and auto subscribed
+	 * 	} = f.signals(subscribe);
+	 * 	if(!await isLastCalled(100)) {
+	 * 		return this.dontUpdate; // impertaive debounce
+	 * 	}
+	 * 	// return something;
+	 * });
+	 */
+	signals = (subscribe = undefined) => {
+		const signals = this.#signals;
+		if (subscribe) {
+			ForInSync(signals, (_key, signal) => {
+				subscribe(signal);
+			});
+		}
+		return signals;
+	};
+	/**
+	 * @description
+	 * - is looping synchronously;
+	 * >- will not await any async block;
+	 * - use for operation that doesn't need the value:
+	 * >- unsub from the signal;
+	 * @template {keyof SIGNALS} K
+	 * @param {(key: K,
+	 * signal: SIGNALS[K]
+	 * )=>void} callback
+	 * @returns {void}
+	 * @example
+	 * import { Signal, Derived, Effect, SignalCollection } from 'vivth/neutral';
+	 *
+	 * const a = new Signal('a');
+	 * const b = new Signal('b');
+	 * const c = new Derived(async ({ subscribe }) => {
+	 * 	return `${subscribe(b).value}_b`;
+	 * });
+	 *
+	 * const f = new SignalCollection({ a, c });
+	 *
+	 * f.forInSignals((key, signal)=>{
+	 * 	// code
+	 * })
+	 */
+	forInSignals(callback) {
+		ForInSync(this.#signals, (key, signal) => {
+			callback(
+				/**
+				 * @type {K}
+				 */
+				(key),
+				/**
+				 * @type {SIGNALS[K]}
+				 */
+				(signal),
+			);
+		});
+	}
+}

package/src/class/WalkThrough.mjs

@@ -27,7 +27,7 @@ export class WalkThrough {
 	 * @param {(value:VAL)=>void} callback
 	 * @returns {void}
 	 * @example
-	 * import { WalkThrough } from 'vivth';
+	 * import { WalkThrough } from 'vivth/neutral';
 	 *
 	 * WalkThrough.set(setOfSomething, (value) => {
 	 * 	// code
@@ -35,7 +35,7 @@ export class WalkThrough {
 	 */
 	static set(setInstance, callback) {
 		WalkThrough.#handler(setInstance.values(), callback);
-	};
+	}
 	/**
 	 * @description
 	 * - method helper to WalkThrough `Map`;
@@ -44,7 +44,7 @@ export class WalkThrough {
 	 * @param {(res:[key: KEY, value: VAL]) => void} callback
 	 * @returns {void}
 	 * @example
-	 * import { WalkThrough } from 'vivth';
+	 * import { WalkThrough } from 'vivth/neutral';
 	 *
 	 * WalkThrough.map(mapOfSomething, ([key, value]) => {
 	 * 	// code
@@ -52,7 +52,7 @@ export class WalkThrough {
 	 */
 	static map(mapInstance, callback) {
 		WalkThrough.#handler(mapInstance.entries(), callback);
-	};
+	}
 	/**
 	 * @description
 	 * - method helper to WalkThrough `Array`;
@@ -61,7 +61,7 @@ export class WalkThrough {
 	 * @param {(res:[value: VAL, index: number]) => void} callback
 	 * @returns {void}
 	 * @example
-	 * import { WalkThrough } from 'vivth';
+	 * import { WalkThrough } from 'vivth/neutral';
 	 *
 	 * WalkThrough.array(arrayOfSomething, ([value, index]) => {
 	 * 	// code
@@ -69,22 +69,5 @@ export class WalkThrough {
 	 */
 	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/class/{WorkerMainThreadBundled.mjs → WorkerMainThread.bundled.mjs}

@@ -1,34 +1,43 @@
 // @ts-check
 
-import { FSInline } from '../bundler/FSInline.mjs';
+import { PathFSFile } from '../bundler/adds/PathFSFile.mjs';
+import { FSasar } from '../bundler/FSasar.mjs';
 import { Base64URL } from '../common/Base64URL.mjs';
-import { closeWorkerThreadEventObject } from '../common/eventObjects.mjs';
+import { Preferrence } from '../common/Preferrence.mjs';
 import { GetRuntime } from '../function/GetRuntime.mjs';
 import { Tries } from '../function/Tries.mjs';
 import { Console } from './Console.mjs';
 import { Derived } from './Derived.mjs';
 import { Effect } from './Effect.mjs';
-import { Paths } from './Paths.mjs';
-import { SafeExit } from './SafeExit.mjs';
 import { Signal } from './Signal.mjs';
+import { closeWorkerThreadEventObject } from '../common/eventObjects.mjs';
 
 /**
- * @template POST
- * @typedef {import('./WorkerResult.mjs').WorkerResult<POST>} WorkerResult
- */
-/**
- * @template RECEIVE
- * @template POST
- * @typedef {import('./WorkerThread.mjs').WorkerThread<RECEIVE, POST>} WorkerThread
+ * it supposed to be able to call on browser too
+ * ```js
+ * import { SafeExit } from './SafeExit.mjs';
+ * ```
+ * need to add cleaner for SafeExit.instance?.addCallback
  */
+
 /**
- * @typedef {import('../common/lazie.mjs').unwrapLazy} unwrapLazy
+ * @typedef {import('../typehints/VivthCleanup.mjs').VivthCleanup} VivthCleanup
  */
 
 /**
  * @template {WorkerThread<any, any>} WT
+ * @implements {VivthCleanup}
  */
 export class WorkerMainThread {
+	/**
+	 * @template POST
+	 * @typedef {import('./WorkerResult.mjs').WorkerResult<POST>} WorkerResult
+	 */
+	/**
+	 * @template RECEIVE
+	 * @template POST
+	 * @typedef {import('./WorkerThread.mjs').WorkerThread<RECEIVE, POST>} WorkerThread
+	 */
 	/**
 	 * @type {boolean}
 	 */
@@ -39,9 +48,6 @@ export class WorkerMainThread {
 	 * @param {typeof WorkerMainThread["pathValidator"]} param0.pathValidator
 	 */
 	static setup = ({ workerClass, pathValidator }) => {
-		if (Paths.root === undefined) {
-			return;
-		}
 		if (WorkerMainThread.#isRegistered) {
 			Console.warn({ message: 'WorkerMainThread.setup, can only be called once' });
 			return;
@@ -63,17 +69,8 @@ export class WorkerMainThread {
 			type: 'module',
 		});
 	/**
-	 * @template {WorkerThread<any, any>} WT
-	 * @param {string} handler
-	 * @param {Omit<WorkerOptions|import('node:worker_threads').WorkerOptions, 'eval'|'type'>} [options]
-	 * @returns {WorkerMainThread<WT>}
-	 */
-	static newVivthWorker(handler, options = {}) {
-		return new WorkerMainThread(handler, options);
-	}
-	/**
-	 * @param {Parameters<typeof WorkerMainThread<WT>["newVivthWorker"]>[0]} handler
-	 * @param {Parameters<typeof WorkerMainThread<WT>["newVivthWorker"]>[1]} [options]
+	 * @param {PathFSFile} handler
+	 * @param {Omit<WorkerOptions|import('node:worker_threads').WorkerOptions, 'eval'|'type'>} options
 	 */
 	constructor(handler, options = {}) {
 		/**
@@ -83,7 +80,7 @@ export class WorkerMainThread {
 		const listener = (ev) => {
 			this.#proxyReceiver.value = ev;
 		};
-		WorkerMainThread.#workerFilehandler(handler, options, this, listener);
+		WorkerMainThread.#workerFilehandler(handler.path, options, this, listener);
 	}
 	/**
 	 * @type {import('./Signal.mjs').Signal<import('./WorkerResult.mjs').WorkerResult<WT["POST"]>|MessageEvent<import('./WorkerResult.mjs').WorkerResult<WT["POST"]>>>}
@@ -101,79 +98,61 @@ export class WorkerMainThread {
 	 */
 	static async #workerFilehandler(handler, options, worker, listener) {
 		WorkerMainThread.#options.eval = true;
-		const resolvedPath = (await FSInline.vivthFSInlineFile(handler)).toString('utf-8');
+		const resolvedPath =
+			(await FSasar.file(PathFSFile.vivthFile(handler)))?.toString(Preferrence.encoding) ?? '';
 		const runtime = GetRuntime();
 		const workerClass = WorkerMainThread.workerClass;
-		if (
-			//
-			!workerClass
-		) {
-			Console.error('invalid `Worker` inputed to `WorkerMainThread`;');
+		if (!workerClass) {
+			Console.error('invalid `Worker` inputed to `WorkerMainThread`;', { now: true });
 			return;
 		}
-		const [, errorCreatingWorker] = await Tries({
+		const [[key], errorCreatingWorker] = await Tries({
 			browser: async () => {
 				if (runtime !== 'browser') {
-					throw new Error('not a browser');
+					throw 'not a browser';
 				}
 				const inlineURL = Base64URL(handler, 'application/javascript', btoa);
-				const worker_ = (worker.#worker.value = new workerClass(
-					inlineURL,
-					// @ts-expect-error
-					{
-						...options,
-						...WorkerMainThread.#options,
-					}
-				));
+				const worker_ = (worker.#worker.value = new workerClass(inlineURL, {
+					...options,
+					...WorkerMainThread.#options,
+				}));
 				if ('onmessage' in worker_ === false) {
-					throw new Error('not a browser');
+					throw 'not a browser';
 				}
 				worker_.onmessage = listener;
-				if (SafeExit.instance) {
-					SafeExit.instance.addCallback(async () => {
-						worker_.onmessage = null;
-					});
-				}
+				// SafeExit.instance?.addCallback(async () => {
+				// 	worker_.onmessage = null;
+				// });
 			},
 			nonBrowser: async () => {
-				if (workerClass !== (await import('node:worker_threads')).Worker) {
-					throw "Worker are not impored from 'node:worker_threads'";
-				}
 				const worker_ = (worker.#worker.value = new workerClass(resolvedPath, {
 					...options,
 					...WorkerMainThread.#options,
 				}));
 				if ('addEventListener' in worker_) {
-					// @ts-expect-error
 					worker_.addEventListener('message', listener);
-					if (SafeExit.instance) {
-						SafeExit.instance.addCallback(async () => {
-							// @ts-expect-error
-							worker_.removeEventListener('message', listener);
-						});
-					}
-				} else if ('addListener' in worker_) {
+					// SafeExit.instance?.addCallback(async () => {
+					// 	worker_.removeEventListener('message', listener);
+					// });
+					return;
+				}
+				if ('addListener' in worker_) {
 					worker_.addListener('message', listener);
-					if (SafeExit.instance) {
-						SafeExit.instance.addCallback(async () => {
-							worker_.removeListener('message', listener);
-						});
-					}
-				} else {
-					throw new Error('not a standard non browser');
+					// SafeExit.instance?.addCallback(async () => {
+					// 	worker_.removeListener('message', listener);
+					// });
+					return;
 				}
+				throw 'not a standard non browser';
 			},
 		});
-		if (errorCreatingWorker) {
-			Console.error(errorCreatingWorker);
+		if (!key) {
+			Console.error({ errorCreatingWorker }, { now: true });
 			return;
 		}
-		if (!SafeExit.instance) {
-			return;
-		}
-		SafeExit.instance.addCallback(async () => {
-			worker.terminate();
-		});
+		// SafeExit.instance?.addCallback(async () => {
+		// 	worker.terminate();
+		// });
 	}
 	/**
 	 * lazyly generated because node version need to await
@@ -194,9 +173,9 @@ export class WorkerMainThread {
 		worker.postMessage(postData, []);
 	});
 	/**
-	 * @return {void}
+	 * @return {Promise<void>}
 	 */
-	terminate = () => {
+	vivthCleanup = async () => {
 		this.postMessage(closeWorkerThreadEventObject);
 		/**
 		 * this is more for browser, as most of this are automatically cleaned with `SafeExit`;