vivth 1.4.10 → 1.5.1

package/src/class/EsWatcher.mjs

@@ -0,0 +1,60 @@
+// @ts-check
+
+import { context } from 'esbuild';
+import { SafeExit } from './SafeExit.mjs';
+import { TryAsync } from '../function/TryAsync.mjs';
+
+/**
+ * @typedef {import('../typehints/VivthCleanup.mjs').VivthCleanup} VivthCleanup
+ */
+
+/**
+ * @description
+ * - wrapper for `watcher` via `esbuild.context`;
+ * - watcher cleanup is automatically registered to `SafeExit`;
+ * @template {import('esbuild').BuildOptions} O
+ * @implements {VivthCleanup}
+ */
+export class EsWatcher {
+	/**
+	 * @description
+	 * @param {Partial<O>} buildOptions
+	 * @param {import('esbuild').WatchOptions} [watchOptions]
+	 * @example
+	 * import { EsWatcher } from 'vivth/node';
+	 *
+	 * const { context, remove } = new EsWatcher({
+	 *  ...esbuildOptions,
+	 * });
+	 */
+	constructor(buildOptions, watchOptions) {
+		const context_ = (this.ctx = context(
+			// @ts-expect-error
+			buildOptions,
+		));
+		context_.then(async (ctx) => {
+			await ctx.watch(watchOptions);
+			SafeExit.instance?.addCallback(this.vivthCleanup);
+		});
+	}
+
+	/**
+	 * @type {()=>Promise<void>}
+	 */
+	vivthCleanup = async () => {
+		SafeExit.instance?.removeCallback(this.vivthCleanup);
+		const { cancel, dispose } = await this.ctx;
+		await Promise.all([TryAsync(cancel), TryAsync(dispose)]);
+	};
+
+	/**
+	 * @description
+	 * - Promise of `BuildContext`;
+	 * @type {Promise<import('esbuild').BuildContext<O>>}
+	 */
+	ctx;
+	rebuild = async () => {
+		const ctx = await this.ctx;
+		return ctx.rebuild();
+	};
+}

package/src/class/EventSignal.mjs

@@ -2,82 +2,79 @@
 
 import { LazyFactory } from '../function/LazyFactory.mjs';
 import { Derived } from './Derived.mjs';
-import { ListDerived } from './ListDerived.mjs';
-import { ListSignal } from './ListSignal.mjs';
 import { QChannel } from './QChannel.mjs';
 import { Signal } from './Signal.mjs';
 
