vivth 0.11.2 → 1.0.0

package/src/class/Effect.mjs

@@ -0,0 +1,106 @@
+// @ts-check
+
+import { unwrapLazy } from '../common/lazie.mjs';
+import { LazyFactory } from '../function/LazyFactory.mjs';
+import { TryAsync } from '../function/TryAsync.mjs';
+import { Console } from './Console.mjs';
+import { Signal } from './Signal.mjs';
+
+/**
+ * @type {Set<Effect>}
+ */
+export const setOfEffects = new Set();
+
+/**
+ * @description
+ * - a class for creating effect;
+ * - compared to previous class <b>$</b> reactivity model, `Effect`:
+ * >- 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;
+ */
+export class Effect {
+	/**
+	 * @description
+	 * @param {(arg0:Effect["options"])=>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;
+	 * 		}) => {
+	 * 			Console.log(subscribe(double).value); // effect listen to double changes
+	 * 			const a = double.value; //  no need to wrap double twice with $
+	 * })
+	 *
+	 * count.value++;
+	 */
+	constructor(effect) {
+		this.#effect = 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
+	 * @returns {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}
+	 * @example
+	 * const effect = new Effect(async ()=>{
+	 * 	// code
+	 * })
+	 * effect.run();
+	 */
+	run = () => {
+		TryAsync(async () => await this.#effect(this.options)).then(([_, error]) => {
+			if (!error) {
+				return;
+			}
+			Console.error(error);
+		});
+	};
+}

package/src/class/EnvSignal.mjs

