vivth 0.11.1 → 1.0.0

package/types/src/class/EventSignal.d.mts

@@ -0,0 +1,145 @@
+/**
+ * @description
+ * - Signal implementation for `CustomEvent`, to dispatch and listen;
+ * @template {IsListSignal} isList
+ * - boolean;
+ */
+export class EventSignal<isList extends boolean> {
+    /**
+     * @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: Map<string, EventSignal<any>>;
+    /**
+     * @type {QChannel<string>}
+     */
+    static "__#12261@#qChannelEventSignal": QChannel<string>;
+    /**
+     * @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 get(stringName: string, isList_?: boolean): Promise<EventSignal<any>>;
+    /**
+     * @description
+     * - methods of this static property is lazily created;
+     * - remove signal and effect subscription of the named `EventSignal_instance`;
+     */
+    static remove: {
+        /**
+         * @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: string, effect: import("./Effect.mjs").Effect) => void;
+        /**
+         * @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: string) => void;
+        /**
+         * @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: string) => void;
+    } & {
+        "vivth:unwrapLazy;": string;
+    };
+    /**
+     * @private
+     * @param {string} name
+     * @param {isList} [isList]
+     */
+    private constructor();
+    /**
+     * @type {string}
+     */
+    name: string;
+    /**
+     * @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: Signal<any> | ListSignal<any>;
+    /**
+     * @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: Derived<any> | ListDerived<any>;
+    remove: {
+        /**
+         * @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: import("./Effect.mjs").Effect) => void;
+        /**
+         * @instance remove
+         * @description
+         * - remove allSubscribers from the `EventSignal_instance`;
+         * @type  {()=>void}
+         * @example
+         * eventSignal_instance.remove.allSubscribers();
+         */
+        allSubscribers: () => void;
+        /**
+         * @instance remove
+         * @description
+         * - remove reference of the `proxySignals` of the `EventSignal_instance`;
+         * @type {()=>void}
+         * @example
+         * eventSignal_instance.remove.ref();
+         */
+        ref: () => void;
+    } & {
+        "vivth:unwrapLazy;": string;
+    };
+    #private;
+}
+import { Signal } from './Signal.mjs';
+import { ListSignal } from './ListSignal.mjs';
+import { Derived } from './Derived.mjs';
+import { ListDerived } from './ListDerived.mjs';
+import { QChannel } from './QChannel.mjs';

package/types/src/class/ListDerived.d.mts

@@ -0,0 +1,35 @@
+/**
+ * @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<LA extends import("../types/ListArg.mjs").ListArg> extends Derived<LA[]> {
+    /**
+     * @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: (effectInstanceOptions: Effect["options"]) => Promise<LA[]>);
+}
+import { Derived } from './Derived.mjs';
+import { Effect } from './Effect.mjs';

package/types/src/class/ListSignal.d.mts

@@ -0,0 +1,150 @@
+/**
+ * @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<LA extends import("../types/ListArg.mjs").ListArg> extends Signal<LA[]> {
+    /**
+     * @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: unknown) => value is Array<Record<string, string>>;
+    /**
+     * @description
+     * - usefull for `loops`;
+     * @param {LA[]} [value]
+     * @example
+     * import { ListSignal } from 'vivth';
+     *
+     * const listExample = new ListSignal([
+     *      {key1: "test1",},
+     *      {key1: "test2",},
+     * ]);
+     */
+    constructor(value?: LA[]);
+    /**
+     * @description
+     * - methods collection that mimics `Array` API;
+     * - calling this methods will notify subscribers for changes, except for some;
+     */
+    arrayMethods: {
+        /**
+         * @instance arrayMethods
+         * @description
+         * - reference to structuredClone elements of `value`;
+         * - calling doesn't notify
+         * @type {Array<LA>}
+         */
+        readonly structuredClone: Array<LA>;
+        /**
+         * @instance arrayMethods
+         * @description
+         * - appends new elements to the end;
+         * @param {...LA} listArg
+         * @returns {void}
+         */
+        push: (...listArg: LA[]) => void;
+        /**
+         * @instance arrayMethods
+         * @description
+         * - removes the first element;
+         * @type {()=>void}
+         */
+        shift: () => void;
+        /**
+         * @instance arrayMethods
+         * @description
+         * - inserts new element at the start;
+         * @param  {...LA} listArg
+         * @returns {void}
+         */
+        unshift: (...listArg: LA[]) => void;
+        /**
+         * @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?: number, end?: number) => void;
+        /**
+         * @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: LA[]) => void;
+        /**
+         * @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: number, deleteCount: number, ...listArg: LA[]) => void;
+        /**
+         * @instance arrayMethods
+         * @description
+         * - swap `List` data between two indexes;
+         * @param {number} indexA
+         * @param {number} indexB
+         * @returns {void}
+         */
+        swap: (indexA: number, indexB: number) => void;
+        /**
+         * @instance arrayMethods
+         * @description
+         * - modify `List` element at specific index;
+         * @param {number} index
+         * @param {Partial<LA>} listArg
+         * @returns {void}
+         */
+        modify: (index: number, listArg: Partial<LA>) => void;
+        /**
+         * @instance arrayMethods
+         * @description
+         * - remove `List` element at specific index;
+         * @param {number} index
+         * @returns {void}
+         */
+        remove: (index: number) => void;
+        /**
+         * @instance arrayMethods
+         * @description
+         * - reverses the elements in an `List` in place.
+         * @returns {void}
+         */
+        reverse: () => void;
+        /**
+         * @instance arrayMethods
+         * @description
+         * - removes the last element;
+         * @returns {void}
+         */
+        pop: () => void;
+    } & {
+        "vivth:unwrapLazy;": string;
+    };
+    #private;
+}
+export type ListArg = import("../types/ListArg.mjs").ListArg;
+export type MutationType = import("../types/MutationType.mjs").MutationType;
+import { Signal } from './Signal.mjs';

