vivth 1.4.9 → 1.5.0

package/types/src/bundler/FSInline.d.mts

@@ -1,50 +0,0 @@
-/**
- * @description
- * - class helper to inline files;
- * >- as `type: "buffer"`;
- * - use only if you are planning to use [CompileJS](#compilejs);
- * >- the class static methods don't obfuscate target file;
- * >- don't embed any sensitive content using this methods of this class;
- */
-export class FSInline {
-    /**
-     * @description
-     * - declare entrypoint of file inlining;
-     * >- on the dev time, it's just regullar `readFile` from `node:fs/promises`;
-     * >- on the compiled, it will read file from `FSInline.vivthFSInlinelists`
-     * @param {string} filePathFromProject
-     * - doesn't require prefix;
-     * @returns {Promise<Buffer<ArrayBuffer>>}
-     * - dev: returns `ArrayBuffer`;
-     * - bundled: embed the `ArrayBuffer` of file, which then returned;
-     * >- `Dev` will be cleaned up;
-     * @example
-     * import { FSInline } from 'vivth';
-     *
-     * (await FSInline.vivthFSInlineFile('/assets/text.txt')).toString('utf-8');
-     */
-    static vivthFSInlineFile: (filePathFromProject: string) => Promise<Buffer<ArrayBuffer>>;
-    /**
-     * @description
-     * - declare entrypoint of file inlining, include all files on `dir` and `subdir` that match the `fileRule`;
-     * - consider this as inline assets embed/bundler;
-     * @param {string} dirPathFromProject
-     * - doesn't require prefix;
-     * @param {RegExp} fileRule
-     * @returns {Promise<typeof FSInline["vivthFSInlineFile"]>}
-     * @example
-     * import { FSInline } from 'vivth';
-     *
-     * export const pngAssets = await FSInline.vivthFSInlineDir('/assets', /.png$/g);
-     */
-    static vivthFSInlineDir: (dirPathFromProject: string, fileRule: RegExp) => Promise<(typeof FSInline)["vivthFSInlineFile"]>;
-    /**
-     * @description
-     * - placeholder for FSInline;
-     * - it's remain publicly accessible so it doesn't mess with regex analyze on bundle;
-     * - shouldn't be manually accessed;
-     * >- access via `FSInline.vivthFSInlineFile` or `FSInline.vivthFSInlineDir`;
-     * @type {Record<string, Buffer<ArrayBuffer>>}
-     */
-    static vivthFSInlinelists: Record<string, Buffer<ArrayBuffer>>;
-}

package/types/src/bundler/FSInlineAnalyzer.d.mts

@@ -1,37 +0,0 @@
-/**
- * @description
- * - collections of static method to analyze content for `FSInline`;
- * - mostly used internally;
- */
-export class FSInlineAnalyzer {
-    /**
-     * @description
-     * - to be used on bundled content;
-     * @param {string} content
-     * @param {'cjs'|'esm'} format
-     * @returns {ReturnType<typeof TryAsync<string>>}
-     * @example
-     * import { readFile } from 'node:fs/promises';
-     *
-     * import { FSInlineAnalyzer } from 'vivth';
-     *
-     * const [resultFinalContent, errorFinalContent] = await FSInlineAnalyzer.finalContent(
-     * 	await readFile('./resultESBunlded.mjs', {encoding: 'utf-8'}),
-     * 	'esm'
-     * );
-     */
-    static finalContent: (content: string, format: "cjs" | "esm") => ReturnType<typeof TryAsync<string>>;
-    /**
-     * @typedef {{path:string, buffer:Buffer<ArrayBuffer>}[]} _dirReturn
-     */
-    /**
-     * @param {string} dirName
-     * @param {RegExp} ruleForFileFullPath
-     * @returns {Promise<_dirReturn>}
-     */
-    static "__#private@#dir": (dirName: string, ruleForFileFullPath: RegExp) => Promise<{
-        path: string;
-        buffer: Buffer<ArrayBuffer>;
-    }[]>;
-}
-import { TryAsync } from '../function/TryAsync.mjs';

package/types/src/bundler/FSInlineBundled.d.mts

@@ -1,22 +0,0 @@
-export class FSInline {
-    static prefix: string;
-    /**
-     * @param {string} filePathFromProject
-     * @returns {Promise<Buffer<ArrayBuffer>>}
-     */
-    static vivthFSInlineFile: (filePathFromProject: string) => Promise<Buffer<ArrayBuffer>>;
-    /**
-     * @param {string} dirPathFromProject
-     * @param {Object} regexRule
-     * @param {RegExp} regexRule.dir
-     * @param {RegExp} regexRule.file
-     * @returns {Promise<typeof FSInline["vivthFSInlineFile"]>}
-     * - relative to the `dirPathFromProject`
-     */
-    static vivthFSInlineDir: (dirPathFromProject: string) => Promise<(typeof FSInline)["vivthFSInlineFile"]>;
-    /**
-     * - to be used as embed placeholder on `bundled` and `compiled`;
-     * @type {Record<string, Buffer<ArrayBufferLike>>}
-     */
-    static vivthFSInlinelists: Record<string, Buffer<ArrayBufferLike>>;
-}