@@ -0,0 +1,88 @@
+// @ts-check
+
+import { LazyFactory } from '../function/LazyFactory.mjs';
+import { Console } from './Console.mjs';
+import { Derived } from './Derived.mjs';
+import { Signal } from './Signal.mjs';
+
+/**
+ * @description
+ * - non browser API;
+ * - uses [Signal](#signal) and [Derived](#derived) under the hood;
+ * @template V
+ */
+export class EnvSignal {
+	/**
+	 * @description
+	 * - create `EnvSignal` instance;
+	 * @param {V} initialValue
+	 */
+	constructor(initialValue) {
+		this.#proxyConst = LazyFactory(() => new Signal(initialValue));
+		let isRun = false;
+		this.env = LazyFactory(
+			() =>
+				new Derived(async ({ subscribe }) => {
+					const derived = subscribe(this.#proxyConst).value;
+					if (!isRun) {
+						isRun = true;
+						return initialValue;
+					}
+					return derived;
+				})
+		);
+	}
+	#isModified = false;
+	/**
+	 * @type {Signal<V>}
+	 */
+	#proxyConst;
+	/**
+	 * @description
+	 * - exposed property to listen to;
+	 * @type {Derived<V>}
+	 * @example
+	 * import { EnvSignal, Effect } from 'vivth';
+	 *
+	 * export const myEnv = new EnvSignal(true);
+	 * new Effect(async ({ subscribe }) => {
+	 * 	const myEnvValue = subscribe(myEnv.env).value;
+	 * 	// code
+	 * })
+	 */
+	env;
+	/**
+	 * @description
+	 * - call to correct the value of previously declared value;
+	 * - can only be called once;
+	 * @param {V} correctedValue
+	 * @returns {void}
+	 * @example
+	 * import { EnvSignal } from 'vivth';
+	 *
+	 * export const myEnv = new EnvSignal(true);
+	 *
+	 * // somewhere else on the program
+	 * import { myEnv } from '$src/myEnv'
+	 *
+	 * myEnv.correction(false); // this will notify all subscribers;
+	 */
+	correction = (correctedValue) => {
+		if (this.#proxyConst.value === null) {
+			return;
+		}
+		Console;
+		if (this.#isModified) {
+			Console.warn({
+				correctedValue,
+				value: this.#proxyConst.value,
+				instance: this,
+				message: '"correct" of this instance can only be called once',
+			});
+			return;
+		}
+		this.#isModified = true;
+		this.#proxyConst.value = correctedValue;
+		this.#proxyConst.remove.ref();
+	};
+}

package/src/class/EventSignal.mjs

@@ -0,0 +1,200 @@
+// @ts-check
+
+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';
+
+/**
+ * @description
+ * - Signal implementation for `CustomEvent`, to dispatch and listen;
+ * @template {IsListSignal} isList
+ * - boolean;
+ */
+export class EventSignal {
+	/**
+	 * @typedef {import('../types/IsListSignal.mjs').IsListSignal} IsListSignal
+	 */
+	/**
+	 * @description
+	 * - `Map` of `EventSignal`, using the `stringName` of the `EventSignal_instance` as `key`;
+	 * @type {Map<string, EventSignal>}
+	 */
+	static map = new Map();
+	/**
+	 * @type {QChannel<string>}
+	 */
+	static #qChannelEventSignal = new QChannel();
+	/**
+	 * @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>}
+	 * @example
+	 * import { EventSignal } from 'vivth';
+	 *
+	 * const myEventSignal = await EventSignal.get('dataEvent');
+	 */
+	static async get(stringName, isList_ = false) {
+		const { resume } = await EventSignal.#qChannelEventSignal.key(stringName);
+		const mapped = EventSignal.map;
+		if (!mapped.has(stringName)) {
+			let instance = new EventSignal(stringName, isList_);
+			mapped.set(stringName, instance);
+		}
+		resume();
+		return mapped.get(stringName);
+	}
+	/**
+	 * @private
+	 * @param {string} name
+	 * @param {isList} [isList]
+	 */
+	// @ts-expect-error
+	constructor(name, isList = false) {
+		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;
+	 * - 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}
+	 */
+	dispatch = LazyFactory(() => {
+		if (this.#isList) {
+			return new ListSignal([]);
+		}
+		return new Signal(undefined);
+	});
+	/**
+	 * @description
+	 * - is [Derived](#derived) or [ListDerived](#listderived) instance, depending on the `isList` argument;
+	 * - 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}
+	 */
+	listen = LazyFactory(() => {
+		const dispatch = this.dispatch;
+		const _ = dispatch.value;
+		if (this.#isList) {
+			return new ListDerived(async ({ subscribe }) => {
+				return subscribe(dispatch).value;
+			});
+		}
+		return new Derived(async ({ subscribe }) => {
+			return subscribe(dispatch).value;
+		});
+	});
+	/**
+	 * @description
+	 * - methods of this static property is lazily created;
+	 * - remove signal and effect subscription of the named `EventSignal_instance`;
+	 */
+	static remove = LazyFactory(() => ({
+		/**
+		 * @static remove
+		 * @description
+		 * - remove subscriber from the named `EventSignal_instance`;
+		 * @param {string} name
+		 * @param {import('./Effect.mjs').Effect} effect
+		 * @returns {void}
+		 * @example
+		 * import { EventSignal } from 'vivth';
+		 *
+		 * EventSignal.remove.subscriber('yourEventSignalName', yourEffectInstance);
+		 */
+		subscriber: (name, effect) => {
+			effect.options.removeEffect();
+			EventSignal.get(name).then(({ remove }) => {
+				remove.subscriber(effect);
+			});
+		},
+		/**
+		 * @static remove
+		 * @description
+		 * - remove all subscribers from the named `EventSignal_instance`;
+		 * @param {string} name
+		 * @returns {void}
+		 * @example
+		 * import { EventSignal } from 'vivth';
+		 *
+		 * EventSignal.remove.allSubscribers('yourEventSignalName');
+		 */
+		allSubscribers: (name) => {
+			EventSignal.get(name).then(({ remove }) => {
+				remove.allSubscribers();
+			});
+		},
+		/**
+		 * @static remove
+		 * @description
+		 * - remove reference of the `proxySignals` of the named `EventSignal_instance`;
+		 * @param {string} name
+		 * @returns {void}
+		 * @example
+		 * import { EventSignal } from 'vivth';
+		 *
+		 * EventSignal.remove.refs('yourEventSignalName');
+		 */
+		refs: (name) => {
+			EventSignal.get(name).then(({ remove }) => {
+				remove.ref();
+			});
+		},
+	}));
+	remove = LazyFactory(() => ({
+		/**
+		 * @instance remove
+		 * @description
+		 * - remove subscriber from the `EventSignal_instance`;
+		 * @param {import('./Effect.mjs').Effect} effect
+		 * @returns {void}
+		 * @example
+		 * eventSignal_instance.remove.subscriber(yourEffectInstance);
+		 */
+		subscriber: (effect) => {
+			effect.options.removeEffect();
+			this.dispatch.remove.subscriber(effect);
+			this.listen.remove.subscriber(effect);
+		},
+		/**
+		 * @instance remove
+		 * @description
+		 * - remove allSubscribers from the `EventSignal_instance`;
+		 * @type  {()=>void}
+		 * @example
+		 * eventSignal_instance.remove.allSubscribers();
+		 */
+		allSubscribers: () => {
+			this.dispatch.remove.allSubscribers();
+			this.listen.remove.allSubscribers();
+		},
+		/**
+		 * @instance remove
+		 * @description
+		 * - remove reference of the `proxySignals` of the `EventSignal_instance`;
+		 * @type {()=>void}
+		 * @example
+		 * eventSignal_instance.remove.ref();
+		 */
+		ref: () => {
+			this.dispatch.remove.ref();
+			this.listen.remove.ref();
+		},
+	}));
+}

package/src/class/ListDerived.mjs

@@ -0,0 +1,39 @@
+// @ts-check
+
+import { Derived } from './Derived.mjs';
+import { Effect } from './Effect.mjs';
+/**
+ * @description
+ * - class to create `dervivedList` that satisfy `Array<Record<string, string>>`;
+ * - usefull for `derivedLoops`, e.g. temporary search values;
+ * - is a `Derived` instance;
+ * @template {ListArg} LA
+ * @extends {Derived<LA[]>}
+ */
+export class ListDerived extends Derived {
+	/**
+	 * @typedef {import('../types/ListArg.mjs').ListArg} ListArg
+	 */
+	/**
+	 * @description
+	 * @param {(effectInstanceOptions:Effect["options"])=>Promise<LA[]>} derivedFunction
+	 * @example
+	 * import { ListSignal, ListDerived } from 'vivth';
+	 *
+	 * const listExample = new ListSignal([
+	 * 	{key1: "test1"},
+	 * 	{key1: "test2"},
+	 * ]);
+	 *
+	 * export const listDerivedExample = new ListDerived(async({ subscribe }) => {
+	 * 	// becarefull to not mutate the reference value
+	 * 	return subscribe(listExample).value.filter((val) => {
+	 * 		// subscribe(listExample).structuredClone can be used as alternative
+	 * 		// filter logic
+	 * 	})
+	 * });
+	 */
+	constructor(derivedFunction) {
+		super(derivedFunction);
+	}
+}

package/src/class/ListSignal.mjs

@@ -0,0 +1,256 @@
+// @ts-check
+
+import { LazyFactory } from '../function/LazyFactory.mjs';
+import { Console } from './Console.mjs';
+import { Signal } from './Signal.mjs';
+
+/**
+ * @typedef {import('../types/ListArg.mjs').ListArg} ListArg
+ * @typedef {import('../types/MutationType.mjs').MutationType} MutationType
+ */
+/**
+ * @description
+ * - class to create list that satisfy `Array<Record<string, string>>`.
+ * @template {import('../types/ListArg.mjs').ListArg} LA
+ * @extends {Signal<LA[]>}
+ */
+export class ListSignal extends Signal {
+	/**
+	 * @description
+	 * - Checks if the input is an array whose first item (if present) is a plain object
+	 * - with string keys and string values. Allows empty arrays.
+	 * @param {unknown} value - The value to validate.
+	 * @returns {value is Array<Record<string, string>>} True if the first item is a valid string record or array is empty.
+	 */
+	static isValid = (value) => {
+		if (!Array.isArray(value)) return false;
+		const first = value[0];
+		if (first === undefined) {
+			// allow empty array
+			return true;
+		}
+		return (
+			first &&
+			typeof first === 'object' &&
+			!Array.isArray(first) &&
+			Object.entries(first).every(
+				([key, val]) => typeof key === 'string' && typeof val === 'string'
+			)
+		);
+	};
+	/**
+	 * @description
+	 * - usefull for `loops`;
+	 * @param {LA[]} [value]
+	 * @example
+	 * import { ListSignal } from 'vivth';
+	 *
+	 * const listExample = new ListSignal([
+	 *      {key1: "test1",},
+	 *      {key1: "test2",},
+	 * ]);
+	 */
+	constructor(value = []) {
+		super(value);
+	}
+	/**
+	 * @description
+	 * - reference to original inputed `value`;
+	 * @type {LA[]}
+	 */
+	get value() {
+		return super.value;
+	}
+	/**
+	 * @description
+	 * - you cannot mannually set`value` `ListSignal_instance`;
+	 * @private
+	 * @type {LA[]}
+	 */
+	set value(_) {
+		Console.error('`List.value` `setter` are not available outside the class or instance');
+	}
+	/**
+	 * @description
+	 * - methods collection that mimics `Array` API;
+	 * - calling this methods will notify subscribers for changes, except for some;
+	 */
+	arrayMethods = LazyFactory(() => {
+		return {
+			/**
+			 * @instance arrayMethods
+			 * @description
+			 * - reference to structuredClone elements of `value`;
+			 * - calling doesn't notify
+			 * @type {Array<LA>}
+			 */
+			get structuredClone() {
+				return structuredClone(super.value);
+			},
+			/**
+			 * @instance arrayMethods
+			 * @description
+			 * - appends new elements to the end;
+			 * @param {...LA} listArg
+			 * @returns {void}
+			 */
+			push: (...listArg) => {
+				super.value.push(...listArg);
+				this.subscribers.notify();
+			},
+			/**
+			 * @instance arrayMethods
+			 * @description
+			 * - removes the first element;
+			 * @type {()=>void}
+			 */
+			shift: () => {
+				super.value.shift();
+				this.subscribers.notify();
+			},
+			/**
+			 * @instance arrayMethods
+			 * @description
+			 * - inserts new element at the start;
+			 * @param  {...LA} listArg
+			 * @returns {void}
+			 */
+			unshift: (...listArg) => {
+				super.value.unshift(...listArg);
+				this.subscribers.notify();
+			},
+			/**
+			 * @instance arrayMethods
+			 * @description
+			 * - for both start and end, a negative index can be used to indicate an offset from the end of the data. For example, -2 refers to the second to last element of the data;
+			 * @param {number} [start]
+			 * - the beginning index of the specified portion of the data. If start is undefined, then the slice begins at index 0.
+			 * @param {number} [end]
+			 * - the end index of the specified portion of the data. This is exclusive of the element at the index 'end'. If end is undefined, then the slice extends to the end of the data.
+			 * @returns {void}
+			 */
+			slice: (start = 0, end = 0) => {
+				const deleteCount = end - start + 1;
+				this.arrayMethods.splice(start, deleteCount);
+			},
+			/**
+			 * @instance arrayMethods
+			 * @description
+			 * - replace whole `List` data with new array.
+			 * @param {LA[]} listArgs
+			 * - new array in place of the deleted array.
+			 * @returns {void}
+			 */
+			replace: (listArgs) => {
+				this.arrayMethods.splice(0, super.value.length, ...listArgs);
+			},
+			/**
+			 * @instance arrayMethods
+			 * @description
+			 * - removes elements from an data and, if necessary, inserts new elements in their place;
+			 * @param {number} start
+			 * - The zero-based location in the data from which to start removing elements.
+			 * @param {number} deleteCount
+			 * -The number of elements to remove.
+			 * @param {...LA} listArg
+			 * - new data in place of the deleted data.
+			 * @returns {void}
+			 */
+			splice: (start, deleteCount, ...listArg) => {
+				const end = start + deleteCount - 1;
+				if (!this.#checkLength('splice', end)) {
+					return;
+				}
+				super.value.splice(start, deleteCount, ...listArg);
+				this.subscribers.notify();
+			},
+			/**
+			 * @instance arrayMethods
+			 * @description
+			 * - swap `List` data between two indexes;
+			 * @param {number} indexA
+			 * @param {number} indexB
+			 * @returns {void}
+			 */
+			swap: (indexA, indexB) => {
+				if (!this.#checkLength('swap', indexA) || !this.#checkLength('swap', indexB)) {
+					return;
+				}
+				[super.value[indexA], super.value[indexB]] = [super.value[indexB], super.value[indexA]];
+				this.subscribers.notify();
+			},
+			/**
+			 * @instance arrayMethods
+			 * @description
+			 * - modify `List` element at specific index;
+			 * @param {number} index
+			 * @param {Partial<LA>} listArg
+			 * @returns {void}
+			 */
+			modify: (index, listArg) => {
+				if (!this.#checkLength('modify', index)) {
+					return;
+				}
+				for (const key in listArg) {
+					const listArgKey = listArg[key];
+					if (!listArgKey) {
+						continue;
+					}
+					super.value[index][key] = listArgKey;
+				}
+				this.subscribers.notify();
+			},
+			/**
+			 * @instance arrayMethods
+			 * @description
+			 * - remove `List` element at specific index;
+			 * @param {number} index
+			 * @returns {void}
+			 */
+			remove: (index) => {
+				if (!this.#checkLength('remove', index)) {
+					return;
+				}
+				this.arrayMethods.splice(index, 1);
+			},
+			/**
+			 * @instance arrayMethods
+			 * @description
+			 * - reverses the elements in an `List` in place.
+			 * @returns {void}
+			 */
+			reverse: () => {
+				super.value.reverse();
+				this.subscribers.notify();
+			},
+			/**
+			 * @instance arrayMethods
+			 * @description
+			 * - removes the last element;
+			 * @returns {void}
+			 */
+			pop: () => {
+				super.value.pop();
+				this.subscribers.notify();
+			},
+		};
+	});
+	/**
+	 * @param {MutationType} mode
+	 * @param {number} end
+	 * @returns {boolean}
+	 */
+	#checkLength = (mode, end) => {
+		const dataLength = super.value.length;
+		if (end >= dataLength) {
+			Console.error({
+				mode,
+				end,
+				dataLength,
+				message: 'list modifier, end is out of dataLength',
+			});
+			return false;
+		}
+		return true;
+	};
+}