vivth 0.11.1 → 1.0.0

package/src/class/Paths.mjs

@@ -0,0 +1,70 @@
+// @ts-check
+
+import { Console } from './Console.mjs';
+
+/**
+ * @description
+ * - class helpers to define pathReference;
+ * - is a singleton;
+ */
+export class Paths {
+	/**
+	 * @type {Paths}
+	 */
+	static #instance = undefined;
+	/**
+	 * @description
+	 * @param {Object} options
+	 * @param {string} options.root
+	 * - browser: location.origin
+	 * - node/bun compatible: process?.env?.INIT_CWD ?? process?.cwd();
+	 * - deno: Deno.env.get("INIT_CWD") ?? Deno.cwd(); need for `deno run --allow-env --allow-read your_script.ts`
+	 * - other: you need to check your JSRuntime for the rootPath reference;
+	 * @example
+	 * import { Paths } from 'vivth';
+	 *
+	 * new Paths({
+	 * 	root: location.origin,
+	 * })
+	 */
+	constructor({ root }) {
+		if (Paths.#instance) {
+			return Paths.#instance;
+		}
+		Paths.#instance = this;
+		this.#root = root;
+	}
+	/**
+	 * @type {string}
+	 */
+	#root = undefined;
+	/**
+	 * @description
+	 * - reference for rootPath
+	 * - `Paths` needed to be instantiated via:
+	 * >- `Paths` constructor;
+	 * >- `Setup.paths` constructor;
+	 * @type {string}
+	 */
+	static get root() {
+		if (!Paths.#instance.#root) {
+			Console.error({
+				error: 'Paths.instance.#root is undefined',
+				solutions: 'instantiate `Paths` or instantiate `Setup`',
+			});
+			return undefined;
+		}
+		return Paths.#instance.#root;
+	}
+	/**
+	 * @description
+	 * - normalize path separator to forward slash `/`;
+	 * @param {string} path_
+	 * @returns {string}
+	 * @example
+	 * import { Paths } from 'vivth';
+	 *
+	 * Paths.normalize('file:\\D:\\myFile.mjs'); // return 'file://D://myFile.mjs'
+	 */
+	static normalize = (path_) => path_.replace(/\\/g, '/');
+}

package/src/class/QChannel.mjs

