vivth 1.1.1 → 1.2.0

package/src/bundler/adds/ToBundledJSPlugin.mjs

@@ -0,0 +1,77 @@
+// @ts-check
+
+import { basename, extname } from 'node:path';
+import { readFile, exists } from 'node:fs/promises';
+import { CreateESPlugin } from '../CreateESPlugin.mjs';
+
+/**
+ * @description
+ * - generate `esbuild.Plugin` for changing dev time file into runtime file;
+ * - on using esbuild with this plugin, it will replace any module that have similiar file name but ended with Bundled(before extname);
+ * >- works on `.mts`|`.ts`|`.mjs`|`.cjs`|`.js`;
+ * >- `anyFileName.mjs` -> seek for and use `anyFileNameBundled.mjs`, if not found use `anyFileName.mjs`;
+ * @param {string} includedInPath
+ * - is generalized, you can freely uses forward or backward slash;
+ * @returns {ReturnType<CreateESPlugin>}
+ * @example
+ * import { ToBundledJSPlugin } from 'vivth';
+ *
+ * export const myBundledPlugin = ToBundledJSPlugin('/myProjectName/src/');
+ */
+export function ToBundledJSPlugin(includedInPath) {
+	const filter = new RegExp(includedInPath.replace(/[\\/]/g, '[\\\\/]'), '');
+	return CreateESPlugin(`ToBundledJSPlugin:${includedInPath}`, (build) => {
+		build.onLoad({ filter }, async (args) => {
+			const filePath = args.path;
+			const fileExt = extname(filePath);
+			/**
+			 * @type {'js'|'ts'}
+			 */
+			let loader;
+			switch (fileExt) {
+				case '.mts':
+				case '.ts':
+					loader = 'ts';
+					break;
+				case '.mjs':
+				case '.cjs':
+				case '.js':
+				default:
+					loader = 'js';
+					break;
+			}
+			const originalContent = (await readFile(filePath)).toString('utf-8');
+			if (!loader) {
+				return {
+					contents: originalContent,
+					loader,
+				};
+			}
+			if (filePath.endsWith(`Bundled${fileExt}`)) {
+				return {
+					contents: originalContent,
+					loader,
+				};
+			}
+			const originalBaseName = basename(filePath);
+			const originalFileName = originalBaseName.replace(fileExt, '');
+			const realRef = `${originalFileName}Bundled`;
+			const runtimeFile = filePath.replace(
+				new RegExp(`${originalBaseName}\$`.replace('.', '\\.'), ''),
+				`${realRef}${fileExt}`
+			);
+			const isExist = await exists(runtimeFile);
+			if (!isExist) {
+				return {
+					contents: originalContent,
+					loader,
+				};
+			}
+			const contents = (await readFile(runtimeFile)).toString('utf-8');
+			return {
+				contents,
+				loader,
+			};
+		});
+	});
+}

package/src/bundler/adds/externals.mjs

@@ -0,0 +1,8 @@
+// @ts-check
+
+export const externals = [
+	'esbuild',
+	'../prelude/bootstrap.js',
+	'./common',
+	'../prelude/diagnostic.js',
+];

package/src/bundler/adds/pluginVivthBundle.mjs

@@ -0,0 +1,5 @@
+// @ts-check
+
+import { ToBundledJSPlugin } from './ToBundledJSPlugin.mjs';
+
+export const pluginVivthBundle = ToBundledJSPlugin('/vivth/src/');

package/src/class/Console.mjs

@@ -2,61 +2,82 @@
 
 /**
  * @description
- * - class with static methods to print to standard console with added style;
+ * - class with static methods to print to standard console with bare minimum ANSI styles;
  */
 export class Console {
+	static #ansi = {
+		reset: '\x1b[0m',
+		bold: '\x1b[1m',
+		colors: {
+			log: '\x1b[32m', // green
+			info: '\x1b[34m', // blue
+			warn: '\x1b[33m', // yellow
+			error: '\x1b[31m', // red
+		},
+	};
 	/**
 	 * @param {string} prefix
 	 * @param {'log'|'info'|'error'|'warn'} mode
-	 * - Console method to use
 	 * @param {any} data
-	 * @param {string} color
-	 * @param {string} bgcolor
 	 * @returns {void}
 	 */
-	static #call = (prefix, mode, data, color, bgcolor) => {
-		/** @type {unknown} */
+	static #call = (prefix, mode, data) => {
 		const fn = console[mode];
