vivth 1.3.3 → 1.3.5

package/README.md

@@ -31,6 +31,11 @@ npm i vivth
   >   > - abstracted via `esbuild`;
   > - opionated `compiler`;
   >   > - abstracted via `pkg`, `deno`, and `bun`;
+- when using runtime that doesn't provide specific common modules golbally(like `Deno`), dev should
+  import it statically from `node:module_name`, example:
+  ```js
+  import process from "node:process";
+  ```
 
 ## versions:
 
@@ -189,16 +194,18 @@ export const myBundledPlugin = ToBundledJSPlugin("/myProjectName/src/");
 - <i>example</i>:
 
 ```js
+import process from "node:process";
 import { join } from "node:path";
+
 import { CompileJS, Console, Paths, Setup } from "vivth";
 
 const { paths, safeExit } = Setup;
 new paths({
-  root: process?.env?.INIT_CWD ?? process?.cwd(),
+  root: process.env.INIT_CWD ?? process.cwd(),
 });
 new safeExit({
   eventNames: ["SIGINT", "SIGTERM"],
-  terminator: () => process.exit(0), // OR on deno () => Deno.exit* (0),
+  terminator: () => process.exit(0),
   listener: (eventName) => {
     process.once(eventName, function () {
       if (!safeExit.instance) {
@@ -1074,6 +1081,33 @@ eventSignal_instance.remove.ref();
 
 - collection of static methods of file access with added safety to mkdir before proceeding;
 
+#### reference:`FileSafe.exist`
+
+- method to safely detects whether filePaths exist;
+- uses fs/promises access under the hood;
+- also returning promise of result & error as value;
+
+```js
+/**
+ * @param {string} filePath
+ * @returns {ReturnType<typeof TryAsync<true>>}
+ */
+```
+
+- <i>example</i>:
+
+```js
+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
+}
+```
+
 #### reference:`FileSafe.write`
 
 - method to create file safely by recursively mkdir the dirname of the outFile;
@@ -1110,7 +1144,7 @@ const [, errorWrite] = await FileSafe.write(
 /**
  * @param {Parameters<typeof copyFile>[0]} sourceFile
  * @param {Parameters<typeof copyFile>[1]} destinationFile
- * @param {Parameters<typeof copyFile>[2]} mode
+ * @param {Parameters<typeof copyFile>[2]} [mode]
  * @returns {ReturnType<typeof TryAsync<void>>}
  */
 ```
@@ -1703,11 +1737,8 @@ const [resultOfMatchedAllAndGrouped, error] =
  * ```
  * - 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()
+ * import process from 'node:process';
+ * process.env.INIT_CWD ?? process.cwd()
  * ```
  * - other: you need to check your JSRuntime for the rootPath reference;
  */
@@ -1970,14 +2001,10 @@ const [result, error] = await q.callback(keyID, async ({ isLastOnQ }) => {
  *  ['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
@@ -1988,17 +2015,6 @@ const [result, error] = await q.callback(keyID, async ({ isLastOnQ }) => {
  * 	});
  * }
  * ```
- * - 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
  */
 ````
@@ -2006,22 +2022,19 @@ const [result, error] = await q.callback(keyID, async ({ isLastOnQ }) => {
 - <i>example</i>:
 
 ```js
- import { SafeExit, Console } from 'vivth';
-
- new SafeExit({
- 	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();
- 			Console.log(`safe exit via "${eventName}"`);
- 		}
- 	}
- });
+import process from "node:process";
+import { SafeExit, Console } from "vivth";
 
+new SafeExit({
+  eventNames: ["SIGINT", "SIGTERM", ...eventNames],
+  terminator: () => process.exit(0),
+  listener: (eventName) => {
+    process.once(eventName, function () {
+      SafeExit.instance?.exiting.correction(true);
+      Console.log(`safe exit via "${eventName}"`);
+    });
+  },
+});
 ```
 
 #### reference:`SafeExit_instance.exiting`
@@ -2098,24 +2111,20 @@ const [result, error] = await q.callback(keyID, async ({ isLastOnQ }) => {
 - <i>example</i>:
 
 ```js
- import { Setup, Console } from 'vivth';
-
- new Setup.safeExit({
- 	// 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();
- 				Console.log(`safe exit via "${eventName}"`);
- 			}
- 	}
- });
+import { Setup, Console } from "vivth";
 