package/types/src/bundler/adds/externals.d.mts

@@ -1 +0,0 @@
-export const externals: string[];

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

@@ -1,71 +0,0 @@
-/**
- * @description
- * - class with static methods to print to standard console with bare minimum ANSI styles;
- */
-export class Console {
-    static "__#private@#ansi": {
-        reset: string;
-        bold: string;
-        colors: {
-            log: string;
-            info: string;
-            warn: string;
-            error: string;
-        };
-    };
-    /**
-     * @param {string} prefix
-     * @param {'log'|'info'|'error'|'warn'} mode
-     * @param {any} data
-     * @returns {void}
-     */
-    static "__#private@#call": (prefix: string, mode: "log" | "info" | "error" | "warn", data: any) => void;
-    /**
-     * @description
-     * @param {any} data
-     * @returns {void}
-     * @example
-     * import { Console } from 'vivth';
-     *
-     * Console.log({
-     * 	hello: 'world!!',
-     * });
-     */
-    static log: (data: any) => void;
-    /**
-     * @description
-     * @param {any} data
-     * @returns {void}
-     * @example
-     * import { Console } from 'vivth';
-     *
-     * Console.info({
-     * 	hello: 'world!!',
-     * });
-     */
-    static info: (data: any) => void;
-    /**
-     * @description
-     * @param {any} data
-     * @returns {void}
-     * @example
-     * import { Console } from 'vivth';
-     *
-     * Console.warn({
-     * 	hello: 'world!!',
-     * });
-     */
-    static warn: (data: any) => void;
-    /**
-     * @description
-     * @param {any} data
-     * @returns {void}
-     * @example
-     * import { Console } from 'vivth';
-     *
-     * Console.error({
-     * 	hello: 'world!!',
-     * });
-     */
-    static error: (data: any) => void;
-}

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

