vivth 1.4.10 → 1.5.0

package/src/class/Derived.mjs

@@ -3,31 +3,37 @@
 import { Signal } from './Signal.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 VALUE
- * @extends Signal<VALUE>
+ * @extends Signal<VALUE|undefined>
  */
 export class Derived extends Signal {
 	/**
 	 * @description
 	 * - Derived used [Signal](#signal) and [Effect](#effect) under the hood;
-	 * @param {(effectInstanceOptions:Omit<Effect["options"] &
-	 * Derived<VALUE>["options"], unwrapLazy>) =>
-	 * Promise<VALUE>} derivedFunction
+	 * @param {(
+	 * 		effectInstanceOptions: Parameters<ConstructorParameters<typeof Effect>[0]>[0] &
+	 * 		{
+	 * 			dontUpdate:Derived<VALUE>["dontUpdate"]
+	 * 		}
+	 * 	) => Promise<Derived<VALUE>["dontUpdate"] | VALUE>
+	 * } derivedFunction
+	 * @param {ConstructorParameters<typeof Effect>[1]} [maxTimelapseBeingDebounced]
+	 * - prevent rapid changes from being unhandled more than the value;
+	 * - in miliseconds;
+	 * - default: `2_000`;
 	 * @example
-	 * import { Signal, Derived } from  'vivth';
+	 * import { Signal, Derived } from 'vivth/neutral';
 	 *
 	 * const count = new Signal(0);
 	 * const double = new Derived(async({
 	 * 		subscribe,
 	 * 		// : registrar callback for this derived instance, immediately return the signal instance
 	 * 	}) => {
-	 * 	return subscribe(count).value + count.value;
+	 * 	return subscribe(count).value \* 2;
 	 * 	// double listen to count changes, by returning the value, double.value also changes
 	 * 	// notice the count.value are accessed double, but it's all safe,
 	 * 	// since the wrapped one is the only one that are recorded as notifier.
@@ -35,64 +41,70 @@ export class Derived extends Signal {
 	 *
 	 * count.value++;
 	 */
-	constructor(derivedFunction) {
-		// @ts-expect-error
+	constructor(derivedFunction, maxTimelapseBeingDebounced = undefined) {
 		super(undefined);
-		const derived_instanceOptions = this.options;
 		new Effect(async (options) => {
-			const currentValue = await derivedFunction({
-				...options,
-				...derived_instanceOptions[unwrapLazy](),
-			});
-			if (currentValue === derived_instanceOptions.dontUpdate) {
+			const currentValue = await derivedFunction(
+				Object.assign(options, { dontUpdate: this.dontUpdate }),
+			);
+			if (currentValue === this.dontUpdate) {
 				return;
 			}
+			// @ts-expect-error
 			super.value = currentValue;
-		});
+		}, maxTimelapseBeingDebounced);
 	}
 	/**
 	 * @description
-	 * - additional helper to be accessed on effect;
+	 * - return this value to not to update the value of this instance, even when returning early;
+	 * @type {Symbol}
+	 * @example
+	 * import { Signal, Derived } from 'vivth/neutral';
+	 *
+	 * const count = new Signal(0);
+	 * const double = new Derived(async({
+	 * 		subscribe,
+	 * 		isLastCalled,
+	 * 	}) => {
+	 * 		if(!(await isLastCalled(100))) {
+	 * 			return this.dontUpdate;
+	 * 		}
+	 * 		const currentValue = subscribe(count).value;
+	 * 		const res = await fetch(`some/path/${curentValue.toString()}`);
+	 * 		if (
+	 * 			!(await isLastCalled()) ||
+	 * 			!res
+	 * 		) {
+	 * 			// returning early prevent race condition, even if the earlier fetch return late;
+	 *			return this.dontUpdate;
+	 *			// returning this.dontUpdate, will not modify the derived instance value;
+	 * 		}
+	 * 		count.value++;
+	 * 		return res;
+	 * });
+	 *
 	 */
-	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: {},
-		};
-	});
+	dontUpdate = Symbol('');
 	/**
 	 * @description
-	 * - the most recent value of the instance
+	 * - the most recent value of the instance;
 	 * - can be turn into reactive with Effect or Derived instantiation;
-	 * - initial value are always `undefined`, make sure to put a check before consuming(inside an `Effect`);
-	 * @returns {VALUE}
+	 * - value are allowed to be `undefined` and always be `undefined` at the instantiation time;
+	 * >- make sure to put a check before consuming(inside an `Effect`);
+	 * @returns {VALUE|undefined}
 	 * @override
+	 * @example
+	 * import { Signal, Derived, Effect } from 'vivth/neutral';
+	 *
+	 * const numberSignal = new Signal(0);
+	 * const doubleDerived = new Derived(async({ subscribe }) => {
+	 * 	return subscribe(numberSignal).value \* 2;
+	 * });
+	 *
+	 * new Effect(async({ subscribe }) => {
+	 * 	console.log(subscribe(doubleDerived).value);
+	 * })
+	 * numberSignal++;
 	 */
 	get value() {
 		return super.value;
@@ -100,9 +112,9 @@ export class Derived extends Signal {
 	/**
 	 * @description
 	 * - Derived instance value cannot be manually assigned;
-	 * - it's value should always be determined by it's own `derivedFunction`;
+	 * - it's value should always be determined by it's own returned value from `derivedFunction`;
 	 * @private
-	 * @type {VALUE}
+	 * @type {(value:VALUE|undefined)=>void}
 	 * @override
 	 */
 	set value(newValue) {

package/src/class/Effect.mjs

@@ -1,13 +1,18 @@
 // @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';
 import { Console } from './Console.mjs';
 import { Signal } from './Signal.mjs';
-
+import { ForInSync } from '../function/ForInSync.mjs';
+import { FactoryKey } from '../common/FactoryKey.mjs';
+import { IsInstanceOf } from '../function/IsInstanceOf.mjs';
+import { ForOfSync } from '../function/ForOfSync.mjs';
+/**
+ * @typedef { import('../typehints/VivthCleanup.mjs').VivthCleanup } VivthCleanup
+ */
 /**
  * @type {Map<Effect, Set<Signal<any>>>}
  */
@@ -16,19 +21,55 @@ export const mapOfEffects = new Map();
 /**
  * @description
  * - a class for creating effect;
- * - compared to previous class <b>$</b> reactivity model, `Effect`:
+ * - behaviour:
  * >- doesn't autosubscribe at first run;
- * >- it is using passed <b>$</b> named `arg0` options as subscriber;
- * >- doesn't block other queues during first run(previously blocks other queues to safely register signal autoscubscriber);
- * >- now can dynamically subscribes to signal, even on conditionals, that are not run during first run;
+ * >- it is using passed <b>subscribe</b> named `arg0` options as subscriber;
+ * >- doesn't block other queues during first run;
+ * >- can dynamically subscribes to signal, even on conditionals, that are not run during first run;
+ * @implements {VivthCleanup}
  */
 export class Effect {
+	vivthCleanup = async () => {
+		this.options.removeEffect();
+	};
 	/**
-	 * @typedef {import('../common/lazie.mjs').unwrapLazy} unwrapLazy
+	 * @description
+	 * @param {(
+	 * 		arg0: Effect["options"]
+	 * 	) => Promise<void>
+	 * } effect
+	 * @param {number} [maxTimelapseBeingDebounced]
+	 * - prevent rapid changes from being unhandled more than the value;
+	 * - in miliseconds;
+	 * - default: `2_000`;
+	 * @example
+	 * import { Signal, Derived, Effect, Console } from 'vivth/neutral';
+	 *
+	 * const count = new Signal(0);
+	 *
+	 * // double listen to count changes
+	 * const double = new Derived(async({subscribe}) => subscribe(count).value \* 2);
+	 *
+	 * 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 instance last called effect;
+	 * 		}) => {
+	 * 			const { value: currentValue, prev: prevValue } = subscribe(double); // effect listen to double changes
+	 * 			Console.log({ currentValue, prevValue });
+	 * })
+	 *
+	 * count.value++;
 	 */
+	constructor(effect, maxTimelapseBeingDebounced = 2_000) {
+		this.#maxTimelapseBeingDebounced = maxTimelapseBeingDebounced;
+		this.#effect = effect;
+		mapOfEffects.set(this, new Set());
+		this.run();
+	}
 	/**
 	 * @description
-	 * - collections of lazy methods to handle effect calls of this instance;
+	 * - collections of methods to handle effect calls of this instance;
 	 */
 	options = LazyFactory(() => {
 		const this_ = this;
@@ -36,59 +77,56 @@ export class Effect {
 			/**
 			 * @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;
+			 * - subscribe to `Signal_instance`;
+			 * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
+			 * @template {Signal<any>} SIGV
+			 * @param {SIGV} signalInstance
+			 * @returns {SIGV}
 			 * @example
+			 * import { Signal, Effect } from 'vivth/neutral';
 			 *
-			 * 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;
+			 * const signal1 = new Signal(0);
+			 * const signal2 = new Signal(true);
+			 * const signal3 = new Signal(true);
+			 * const effect = new Effect(async ({ subscribe }) => {
+			 * 	const signal1Value = subscribe(signal1).value;
+			 * 	if(signal1Value % 2){
+			 * 		// only subscribe to signal3, on conditional block
+			 * 		const signal3Value = subscribe(signal3).value;
 			 * 	}
 			 * })
+			 * effect.options.subscribe(signal2);
 			 */
-			get isLastCalled() {
-				const current = {};
-				this_.#current = current;
-				return async (timeoutMS = 0) => {
-					if (timeoutMS) {
-						await Timeout(timeoutMS);
-					}
-					return current === this_.#current;
-				};
+			subscribe: (signalInstance) => {
+				if (!IsInstanceOf(signalInstance, Signal)) {
+					signalInstance = signalInstance[FactoryKey];
+				}
+				signalInstance.subscribers.setOf.add(this_);
+				return signalInstance;
 			},
 			/**
 			 * @instance options
 			 * @description
-			 * - subscribe to `Signal_instance`;
+			 * - the same with `.options.subscribe`, but for batches subscription;
+			 * - ideal for first run which to add signal to subscription on main condition;
 			 * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
-			 * @template V
-			 * @param {Signal<V>} signalInstance
-			 * @returns {Signal<V>}
+			 * @template {ReadonlyArray<any>} T
+			 * @param {T} signalInstances
+			 * @returns {T}
 			 * @example
-			 * import { Effect } from 'vivth';
+			 * import { Signal, Effect } from 'vivth/neutral';
 			 *
-			 * const effect = new Effect(async () => {
-			 * 	// code
+			 * const signal1 = new Signal(0);
+			 * const signal2 = new Signal(true);
+			 * const effect = new Effect(async ({ subscribes }) => {
+			 * 	const [{value: signal1Value}, {value: signal2Value}]= subscribes([signal1, signal2]);
 			 * })
-			 * effect.options.subscribe(signalInstance);
 			 */
-			subscribe: (signalInstance) => {
-				if (signalInstance instanceof Signal === false) {
-					// @ts-expect-error
-					signalInstance = signalInstance[unwrapLazy]();
-				}
-				signalInstance.subscribers.setOf.add(this_);
-				return signalInstance;
+			subscribes: (signalInstances) => {
+				ForOfSync(signalInstances, (signal) => {
+					this.options.subscribe(signal).value;
+				});
+				return signalInstances;
 			},
 			/**
 			 * @instance options
@@ -96,11 +134,15 @@ export class Effect {
 			 * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
 			 * @type {()=>void}
 			 * @example
-			 * import { Effect } from 'vivth';
+			 * import { Effect } from 'vivth/neutral';
 			 *
-			 * const effect = new Effect(async () => {
-			 * 	// code
+			 * const effect = new Effect(async ({removeEffect}) => {
+			 * 	if(someCondition){
+			 * 		removeEffect();
+			 * 		return
+			 * 	}
 			 * })
+			 * // OR
 			 * effect.options.removeEffect();
 			 */
 			removeEffect: () => {
@@ -121,7 +163,7 @@ export class Effect {
 			 * @param {Signal<any>} signalInstance
 			 * @returns {void}
 			 * @example
-			 * import { Effect, Signal } from 'vivth';
+			 * import { Effect, Signal } from 'vivth/neutral';
 			 *
 			 * const count = new Signal(0);
 			 * const effect = new Effect(async ({ subscribe }) => {
@@ -143,50 +185,188 @@ export class Effect {
 				}
 				mapOfEffects.delete(this);
 			},
+			/**
+			 * @description
+			 * - remove inputed `SignalCollection` from this `Effect_instance`;
+			 * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
+			 * @param {import('./SignalCollection.mjs').SignalCollection<Record<string, Signal<any>>>} collectionInstance
+			 * @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 });
+			 *
+			 * const e = new Effect(async ({ subscribe, isLastCalled, removeCollection }) => {
+			 * 	const {
+			 * 		a: { value: aa }, // safely desctructured and auto subscribed
+			 * 		c: { value: cc }, // safely desctructured and auto subscribed
+			 * 	} = f.signals(subscribe);
+			 * 	if(!await isLastCalled(100)) {
+			 * 		return; // impertaive debounce
+			 * 	}
+			 * 	// removeCollection(f); // standard call from outside callback;
+			 * });
+			 * // optional call from outside callback;
+			 * e.options.removeCollection(f)
+			 */
+			removeCollection: (collectionInstance) => {
+				const collection = collectionInstance.signals();
+				const removeSignal = this.options.removeSignal;
+				ForInSync(collection, (_key, signal) => {
+					removeSignal(signal);
+				});
+			},
+			/**
+			 * @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/neutral';
+			 *
+			 * 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;
+				let isRealyEnforced = false;
+				return async (timeoutMS = 0) => {
+					const firstTimeDebounced = this_.#firstTimeDebounced;
+					if (isRealyEnforced) {
+						return true;
+					}
+					if (timeoutMS) {
+						await Timeout(timeoutMS);
+					}
+					if (!(await this_.#shallowCurrentCheck(current))) {
+						return false;
+					}
+					const [isLast, isEnforced] = await this_.#deepCurrentCheck(current, firstTimeDebounced);
+					if (isEnforced) {
+						isRealyEnforced = true;
+						this_.#promiser(current);
+					}
+					return isLast;
+				};
+			},
 		};
 	});
 	/**
-	 * @description
-	 * @param {( arg0:
-	 * Omit<Effect["options"], typeof unwrapLazy>
-	 * ) =>
-	 * Promise<void>} effect
-	 * @example
-	 * import { Signal, Derived, Effect, Console } from  'vivth';
-	 *
-	 * const count = new Signal(0);
-	 * const double = new Derived( async({$}) => $(count).value \* 2); // double listen to count changes
-	 * 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 $
-	 * })
-	 *
-	 * count.value++;
+	 * @param {Object} current
+	 * @returns {void}
 	 */
-	constructor(effect) {
-		this.#effect = effect;
-		mapOfEffects.set(this, new Set());
-		this.run();
-	}
+	#promiser = (current) => {
+		const { promise, resolve } = Promise.withResolvers();
+		this.#promise = promise;
+		const cleanupCallback = () => {
+			resolve(true);
+			this.#promise = undefined;
+			Effect.#mapCurrentCleanupCallback.delete(current);
+		};
+		Effect.#mapCurrentCleanupCallback.set(current, cleanupCallback);
+	};
+	/**
+	 * @type {undefined|Promise<any>}
+	 */
+	#promise = undefined;
 	/**
 	 * @type {Object}
 	 */
 	#current = {};
 	/**
-	 * @param {Omit<Effect["options"], typeof unwrapLazy>} effectInstance
-	 * @returns {Promise<void>}
+	 * @type {WeakMap<Object, ()=>void>}
+	 */
+	static #mapCurrentCleanupCallback = new WeakMap();
+
+	/**
+	 * @type {number|undefined}
+	 */
+	#firstTimeDebounced_ = undefined;
+	get #firstTimeDebounced() {
+		if (!this.#firstTimeDebounced_) {
+			this.#firstTimeDebounced_ = Date.now();
+		}
+		return this.#firstTimeDebounced_;
+	}
+	/**
+	 * @type {number}
+	 */
+	#maxTimelapseBeingDebounced;
+	/**
+	 * @param {Object} current
+	 * @returns {boolean}
+	 */
+	#shallowerCurrentCheck_ = (current) => {
+		if (this.#current === current) {
+			return true;
+		}
+		this.#firstTimeDebounced_ = undefined;
+		return false;
+	};
+	/**
+	 * @param {Object} current
+	 * @returns {Promise<boolean>}
+	 */
+	#shallowCurrentCheck = async (current) => {
+		if (!this.#shallowerCurrentCheck_(current)) {
+			return false;
+		}
+		if (this.#promise) {
+			await this.#promise;
+			if (!this.#shallowerCurrentCheck_(current)) {
+				return false;
+			}
+		}
+		return true;
+	};
+	/**
+	 * @param {Object} current
+	 * @param {number} chacedFirstTimeDebounced
+	 * @returns {Promise<[isLast:boolean, isEnforced:boolean]>}
+	 */
+	#deepCurrentCheck = async (current, chacedFirstTimeDebounced) => {
+		const elapsed = Date.now() - chacedFirstTimeDebounced;
+		let isLast;
+		let isEnforced;
+		if (elapsed >= this.#maxTimelapseBeingDebounced) {
+			isLast = true;
+			isEnforced = true;
+		} else {
+			isLast = current === this.#current;
+			isEnforced = false;
+		}
+		if (isLast) {
+			this.#firstTimeDebounced_ = undefined;
+		}
+		return [isLast, isEnforced];
+	};
+	/**
+	 * @type {(effectCallback:Parameters<ConstructorParameters<typeof Effect>[0]>[0])=>Promise<void>}
 	 */
 	#effect;
 	/**
 	 * @description
 	 * - normally is to let to be automatically run when dependency signals changes, however it's also accessible as instance method;
-	 * @returns {void}
+	 * @type {()=>void}
 	 * @example
-	 * import { Effect } from 'vivth';
+	 * import { Effect } from 'vivth/neutral';
 	 *
 	 * const effect = new Effect(async ()=>{
 	 * 	// code
@@ -194,6 +374,7 @@ export class Effect {
 	 * effect.run();
 	 */
 	run = () => {
+		const current = {};
 		TryAsync(async () => {
 			if (
 				//
@@ -202,12 +383,17 @@ export class Effect {
 				this.options.removeEffect();
 				return;
 			}
-			await this.#effect(this.options[unwrapLazy]());
-		}).then(([, error]) => {
-			if (error === undefined) {
+			const options = this.options[FactoryKey];
+			if (!options) {
 				return;
 			}
-			Console.error(error);
+			this.#current = current;
+			await this.#effect(options);
+		}).then(([, error]) => {
+			if (error) {
+				Console.error(error);
+			}
+			Effect.#mapCurrentCleanupCallback.get(current)?.(); // technically this line is a mock finally block
 		});
 	};
 }

package/src/class/EnvSignal.mjs

@@ -15,15 +15,18 @@ export class EnvSignal {
 	 * @description
 	 * - create `EnvSignal` instance;
 	 * @param {VALUE} initialValue
+	 * @example
+	 * import { EnvSignal } from 'vivth/neutral';
+	 *
+	 * export const myEnv = new EnvSignal(true);
 	 */
 	constructor(initialValue) {
 		this.#proxyConst = LazyFactory(() => new Signal(initialValue));
-		this.env = LazyFactory(
-			() =>
-				new Derived(async ({ subscribe }) => {
-					return subscribe(this.#proxyConst).value;
-				})
-		);
+		this.env = LazyFactory(() => {
+			return new Derived(async ({ subscribe }) => {
+				return subscribe(this.#proxyConst).value;
+			});
+		});
 	}
 	#isModified = false;
 	/**
@@ -35,7 +38,7 @@ export class EnvSignal {
 	 * - exposed property to listen to;
 	 * @type {Derived<VALUE>}
 	 * @example
-	 * import { EnvSignal, Effect } from 'vivth';
+	 * import { EnvSignal, Effect } from 'vivth/neutral';
 	 *
 	 * export const myEnv = new EnvSignal(true);
 	 * new Effect(async ({ subscribe }) => {
@@ -51,7 +54,7 @@ export class EnvSignal {
 	 * @param {VALUE} correctedValue
 	 * @returns {void}
 	 * @example
-	 * import { EnvSignal } from 'vivth';
+	 * import { EnvSignal } from 'vivth/neutral';
 	 *
 	 * export const myEnv = new EnvSignal(true);
 	 *