@@ -0,0 +1,184 @@
+// @ts-check
+
+import { LazyFactory } from '../function/LazyFactory.mjs';
+import { TryAsync } from '../function/TryAsync.mjs';
+
+/**
+ * @description
+ * - class for `Queue` handling;
+ * @template {AnyButUndefinedType} T
+ */
+export class QChannel {
+	/**
+	 * @typedef {import('../types/AnyButUndefined.mjs').AnyButUndefined} AnyButUndefinedType
+	 * @typedef {import('../types/QCBReturn.mjs').QCBReturn} QCBReturn
+	 * @typedef {import('../types/QCBFIFOReturn.mjs').QCBFIFOReturn} QCBFIFOReturn
+	 */
+	/**
+	 * @description
+	 * - to modify `MapReference`
+	 * @param {Map<AnyButUndefinedType, [Promise<any>, {}]>} uniqueMap
+	 * @returns {typeof QChannel}
+	 * - usefull for Queue primitive on multiple library but single reference, like the Web by making the `Map` on `window` object;
+	 */
+	static makeQClass = (uniqueMap) => {
+		QChannel.#uniquePromiser = uniqueMap;
+		return QChannel;
+	};
+	/**
+	 * @type {Map<AnyButUndefinedType, [Promise<any>, {}]>}
+	 */
+	static #uniquePromiser = new Map();
+	/**
+	 * - ensures that each id has only one task running at a time.
+	 * - calls with the same id will wait for the previous call to finish.
+	 * @param {AnyButUndefinedType} id
+	 * @returns {Promise<QCBReturn>} Resolves when it's safe to proceed for the given id, returning a cleanup function
+	 */
+	static #uniqueCB = async (id) => {
+		const existing = QChannel.#uniquePromiser.get(id);
+		let resolveFn;
+		const nextPromise = new Promise((resolve) => {
+			resolveFn = resolve;
+		});
+		const context = {};
+		if (!existing) {
+			QChannel.#uniquePromiser.set(id, [nextPromise, context]);
+			await Promise.resolve();
+		} else {
+			const [prevPromise] = existing;
+			await prevPromise;
+			QChannel.#uniquePromiser.set(id, [nextPromise, context]);
+		}
+		const resume = () => {
+			resolveFn();
+			QChannel.#uniquePromiser.delete(id);
+		};
+		return {
+			resume,
+			get isLastOnQ() {
+				const [_, lastContext] = QChannel.#uniquePromiser.get(id);
+				return lastContext === context;
+			},
+		};
+	};
+	/**
+	 * @description
+	 * - first in first out handler
+	 */
+	static fifo = LazyFactory(() => {
+		const qfifo = new QChannel();
+		return {
+			/**
+			 * @static fifo
+			 * @description
+			 * - blocks execution for subsequent calls until the current one finishes.
+			 * @returns {Promise<QCBFIFOReturn>} Resolves when it's safe to proceed, returning a cleanup function
+			 * @example
+			 * const { resume } = await QChannel.fifo.key();
+			 * // blocks all `FIFO` called using this method and QChannel.fifoCallback;
+			 * resume();
+			 */
+			key: async () => {
+				return await qfifo.key(
+					/**
+					 * uses locally declared object to make it unique from other QChannel instances;
+					 */
+					qfifo
+				);
+			},
+			/**
+			 * @static fifo
+			 * @description
+			 * - blocks execution for subsequent calls until the current one finishes.
+			 * @template ResultType
+			 * @param {()=>Promise<ResultType>} asyncCallback
+			 * @returns {Promise<[ResultType|undefined, Error|undefined]>}
+			 * @example
+			 * const [result, error] = await QChannel.fifo.callback(async () = > {
+			 * 	// code
+			 * })
+			 */
+			callback: async (asyncCallback) => {
+				return await TryAsync(async () => {
+					const { resume } = await this.fifo.key();
+					const result = await asyncCallback();
+					resume();
+					return result;
+				});
+			},
+		};
+	});
+	/**
+	 * @type {Map<T, WeakKey>}
+	 */
+	#mapped = new Map();
+	/**
+	 * @description
+	 * - clear up all queued on the instance;
+	 * - only clear up the reference, the already called will not be stoped;
+	 * @returns {void}
+	 */
+	clear = () => {
+		this.#mapped.clear();
+	};
+	/**
+	 * @description
+	 * - each `QChannelInstance` are managing it's own `queue`, and will not `await` for other `QChannelInstance`;
+	 * - caveat:
+	 * >- need to manually call resume();
+	 * >- slightly more performant than `callback`;
+	 * @param {T} keyID
+	 * @returns {Promise<QCBReturn>}
+	 * @example
+	 * const q = new QChannel();
+	 * const handler = async () => {
+	 * 	const { resume, isLastOnQ } = await q.key(keyID);
+	 * 	// if (!isLastOnQ) { // imperative debounce if needed
+	 * 	// 	resume();
+	 * 	// 	return;
+	 * 	// }
+	 * 	// don't forget to call resume before any returns;
+	 * 	// blocks only if keyID is the same, until resume is called;
+	 * 	resume(); // don't forget to call resume before any returns;
+	 * 	return 'something';
+	 * }
+	 * handler();
+	 */
+	key = async (keyID) => {
+		const { resume } = await QChannel.#uniqueCB(this);
+		const mapped = this.#mapped;
+		if (!mapped.has(keyID)) {
+			mapped.set(keyID, {});
+		}
+		resume();
+		return await QChannel.#uniqueCB(mapped.get(keyID));
+	};
+	/**
+	 * @description
+	 * - `callbackBlock` with error as value:
+	 * - caveat:
+	 * >- no need to manually call resume();
+	 * >- slightly less performant than `callback`;
+	 * @template ResultType
+	 * @param {T} keyID
+	 * @param {(options:Omit<QCBReturn, "resume">)=>Promise<ResultType>} asyncCallback
+	 * @returns {Promise<[ResultType|undefined, Error|undefined]>}
+	 * @example
+	 * const q = new QChannel();
+	 * const [result, error] = await q.callback(keyID, async ({ isLastOnQ }) = > {
+	 * 	// if (!isLastOnQ) { // imperative debounce if needed
+	 * 	// 	return;
+	 * 	// }
+	 * 	// code
+	 * })
+	 */
+	callback = async (keyID, asyncCallback) => {
+		return await TryAsync(async () => {
+			const { resume, isLastOnQ } = await this.key(keyID);
+			const result = await asyncCallback({ isLastOnQ });
+			resume();
+			return result;
+		});
+	};
+}

package/src/class/SafeExit.mjs