+new Setup.safeExit({
+  // 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),
+  listener: (eventName) => {
+    process.once(eventName, function () {
+      SafeExit.instance?.exiting.correction(true);
+      Console.log(`safe exit via "${eventName}"`);
+    });
+  },
+});
 ```
 
 #### reference:`Setup.paths`

package/README.src.md

@@ -31,6 +31,11 @@ npm i vivth
   >   > - abstracted via `esbuild`;
   > - opionated `compiler`;
   >   > - abstracted via `pkg`, `deno`, and `bun`;
+- when using runtime that doesn't provide specific common modules golbally(like `Deno`), dev should
+  import it statically from `node:module_name`, example:
+  ```js
+  import process from 'node:process';
+  ```
 
 ## versions:
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "vivth",
-	"version": "1.3.3",
+	"version": "1.3.5",
 	"description": "library primitives",
 	"main": "index.mjs",
 	"types": "./types/index.d.mts",
@@ -36,8 +36,8 @@
 	},
 	"homepage": "https://github.com/hakimjazuli/vivth#readme",
 	"scripts": {
-		"dev-wo": "concurrently 'bun ./dev/index.mjs' 'bun tsc --watch'",
-		"dev": "concurrently 'bun --watch ./dev/index.mjs' 'bun tsc --watch'"
+		"dev-wo": "concurrently 'bun ./dev/auto-doc.mjs' 'bun tsc --watch'",
+		"dev": "concurrently 'bun --watch ./dev/auto-doc.mjs' 'bun tsc --watch'"
 	},
 	"sideEffects": false
 }

package/src/bundler/CompileJS.mjs

@@ -114,16 +114,18 @@ const getBinaryExtension = () => {
  * bundledJSFile:string|undefined
  * }>>}
  * @example
+ * import process from 'node:process';
  * import { join } from 'node:path';
+ *
  * import { CompileJS, Console, Paths, Setup } from 'vivth';
  *
  * const { paths, safeExit } = Setup;
  * new paths({
- * 	root: process?.env?.INIT_CWD ?? process?.cwd(),
+ * 	root: process.env.INIT_CWD ?? process.cwd(),
  * });
  * new safeExit({
  * 	eventNames: ['SIGINT', 'SIGTERM'],
- * 	terminator: () => process.exit(0), // OR on deno () => Deno.exit\* (0),
+ * 	terminator: () => process.exit(0),
  * 	listener: (eventName) => {
  * 		process.once(eventName, function () {
  * 			if (!safeExit.instance) {

package/src/bundler/adds/ToBundledJSPlugin.mjs

@@ -1,9 +1,11 @@
 // @ts-check
 
 import { basename, extname } from 'node:path';
-import { readFile, exists } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
+
 import { CreateESPlugin } from '../CreateESPlugin.mjs';
 import { GetNamedImportAlias } from '../../function/GetNamedImportAlias.mjs';
+import { FileSafe } from '../../class/FileSafe.mjs';
 
 /**
  * @param {string} originalContent_
@@ -74,8 +76,8 @@ export function ToBundledJSPlugin(includedInPath) {
 				new RegExp(`${originalBaseName}\$`.replace('.', '\\.'), ''),
 				`${realRef}${fileExt}`
 			);
-			const isExist = await exists(bundledFile);
-			if (isExist === false) {
+			const [, error] = await FileSafe.exist(bundledFile);
+			if (error) {
 				const originalContent = (await readFile(filePath)).toString('utf-8');
 				ret.contents = removeVivthDevCodeBlock(originalContent);
 				return ret;

package/src/class/FileSafe.mjs

@@ -1,6 +1,8 @@
 // @ts-check
-import { writeFile, mkdir, copyFile, rename, rm } from 'node:fs/promises';
+
+import { writeFile, mkdir, copyFile, rename, rm, access } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { constants } from 'node:fs';
 
 import { TryAsync } from '../function/TryAsync.mjs';
 
@@ -9,6 +11,33 @@ import { TryAsync } from '../function/TryAsync.mjs';
  * - 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 = async (filePath) => {
+		// @ts-expect-error
+		return await TryAsync(async () => {
+			await access(filePath, constants.F_OK);
+			return true;
+		});
+	};
 	/**
 	 * @description
 	 * - method to create file safely by recursively mkdir the dirname of the outFile;
@@ -42,7 +71,7 @@ export class FileSafe {
 	 * - also returning promise of result & error as value;
 	 * @param {Parameters<typeof copyFile>[0]} sourceFile
 	 * @param {Parameters<typeof copyFile>[1]} destinationFile
-	 * @param {Parameters<typeof copyFile>[2]} mode
+	 * @param {Parameters<typeof copyFile>[2]} [mode]
 	 * @returns {ReturnType<typeof TryAsync<void>>}
 	 * @example
 	 * import { join } from 'node:path';

package/src/class/Paths.mjs

@@ -1,7 +1,5 @@
 // @ts-check
 
-import { relative } from 'node:path';
-
 import { Console } from './Console.mjs';
 
 /**
@@ -25,11 +23,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()
+	 * import process from 'node:process';
+	 * process.env.INIT_CWD ?? process.cwd()
 	 * ```
 	 * - other: you need to check your JSRuntime for the rootPath reference;
 	 * @example

