vivth 1.3.2 → 1.3.4

package/types/index.d.mts

@@ -1,3 +1,4 @@
+export { ToBundledJSPlugin } from "./src/bundler/adds/ToBundledJSPlugin.mjs";
 export { CompileJS } from "./src/bundler/CompileJS.mjs";
 export { CreateESPlugin } from "./src/bundler/CreateESPlugin.mjs";
 export { EsBundler } from "./src/bundler/EsBundler.mjs";
@@ -18,13 +19,18 @@ export { SafeExit } from "./src/class/SafeExit.mjs";
 export { Setup } from "./src/class/Setup.mjs";
 export { Signal } from "./src/class/Signal.mjs";
 export { WorkerMainThread } from "./src/class/WorkerMainThread.mjs";
+export { WorkerResult } from "./src/class/WorkerResult.mjs";
+export { WorkerThread } from "./src/class/WorkerThread.mjs";
 export { Base64URL } from "./src/common/Base64URL.mjs";
 export { Base64URLFromFile } from "./src/common/Base64URLFromFile.mjs";
+export { Dev } from "./src/common/Dev.mjs";
 export { EventNameSpace } from "./src/common/EventNameSpace.mjs";
+export { Trace } from "./src/common/Trace.mjs";
 export { JSautoDOC } from "./src/doc/JSautoDOC.mjs";
 export { CreateImmutable } from "./src/function/CreateImmutable.mjs";
 export { EventCheck } from "./src/function/EventCheck.mjs";
 export { EventObject } from "./src/function/EventObject.mjs";
+export { GetNamedImportAlias } from "./src/function/GetNamedImportAlias.mjs";
 export { GetRuntime } from "./src/function/GetRuntime.mjs";
 export { IsAsync } from "./src/function/IsAsync.mjs";
 export { LazyFactory } from "./src/function/LazyFactory.mjs";
@@ -33,10 +39,8 @@ export { Try } from "./src/function/Try.mjs";
 export { TryAsync } from "./src/function/TryAsync.mjs";
 export { TrySync } from "./src/function/TrySync.mjs";
 export { TsToMjs } from "./src/function/TsToMjs.mjs";
-export { WorkerResult } from "./src/class/WorkerResult.mjs";
-export { WorkerThread } from "./src/class/WorkerThread.mjs";
-export { ToBundledJSPlugin } from "./src/bundler/adds/ToBundledJSPlugin.mjs";
 export type AnyButUndefined = import("./src/types/AnyButUndefined.mjs").AnyButUndefined;
+export type DevTestCB = import("./src/types/DevTestCB.mjs").DevTestCB;
 export type ExtnameType = import("./src/types/ExtnameType.mjs").ExtnameType;
 export type IsListSignal = import("./src/types/IsListSignal.mjs").IsListSignal;
 export type ListArg = import("./src/types/ListArg.mjs").ListArg;
@@ -46,3 +50,4 @@ export type MutationType = import("./src/types/MutationType.mjs").MutationType;
 export type QCBFIFOReturn = import("./src/types/QCBFIFOReturn.mjs").QCBFIFOReturn;
 export type QCBReturn = import("./src/types/QCBReturn.mjs").QCBReturn;
 export type Runtime = import("./src/types/Runtime.mjs").Runtime;
+export type VivthDevCodeBlockStringType = import("./src/types/VivthDevCodeBlockStringType.mjs").VivthDevCodeBlockStringType;

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