@@ -0,0 +1,131 @@
+// @ts-check
+
+import { TryAsync } from '../function/TryAsync.mjs';
+import { Console } from './Console.mjs';
+import { Effect, setOfEffects } from './Effect.mjs';
+import { EnvSignal } from './EnvSignal.mjs';
+import { setOFSignals } from './Signal.mjs';
+
+/**
+ * @type {Set<()=>Promise<void>>}
+ */
+export const safeCleanUpCBs = new Set();
+
+/**
+ * @description
+ * - class helper for describing how to Safely Response on exit events
+ * - singleton;
+ * @template {[string, ...string[]]} ExitEventNames
+ */
+export class SafeExit {
+	/**
+	 * @description
+	 * - only accessible after instantiation;
+	 * @type {SafeExit}
+	 */
+	static instance = undefined;
+	/**
+	 * @description
+	 * @param {Object} options
+	 * @param {ExitEventNames} options.exitEventNames
+	 * @param {(eventName:string)=>void} [options.exitCallbackListeners]
+	 * - default value
+	 * ```js
+	 * (eventName) => {
+	 * 	process.once(eventName, function () {
+	 * 		SafeExit.instance.exiting.correction(true);
+	 * 		Console.log(`safe exit via "${eventName}"`);
+	 * 	});
+	 * };
+	 * ```
+	 * - if your exit callback doesn't uses `process` global object you need to input on the SafeExit instantiation
+	 * @example
+	 * import { SafeExit, Console } from 'vivth';
+	 *
+	 * new SafeExit({
+	 * 	// exitEventNames are blank by default, you need to manually name them all;
+	 * 	exitEventNames: ['SIGINT', 'SIGTERM', ...otherExitEventNames],
+	 * 	// optional deno example
+	 * 	exitCallbackListeners = (eventName) => {
+	 * 		const sig = Deno.signal(eventName);
+	 * 			for await (const _ of sig) {
+	 * 				exiting.correction(true);
+	 * 				sig.dispose();
+	 * 				Console.log(`safe exit via "${eventName}"`);
+	 * 			}
+	 * 	}
+	 * });
+	 */
+	constructor({ exitEventNames, exitCallbackListeners = undefined }) {
+		if (SafeExit.instance) {
+			return SafeExit.instance;
+		}
+		SafeExit.instance = this;
+		if (exitCallbackListeners) {
+			this.#exitCallbackListeners = exitCallbackListeners;
+		}
+		this.#register(exitEventNames);
+	}
+	/**
+	 * @description
+	 * - optional exit event registration, by listening to it inside an `Effect`;
+	 * - when the value is `true`, meaning program is exitting;
+	 * @type {EnvSignal<boolean>}
+	 */
+	exiting = new EnvSignal(false);
+	/**
+	 * @param {ExitEventNames} exitEventNames
+	 * @returns {void}
+	 */
+	#register = (exitEventNames) => {
+		exitEventNames.forEach((eventName) => {
+			this.#exitCallbackListeners(eventName);
+		});
+	};
+	/**
+	 * @type {(eventName:string)=>void}
+	 */
+	#exitCallbackListeners = (eventName) => {
+		SafeExit.instance.exiting.env.value;
+		process.once(eventName, function () {
+			Console.log(`safe exit via "${eventName}"`);
+			SafeExit.instance.exiting.correction(true);
+		});
+	};
+	/**
+	 * @description
+	 * - optional exit event registration;
+	 * - the callbacks will be called when exiting;
+	 * @param {()=>(Promise<void>)} cb
+	 * @example
+	 * import { SafeExit } from 'vivth';
+	 *
+	 * SafeExit.instance.addCallback(()=>{
+	 * 	// code
+	 * })
+	 */
+	addCallback = (cb) => {
+		safeCleanUpCBs.add(cb);
+	};
+	#autoCleanUp = new Effect(async ({ subscribe }) => {
+		if (!subscribe(this.exiting.env).value) {
+			return;
+		}
+		setOFSignals.forEach((signal) => {
+			signal.remove.ref();
+		});
+		setOfEffects.forEach((effect) => {
+			effect.options.removeEffect();
+		});
+		safeCleanUpCBs.forEach((cleanup) => {
+			TryAsync(async () => {
+				await cleanup();
+			}).then(([_, error]) => {
+				if (!error) {
+					return;
+				}
+				Console.error(error);
+			});
+		});
+	});
+}

package/src/class/Setup.mjs

