vivth 1.4.10 → 1.5.0

package/src/common/EnvMode.mjs

@@ -0,0 +1,172 @@
+// @ts-check
+
+import { Console } from '../class/Console.mjs';
+import { Derived } from '../class/Derived.mjs';
+import { Effect } from '../class/Effect.mjs';
+import { Signal } from '../class/Signal.mjs';
+import { ForOfSync } from '../function/ForOfSync.mjs';
+import { LazyFactory } from '../function/LazyFactory.mjs';
+import { TryAsync } from '../function/TryAsync.mjs';
+import { FactoryKey } from './FactoryKey.mjs';
+import { TracePath } from './TracePath.mjs';
+
+/**
+ * @typedef {import('../typehints/EnvModeType.mjs').EnvModeType} EnvModeType
+ * @typedef {import('../typehints/DevTestCB.mjs').DevTestCB} DevTestCB
+ */
+
+/**
+ * @description
+ * - class helper for determining environtment mode to be `developement` or `production`;
+ */
+export class EnvMode {
+	/**
+	 * @type {Signal<EnvModeType>}
+	 */
+	// @ts-expect-error
+	static #mode = LazyFactory(() => new Signal('dev'));
+	/**
+	 * @description
+	 * - `Derived` wrapper of whether is in `dev` mode or `prod` not;
+	 * >- for listener only;
+	 * @type {Derived<EnvModeType>}
+	 * @example
+	 * import { EnvMode, Effect } from 'vivth/neutral';
+	 *
+	 * console.log(EnvMode.mode.value); // default: 'dev'
+	 *
+	 * // listeneing to changes;
+	 * new Effect(async({ subscribe }) => {
+	 * 	const mode = subscribe(EnvMode.mode).value;
+	 * 	// code
+	 * })
+	 */
+	static mode = LazyFactory(() => {
+		return new Derived(async ({ subscribe }) => {
+			return subscribe(EnvMode.#mode).value;
+		});
+	});
+	/**
+	 * @description
+	 * - enforce development or production mode;
+	 * - DO NOT EXPOSE THIS API TO UNSECURED ACCESS, DIRECTLY NOR INDIRECTLY;
+	 * @param {EnvModeType} mode
+	 * @returns {void}
+	 * @example
+	 * import { EnvMode } from 'vivth/neutral';
+	 *
+	 * EnvMode.enforce('dev'); // OR
+	 * EnvMode.enforce('prod');
+	 */
+	static enforce = (mode) => {
+		switch (mode) {
+			case 'dev':
+			case 'prod':
+				EnvMode.#mode.value = mode;
+				break;
+			default:
+				EnvMode.#mode.value = 'prod';
+				break;
+		}
+	};
+	/**
+	 * @type {Signal<Map<string,Awaited<ReturnType<typeof TryAsync<boolean>>>>>}
+	 */
+	static #notifications = LazyFactory(() => new Signal(new Map()));
+
+	/**
+	 * @type {DevTestCB}
+	 */
+	static #test = (testName, testCallback) => {
+		testName = `${testName}:'${TracePath((path) => {
+			return !path.includes('vivth/src/common/EnvMode.mjs');
+		})}'`;
+		EnvMode.#notifications.subscribers.notify(async ({ signalInstance }) => {
+			signalInstance.value.set(
+				testName,
+				await TryAsync(async () => {
+					return await testCallback();
+				}),
+			);
+		});
+		EnvMode.#effectForCheck[FactoryKey];
+		return {
+			removeId: () => {
+				EnvMode.#notifications.subscribers.notify(async ({ signalInstance }) => {
+					signalInstance.value.delete(testName);
+				});
+			},
+		};
+	};
+
+	static #effectForCheck = LazyFactory(
+		() =>
+			new Effect(async ({ subscribe }) => {
+				const notifications = subscribe(EnvMode.#notifications).value;
+				const testCount = notifications.size;
+				if (!testCount) {
+					return;
+				}
+				/**
+				 * @type {Set<string>}
+				 */
+				const succeedTests = new Set();
+				/**
+				 * @type {Set<string>}
+				 */
+				const failedTests = new Set();
+				ForOfSync(notifications, ([notificationID, [isCorrect, error]]) => {
+					if (error || isCorrect !== true) {
+						failedTests.add(notificationID);
+						return;
+					}
+					succeedTests.add(notificationID);
+				});
+				/**
+				 * @type {{
+				 * testCount:number,
+				 * succeed?: {count:string, testIDs:Set<string>},
+				 * failed?: {count:string, testIDs:Set<string>},
+				 * }}
+				 */
+				let warn = { testCount };
+				if (succeedTests.size) {
+					warn.succeed = {
+						count: `${succeedTests.size} of ${testCount}`,
+						testIDs: succeedTests,
+					};
+				}
+				if (failedTests.size) {
+					warn.failed = {
+						count: `${failedTests.size} of ${testCount}`,
+						testIDs: failedTests,
+					};
+				}
+				Console.warn(warn);
+			}),
+	);
+	/**
+	 * @description
+	 * @param {(options:{devTest:DevTestCB}|
+	 * {devTest:undefined})=>Promise<void>
+	 * } callback
+	 * - when on `dev` mode also provide `test` method for inline testing:
+	 * >- which is wrapped in `TryAsync`, throwed errors will automatically return `false`;
+	 * - for smaller bundle size, you can wrap the `devTest` with `BundleV.vivthUnBundledCodeBlock`;
+	 * @param {Effect["options"]["subscribe"]} [subscribe]
+	 * - optional whether to scope the callback into an `Effect`;
+	 * @returns {Promise<void>}
+	 */
+	static async codeBlock(callback, subscribe = undefined) {
+		/**
+		 * @type {EnvModeType|undefined}
+		 */
+		let mode;
+		if (!subscribe) {
+			mode = EnvMode.#mode.value;
+		} else {
+			mode = subscribe(EnvMode.#mode).value;
+		}
+		await callback(mode === 'dev' ? { devTest: EnvMode.#test } : { devTest: undefined });
+	}
+}

package/src/common/FactoryKey.mjs

@@ -0,0 +1,11 @@
+// @ts-check
+
+/**
+ * @description
+ * - key symbol to imediately generate object wrapped by `LazyFactory`;
+ * - usefull for Object that has different accessor behaviour when being get via Proxy, like:
+ * >- `Set<any>`;
+ * >- `Map<any, any>`;
+ * @type {symbol}
+ */
+export const FactoryKey = Symbol('FactoryKey');

package/src/common/Preferrence.mjs

@@ -0,0 +1,27 @@
+// @ts-check
+
+/**
+ * @description
+ * - class wrapper for `vivth` innerworking preferrences;
+ */
+export class Preferrence {
+	/**
+	 * @description
+	 * - default `vivth` innerworking encoding;
+	 * @type {BufferEncoding}
+	 */
+	static encoding = 'utf-8';
+	/**
+	 * @description
+	 * - setup `vivth `preffered encoding;
+	 * @param {Object} arg0
+	 * @param {typeof Preferrence["encoding"]} arg0.encoding
+	 * @example
+	 * import { Preferrence } from 'vivth/neutral';
+	 *
+	 * Preferrence.setup({ encoding: 'utf-8' });
+	 */
+	static setup = ({ encoding }) => {
+		Preferrence.encoding = encoding;
+	};
+}

package/src/common/Trace.mjs

@@ -11,7 +11,7 @@ import { Paths } from '../class/Paths.mjs';
  * @param {number} traceIndex
  * @returns {string}
  * @example
- * import { Trace, Console } from 'vivth';
+ * import { Trace, Console } from 'vivth/neutral';
  *
  * Console.log(Trace(3)); // "D://test.mjs:3:13"
  */

package/src/common/TracePath.mjs

@@ -1,7 +1,45 @@
 // @ts-check
 
 import { Paths } from '../class/Paths.mjs';
+import { GetRuntime } from '../function/GetRuntime.mjs';
+import { IsSameFile } from '../function/IsSameFile.mjs';
 
+/**
+ * - for browser
+ * @param {string} url
+ * @returns {string}
+ */
+function fileURLToPath(url) {
+	if (GetRuntime() === 'browser') {
+		return url;
+	}
+	const u = new URL(url);
+	if (u.protocol !== 'file:') {
+		throw new Error('Only file:// URLs can be converted to paths');
+	}
+	// decode %20 etc.
+	let pathname = decodeURIComponent(u.pathname);
+
+	// On Windows, strip leading slash and convert / to \
+	if (/^\/[A-Za-z]:/.test(pathname)) {
+		pathname = pathname.slice(1);
+	}
+	return pathname.replace(/\//g, '\\');
+}
+
+/**
+ * @param {string} match
+ * @param {string} importMetaURL
+ */
+const tracePathSameFileFilter = (match, importMetaURL) => {
+	const [letter, path_] = match.split(':');
+	const newPath = [letter, path_].join(':');
+	return IsSameFile(newPath, importMetaURL);
+};
+/**
+ * @type {string}
+ */
+let thisPath;
 /**
  * @description
  * - get stack trace path that matched with truthy filterCallback;
@@ -15,7 +53,7 @@ import { Paths } from '../class/Paths.mjs';
  * - if return false, continue to check the stacks;
  * @returns {string|undefined}
  * @example
- * import { TracePath, Console } from 'vivth';
+ * import { TracePath, Console } from 'vivth/neutral';
  *
  * Console.log(
  * 	TracePath((stackString) => {
@@ -29,14 +67,26 @@ export function TracePath(filterCallback) {
 	if (!stacks || !stacks.length) {
 		return;
 	}
+	/**
+	 * @type {Parameters<typeof TracePath>[0]}
+	 */
+	const trueFilterCallback = (match) => {
+		if (!thisPath) {
+			thisPath = Paths.normalize(fileURLToPath(import.meta.url));
+		}
+		return filterCallback(match) && !tracePathSameFileFilter(match, thisPath);
+	};
 	for (let i = 0; i < stacks.length; i++) {
 		const stack = stacks[i];
 		if (!stack) {
 			return;
 		}
 		const check = stack.match(/([A-Z]:[^ ]*[0-9]|\/[^ )]+:\d+:\d+)/m);
-		const match = Paths.normalize(check?.[1] ?? stack.trim());
-		if (!filterCallback(match)) {
+		if (!check || !check[1]) {
+			continue;
+		}
+		const match = Paths.normalize(check[1]);
+		if (!trueFilterCallback(match)) {
 			continue;
 		}
 		return match;

package/src/common/VivthUnBundledCodeBlock.mjs

@@ -0,0 +1,8 @@
+// @ts-check
+
+/**
+ * @description
+ * - string typehinting value for unbundled only code;
+ * @type {'vivthUnBundledCodeBlock'}
+ */
+export const VivthUnBundledCodeBlock = 'vivthUnBundledCodeBlock';