@@ -1,9 +1,9 @@
 /**
  * @description
  * - function to compile `.ts`|`.mts`|`.mjs` file, into a single executable;
- * - also generate js representation;
+ * - also generate js representation of the `bundled` version of the target;
  * - uses [pkg](https://www.npmjs.com/package/pkg), [bun](https://bun.com/docs/bundler/executables), and [deno](https://docs.deno.com/runtime/reference/cli/compile/) compiler under the hood;
- * >- they are used only as packaging agent, and doesn't necessarily supports their advanced feature, such as, assets bundling(use [FSInline](#fsinline) instead);
+ * >- they are used only as packaging/compiler agent, and doesn't necessarily supports their advanced feature, such as, assets bundling(use [`FSInline`](#fsinline) instead);
  * >- `WorkerThread` will be converted to inline using `FSInline` too;
  *
  * !!!WARNING!!!
@@ -22,8 +22,12 @@
  * @param {string} options.entryPoint
  * - need to be manually prefixed;
  * @param {BufferEncoding} [options.encoding]
- * - write and read encoding for the sources;
+ * - read and write encoding for the sources;
  * - default: `utf-8`;
+ * @param {(entryPointContent:string)=>string} [options.preprocessEntryPoint]
+ * - to modify entry point before bundling;
+ * - `entryPointContent` is the original string of the entry point;
+ * - returned value then passed to `ESBundler`;
  * @param {boolean} options.minifyFirst
  * - minify the bundle before compilation;
  * @param {string} options.outDir
@@ -43,39 +47,65 @@
  * bundledJSFile:string|undefined
  * }>>}
  * @example
+ * import process from 'node:process';
  * import { join } from 'node:path';
  *
- * import { CompileJS, Paths } from 'vivth';
+ * import { CompileJS, Console, Paths, Setup } from 'vivth';
+ *
+ * const { paths, safeExit } = Setup;
+ * new paths({
+ * 	root: process.env.INIT_CWD ?? process.cwd(),
+ * });
+ * new safeExit({
+ * 	eventNames: ['SIGINT', 'SIGTERM'],
+ * 	terminator: () => process.exit(0),
+ * 	listener: (eventName) => {
+ * 		process.once(eventName, function () {
+ * 			if (!safeExit.instance) {
+ * 				return;
+ * 			}
+ * 			safeExit.instance.exiting.correction(true);
+ * 			Console.log(`safe exit via "${eventName}"`);
+ * 		});
+ * 	},
+ * });
+ * const pathRoot = Paths.root;
+ * if (pathRoot) {
+ * 	const [[, error], [, errorbun]] = await Promise.all([
+ * 		CompileJS({
+ * 			entryPoint: join(pathRoot, '/dev/myEntryPoint.mjs'),
+ * 			minifyFirst: true,
+ * 			outDir: join(pathRoot, '/dev-pkg/'),
+ * 			compiler: 'pkg',
+ * 			compilerArguments: {
+ * 				target: 'node18-win-x64',
+ * 			},
+ * 			encoding: 'utf-8',
+ * 		}),
+ * 		await CompileJS({
+ * 			entryPoint: join(pathRoot, '/dev/myEntryPoint.mjs'),
+ * 			minifyFirst: true,
+ * 			outDir: join(pathRoot, '/dev-bun/'),
+ * 			compiler: 'bun',
+ * 			compilerArguments: {
+ * 				target: 'bun-win-x64',
+ * 			},
+ * 			encoding: 'utf-8',
+ * 		}),
+ * 	]);
+ * 	if (error || errorbun) {
+ * 		Console.error({ error, errorbun });
+ * 	}
+ * }
  *
- * const [[resultPkg, errorPkg], [resultBun, errorBun]] = await Promise.all([
- * 	CompileJS({
- * 		entryPoint: join(Paths.root, '/dev'),
- * 		minifyFirst: true,
- * 		outDir: join(Paths.root, '/dev-pkg'),
- * 		compiler: 'pkg',
- * 		compilerArguments: {
- * 			target: ['node18-win-x64'],
- * 		},
- * 		esBundlerPlugins: [],
- * 	}),
- * 	CompileJS({
- * 		entryPoint: join(Paths.root, '/dev'),
- * 		minifyFirst: true,
- * 		outDir: join(Paths.root, '/dev-pkg'),
- * 		compiler: 'bun',
- * 		compilerArguments: {
- * 			target: ['bun-win-x64'],
- * 		},
- * 		esBundlerPlugins: [],
- * 	}),
- * ])
  */