package/src/class/SafeExit.mjs

@@ -36,14 +36,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
@@ -54,32 +50,19 @@ export class SafeExit {
 	 * 	});
 	 * }
 	 * ```
-	 * - 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();
-	 * 			Console.log(`safe exit via "${eventName}"`);
-	 * 		}
+	 * 			process.once(eventName, function () {
+	 * 				SafeExit.instance?.exiting.correction(true);
+	 * 				Console.log(`safe exit via "${eventName}"`);
+	 * 			});
 	 * 	}
 	 * });
 	 */

package/src/class/Setup.mjs

@@ -20,15 +20,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/src/doc/JSautoDOC.mjs

@@ -5,6 +5,7 @@ import { readFile } from 'node:fs/promises';
 
 import prettier from 'prettier';
 import chokidar from 'chokidar';
+
 import { EventSignal } from '../class/EventSignal.mjs';
 import { parsedFile } from './parsedFile.mjs';
 import { SafeExit } from '../class/SafeExit.mjs';

package/src/doc/correctBeforeParse.mjs

@@ -1,9 +1,9 @@
 // @ts-check
 
+import { readFile, writeFile } from 'node:fs/promises';
 import { basename } from 'node:path';
 
 import { TryAsync } from '../function/TryAsync.mjs';
-import { readFile, writeFile } from 'node:fs/promises';
 import { Console } from '../class/Console.mjs';
 import { Timeout } from '../function/Timeout.mjs';
 import { LitExp } from '../class/LitExp.mjs';

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

@@ -47,16 +47,18 @@
  * bundledJSFile:string|undefined
  * }>>}
  * @example
+ * import process from 'node:process';
  * import { join } from 'node:path';
+ *
  * import { CompileJS, Console, Paths, Setup } from 'vivth';
  *
  * const { paths, safeExit } = Setup;
  * new paths({
- * 	root: process?.env?.INIT_CWD ?? process?.cwd(),
+ * 	root: process.env.INIT_CWD ?? process.cwd(),
  * });
  * new safeExit({
  * 	eventNames: ['SIGINT', 'SIGTERM'],
- * 	terminator: () => process.exit(0), // OR on deno () => Deno.exit\* (0),
+ * 	terminator: () => process.exit(0),
  * 	listener: (eventName) => {
  * 		process.once(eventName, function () {
  * 			if (!safeExit.instance) {

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;
@@ -28,7 +49,7 @@ export class FileSafe {
      * - also returning promise of result & error as value;
      * @param {Parameters<typeof copyFile>[0]} sourceFile
      * @param {Parameters<typeof copyFile>[1]} destinationFile
-     * @param {Parameters<typeof copyFile>[2]} mode
+     * @param {Parameters<typeof copyFile>[2]} [mode]
      * @returns {ReturnType<typeof TryAsync<void>>}
      * @example
      * import { join } from 'node:path';
@@ -40,7 +61,7 @@ export class FileSafe {
      * 	{ encoding: 'utf-8' }
      * );
      */
-    static copy: (sourceFile: Parameters<typeof copyFile>[0], destinationFile: Parameters<typeof copyFile>[1], mode: Parameters<typeof copyFile>[2]) => ReturnType<typeof TryAsync<void>>;
+    static copy: (sourceFile: Parameters<typeof copyFile>[0], destinationFile: Parameters<typeof copyFile>[1], mode?: Parameters<typeof copyFile>[2]) => ReturnType<typeof TryAsync<void>>;
     /**
      * @description
      * - method to rename file/dir safely by recursively mkdir the dirname of the dest;

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

@@ -51,11 +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()
+     * 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/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
@@ -44,32 +40,19 @@ export class SafeExit {
      * 	});
      * }
      * ```
-     * - 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();
-     * 			Console.log(`safe exit via "${eventName}"`);
-     * 		}
+     * 			process.once(eventName, function () {
+     * 				SafeExit.instance?.exiting.correction(true);
+     * 				Console.log(`safe exit via "${eventName}"`);
+     * 			});
      * 	}
      * });
      */

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}"`);
-     * 			}
+     * 			});
      * 	}
      * });
      */