package/types/src/class/Paths.d.mts

@@ -0,0 +1,50 @@
+/**
+ * @description
+ * - class helpers to define pathReference;
+ * - is a singleton;
+ */
+export class Paths {
+    /**
+     * @type {Paths}
+     */
+    static "__#13337@#instance": Paths;
+    /**
+     * @description
+     * - reference for rootPath
+     * - `Paths` needed to be instantiated via:
+     * >- `Paths` constructor;
+     * >- `Setup.paths` constructor;
+     * @type {string}
+     */
+    static get root(): string;
+    /**
+     * @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_: string) => string;
+    /**
+     * @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 }: {
+        root: string;
+    });
+    #private;
+}

package/types/src/class/QChannel.d.mts

@@ -0,0 +1,115 @@
+/**
+ * @description
+ * - class for `Queue` handling;
+ * @template {AnyButUndefinedType} T
+ */
+export class QChannel<T extends import("../types/AnyButUndefined.mjs").AnyButUndefined> {
+    /**
+     * @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: Map<import("../types/AnyButUndefined.mjs").AnyButUndefined, [Promise<any>, {}]>) => typeof QChannel;
+    /**
+     * @type {Map<AnyButUndefinedType, [Promise<any>, {}]>}
+     */
+    static "__#7@#uniquePromiser": Map<import("../types/AnyButUndefined.mjs").AnyButUndefined, [Promise<any>, {}]>;
+    /**
+     * - 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 "__#7@#uniqueCB": (id: import("../types/AnyButUndefined.mjs").AnyButUndefined) => Promise<import("../types/QCBReturn.mjs").QCBReturn>;
+    /**
+     * @description
+     * - first in first out handler
+     */
+    static fifo: {
+        /**
+         * @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: () => Promise<import("../types/QCBFIFOReturn.mjs").QCBFIFOReturn>;
+        /**
+         * @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: <ResultType>(asyncCallback: () => Promise<ResultType>) => Promise<[ResultType | undefined, Error | undefined]>;
+    } & {
+        "vivth:unwrapLazy;": string;
+    };
+    /**
+     * @description
+     * - clear up all queued on the instance;
+     * - only clear up the reference, the already called will not be stoped;
+     * @returns {void}
+     */
+    clear: () => void;
+    /**
+     * @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: (keyID: T) => Promise<import("../types/QCBReturn.mjs").QCBReturn>;
+    /**
+     * @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: (keyID: T, asyncCallback: (options: Omit<import("../types/QCBReturn.mjs").QCBReturn, "resume">) => Promise<ResultType>) => Promise<[ResultType | undefined, Error | undefined]>;
+    #private;
+}

package/types/src/class/SafeExit.d.mts

@@ -0,0 +1,76 @@
+/**
+ * @type {Set<()=>Promise<void>>}
+ */
+export const safeCleanUpCBs: Set<() => Promise<void>>;
+/**
+ * @description
+ * - class helper for describing how to Safely Response on exit events
+ * - singleton;
+ * @template {[string, ...string[]]} ExitEventNames
+ */
+export class SafeExit<ExitEventNames extends [string, ...string[]]> {
+    /**
+     * @description
+     * - only accessible after instantiation;
+     * @type {SafeExit}
+     */
+    static instance: SafeExit<any>;
+    /**
+     * @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 }: {
+        exitEventNames: ExitEventNames;
+        exitCallbackListeners?: (eventName: string) => void;
+    });
+    /**
+     * @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: EnvSignal<boolean>;
+    /**
+     * @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: () => (Promise<void>)) => void;
+    #private;
+}
+import { EnvSignal } from './EnvSignal.mjs';

package/types/src/class/Setup.d.mts

@@ -0,0 +1,76 @@
+/**
+ * @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: typeof SafeExit;
+    /**
+     * @description
+     * - proxy `Paths_instance` for Setup;
+     * @example
+     * import { Setup } from 'vivth';
+     *
+     * new Setup.paths({
+     * 	root: location.origin, // browser example
+     * })
+     */
+    static paths: typeof 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: ({ workerClass, pathValidator, basePath }: {
+        workerClass: (typeof WorkerMainThread)["workerClass"];
+        pathValidator: (typeof WorkerMainThread)["pathValidator"];
+        basePath?: (typeof WorkerMainThread)["basePath"];
+    }) => void;
+    /**
+     * @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: <Receive_, Post_>(parentPortRef: {
+        parentPort: () => Promise<any>;
+    }) => typeof WorkerThread<Receive_, Post_>;
+}
+import { SafeExit } from './SafeExit.mjs';
+import { Paths } from './Paths.mjs';
+import { WorkerMainThread } from './WorkerMainThread.mjs';
+import { WorkerThread } from './WorkerThread.mjs';