-export function CompileJS({ entryPoint, minifyFirst, encoding, outDir, compiler, compilerArguments, esBundlerPlugins, }: {
+export function CompileJS({ entryPoint, minifyFirst, encoding, outDir, preprocessEntryPoint, compiler, compilerArguments, esBundlerPlugins, }: {
     entryPoint: string;
     encoding?: BufferEncoding | undefined;
+    preprocessEntryPoint?: ((entryPointContent: string) => string) | undefined;
     minifyFirst: boolean;
     outDir: string;
-    compiler?: "bun" | "deno" | "pkg" | undefined;
+    compiler?: "pkg" | "bun" | "deno" | undefined;
     compilerArguments?: Record<string, string> | undefined;
     esBundlerPlugins?: import("esbuild").Plugin[] | undefined;
 }): ReturnType<typeof TryAsync<{

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

@@ -7,7 +7,7 @@
  * - the code can also uses composites from the result from multiple readFiles;
  * @param {string} options.root
  * - use dirname of said fileString path;
- * @param {'.mts'|'.ts'|'.mjs'} options.extension
+ * @param {'.mts'|'.ts'|'.mjs'|'.cjs'} options.extension
  * @param {boolean} [options.withBinHeader]
  * @param {Omit<Parameters<build>[0],
  * 'entryPoints'|'bundle'|'write'|'sourcemap'>
@@ -29,7 +29,7 @@
 export function EsBundler({ content, extension, root, withBinHeader }: {
     content: string;
     root: string;
-    extension: ".mts" | ".ts" | ".mjs";
+    extension: ".mts" | ".ts" | ".mjs" | ".cjs";
     withBinHeader?: boolean | undefined;
 }, esbuildOptions?: Omit<Parameters<typeof build>[0], "entryPoints" | "bundle" | "write" | "sourcemap">): ReturnType<typeof TryAsync<string>>;
 import { build } from 'esbuild';

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

@@ -1,7 +1,10 @@
 /**
  * @description
- * - class helper to inline file;
+ * - 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 {
     /**
@@ -12,6 +15,9 @@ export class FSInline {
      * @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';
      *
@@ -21,6 +27,7 @@ export class FSInline {
     /**
      * @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

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

@@ -1,6 +1,7 @@
 /**
  * @description
  * - collections of static method to analyze content for `FSInline`;
+ * - mostly used internally;
  */
 export class FSInlineAnalyzer {
     /**

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

@@ -1,11 +1,13 @@
 /**
  * @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);
+ * - 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`;
+ * >- `${fileName}.mjs` -> seek for and use `${fileName}Bundled.mjs`, if not found use `${fileName}.mjs`;
+ * >- removes `Dev.vivthDevCodeBlock` code block;
  * @param {string} includedInPath
- * - is generalized, you can freely uses forward or backward slash;
+ * - is generalized path, you can freely uses forward or backward slash;
  * @returns {ReturnType<CreateESPlugin>}
  * @example
  * import { ToBundledJSPlugin } from 'vivth';
@@ -13,4 +15,5 @@
  * export const myBundledPlugin = ToBundledJSPlugin('/myProjectName/src/');
  */
 export function ToBundledJSPlugin(includedInPath: string): ReturnType<typeof CreateESPlugin>;
+export function removeVivthDevCodeBlock(originalContent_: string): string;
 import { CreateESPlugin } from '../CreateESPlugin.mjs';

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

@@ -44,14 +44,14 @@ export class EventSignal<ISLIST extends boolean> {
          * @description
          * - remove subscriber from the named `EventSignal_instance`;
          * @param {string} name
-         * @param {import('./Effect.mjs').Effect} effect
+         * @param {import('./Effect.mjs').Effect} effectInstance
          * @returns {void}
          * @example
          * import { EventSignal } from 'vivth';
          *
          * EventSignal.remove.subscriber('yourEventSignalName', myEffectInstance);
          */
-        subscriber: (name: string, effect: import("./Effect.mjs").Effect) => void;
+        subscriber: (name: string, effectInstance: import("./Effect.mjs").Effect) => void;
         /**
          * @static remove
          * @description
@@ -83,14 +83,14 @@ export class EventSignal<ISLIST extends boolean> {
              * @description
              * - remove subscriber from the named `EventSignal_instance`;
              * @param {string} name
-             * @param {import('./Effect.mjs').Effect} effect
+             * @param {import('./Effect.mjs').Effect} effectInstance
              * @returns {void}
              * @example
              * import { EventSignal } from 'vivth';
              *
              * EventSignal.remove.subscriber('yourEventSignalName', myEffectInstance);
              */
-            subscriber: (name: string, effect: import("./Effect.mjs").Effect) => void;
+            subscriber: (name: string, effectInstance: import("./Effect.mjs").Effect) => void;
             /**
              * @static remove
              * @description
@@ -170,7 +170,7 @@ export class EventSignal<ISLIST extends boolean> {
          * @instance remove
          * @description
          * - remove subscriber from the `EventSignal_instance`;
-         * @param {import('./Effect.mjs').Effect} effect
+         * @param {import('./Effect.mjs').Effect} effectInstance
          * @returns {void}
          * @example
          * import { EventSignal, Effect, Console } from 'vivth';
@@ -184,7 +184,7 @@ export class EventSignal<ISLIST extends boolean> {
          * myEventSignal.dispatch.value = 'hey';
          * eventSignal_instance.remove.subscriber(myEffectInstance);
          */
-        subscriber: (effect: import("./Effect.mjs").Effect) => void;
+        subscriber: (effectInstance: import("./Effect.mjs").Effect) => void;
         /**
          * @instance remove
          * @description
@@ -227,7 +227,7 @@ export class EventSignal<ISLIST extends boolean> {
              * @instance remove
              * @description
              * - remove subscriber from the `EventSignal_instance`;
-             * @param {import('./Effect.mjs').Effect} effect
+             * @param {import('./Effect.mjs').Effect} effectInstance
              * @returns {void}
              * @example
              * import { EventSignal, Effect, Console } from 'vivth';
@@ -241,7 +241,7 @@ export class EventSignal<ISLIST extends boolean> {
              * myEventSignal.dispatch.value = 'hey';
              * eventSignal_instance.remove.subscriber(myEffectInstance);
              */
-            subscriber: (effect: import("./Effect.mjs").Effect) => void;
+            subscriber: (effectInstance: import("./Effect.mjs").Effect) => void;
             /**
              * @instance remove
              * @description

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

@@ -3,6 +3,27 @@
  * - collection of static methods of file access with added safety to mkdir before proceeding;
  */
 export class FileSafe {
+    /**
+     * @description
+     * - method to safely detects whether filePaths exist;
+     * - uses fs/promises access under the hood;
+     * - also returning promise of result & error as value;
+     * @param {string} filePath
+     * @returns {ReturnType<typeof TryAsync<true>>}
+     * @example
+     * import { join } from 'node:path';
+     * import { FileSafe, Paths } from 'vivth';
+     *
+     * const [, error] = await FileSafe.write(
+     * 	join(Paths.root, '/some/path.mjs'),
+     * );
+     * if (!error) {
+     * 	// file exists
+     * } else {
+     * 	// file not exists
+     * }
+     */
+    static exist: (filePath: string) => ReturnType<typeof TryAsync<true>>;
     /**
      * @description
      * - method to create file safely by recursively mkdir the dirname of the outFile;

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

@@ -40,7 +40,7 @@ export class ListSignal<LISTARG extends import("../types/ListArg.mjs").ListArg>
          * @instance arrayMethods
          * @description
          * - reference to structuredClone elements of `value`;
-         * - calling doesn't notify
+         * - calling doesn't notify for changes;
          * @returns {Array<LISTARG>}
          */
         readonly structuredClone: Array<LISTARG>;
@@ -146,7 +146,7 @@ export class ListSignal<LISTARG extends import("../types/ListArg.mjs").ListArg>
              * @instance arrayMethods
              * @description
              * - reference to structuredClone elements of `value`;
-             * - calling doesn't notify
+             * - calling doesn't notify for changes;
              * @returns {Array<LISTARG>}
              */
             readonly structuredClone: Array<LISTARG>;

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

@@ -7,6 +7,7 @@
  * >- destructuring is meant for extensive typehelper;
  * >- and destructuring can lead to unhandled error here and there;
  * >- therefore error as value is introduced to help to prevent error on runtime;
+ * - made primarily for generating string file, that are purely managed programatically;
  * @template {LitExpKeyType} KEYS
  */
 export class LitExp<KEYS extends import("../types/LitExpKeyType.mjs").LitExpKeyType> {

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

@@ -51,15 +51,8 @@ export class Paths {
      * ```
      * - node/bun compatible:
      * ```js
-     * process?.env?.INIT_CWD ?? process?.cwd()
-     * ```
-     * - deno: need for `deno run --allow-env --allow-read your_script.ts`:
-     * ```js
-     * Deno.env.get("INIT_CWD") ?? Deno.cwd()
-     * ```
-     * - pkg:
-     * ```js
-     * __dirname
+     * import process from 'node:process';
+     * process.env.INIT_CWD ?? process.cwd()
      * ```
      * - other: you need to check your JSRuntime for the rootPath reference;
      * @example

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

@@ -19,9 +19,9 @@ export class QChannel<DEFINEDANY extends import("../types/AnyButUndefined.mjs").
      * import { QChannel } from 'vivth';
      *
      * const myMappedQref = (window['myMappedQref'] = new Map());
-     * export const MyQClass = QChannel.makeQClass(myMappedQref);
+     * export const MyQClass = QChannel.setup(myMappedQref);
      */
-    static makeQClass: (uniqueMap: Map<import("../types/AnyButUndefined.mjs").AnyButUndefined, [Promise<any>, {}]>) => typeof QChannel;
+    static setup: (uniqueMap: Map<import("../types/AnyButUndefined.mjs").AnyButUndefined, [Promise<any>, {}]>) => typeof QChannel;
     /**
      * @type {Map<AnyButUndefined, [Promise<any>, {}]>}
      */
@@ -140,7 +140,7 @@ export class QChannel<DEFINEDANY extends import("../types/AnyButUndefined.mjs").
      * - `callbackBlock` with error as value:
      * - caveat:
      * >- no need to manually call resume();
-     * >- slightly less performant than `callback`;
+     * >- slightly less performant than `key`;
      * @template RESULT
      * @param {DEFINEDANY} keyID
      * @param {(options:Omit<QCBReturn,
@@ -149,7 +149,7 @@ export class QChannel<DEFINEDANY extends import("../types/AnyButUndefined.mjs").
      * @returns {ReturnType<typeof TryAsync<RESULT>>}
      * @example
      * const q = new QChannel('channel name');
-     * const [result, error] = await q.callback(keyID, async ({ isLastOnQ }) = > {
+     * const [result, error] = await q.callback(keyID, async ({ isLastOnQ }) => {
      * 	// if (!isLastOnQ()) { // imperative debounce if needed
      * 	// 	return;
      * 	// }

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

@@ -26,14 +26,10 @@ export class SafeExit {
      *  ['SIGINT', 'SIGTERM']
      * ```
      * @param {()=>void} options.terminator
-     * - standard node/bun:
+     * - standard, process must be imported statically from 'node:process':
      * ```js
      * () => process.exit(0),
      * ```
-     * - Deno:
-     * ```js
-     * () => Deno.exit(0),
-     * ```
      * @param {(eventName:string)=>void} [options.listener]
      * - default value
      * ```js
@@ -42,34 +38,21 @@ export class SafeExit {
      * 		SafeExit.instance.exiting.correction(true);
      * 		Console.log(`safe exit via "${eventName}"`);
      * 	});
-     * };
-     * ```
-     * - example Deno:
-     * ```js
-     * (eventName) => {
-     * 	const sig = Deno.signal(eventName);
-     * 		for await (const _ of sig) {
-     * 			exiting.correction(true);
-     * 			sig.dispose();
-     * 			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 process from 'node:process';
      * import { SafeExit, Console } from 'vivth';
      *
      * new SafeExit({
      * 	eventNames: ['SIGINT', 'SIGTERM', ...eventNames],
-     * 	terminator : () => process.exit(0), // OR on deno () => Deno.exit(0),
-     * 	// optional deno example
+     * 	terminator : () => process.exit(0),
      * 	listener : (eventName) => {
-     * 		const sig = Deno.signal(eventName);
-     * 			for await (const _ of sig) {
-     * 				exiting.correction(true);
-     * 				sig.dispose();
+     * 			process.once(eventName, function () {
+     * 				SafeExit.instance?.exiting.correction(true);
      * 				Console.log(`safe exit via "${eventName}"`);
-     * 			}
+     * 			});
      * 	}
      * });
      */
@@ -111,7 +94,7 @@ export class SafeExit {
      * 	// code
      * }
      * SafeExit.instance.addCallback(exitCallback);
-     *
+     * // somewhere else
      * SafeExit.instance.removeCallback(exitCallback);
      */
     removeCallback: (cb: () => (Promise<void>)) => void;

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

@@ -13,15 +13,12 @@ export class Setup {
      * 	// eventNames are blank by default, you need to manually name them all;
      * 	// 'exit' will be omited, as it might cause async callbacks failed to execute;
      * 	eventNames: ['SIGINT', 'SIGTERM', ...eventNames],
-     * 	terminator = () => process.exit(0), // OR on deno () => Deno.exit(0),
-     * 	// optional deno example
-     * 	listener = (eventName) => {
-     * 		const sig = Deno.signal(eventName);
-     * 			for await (const _ of sig) {
-     * 				exiting.correction(true);
-     * 				sig.dispose();
+     * 	terminator : () => process.exit(0),
+     * 	listener : (eventName) => {
+     * 			process.once(eventName, function () {
+     * 				SafeExit.instance?.exiting.correction(true);
      * 				Console.log(`safe exit via "${eventName}"`);
-     * 			}
+     * 			});
      * 	}
      * });
      */

package/types/src/common/Base64URL.d.mts

@@ -2,21 +2,23 @@
  * @description
  * - create inline base64 url;
  * - usage:
- * >- can be extremely usefull to display file on desktop app webview, without exposing http server;
+ * >- can be extremely usefull to display file on desktop app `webview` or any bundled browser, without exposing http server;
  * @param {string} fileString
  * @param {string} mimeType
  * @param {(string:string)=>string} btoaFunction
  * - check your js runtime `btoa`;
  * - node compatible:
  * ```js
- * (str, prevBufferEncoding) =>
- * 	Buffer.from(str, prevBufferEncoding).toString('base64')
+ * (str, prevBufferEncoding) => {
+ * 	return Buffer.from(str, prevBufferEncoding).toString('base64');
+ * }
  * ```
  * @returns {string}
  * @example
  * import { Base64URL } from 'vivth'
  * import fileString from './fileString.mjs';
  *
+ * // example for browser;
  * Base64URL(fileString, 'application/javascript', btoa);
  */
 export function Base64URL(fileString: string, mimeType: string, btoaFunction: (string: string) => string): string;

package/types/src/common/Dev.d.mts

@@ -0,0 +1,68 @@
+/**
+ * @typedef {import("../types/VivthDevCodeBlockStringType.mjs").VivthDevCodeBlockStringType} VivthDevCodeBlockStringType
+ * @typedef {import('../types/DevTestCB.mjs').DevTestCB} DevTestCB
+ */
+/**
+ * @description
+ * - class helper for `devTime` only code block;
+ */
+export class Dev {
+    /**
+     * @description
+     * - persistent variable(during `devTime` and `bundled`);
+     * - can be used as `condition` for checking whether it is in `devTime` or `bundled`;
+     * @type {boolean}
+     * @example
+     * import { Dev } from 'vivth';
+     *
+     * if (Dev.isDev) {
+     * 	// this code block will presist even on `bundled`;
+     * }
+     */
+    static isDev: boolean;
+    /**
+     * @type {Signal<Map<string,Awaited<ReturnType<typeof TryAsync<boolean>>>>>}
+     */
+    static #notifications: Signal<Map<string, Awaited<ReturnType<typeof TryAsync<boolean>>>>>;
+    /**
+     * @type {DevTestCB}
+     */
+    static #test: DevTestCB;
+    static #effectForCheck: Effect & {
+        "vivth:unwrapLazy;": () => Effect;
+    };
+    /**
+     * @description
+     * - to wrap `devTime` only code block;
+     * - when bundled uses `EsBundler` or esbuild with `ToBundledJSPlugin` plugin, the code block will be removed on the bundled version;
+     * @param {(options:{test:DevTestCB})=>Promise<void>} callback
+     * - also provide `test` method for inline testing:
+     * >- which is wrapped in `TryAsync`, throwed errors will automatically return `false`;
+     * @param {VivthDevCodeBlockStringType} _closing
+     * - it is needed to detect the code block closing;
+     * - should use single or double quote and not back tick;
+     * @returns {Promise<void>}
+     * @example
+     * import { Dev, Signal } from 'vivth';
+     *
+     * Dev.vivthDevCodeBlock(async function () {
+     * 	// this code block will be removed on `bundled` version;
+     * }, 'vivthDevCodeBlock');
+     *
+     * const numberSignal = new Signal(0);
+     * Dev.vivthDevCodeBlock(async ({ test }) => {
+     * 	// this code block will be removed on `bundled` version;
+     * 	const [{ removeId: removeTest }] = await Promise.all([
+     * 		test(async () => numberSignal.value === 0)
+     * 	])
+     * }, 'vivthDevCodeBlock');
+     */
+    static vivthDevCodeBlock: (callback: (options: {
+        test: DevTestCB;
+    }) => Promise<void>, _closing: VivthDevCodeBlockStringType) => Promise<void>;
+}
+export type VivthDevCodeBlockStringType = import("../types/VivthDevCodeBlockStringType.mjs").VivthDevCodeBlockStringType;
+export type DevTestCB = import("../types/DevTestCB.mjs").DevTestCB;
+import { Signal } from '../class/Signal.mjs';
+import { TryAsync } from '../function/TryAsync.mjs';
+import { Effect } from '../class/Effect.mjs';

package/types/src/common/DevBundled.d.mts

@@ -0,0 +1,3 @@
+export class Dev {
+    static isDev: boolean;
+}

package/types/src/common/Trace.d.mts

@@ -0,0 +1,14 @@
+/**
+ * @description
+ * - returns position of stack trace as string, formatted as `fileName:lineNumber:columnNumber`;
+ * - extremely usefull for:
+ * >- jumping positions to code line;
+ * >- creating dynamic string id;
+ * @param {number} traceIndex
+ * @returns {string}
+ * @example
+ * import { Trace, Console } from 'vivth';
+ *
+ * Console.log(Trace(3)); // "D://test.mjs:3:13"
+ */
+export function Trace(traceIndex: number): string;

package/types/src/doc/JSautoDOC.d.mts

@@ -4,21 +4,22 @@
  * - this autodocumenter uses [chokidar](https://npmjs.com/package/chokidar) under the hood;
  * - this class also is used to generate this `README.md`;
  * - behaviours:
+ * >- auto export must follows the following rules;
  * >1) add `"at"noautodoc` on self closing jsdoc comment to opt out from generating documentation on said file;
- * >>- auto export must follows the following rules, and there's no way to override;
- * >2) export all named exported 'const'|'function'|'async function'|'class', alphanumeric name, started with Capital letter, same name with fileName on `options.pahts.file`;
- * >3) declare typedef of existing typedef with alphanumeric name, started with Capital letter, same name with fileName, and have no valid export like on point <sup>1</sup> on `options.pahts.file`;
- * >4) create `README.md` based on, `options.paths.dir` and `README.src.md`;
+ * >2) will (generate) export all named exported 'const'|'function'|'async function'|'class', alphanumeric name, started with Capital letter, same name with fileName on `options.paths.file`;
+ * >3) will (generate) declare typedef of existing typedef with alphanumeric name, started with Capital letter, same name with fileName, and have no valid export like on point <sup>1</sup> on `options.paths.file`;
+ * >4) will (generate) create `README.md` based on, `options.paths.dir` and `README.src.md`;
  * >5) extract `"at"description` jsdoc:
  * >>- on static/prop that have depths, all of children should have `"at"static`/`"at"instance` `nameOfImmediateParent`, same block but before `"at"description` comment line;
  * >>- `"at"description` are treated as plain `markdown`;
  * >>- first `"at"${string}` after `"at"description` until `"at"example` will be treated as `javascript` comment block on the `markdown`;
  * >>- `"at"example` are treated as `javascript` block on the `markdown` file, and should be placed last on the same comment block;
  * >>- you can always look at `vivth/src` files to check how the source, and the `README.md` and `index.mjs` documentation/generation results;
- * >6) this types of arrow functions will be converted to regullar function, for concise type emition:
+ * >6) this types of arrow functions will be converted to regullar function, for concise type emition, includes:
  * >>- validly exported function;
- * >>- static/instance method(s) with generic template;
- * >7) transpile `.ts` and `.mts` to `.mjs` same name and directory;
+ * >>- static/instance method with generic template;
+ * >7) transpile `.ts` and `.mts` to `.mjs` with same name and directory;
+ * >>- use `"at"preserve` to preserve tsdoc comment section;
  */
 export class JSautoDOC {
     /**