@@ -1,98 +0,0 @@
-/**
- * @description
- * - a class for creating derived version of [Signal](#signal);
- * @template VALUE
- * @extends Signal<VALUE>
- */
-export class Derived<VALUE> extends Signal<VALUE> {
-    /**
-     * @description
-     * - Derived used [Signal](#signal) and [Effect](#effect) under the hood;
-     * @param {(effectInstanceOptions:Omit<Effect["options"] &
-     * Derived<VALUE>["options"], unwrapLazy>) =>
-     * Promise<VALUE>} derivedFunction
-     * @example
-     * import { Signal, Derived } from  'vivth';
-     *
-     * 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;
-     * 	// 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.
-     * });
-     *
-     * count.value++;
-     */
-    constructor(derivedFunction: (effectInstanceOptions: Omit<Effect["options"] & Derived<VALUE>["options"], "vivth:unwrapLazy;">) => Promise<VALUE>);
-    /**
-     * @description
-     * - additional helper to be accessed on effect;
-     */
-    options: {
-        /**
-         * @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: Object;
-    } & {
-        "vivth:unwrapLazy;": () => {
-            /**
-             * @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: Object;
-        };
-    };
-}
-import { Signal } from './Signal.mjs';
-import { Effect } from './Effect.mjs';

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

@@ -1,216 +0,0 @@
-/**
- * @type {Map<Effect, Set<Signal<any>>>}
- */
-export const mapOfEffects: Map<Effect, Set<Signal<any>>>;
-/**
- * @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:
-     * 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++;
-     */
-    constructor(effect: (arg0: Omit<Effect["options"], typeof unwrapLazy>) => Promise<void>);
-    /**
-     * @typedef {import('../common/lazie.mjs').unwrapLazy} unwrapLazy
-     */
-    /**
-     * @description
-     * - collections of lazy methods to handle effect calls of this instance;
-     */
-    options: {
-        /**
-         * @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;
-         * 	}
-         * })
-         */
-        readonly isLastCalled: (timeoutMS?: number) => Promise<boolean>;
-        /**
-         * @instance options
-         * @description
-         * - subscribe to `Signal_instance`;
-         * - 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>}
-         * @example
-         * import { Effect } from 'vivth';
-         *
-         * const effect = new Effect(async () => {
-         * 	// code
-         * })
-         * effect.options.subscribe(signalInstance);
-         */
-        subscribe: <V>(signalInstance: Signal<V>) => Signal<V>;
-        /**
-         * @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: () => void;
-        /**
-         * @description
-         * - remove inputed signal from this `Effect_instance`;
-         * - if effect signal has no other `Signal_instance` to listen to, it will then completely rendered non reactive;
-         * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
-         * @param {Signal<any>} signalInstance
-         * @returns {void}
-         * @example
-         * import { Effect, Signal } from 'vivth';
-         *
-         * const count = new Signal(0);
-         * const effect = new Effect(async ({ subscribe }) => {
-         * 	console.log(subscribe(count).value); // will subscribe  count changes;
-         * })
-         * count.value++; // will increase the count and trigger effect;
-         * effect.options.removeSignal(count);
-         * count.value++; // will increase the count but will no longer trigger effect;
-         */
-        removeSignal: (signalInstance: Signal<any>) => void;
-    } & {
-        "vivth:unwrapLazy;": () => {
-            /**
-             * @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;
-             * 	}
-             * })
-             */
-            readonly isLastCalled: (timeoutMS?: number) => Promise<boolean>;
-            /**
-             * @instance options
-             * @description
-             * - subscribe to `Signal_instance`;
-             * - 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>}
-             * @example
-             * import { Effect } from 'vivth';
-             *
-             * const effect = new Effect(async () => {
-             * 	// code
-             * })
-             * effect.options.subscribe(signalInstance);
-             */
-            subscribe: <V>(signalInstance: Signal<V>) => Signal<V>;
-            /**
-             * @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: () => void;
-            /**
-             * @description
-             * - remove inputed signal from this `Effect_instance`;
-             * - if effect signal has no other `Signal_instance` to listen to, it will then completely rendered non reactive;
-             * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
-             * @param {Signal<any>} signalInstance
-             * @returns {void}
-             * @example
-             * import { Effect, Signal } from 'vivth';
-             *
-             * const count = new Signal(0);
-             * const effect = new Effect(async ({ subscribe }) => {
-             * 	console.log(subscribe(count).value); // will subscribe  count changes;
-             * })
-             * count.value++; // will increase the count and trigger effect;
-             * effect.options.removeSignal(count);
-             * count.value++; // will increase the count but will no longer trigger effect;
-             */
-            removeSignal: (signalInstance: Signal<any>) => void;
-        };
-    };
-    /**
-     * @description
-     * - 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: () => void;
-    #private;
-}
-import { Signal } from './Signal.mjs';
-type unwrapLazy = "vivth:unwrapLazy;";
-import { unwrapLazy } from '../common/lazie.mjs';
-export {};

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

@@ -1,38 +0,0 @@
-/**
- * @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} LISTARG
- * @extends {Derived<LISTARG[]>}
- */
-export class ListDerived<LISTARG extends import("../types/ListArg.mjs").ListArg> extends Derived<LISTARG[]> {
-    /**
-     * @typedef {import('../types/ListArg.mjs').ListArg} ListArg
-     * @typedef {import('../common/lazie.mjs').unwrapLazy} unwrapLazy
-     */
-    /**
-     * @description
-     * @param {(effectInstanceOptions:Omit<Effect["options"],
-     * unwrapLazy>)=>
-     * Promise<LISTARG[]>} 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: Omit<Effect["options"], "vivth:unwrapLazy;">) => Promise<LISTARG[]>);
-}
-import { Derived } from './Derived.mjs';
-import { Effect } from './Effect.mjs';

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

@@ -1,69 +0,0 @@
-/**
- * @description
- * - class helpers to define pathReference;
- * - is a singleton;
- * - most of functionality need to access `Paths.root`, if you get warning, you can instantiate `Paths` before running anything;
- */
-export class Paths {
-    /**
-     * @type {Paths|undefined}
-     */
-    static "__#private@#instance": Paths | undefined;
-    /**
-     * @description
-     * - reference for rootPath
-     * - `Paths` needed to be instantiated via:
-     * >- `Paths` constructor;
-     * >- `Setup.paths` constructor;
-     * @type {string|undefined}
-     */
-    static get root(): string | undefined;
-    /**
-     * @description
-     * - normalize path separator to forward slash `/`;
-     * @param {string} path_
-     * @returns {string}
-     * @example
-     * import { Paths } from 'vivth';
-     *
-     * Paths.normalize('file:\\D:\\myFile.mjs'); //  "file://D://myFile.mjs"
-     */
-    static normalize: (path_: string) => string;
-    /**
-     * @description
-     * - normalize path separator to forward slash `/`;
-     * - then starts with forward slash `/`;
-     * @param {string} path_
-     * @returns {`/${string}`}
-     * @example
-     * import { Paths } from 'vivth';
-     *
-     * Paths.normalizesForRoot('path\\myFile.mjs'); //  "/path/myFile.mjs"
-     */
-    static normalizesForRoot: (path_: string) => `/${string}`;
-    /**
-     * @description
-     * @param {Object} options
-     * @param {string} options.root
-     * - browser:
-     * ```js
-     * location.origin
-     * ```
-     * - node/bun compatible:
-     * ```js
-     * import process from 'node:process';
-     * process.env.INIT_CWD ?? process.cwd()
-     * ```
-     * - 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;
-}