vivth 1.3.2 → 1.3.3

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/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

@@ -57,10 +57,6 @@ export class Paths {
      * ```js
      * Deno.env.get("INIT_CWD") ?? Deno.cwd()
      * ```
-     * - pkg:
-     * ```js
-     * __dirname
-     * ```
      * - other: you need to check your JSRuntime for the rootPath reference;
      * @example
      * import { Paths } from 'vivth';

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

@@ -42,7 +42,7 @@ export class SafeExit {
      * 		SafeExit.instance.exiting.correction(true);
      * 		Console.log(`safe exit via "${eventName}"`);
      * 	});
-     * };
+     * }
      * ```
      * - example Deno:
      * ```js
@@ -65,11 +65,11 @@ export class SafeExit {
      * 	// optional deno example
      * 	listener : (eventName) => {
      * 		const sig = Deno.signal(eventName);
-     * 			for await (const _ of sig) {
-     * 				exiting.correction(true);
-     * 				sig.dispose();
-     * 				Console.log(`safe exit via "${eventName}"`);
-     * 			}
+     * 		for await (const _ of sig) {
+     * 			exiting.correction(true);
+     * 			sig.dispose();
+     * 			Console.log(`safe exit via "${eventName}"`);
+     * 		}
      * 	}
      * });
      */
@@ -111,7 +111,7 @@ export class SafeExit {
      * 	// code
      * }
      * SafeExit.instance.addCallback(exitCallback);
-     *
+     * // somewhere else
      * SafeExit.instance.removeCallback(exitCallback);
      */
     removeCallback: (cb: () => (Promise<void>)) => void;

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 {
     /**

package/types/src/function/GetNamedImportAlias.d.mts

@@ -0,0 +1,22 @@
+/**
+ * @description
+ * - regex helper for:
+ * >- get named import; OR
+ * >- alias of named import;
+ * @param {string} content
+ * @param {string} moduleName
+ * @param {string} packageName
+ * @returns {string|undefined}
+ * @example
+ * import { GetNamedImportAlias } from 'vivth';
+ *
+ * const checkNoAlias = `
+ * import { something } from 'packageName';
+ * `
+ * const checkAlias = `
+ * import { something as somethingElse } from 'packageName';
+ * `
+ * GetNamedImportAlias(checkNoAlias, 'something', 'packageName'); // 'something'
+ * GetNamedImportAlias(checkAlias, 'something', 'packageName'); // 'somethingElse'
+ */
+export function GetNamedImportAlias(content: string, moduleName: string, packageName: string): string | undefined;

package/types/src/function/LazyFactory.d.mts

@@ -29,7 +29,7 @@
  * const a = myInstance; // not yet initiated;
  * const b = a.myProp // imediately initiated;
  * // OR
- * myInstance["vivth:unwrapLazy;"]() // forcefully call the callback;
+ * myInstance["vivth:unwrapLazy;"]() // forcefully call factory generator;
  */
 export function LazyFactory<FACTORY>(factory: () => FACTORY): FACTORY & {
     [unwrapLazy]: () => FACTORY;

package/types/src/function/TsToMjs.d.mts

@@ -1,8 +1,8 @@
 /**
  * @description
- * - turn `.mts`||`.ts` file into `.mjs`, no bundling, just translation;
+ * - turn `.mts`||`.ts` file into `.mjs`, no bundling, just traspilation;
  * - on certain circumstance where `.mjs` result needed to be typed, you need to manually add `jsdoc`;
- * >- uses `"at"preserve` to register `jsdoc` inline;
+ * >- uses `"at"preserve` to register `jsdoc`;
  * @param {string} path_
  * - path from `Paths.root`;
  * @param {Object} [options]
@@ -15,7 +15,7 @@
  * @example
  * import { TsToMjs } from 'vivth';
  *
- * TsToMjs('./myFile.mts', { encoding: 'utf-8', overrideDir: './other/dir' });
+ * await TsToMjs('./myFile.mts', { encoding: 'utf-8', overrideDir: './other/dir' });
  */
 export function TsToMjs(path_: string, { overrideDir, encoding }?: {
     overrideDir?: string | undefined;

package/types/src/function/WithDefer.d.mts

@@ -0,0 +1,10 @@
+/**
+ * Description
+ * @param {(
+ * this:{defer:(tobeDefered:()=>Promise<void>)=>void}
+ * )=>Promise<void>} cb
+ * @returns {void}
+ */
+export function WithDefer(cb: (this: {
+    defer: (tobeDefered: () => Promise<void>) => void;
+}) => Promise<void>): void;

package/types/src/types/DevTestCB.d.mts

@@ -0,0 +1,3 @@
+export type DevTestCB = (testName: string, testCallback: () => Promise<boolean>) => Promise<{
+    removeId: () => void;
+}>;

package/types/src/types/IsDevCBStringType.d.mts

@@ -0,0 +1,4 @@
+/**
+ * - closing helper for `Dev.IsDevCB`;
+ */
+export type IsDevCBStringType = "IsDevCB";

package/types/src/types/Runtime.d.mts

@@ -1 +1,4 @@
+/**
+ * - for popular runtimes check;
+ */
 export type Runtime = "node" | "bun" | "deno" | "browser" | "unknown";

package/types/src/types/VivthDevCodeBlockStringType.d.mts

@@ -0,0 +1,4 @@
+/**
+ * - closing helper for `Dev.vivthDevCodeBlock`;
+ */
+export type VivthDevCodeBlockStringType = "vivthDevCodeBlock";