@@ -0,0 +1,73 @@
+// @ts-check
+
+import { SafeExit } from './SafeExit.mjs';
+import { Paths } from './Paths.mjs';
+import { WorkerMainThread } from './WorkerMainThread.mjs';
+import { WorkerThread } from './WorkerThread.mjs';
+
+/**
+ * @description
+ * - class with collections of methods/constructors for setting up necessary variables for vivth internal functionalities;
+ */
+export class Setup {
+	/**
+	 * @description
+	 * - proxy `SafeExit_instance` for Setup
+	 * @example
+	 * import { Setup, Console } from 'vivth';
+	 *
+	 * new Setup.safeExit({
+	 * 	// exitEventNames are blank by default, you need to manually name them all;
+	 * 	exitEventNames: ['SIGINT', 'SIGTERM', ...otherExitEventNames],
+	 * 	// optional deno example
+	 * 	exitCallbackListeners = (eventName) => {
+	 * 		const sig = Deno.signal(eventName);
+	 * 			for await (const _ of sig) {
+	 * 				SafeExit.instance.exiting.correction(true);
+	 * 				sig.dispose();
+	 * 				Console.info(`safe exit via "${eventName}"`);
+	 * 			}
+	 * 	}
+	 * });
+	 */
+	static safeExit = SafeExit;
+	/**
+	 * @description
+	 * - proxy `Paths_instance` for Setup;
+	 * @example
+	 * import { Setup } from 'vivth';
+	 *
+	 * new Setup.paths({
+	 * 	root: location.origin, // browser example
+	 * })
+	 */
+	static paths = Paths;
+	/**
+	 * @description
+	 * - proxy `WorkerMainThread_instance` for Setup;
+	 * @example
+	 * import { Setup } from 'vivth';
+	 *
+	 * Setup.workerMain({
+	 * 	workerClass: async () => await (import('worker_threads')).Worker,
+	 * 	basePath: 'public/assets/js/workers',
+	 * 	pathValidator: async (workerPath, root, base) => {
+	 * 		const res = await fetch(`${root}/${base}/${workerPath}`);
+	 * 		// might also check wheter it need base or not
+	 * 		return await res.ok;
+	 * 	},
+	 * });
+	 */
+	static workerMain = WorkerMainThread.setup;
+	/**
+	 * @description
+	 * - correct `parentPort` reference when needed;
+	 * @example
+	 * import { Setup } from 'vivth';
+	 *
+	 * Setup.workerThread({ parentPort: async () => await import('node:worker_threads') });
+	 * // that is the default value, if your parentPort/equivalent API is not that;
+	 * // you need to call this method;
+	 */
+	static workerThread = WorkerThread.setup;
+}

package/src/class/Signal.mjs

@@ -1,99 +1,197 @@
 // @ts-check
 
-import { $ } from './$.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';
 
 /**
- * @description
- * - a class for creating signal;
- * - can be subscribed by using [New$](#new$) or [NewDerived](#newderived);
- * - for minimal total bundle size use `function` [NewSignal](#newSignal) instead;
+ * @type {Set<Signal>}
  */