-		if (typeof fn !== 'function') {
-			return;
-		}
-		fn.call(
-			console,
-			`%c${prefix} ${mode.toUpperCase()}:`,
-			`color:${color};background:${bgcolor};padding:2px 6px;border-radius:4px;`,
-			data
-		);
+		if (typeof fn !== 'function') return;
+
+		const color = Console.#ansi.colors[mode] || '';
+		const styledPrefix = `${color}${Console.#ansi.bold}${prefix} ${mode.toUpperCase()}:${
+			Console.#ansi.reset
+		}`;
+		fn(styledPrefix, data);
 	};
+
 	/**
 	 * @description
 	 * @param {any} data
 	 * @returns {void}
+	 * @example
+	 * import { Console } from 'vivth';
+	 *
+	 * Console.log({
+	 * 	hello: 'world!!',
+	 * });
 	 */
-	static log = (data) => {
-		Console.#call('🟢', 'log', data, 'white', '#2e7d32');
-	};
+	static log = (data) => Console.#call('🟢', 'log', data);
 	/**
 	 * @description
 	 * @param {any} data
 	 * @returns {void}
+	 * @example
+	 * import { Console } from 'vivth';
+	 *
+	 * Console.info({
+	 * 	hello: 'world!!',
+	 * });
 	 */
-	static info = (data) => {
-		Console.#call('🔵', 'info', data, 'white', '#1565c0');
-	};
+	static info = (data) => Console.#call('🔵', 'info', data);
 	/**
 	 * @description
 	 * @param {any} data
 	 * @returns {void}
+	 * @example
+	 * import { Console } from 'vivth';
+	 *
+	 * Console.warn({
+	 * 	hello: 'world!!',
+	 * });
 	 */
-	static warn = (data) => {
-		Console.#call('🟠', 'warn', data, 'black', '#ffb300');
-	};
+	static warn = (data) => Console.#call('🟠', 'warn', data);
 	/**
 	 * @description
 	 * @param {any} data
 	 * @returns {void}
+	 * @example
+	 * import { Console } from 'vivth';
+	 *
+	 * Console.error({
+	 * 	hello: 'world!!',
+	 * });
 	 */
-	static error = (data) => {
-		Console.#call('🔴', 'error', data, 'white', '#c62828');
-	};
+	static error = (data) => Console.#call('🔴', 'error', data);
 }

package/src/class/Derived.mjs

@@ -1,20 +1,24 @@
 // @ts-check
 
 import { Signal } from './Signal.mjs';
-import { Effect } from './Effect.mjs';
 import { Console } from './Console.mjs';