+/**
+ * @typedef { import('../typehints/VivthCleanup.mjs').VivthCleanup } VivthCleanup
+ */
+
 /**
  * @description
  * - Signal implementation for `CustomEvent`, to dispatch and listen;
  * - it's based on string as key, so it can be listened/dispatched even without direct instance reference;
- * @template {IsListSignal} ISLIST
- * - boolean;
+ * @template {any} TYPE
+ * @implements {VivthCleanup}
  */
 export class EventSignal {
+	vivthCleanup = async () => {
+		this.remove.ref();
+	};
 	/**
-	 * @typedef {import('../types/IsListSignal.mjs').IsListSignal} IsListSignal
+	 * @type {QChannel<string>}
 	 */
+	static #q = LazyFactory(() => new QChannel('EventSignal'));
 	/**
-	 * @description
 	 * - `Map` of `EventSignal`, using the `stringName` of the `EventSignal_instance` as `key`;
 	 * @type {Map<string, EventSignal<any>>}
 	 */
-	static map = new Map();
-	/**
-	 * @type {QChannel<string>}
-	 */
-	static #qChannelEventSignal = LazyFactory(() => new QChannel('EventSignal'));
+	static #map = new Map();
 	/**
 	 * @description
 	 * - the constructor it self is set to `private`;
 	 * - it's globally queued:
 	 * >- the `Promise` nature is to prevent race condition on creating the instance;
 	 * @param {string} stringName
-	 * @param {IsListSignal} [isList_]
 	 * @returns {Promise<EventSignal<any>>}
 	 * @example
-	 * import { EventSignal } from 'vivth';
+	 * import { EventSignal, Trace } from 'vivth/neutral';
 	 *
 	 * const myEventSignal = await EventSignal.get('dataEvent');
+	 * // recommendation
+	 * const myEventSignalGenerator = async (name) => {
+	 * 	return await EventSignal.get(`myEventSignalGenerator:${name}`);
+	 * }
 	 */
-	static get = async (stringName, isList_ = false) => {
-		const { resume } = await EventSignal.#qChannelEventSignal.key(stringName);
-		const mapped = EventSignal.map;
-		if (mapped.has(stringName) === false) {
-			let instance = new EventSignal(stringName, isList_);
+	static get = async (stringName) => {
+		const { resume } = await EventSignal.#q.key(stringName);
+		const mapped = EventSignal.#map;
+		if (!mapped.has(stringName)) {
+			let instance = new EventSignal(stringName);
 			mapped.set(stringName, instance);
 		}
 		resume();
-		// @ts-expect-error
+		// @ts-expect-error already setted upstream
 		return mapped.get(stringName);
 	};
 	/**
 	 * @private
 	 * @param {string} name
-	 * @param {ISLIST} [isList]
 	 */
-	// @ts-expect-error
-	constructor(name, isList = false) {
+	constructor(name) {
 		this.name = name;
-		this.#isList = isList;
 	}
-	/**
-	 * @type {IsListSignal}
-	 */
-	#isList;
 	/**
 	 * @type {string}
 	 */
 	name;
 	/**
 	 * @description
-	 * - is [Signal](#signal) or [ListSignal](#listsignal) instance, depending on the `isList` argument;
+	 * - is [Signal](#signal) instance;
 	 * - if needed to pass along the messages, it can be used as `dispatcher` and `listener` at the same time;
 	 * - is `lazily` created;
-	 * @type {Signal<any>|ListSignal<any>}
+	 * @type {Signal<TYPE>}
 	 * @example
-	 * import { EventSignal, Effect, Console } from 'vivth';
+	 * import { EventSignal, Effect, Console } from 'vivth/neutral';
 	 *
 	 * const myEventSignal = await EventSignal.get('dataEvent', false);
 	 *
@@ -88,20 +85,18 @@ export class EventSignal {
 	 * })
 	 * myEventSignal.dispatch.value = 'hey';
 	 */
-	dispatch = LazyFactory(() => {
-		if (this.#isList) {
-			return new ListSignal([]);
-		}
+	// @ts-expect-error
+	dispatcher = LazyFactory(() => {
 		return new Signal(undefined);
 	});
 	/**
 	 * @description
-	 * - is [Derived](#derived) or [ListDerived](#listderived) instance, depending on the `isList` argument;
+	 * - is [Derived](#derived);
 	 * - can be used as listener when passed down value shouldn't be modified manually;
 	 * - is `lazily` created along with `dispatch`, if `listen` is accessed first, then `dispatch` will also be created automatically;
-	 * @type {Derived<any>|ListDerived<any>}
+	 * @type {Derived<TYPE>}
 	 * @example
-	 * import { EventSignal, Effect, Console } from 'vivth';
+	 * import { EventSignal, Effect, Console } from 'vivth/neutral';
 	 *
 	 * const myEventSignal = await EventSignal.get('dataEvent', false);
 	 *
@@ -112,15 +107,8 @@ export class EventSignal {
 	 * })
 	 * myEventSignal.dispatch.value = 'hey';
 	 */
-	listen = LazyFactory(() => {
-		const dispatch = this.dispatch;
-		// @ts-expect-error
-		const _ = dispatch.value;
-		if (this.#isList) {
-			return new ListDerived(async ({ subscribe }) => {
-				return subscribe(dispatch).value;
-			});
-		}
+	listener = LazyFactory(() => {
+		const dispatch = this.dispatcher;
 		return new Derived(async ({ subscribe }) => {
 			return subscribe(dispatch).value;
 		});
@@ -139,7 +127,7 @@ export class EventSignal {
 		 * @param {import('./Effect.mjs').Effect} effectInstance
 		 * @returns {void}
 		 * @example
-		 * import { EventSignal } from 'vivth';
+		 * import { EventSignal } from 'vivth/neutral';
 		 *
 		 * EventSignal.remove.subscriber('yourEventSignalName', myEffectInstance);
 		 */
@@ -159,7 +147,7 @@ export class EventSignal {
 		 * @param {string} name
 		 * @returns {void}
 		 * @example
-		 * import { EventSignal } from 'vivth';
+		 * import { EventSignal } from 'vivth/neutral';
 		 *
 		 * EventSignal.remove.allSubscribers('yourEventSignalName');
 		 */
@@ -175,7 +163,7 @@ export class EventSignal {
 		 * @param {string} name
 		 * @returns {void}
 		 * @example
-		 * import { EventSignal } from 'vivth';
+		 * import { EventSignal } from 'vivth/neutral';
 		 *
 		 * EventSignal.remove.refs('yourEventSignalName');
 		 */
@@ -193,7 +181,7 @@ export class EventSignal {
 		 * @param {import('./Effect.mjs').Effect} effectInstance
 		 * @returns {void}
 		 * @example
-		 * import { EventSignal, Effect, Console } from 'vivth';
+		 * import { EventSignal, Effect, Console } from 'vivth/neutral';
 		 *
 		 * const myEventSignal = await EventSignal.get('dataEvent', false);
 		 *
@@ -209,8 +197,8 @@ export class EventSignal {
 			 * this part is not needed, as the effect might need to react to other signals
 			// effectInstance.options.removeEffect();
 			 */
-			this.dispatch.remove.subscriber(effectInstance);
-			this.listen.remove.subscriber(effectInstance);
+			this.dispatcher.remove.subscriber(effectInstance);
+			this.listener.remove.subscriber(effectInstance);
 		},
 		/**
 		 * @instance remove
@@ -218,7 +206,7 @@ export class EventSignal {
 		 * - remove allSubscribers from the `EventSignal_instance`;
 		 * @type  {()=>void}
 		 * @example
-		 * import { EventSignal, Effect, Console } from 'vivth';
+		 * import { EventSignal, Effect, Console } from 'vivth/neutral';
 		 *
 		 * const myEventSignal = await EventSignal.get('dataEvent', false);
 		 *
@@ -230,8 +218,8 @@ export class EventSignal {
 		 * eventSignal_instance.remove.allSubscribers();
 		 */
 		allSubscribers: () => {
-			this.dispatch.remove.allSubscribers();
-			this.listen.remove.allSubscribers();
+			this.dispatcher.remove.allSubscribers();
+			this.listener.remove.allSubscribers();
 		},
 		/**
 		 * @instance remove
@@ -239,7 +227,7 @@ export class EventSignal {
 		 * - remove reference of the `proxySignals` of the `EventSignal_instance`;
 		 * @type {()=>void}
 		 * @example
-		 * import { EventSignal, Effect, Console } from 'vivth';
+		 * import { EventSignal, Effect, Console } from 'vivth/neutral';
 		 *
 		 * const myEventSignal = await EventSignal.get('dataEvent', false);
 		 *
@@ -251,8 +239,8 @@ export class EventSignal {
 		 * eventSignal_instance.remove.ref();
 		 */
 		ref: () => {
-			this.dispatch.remove.ref();
-			this.listen.remove.ref();
+			this.dispatcher.remove.ref();
+			this.listener.remove.ref();
 		},
 	}));
 }

package/src/class/FSDirArchWatcher.mjs

@@ -0,0 +1,246 @@
+// @ts-check
+
+import { watch } from 'chokidar';
+
+import { Paths } from './Paths.mjs';
+import { Signal } from './Signal.mjs';
+import { SafeExit } from './SafeExit.mjs';
+import { QChannel } from './QChannel.mjs';
+import { Effect } from './Effect.mjs';
+import { TryAsync } from '../function/TryAsync.mjs';
+import { WalkThrough } from './WalkThrough.mjs';
+import { LazyFactory } from '../function/LazyFactory.mjs';
+import { Console } from './Console.mjs';
+
+/**
+ * @typedef {import('../typehints/VivthCleanup.mjs').VivthCleanup} VivthCleanup
+ */
+
+/**
+ * @description
+ * - class helper for chokidar abstraction to watch and iterate paths;
+ * - this class assume `Paths` and `SafeExit` to be instantiated;
+ * @template {any} PASSEDVALUE
+ * @implements {VivthCleanup}
+ */
+export class FSDirArchWatcher {
+	/**
+	 * @type {QChannel<string|FSDirArchWatcher<any>>}
+	 */
+	#q = LazyFactory(() => new QChannel('FSDirArchWatcher'));
+	/**
+	 * @description
+	 * - callback to handle each path;
+	 * @type {(
+	 *  eventName: import('chokidar/handler.js').EventName,
+	 *  path: import('chokidar/handler.js').Path,
+	 *  stats?: import('node:fs').Stats,
+	 *  ) => Promise<PASSEDVALUE>
+	 * }
+	 */
+	eachHandler;
+	/**
+	 * @description
+	 * - callback to handle all registered path;
+	 * - debounced to only handle last changes on full registry with:
+	 * >- `options.debounce`;
+	 * >- `QChannel` `isLastOnQ`;
+	 * @type {(
+	 * 		alphabeticallySortedSharedValue: {
+	 * 			map: Map<string, PASSEDVALUE>,
+	 * 			array: Array<[path: string, PASSEDVALUE]>,
+	 * 		}
+	 * 	) => Promise<void>
+	 * }
+	 */
+	fullHandler;
+	/**
+	 * @description
+	 * @param {string[]} watchPaths
+	 * @param {Object} options
+	 * @param {FSDirArchWatcher<PASSEDVALUE>["eachHandler"]} options.each
+	 * - throw to `ignore` OR `delete` path from the result passed to `.full`;
+	 * @param {FSDirArchWatcher<PASSEDVALUE>["fullHandler"]} options.full
+	 * @param {number} [options.debounce]
+	 * - debounce on calling `fullHandler`;
+	 * @param {import('chokidar').ChokidarOptions} [options.chokidarOptions]
+	 * - `ChokidarOptions`;
+	 * @example
+	 * import { FSDirArchWatcher, IsSameFile } from "vivth/node";
+	 *
+	 * const settingFile = '/fsrouter.setting.mjs';
+	 *
+	 * new FSDirArchWatcher(['/routers/', '/fsrouter.setting.mjs'], {
+	 * 	// debounce: 100,
+	 * 	each: async (eventName, path, stats) => {
+	 * 		// this callback is queued already;
+	 * 		// path are already `Paths.normalized`;
+	 * 		if(IsSameFile(path, settingFile)){
+	 * 			// code;
+	 * 		}
+	 * 		switch (eventName) {
+	 * 			case 'add':
+	 * 			case 'change':
+	 * 				// structure route here and return;
+	 * 				// a throwed call, will delete from sharedMap;
+	 * 				return {};
+	 * 			default:
+	 * 				// only for imperative handler when needed;
+	 * 				// or you can just throw here;
+	 * 				return {};
+	 * 		}
+	 * 		// only non throwed call of path is registered to sharedMap;
+	 * 		// throwed call of path is unregistered from sharedMap;
+	 * 	},
+	 * 	full:async (sharedMap) => {
+	 * 		// this callback is queued already;
+	 * 		// loop through returned from loop then write to a file;
+	 * 	},
+	 * })
+	 */
+	constructor(
+		watchPaths,
+		{ chokidarOptions = undefined, each: eachHandler, full: fullHandler, debounce = 100 },
+	) {
+		const setOfWatchPath = new Set(watchPaths);
+		WalkThrough.set(setOfWatchPath, (watchPath) => {
+			const absolutePath = Paths.diskAbsolute(watchPath);
+			if (setOfWatchPath.has(absolutePath)) {
+				return;
+			}
+			setOfWatchPath.delete(watchPath);
+			setOfWatchPath.add(absolutePath);
+		});
+		this.fullHandler = fullHandler;
+		this.eachHandler = eachHandler;
+		this.watcher = watch(Array.from(setOfWatchPath), chokidarOptions);
+		this.#debounce = debounce;
+		this.watcher.addListener('all', this.#eachHandler);
+		SafeExit.instance?.addCallback(this.vivthCleanup);
+	}
+
+	vivthCleanup = async () => {
+		SafeExit.instance?.removeCallback(this.vivthCleanup);
+		this.watcher.removeAllListeners();
+		await this.watcher.close();
+		Console.log(
+			{
+				FSDirArchWatcher: 'watcher closed',
+			},
+			{ now: true },
+		);
+	};
+
+	/**
+	 * @type {Signal<Map<string, PASSEDVALUE>>}
+	 */
+	#mappedFilePaths = new Signal(new Map());
+
+	/**
+	 * @param {() => boolean} isLastOnQ
+	 * @param {(signalInstance: any) => any} subscribe
+	 * @param {(timeoutMS?: number | undefined) => Promise<boolean>} isLastCalled
+	 * @returns
+	 */
+	#mappedFilePathsHandlerQ = async (isLastOnQ, subscribe, isLastCalled) => {
+		const originalMap = subscribe(this.#mappedFilePaths).value;
+		if (!isLastOnQ() || !(await isLastCalled(this.#debounce))) {
+			return;
+		}
+		const array = [...originalMap.entries()].sort(([a], [b]) => a.localeCompare(b));
+		/**
+		 * @type {Map<string, PASSEDVALUE>}
+		 */
+		const map = new Map(array);
+		await this.fullHandler({ map, array });
+	};
+
+	// @ts-expect-error
+	#mappedFilePathsHandler = new Effect(async ({ isLastCalled, subscribe }) => {
+		this.#q.callback(this, async ({ isLastOnQ }) => {
+			await this.#mappedFilePathsHandlerQ(isLastOnQ, subscribe, isLastCalled);
+		});
+	});
+
+	/**
+	 * @type {ConstructorParameters<typeof FSDirArchWatcher<PASSEDVALUE>>[1]["debounce"]}
+	 */
+	#debounce;
+
+	/**
+	 * @param {()=>boolean} isLastOnQ
+	 * @param {import('chokidar/handler.js').EventName} eventName
+	 * @param {import('chokidar/handler.js').Path} path
+	 * @param {import('node:fs').Stats} [stats]
+	 */
+	#eachHandlerQ = async (isLastOnQ, eventName, path, stats) => {
+		if (!isLastOnQ()) {
+			return;
+		}
+		switch (eventName) {
+			case 'add':
+			case 'change':
+				{
+					if (
+						/**
+						 * - only MARKED file PATH;
+						 */
+						!stats ||
+						!stats.isFile()
+					) {
+						return;
+					}
+					/**
+					 * - outside notify, as to be awaited by `QChannel.callback`
+					 */
+					const [shared, errorCallingEachHandler] = await TryAsync(async () => {
+						return await this.eachHandler(eventName, path, stats);
+					});
+					this.#mappedFilePaths.subscribers.notify(async ({ signalInstance }) => {
+						if (errorCallingEachHandler) {
+							signalInstance.value.delete(path);
+							return;
+						}
+						signalInstance.value.set(path, shared);
+					});
+				}
+				break;
+			default:
+				{
+					if (
+						/**
+						 * - only handle MARKED PATH;
+						 * - which in this case must be a file that no longer exist;
+						 * - and not a dir;
+						 */
+						!this.#mappedFilePaths.value.has(path)
+					) {
+						return;
+					}
+					/**
+					 * - outside notify, as to be awaited by `QChannel.callback`
+					 */
+					await TryAsync(async () => {
+						await this.eachHandler(eventName, path, stats);
+					});
+					this.#mappedFilePaths.subscribers.notify(async ({ signalInstance }) => {
+						signalInstance.value.delete(path);
+					});
+				}
+				break;
+		}
+	};
+
+	/**
+	 * @param {import('chokidar/handler.js').EventName} eventName
+	 * @param {import('chokidar/handler.js').Path} path
+	 * @param {import('node:fs').Stats} [stats]
+	 * @returns {void}
+	 */
+	#eachHandler = (eventName, path, stats) => {
+		path = Paths.normalize(path);
+		this.#q.callback(path, async ({ isLastOnQ }) => {
+			await this.#eachHandlerQ(isLastOnQ, eventName, path, stats);
+		});
+	};
+}