+export const setOFSignals = new Set();
+
 /**
+ * @description
+ * - a class for creating effect to signals;
  * @template Value
  */
 export class Signal {
 	/**
-	 * @protected
-	 */
-	get subscribed() {
-		return $.mappedSignals.get(this);
-	}
-	/**
-	 * destroy all props
+	 * @description
+	 * - subsrcibers reference of this instance;
 	 */
-	unRef = () => {
-		this.removeAll$();
-		this.#Value = null;
-	};
+	subscribers = LazyFactory(() => ({
+		/**
+		 * @instance subscribers
+		 * @description
+		 * - subscribedEffects
+		 * @type {Set<Effect>}
+		 */
+		setOf: new Set(),
+		/**
+		 * @instance subscribers
+		 * @description
+		 * - manually notify on non primitive value or value that have depths;
+		 * @param {(options:{signalInstance:Signal<Value>})=>Promise<void>} [callback]
+		 * @returns {void}
+		 * @example
+		 * // for deep signal like array or object you can:
+		 *
+		 * const arraySignal = new Signal([1,2]);
+		 * arraySignal.value.push(3);
+		 * arraySignal.subscribers.notify();
+		 *
+		 * // OR for more complex mutation:
+		 *
+		 * const objectSignal = new Signal({a:'test', b:'test'});
+		 * objectSignal.subscribers.notify(async ({ signalInstance }) => {
+		 * 	signalInstance.value['c'] = 'testc';
+		 * 	signalInstance.value['d'] = 'testd';
+		 * });
+		 */
+		notify: (callback = undefined) => {
+			if (!callback) {
+				Signal.#notify(this.subscribers.setOf);
+				return;
+			}
+			TryAsync(async () => {
+				await callback({ signalInstance: this });
+			}).then(([_, error]) => {
+				if (error) {
+					Console.error({ message: 'unable to run callback', callback, error });
+					return;
+				}
+				Signal.#notify(this.subscribers.setOf);
+			});
+		},
+	}));
 	/**
-	 * remove all effects
-	 * @return {void}
+	 * @param {Set<Effect>} setOfSubscribers
 	 */
-	removeAll$ = () => {
-		this.subscribed?.forEach(($_) => {
-			$_.remove$();
+	static #notify = (setOfSubscribers) => {
+		const [_, error] = TrySync(() => {
+			const effects = setOfSubscribers;
+			effects.forEach((effect) => {
+				if (!setOfEffects.has(effect)) {
+					effects.delete(effect);
+					return;
+				}
+				/**
+				 * effect.run is already TryAsync
+				 */
+				effect.run();
+			});
 		});
+		if (!error) {
+			return;
+		}
+		Console.error(error);
 	};
 	/**
-	 * remove effect
-	 * @param {$} $_
-	 * @return {void}
+	 * @description
+	 * - collection of remove methods
 	 */
-	remove$ = ($_) => {
-		if ($.effects.get($_)?.has(this)) {
-			$_.remove$();
-		}
-	};
+	remove = LazyFactory(() => ({
+		/**
+		 * @instance remove
+		 * @description
+		 * - remove effect subscriber to react from this instance value changes;
+		 * @param {Effect} effectInstance
+		 * @returns {void}
+		 */
+		subscriber: (effectInstance) => {
+			effectInstance.options.removeEffect();
+			this.subscribers.setOf.delete(effectInstance);
+		},
+		/**
+		 * @instance remove
+		 * @description
+		 * - remove all effect subscribers to react from this instance value changes;
+		 * @type {()=>void}
+		 */
+		allSubscribers: () => {
+			const $ = this.subscribers.setOf;
+			$.forEach(this.remove.subscriber);
+		},
+		/**
+		 * @instance remove
+		 * @description
+		 * - remove this instance from `vivth` reactivity engine, and nullify it's own value;
+		 * @type {()=>void}
+		 */
+		ref: () => {
+			this.remove.allSubscribers();
+			this.#value = null;
+			setOFSignals.delete(this);
+		},
+	}));
 	/**
+	 * @description
 	 * @param {Value} value
+	 * @example
+	 * import { Signal, Effect } from  'vivth';
+	 *
+	 * const count = new Signal(0);
 	 */
 	constructor(value) {
-		this.#Value = value;
+		this.#value = value;
+		setOFSignals.add(this);
 	}
 	/**
 	 * @type {Value}
 	 */
 	#prev = undefined;
-	get prev() {
-		return this.#prev;
-	}
 	/**
+	 * @description
+	 * - value before change;
 	 * @type {Value}
 	 */
-	#Value;
+	get prev() {
+		return this.#prev;
+	}
 	/**
 	 * @type {Value}
 	 */
-	get nonReactiveValue() {
-		return this.#Value;
-	}
+	#value;
 	/**
+	 * @description
+	 * - value after change;
 	 * @type {Value}
+	 * @example
+	 * import { Signal, Effect, Derived } from  'vivth';
+	 *
+	 * const count = new Signal(0);
+	 * count.value; // not reactive
+	 *
+	 * new Effect(async ({ subscribe }) =>{
+	 * 	const countValue = subscribe(count).value; // reactive
+	 * })
+	 * const oneMoreThanCount = new Effect(async ({ subscribe }) =>{
+	 * 	return subscribe(count).value + 1; // reactive
+	 * })
 	 */
 	get value() {
-		if ($.isRegistering) {
-			$.activeSignal.add(this);
-		}
-		return this.#Value;
+		return this.#value;
 	}
 	/**
+	 * @description
+	 * - assign new value then automatically notify all subscribers;
 	 * @type {Value}
+	 * @example
+	 * import { Signal } from  'vivth';
+	 *
+	 * const count = new Signal(0);
+	 * count.value++;
+	 * // OR
+	 * count.value = 9;
 	 */
 	set value(newValue) {
-		if (this.#Value === newValue) {
+		if (this.#value === newValue) {
 			return;
 		}
-		this.#prev = this.#Value;
-		this.#Value = newValue;
-		this.call$();
+		this.#prev = this.#value;
+		this.#value = newValue;
+		this.subscribers.notify();
 	}
-	/**
-	 * @returns {void}
-	 */
-	call$ = () => {
-		if (!this.subscribed) {
-			return;
-		}
-		this.subscribed.forEach(($_) => $_.effect());
-	};
 }