+import { Effect } from './Effect.mjs';
+import { LazyFactory } from '../function/LazyFactory.mjs';
+import { unwrapLazy } from '../common/lazie.mjs';
 
 /**
  * @description
  * - a class for creating derived version of [Signal](#signal);
- * @template V
- * @extends Signal<V>
+ * @template VALUE
+ * @extends Signal<VALUE>
  */
 export class Derived extends Signal {
 	/**
 	 * @description
 	 * - Derived used [Signal](#signal) and [Effect](#effect) under the hood;
-	 * @param {(effectInstanceOptions:Effect["options"])=>Promise<V>} derivedFunction
+	 * @param {(effectInstanceOptions:Omit<Effect["options"] &
+	 * Derived["options"], unwrapLazy>) =>
+	 * Promise<VALUE>} derivedFunction
 	 * @example
 	 * import { Signal, Derived } from  'vivth';
 	 *
@@ -33,15 +37,59 @@ export class Derived extends Signal {
 	 */
 	constructor(derivedFunction) {
 		super(undefined);
+		const derived_instanceOptions = this.options;
 		new Effect(async (options) => {
-			super.value = await derivedFunction(options);
+			const currentValue = await derivedFunction({
+				...options,
+				...derived_instanceOptions[unwrapLazy](),
+			});
+			if (currentValue === derived_instanceOptions.dontUpdate) {
+				return;
+			}
+			super.value = currentValue;
 		});
 	}
+	/**
+	 * @description
+	 * - additional helper to be accessed on effect;
+	 */
+	options = LazyFactory(() => {
+		return {
+			/**
+			 * @instance options
+			 * @description
+			 * - return this value tandem with `isLastCalled`, to not to update the value of this instance, even when returning early;
+			 * @type {Object}
+			 * @example
+			 * import { Signal, Derived } from  'vivth';
+			 *
+			 * const count = new Signal(0);
+			 * const double = new Derived(async({
+			 * 		subscribe,
+			 * 		dontUpdate,
+			 * 		isLastCalled,
+			 * 	}) => {
+			 * 		const currentValue = subscribe(count).value;
+			 * 		if (!(await isLastCalled(10))) {
+			 *			return dontUpdate;
+			 * 		}
+			 * 		const res = await fetch(`some/path/${curentValue.toString()}`);
+			 * 		if (!(await isLastCalled())) {
+			 *			return dontUpdate; // this will prevent race condition, even if the earlier fetch return late;
+			 * 		}
+			 * 		return res;
+			 * });
+			 *
+			 * count.value++;
+			 */
+			dontUpdate: {},
+		};
+	});
 	/**
 	 * @description
 	 * - the most recent value of the instance
 	 * - can be turn into reactive with Effect or Derived instantiation;
-	 * @type {V}
+	 * @returns {VALUE}
 	 */
 	get value() {
 		return super.value;
@@ -51,7 +99,7 @@ export class Derived extends Signal {
 	 * - Derived instance value cannot be manually assigned;
 	 * - it's value should always be determined by it's own `derivedFunction`;
 	 * @private
-	 * @type {V}
+	 * @type {VALUE}
 	 */
 	set value(newValue) {
 		Console.warn({

package/src/class/Effect.mjs

@@ -2,6 +2,7 @@
 
 import { unwrapLazy } from '../common/lazie.mjs';
 import { LazyFactory } from '../function/LazyFactory.mjs';
+import { Timeout } from '../function/Timeout.mjs';
 import { TryAsync } from '../function/TryAsync.mjs';
 import { Console } from './Console.mjs';
 import { Signal } from './Signal.mjs';
@@ -21,9 +22,96 @@ export const setOfEffects = new Set();
  * >- now can dynamically subscribes to signal, even on conditionals, that are not run during first run;
  */
 export class Effect {
+	/**
+	 * @typedef {import('../common/lazie.mjs').unwrapLazy} unwrapLazy
+	 */
+	/**
+	 * @description
+	 * - collections of lazy methods to handle effect calls of this instance;
+	 */
+	options = LazyFactory(() => {
+		const this_ = this;
+		return {
+			/**
+			 * @instance options
+			 * @description
+			 * @returns {(timeoutMS?:number)=>Promise<boolean>}
+			 * - timeoutMS only necessary if the operation doesn't naturally await;
+			 * - if it's operation such as `fetch`, you can just leave it blank;
+			 * @example
+			 *
+			 * import { Effect } from 'vivth';
+			 *
+			 * const effect = new Effect(async ({ isLastCalled }) => {
+			 * 	if (!(await isLastCalled(100))) {
+			 * 		return;
+			 * 	}
+			 * 	// OR
+			 * 	const res = await fetch('some/path');
+			 * 	if (!(await isLastCalled(
+			 * 		// no need to add timeoutMS argument, as fetch are naturally add delay;
+			 * 	))) {
+			 * 		return;
+			 * 	}
+			 * })
+			 */
+			get isLastCalled() {
+				const current = {};
+				this_.#current = current;
+				return async (timeoutMS = 0) => {
+					if (timeoutMS) {
+						await Timeout(timeoutMS);
+					}
+					return current === this_.#current;
+				};
+			},
+			/**
+			 * @instance options
+			 * @description
+			 * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
+			 * @template {Signal} SIGNAL
+			 * @param {SIGNAL} signal
+			 * @returns {SIGNAL}
+			 * @example
+			 * import { Effect } from 'vivth';
+			 *
+			 * const effect = new Effect(async () => {
+			 * 	// code
+			 * })
+			 * effect.options.subscribe(signalInstance);
+			 */
+			subscribe: (signal) => {
+				if (!(signal instanceof Signal)) {
+					// @ts-expect-error
+					signal = signal[unwrapLazy]();
+				}
+				signal.subscribers.setOf.add(this_);
+				return signal;
+			},
+			/**
+			 * @instance options
+			 * @description
+			 * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
+			 * @type {()=>void}
+			 * @example
+			 * import { Effect } from 'vivth';
+			 *
+			 * const effect = new Effect(async () => {
+			 * 	// code
+			 * })
+			 * effect.options.removeEffect();
+			 */
+			removeEffect: () => {
+				setOfEffects.delete(this);
+			},
+		};
+	});
 	/**
 	 * @description
-	 * @param {(arg0:Effect["options"])=>Promise<void>} effect
+	 * @param {( arg0:
+	 * Omit<Effect["options"], typeof unwrapLazy>
+	 * ) =>
+	 * Promise<void>} effect
 	 * @example
 	 * import { Signal, Derived, Effect, Console } from  'vivth';
 	 *
@@ -32,6 +120,7 @@ export class Effect {
 	 * new Effect(async ({
 	 * 			subscribe, // : registrar callback for this effect instance, immediately return the signal instance
 	 * 			removeEffect, // : disable this effect instance from reacting to dependency changes;
+	 * 			isLastCalled, // : check whether this callback run is this instant last called effect;
 	 * 		}) => {
 	 * 			Console.log(subscribe(double).value); // effect listen to double changes
 	 * 			const a = double.value; //  no need to wrap double twice with $
@@ -44,44 +133,12 @@ export class Effect {
 		setOfEffects.add(this);
 		this.run();
 	}
-	options = LazyFactory(() => ({
-		/**
-		 * @instance options
-		 * @description
-		 * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
-		 * @template {Signal} S
-		 * @param {S} signal
-		 * @returns {S}
-		 * @example
-		 * const effect = new Effect(async () => {
-		 * 	// code
-		 * })
-		 * effect.options.subscribe(signalInstance);
-		 */
-		subscribe: (signal) => {
-			if (!(signal instanceof Signal)) {
-				signal = signal[unwrapLazy];
-			}
-			signal.subscribers.setOf.add(this);
-			return signal;
-		},
-		/**
-		 * @instance options
-		 * @description
-		 * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
-		 * @type {()=>void}
-		 * @example
-		 * const effect = new Effect(async () => {
-		 * 	// code
-		 * })
-		 * effect.options.removeEffect();
-		 */
-		removeEffect: () => {
-			setOfEffects.delete(this);
-		},
-	}));
 	/**
-	 * @param {Effect["options"]} effectInstance
+	 * @type {Object}
+	 */
+	#current;
+	/**
+	 * @param {Omit<Effect["options"], typeof unwrapLazy>} effectInstance
 	 * @returns {Promise<void>}
 	 */
 	#effect;
@@ -90,13 +147,17 @@ export class Effect {
 	 * - normally is to let to be automatically run when dependency signals changes, however it's also accessible as instance method;
 	 * @returns {void}
 	 * @example
+	 * import { Effect } from 'vivth';
+	 *
 	 * const effect = new Effect(async ()=>{
 	 * 	// code
 	 * })
 	 * effect.run();
 	 */
 	run = () => {
-		TryAsync(async () => await this.#effect(this.options)).then(([_, error]) => {
+		TryAsync(async () => {
+			await this.#effect(this.options[unwrapLazy]());
+		}).then(([, error]) => {
 			if (!error) {
 				return;
 			}

package/src/class/EnvSignal.mjs

@@ -9,13 +9,13 @@ import { Signal } from './Signal.mjs';
  * @description
  * - non browser API;
  * - uses [Signal](#signal) and [Derived](#derived) under the hood;
- * @template V
+ * @template VALUE
  */
 export class EnvSignal {
 	/**
 	 * @description
 	 * - create `EnvSignal` instance;
-	 * @param {V} initialValue
+	 * @param {VALUE} initialValue
 	 */
 	constructor(initialValue) {
 		this.#proxyConst = LazyFactory(() => new Signal(initialValue));
@@ -34,13 +34,13 @@ export class EnvSignal {
 	}
 	#isModified = false;
 	/**
-	 * @type {Signal<V>}
+	 * @type {Signal<VALUE>}
 	 */
 	#proxyConst;
 	/**
 	 * @description
 	 * - exposed property to listen to;
-	 * @type {Derived<V>}
+	 * @type {Derived<VALUE>}
 	 * @example
 	 * import { EnvSignal, Effect } from 'vivth';
 	 *
@@ -55,7 +55,7 @@ export class EnvSignal {
 	 * @description
 	 * - call to correct the value of previously declared value;
 	 * - can only be called once;
-	 * @param {V} correctedValue
+	 * @param {VALUE} correctedValue
 	 * @returns {void}
 	 * @example
 	 * import { EnvSignal } from 'vivth';

package/src/class/EventSignal.mjs

@@ -10,7 +10,8 @@ import { Signal } from './Signal.mjs';
 /**
  * @description
  * - Signal implementation for `CustomEvent`, to dispatch and listen;
- * @template {IsListSignal} isList
+ * - it's based on string as key, so it can be listened/dispatched even without direct instance reference;
+ * @template {IsListSignal} ISLIST
  * - boolean;
  */
 export class EventSignal {
@@ -26,7 +27,7 @@ export class EventSignal {
 	/**
 	 * @type {QChannel<string>}
 	 */
-	static #qChannelEventSignal = new QChannel();
+	static #qChannelEventSignal = new QChannel('EventSignal');
 	/**
 	 * @description
 	 * - the constructor it self is set to `private`;
@@ -53,7 +54,7 @@ export class EventSignal {
 	/**
 	 * @private
 	 * @param {string} name
-	 * @param {isList} [isList]
+	 * @param {ISLIST} [isList]
 	 */
 	// @ts-expect-error
 	constructor(name, isList = false) {
@@ -74,6 +75,17 @@ export class EventSignal {
 	 * - if needed to pass along the messages, it can be used as `dispatcher` and `listener` at the same time;
 	 * - is `lazily` created;
 	 * @type {Signal|ListSignal}
+	 * @example
+	 * import { EventSignal, Effect, Console } from 'vivth';
+	 *
+	 * const myEventSignal = await EventSignal.get('dataEvent', false);
+	 *
+	 * new Effect(({ subscribe })=>{
+	 * 	const listenValue = subscribe(myEventSignal.dispatch).value;
+	 * 	// dispatch can be used as two way communication;
+	 * 	Console.log({ listenValue });
+	 * })
+	 * myEventSignal.dispatch.value = 'hey';
 	 */
 	dispatch = LazyFactory(() => {
 		if (this.#isList) {
@@ -87,6 +99,17 @@ export class EventSignal {
 	 * - 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|ListDerived}
+	 * @example
+	 * import { EventSignal, Effect, Console } from 'vivth';
+	 *
+	 * const myEventSignal = await EventSignal.get('dataEvent', false);
+	 *
+	 * new Effect(({ subscribe })=>{
+	 * 	const listenValue = subscribe(myEventSignal.listen).value;
+	 * 	// listen can be used only as listener for one way communication;
+	 * 	Console.log({ listenValue });
+	 * })
+	 * myEventSignal.dispatch.value = 'hey';
 	 */
 	listen = LazyFactory(() => {
 		const dispatch = this.dispatch;
@@ -116,7 +139,7 @@ export class EventSignal {
 		 * @example
 		 * import { EventSignal } from 'vivth';
 		 *
-		 * EventSignal.remove.subscriber('yourEventSignalName', yourEffectInstance);
+		 * EventSignal.remove.subscriber('yourEventSignalName', myEffectInstance);
 		 */
 		subscriber: (name, effect) => {
 			effect.options.removeEffect();
@@ -165,7 +188,16 @@ export class EventSignal {
 		 * @param {import('./Effect.mjs').Effect} effect
 		 * @returns {void}
 		 * @example
-		 * eventSignal_instance.remove.subscriber(yourEffectInstance);
+		 * import { EventSignal, Effect, Console } from 'vivth';
+		 *
+		 * const myEventSignal = await EventSignal.get('dataEvent', false);
+		 *
+		 * const myEffectInstance = new Effect(({ subscribe })=>{
+		 * 	const listenValue = subscribe(myEventSignal.dispatch).value;
+		 * 	Console.log({ listenValue });
+		 * })
+		 * myEventSignal.dispatch.value = 'hey';
+		 * eventSignal_instance.remove.subscriber(myEffectInstance);
 		 */
 		subscriber: (effect) => {
 			effect.options.removeEffect();
@@ -178,6 +210,15 @@ export class EventSignal {
 		 * - remove allSubscribers from the `EventSignal_instance`;
 		 * @type  {()=>void}
 		 * @example
+		 * import { EventSignal, Effect, Console } from 'vivth';
+		 *
+		 * const myEventSignal = await EventSignal.get('dataEvent', false);
+		 *
+		 * const myEffectInstance = new Effect(({ subscribe })=>{
+		 * 	const listenValue = subscribe(myEventSignal.dispatch).value;
+		 * 	Console.log({ listenValue });
+		 * })
+		 * myEventSignal.dispatch.value = 'hey';
 		 * eventSignal_instance.remove.allSubscribers();
 		 */
 		allSubscribers: () => {
@@ -190,6 +231,15 @@ export class EventSignal {
 		 * - remove reference of the `proxySignals` of the `EventSignal_instance`;
 		 * @type {()=>void}
 		 * @example
+		 * import { EventSignal, Effect, Console } from 'vivth';
+		 *
+		 * const myEventSignal = await EventSignal.get('dataEvent', false);
+		 *
+		 * const myEffectInstance = new Effect(({ subscribe })=>{
+		 * 	const listenValue = subscribe(myEventSignal.dispatch).value;
+		 * 	Console.log({ listenValue });
+		 * });
+		 *
 		 * eventSignal_instance.remove.ref();
 		 */
 		ref: () => {