vivth 1.1.1 → 1.2.0

package/src/bundler/CompileJS.mjs

@@ -0,0 +1,258 @@
+// @ts-check
+
+import { readFile, readdir } from 'node:fs/promises';
+import { join, extname, basename, dirname } from 'node:path';
+import { platform } from 'node:os';
+
+import { exec } from 'pkg';
+
+import { EsBundler } from './EsBundler.mjs';
+import { FileSafe } from '../class/FileSafe.mjs';
+import { TryAsync } from '../function/TryAsync.mjs';
+import { FSInlineAnalyzer } from './FSInlineAnalyzer.mjs';
+
+/**
+ * @typedef {'win32' | 'linux' | 'darwin' | string} PlatformKey
+ */
+
+let binaryExtension = undefined;
+
+/**
+ * @param {Record<string, string[]|string>} compilerOptions
+ * @returns {string[]}
+ */
+const generateFlagsValue = (compilerOptions) => {
+	const options = [];
+	for (const flag in compilerOptions) {
+		const value = compilerOptions[flag];
+		options.push(`--${flag}`);
+		if (!Array.isArray(value)) {
+			if (value) {
+				options.push(value);
+			}
+			continue;
+		}
+		options.push(value.filter((val) => !!val).join(','));
+	}
+	return options;
+};
+/**
+ * Maps Node.js platform to binary file extension.
+ *
+ * @returns {string} extension including dot (e.g. '.exe', '')
+ */
+const getBinaryExtension = () => {
+	if (!binaryExtension) {
+		switch (platform()) {
+			case 'win32':
+				binaryExtension = '.exe';
+				break;
+			case 'linux':
+				binaryExtension = ''; // Linux binaries typically have no extension
+				break;
+			case 'darwin':
+				binaryExtension = ''; // macOS binaries typically have no extension
+				break;
+			default:
+				binaryExtension = ''; // fallback for unknown platforms
+				break;
+		}
+	}
+	return binaryExtension;
+};
+/**
+ * @description
+ * - function to compile `.ts`|`.mts`|`.mjs` file, into a single executable;
+ * - also generate js representation;
+ * - 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);
+ * >- `WorkerThread` will be converted to inline using `FSInline` too;
+ *
+ * !!!WARNING!!!
+ * !!!WARNING!!!
+ * !!!WARNING!!!
+ *
+ * - This function does not obfuscate and will not prevent decompilation. Do not embed environment variables or sensitive information inside `options.entryPoint`;
+ * - It is designed for quick binarization, allowing execution on machines without `Node.js`, `Bun`, or `Deno` installed;
+ * - The resulting binary will contain `FSInline` and `WorkerMainThread` target paths Buffers, which are loaded into memory at runtime. If your logic depends on the file system, use `node:fs` or `node:fs/promises` APIs and ship external files alongside the binary (not compiled);
+ *
+ * !!!WARNING!!!
+ * !!!WARNING!!!
+ * !!!WARNING!!!
+ *
+ * @param {Object} options
+ * @param {string} options.entryPoint
+ * - need to be manually prefixed;
+ * @param {BufferEncoding} [options.encoding]
+ * - write and read encoding for the sources;
+ * - default: `utf-8`;
+ * @param {boolean} options.minifyFirst
+ * - minify the bundle before compilation;
+ * @param {string} options.outDir
+ * - need manual prefix;
+ * @param {'pkg'|'bun'|'deno'} [options.compiler]
+ * - default: no comilation, just bundling;
+ * - `bun` and `pkg` is checked, if there's bug on `deno`, please report on github for issues;
+ * @param {Record<string, string>} [options.compilerArguments]
+ * - `key` are to used as `--keyName`;
+ * - value are the following value of the key;
+ * - no need to add the output/outdir, as it use the `options.outDir`;
+ * @return {ReturnType<TryAsync<{compileResult:Promise<any>,
+ * commandCalled: string;
+ * compiledBinFile: string;
+ * bundledJSFile:string
+ * }>>}
+ * @example
+ * import { join } from 'node:path';
+ *
+ * import { CompileJS, Paths } from 'vivth';
+ *
+ * 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'],
+ * 		}
+ * 	}),
+ * 	CompileJS({
+ * 		entryPoint: join(Paths.root, '/dev'),
+ * 		minifyFirst: true,
+ * 		outDir: join(Paths.root, '/dev-pkg'),
+ * 		compiler: 'bun',
+ * 		compilerArguments: {
+ * 			target: ['bun-win-x64'],
+ * 		}
+ * 	}),
+ * ])
+ */
+export async function CompileJS({
+	entryPoint,
+	minifyFirst,
+	encoding = 'utf-8',
+	outDir,
+	compiler = undefined,
+	compilerArguments = undefined,
+}) {
+	return await TryAsync(async () => {
+		/**
+		 * @type {'cjs'|'esm'|'iife'}
+		 */
+		let format;
+		switch (compiler) {
+			case 'pkg':
+				format = 'cjs';
+				break;
+			case 'bun':
+			case 'deno':
+				format = 'esm';
+				break;
+			default:
+				minifyFirst = true;
+				format = 'esm';
+				break;
+		}
+		const extOfSource = extname(entryPoint);
+		switch (extOfSource) {
+			case '.mts':
+			case '.ts':
+			case '.mjs':
+				break;
+			default:
+				throw new Error(
+					`extention mismatch: "${extOfSource}", should be one of:".mjs"|".mts"|".ts"`
+				);
+		}
+		const sourceText = await readFile(entryPoint, { encoding });
+		const [bundledPrep, errorPrep] = await EsBundler(
+			{
+				content: sourceText,
+				extension: extOfSource,
+				root: dirname(entryPoint),
+				withBinHeader: compiler ? true : false,
+			},
+			{
+				minify: minifyFirst,
+				format,
+			}
+		);
+		if (errorPrep) {
+			throw errorPrep;
+		}
+		const [analyzedBundled, errorAnalyze] = await FSInlineAnalyzer.finalContent(
+			bundledPrep,
+			format
+		);
+		if (errorAnalyze) {
+			throw errorAnalyze;
+		}
+		const outputBaseNameNoExt = join(outDir, basename(entryPoint).replace(extOfSource, ''));
+		const bundledJSFile = `${outputBaseNameNoExt}${format === 'cjs' ? '.cjs' : '.mjs'}`;
+		await FileSafe.write(bundledJSFile, analyzedBundled, { encoding });
+		const compiledBinFile = `${outputBaseNameNoExt}${getBinaryExtension()}`;
+		switch (compiler) {
+			case 'pkg': {
+				const commandCalled = [
+					bundledJSFile,
+					...generateFlagsValue(compilerArguments),
+					'--output',
+					compiledBinFile,
+				];
+				return {
+					compileResult: await exec(commandCalled),
+					commandCalled: `pkg ${commandCalled.join(' ')}`,
+					compiledBinFile,
+					bundledJSFile,
+				};
+			}
+			case 'bun': {
+				const commandCalled = [
+					'build',
+					bundledJSFile,
+					'--compile',
+					...generateFlagsValue(compilerArguments),
+					'--outfile',
+					compiledBinFile,
+				];
+				return {
+					compileResult: await Bun.spawn(['bun', ...commandCalled]),
+					commandCalled: `bun ${commandCalled.join(' ')}`,
+					compiledBinFile,
+					bundledJSFile,
+				};
+			}
+			case 'deno': {
+				const commandCalled = [
+					'compile',
+					...generateFlagsValue(compilerArguments),
+					'--output',
+					compiledBinFile,
+					bundledJSFile,
+					'--verbose',
+				];
+				// @ts-expect-error
+				const command = new Deno.Command('deno', {
+					args: commandCalled,
+					stdout: 'piped',
+					stderr: 'piped',
+				});
+				return {
+					compileResult: await command.output(),
+					commandCalled: `deno ${commandCalled.join(' ')}`,
+					compiledBinFile,
+					bundledJSFile,
+				};
+			}
+			default: {
+				return {
+					compileResult: undefined,
+					commandCalled: undefined,
+					compiledBinFile: undefined,
+					bundledJSFile,
+				};
+			}
+		}
+	});
+}

package/src/bundler/CreateESPlugin.mjs

@@ -0,0 +1,24 @@
+// @ts-check
+
+/**
+ * @description
+ * - typed esbuild Plugin generator;
+ * @param {string} name
+ * @param {import('esbuild').Plugin["setup"]} setup
+ * @returns {import('esbuild').Plugin}
+ * @example
+ * import { CreateESPlugin } from 'vivth';
+ *
+ * export const pluginAddCopyRight = CreateESPlugin(
+ * 	'MyCopyrightDeclaration',
+ * 	async (build) => {
+ * 		// build script;
+ * 	}
+ * );
+ */
+export function CreateESPlugin(name, setup) {
+	return {
+		name: JSON.stringify({ 'vivth:CustomESBuildPlugin': name }),
+		setup,
+	};
+}

package/src/bundler/EsBundler.mjs

@@ -5,6 +5,8 @@ import { build } from 'esbuild';
 import { Console } from '../class/Console.mjs';
 import { Paths } from '../class/Paths.mjs';
 import { TryAsync } from '../function/TryAsync.mjs';
+import { pluginVivthBundle } from './adds/pluginVivthBundle.mjs';
+import { externals } from './adds/externals.mjs';
 
 /**
  * @description
@@ -13,15 +15,18 @@ import { TryAsync } from '../function/TryAsync.mjs';
  * @param {Object} options
  * @param {string} options.content
  * - the code can also uses composites from the result from multiple readFiles;
- * - the import statements on the content should use absolute path from project root, prefixed with forward slash;
- * @param {string} options.extension
- * @param {boolean} [options.asBinary]
- * @param {Omit<Parameters<build>[0], 'entryPoints'|'bundle'|'write'|'format'|'sourcemap'|'external'|'stdin'>} [esbuildOptions]
- * @returns {Promise<ReturnType<typeof TryAsync<string>>>}
+ * @param {string} options.root
+ * - use dirname of said fileString path;
+ * @param {'.mts'|'.ts'|'.mjs'} options.extension
+ * @param {boolean} [options.withBinHeader]
+ * @param {Omit<Parameters<build>[0],
+ * 'entryPoints'|'bundle'|'write'|'sourcemap'>
+ * } [esbuildOptions]
+ * @returns {ReturnType<typeof TryAsync<string>>}
  * @example
  * import { EsBundler } from 'vivth';
  *
- * const bundledString = EsBundler(,
+ * const bundledString = EsBundler(
  * 	{
  * 		content: ``,
  * 		extension: '.mts',
@@ -31,7 +36,10 @@ import { TryAsync } from '../function/TryAsync.mjs';
  * 	...esbuildOptions,
  * });
  */
-export const EsBundler = async ({ content, extension, asBinary = false }, esbuildOptions = {}) => {
+export async function EsBundler(
+	{ content, extension, root, withBinHeader = false },
+	esbuildOptions = {}
+) {
 	return await TryAsync(async () => {
 		/** @type {Parameters<build>[0]['stdin']['loader']} */
 		let loader;
@@ -52,28 +60,34 @@ export const EsBundler = async ({ content, extension, asBinary = false }, esbuil
 				Console.error(error);
 				throw new Error(JSON.stringify(error));
 		}
+		esbuildOptions.external = [...(esbuildOptions?.external ?? []), ...externals];
+		esbuildOptions.plugins = [...(esbuildOptions?.plugins ?? []), pluginVivthBundle];
 		const result = await build({
 			target: 'esnext',
 			platform: 'node',
+			format: 'esm',
 			...esbuildOptions,
 			stdin: {
 				contents: content,
 				loader,
-				resolveDir: Paths.root,
+				resolveDir: root ?? Paths.root,
+				...esbuildOptions.banner,
 			},
-			format: 'esm',
 			bundle: true,
 			write: false,
 			sourcemap: false,
-			external: [],
 			banner: {
-				js: asBinary ? '#!/usr/bin/env node' : '',
+				js: withBinHeader ? '#!/usr/bin/env node' : '',
+				...esbuildOptions.banner,
 			},
 		});
 		if (result.warnings?.length) {
 			Console.warn(result.warnings.map((w) => w.text).join('\n'));
 		}
 		const resString = result.outputFiles?.[0]?.text;
-		return resString ?? '';
+		if (!resString) {
+			return '';
+		}
+		return resString;
 	});
-};
+}

package/src/bundler/FSInline.mjs

@@ -0,0 +1,57 @@
+// @ts-check
+
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import { Paths } from '../class/Paths.mjs';
+
+/**
+ * @description
+ * - class helper to inline file;
+ * - use only if you are planning to use [CompileJS](#compilejs);
+ */
+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>>}
+	 * @example
+	 * import { FSInline } from 'vivth';
+	 *
+	 * (await FSInline.vivthFSInlineFile('/assets/text.txt')).toString('utf-8');
+	 */
+	static vivthFSInlineFile = async (filePathFromProject) => {
+		filePathFromProject = Paths.normalizesForRoot(filePathFromProject);
+		const fullAbsolutePath = join(Paths.root, filePathFromProject);
+		return Buffer.from(await readFile(fullAbsolutePath));
+	};
+	/**
+	 * @description
+	 * - declare entrypoint of file inlining, include all files on `dir` and `subdir` that match the `fileRule`;
+	 * @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 = async (dirPathFromProject, fileRule) => {
+		dirPathFromProject = Paths.normalizesForRoot(dirPathFromProject);
+		return (path_) => FSInline.vivthFSInlineFile(join(dirPathFromProject, path_));
+	};
+	/**
+	 * @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 = {};
+}

package/src/bundler/FSInlineAnalyzer.mjs

@@ -0,0 +1,197 @@
+// @ts-check
+
+import { dirname, extname, join, relative } from 'node:path';
+import { readFile, readdir } from 'node:fs/promises';
+
+import { Paths } from '../class/Paths.mjs';
+import { LitExp } from '../class/LitExp.mjs';
+import { TryAsync } from '../function/TryAsync.mjs';
+import { FSInline } from './FSInline.mjs';
+import { EsBundler } from './EsBundler.mjs';
+
+/**
+ * @param {string} str
+ * @returns {RegExp}
+ */
+const hydrateRegex = (str) => {
+	const match = str.match(/^\/(.*)\/([a-z]*)$/);
+	if (!match) throw new Error('Invalid regex string format');
+
+	const [, pattern, flags] = match;
+	return new RegExp(pattern, flags);
+};
+
+/**
+ * @description
+ * - collections of static method to analyze content for `FSInline`;
+ */
+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 = async (content, format) => {
+		return await TryAsync(async () => {
+			const [literalFile, errorPrepareFile] = LitExp.prepare({
+				FSInline: /\w*/,
+				method: /\.vivthFSInlineFile\s*?\(\s*?['"]/,
+				path: false,
+				closing: /['"]\s*?\)(?:;|)/,
+			});
+			const [literalWorker, errorPreparWorker] = LitExp.prepare({
+				ref: /\w*/,
+				method: /\.newVivthWorker\s*?\(\s*?['"]/,
+				path: false,
+				closing: /['"]/,
+			});
+			const [literalDir, errorPrepareDir] = LitExp.prepare({
+				FSInline: /\w*/,
+				method: /\.vivthFSInlineDir\s*?\(\s*?['"]/,
+				path: false,
+				methodClosing: /['"]\s*?,/,
+				rule: false,
+				functionClosing: /\)(?:;|)/,
+			});
+			if (errorPrepareFile || errorPrepareDir || errorPreparWorker) {
+				throw { errorPrepareFile, errorPrepareDir, errorPreparWorker };
+			}
+			const templateFile = literalFile`${'FSInline'}${'method'}${'path'}${'closing'}`;
+			const templateWorker = literalWorker`${'ref'}${'method'}${'path'}${'closing'}`;
+			const templateDir = literalDir`${'FSInline'}${'method'}${'path'}${'methodClosing'}${'rule'}${'functionClosing'}`;
+			const [resultMatchingFile, errorMatchingFile] = templateFile.evaluate.matchedAllAndGrouped(
+				content,
+				{
+					flags: 'gm',
+					whiteSpaceSensitive: false,
+				}
+			);
+			const [resultMatchingWorker, errorMatchingWorker] =
+				templateWorker.evaluate.matchedAllAndGrouped(content, {
+					flags: 'gm',
+					whiteSpaceSensitive: false,
+				});
+			const [resultMatchingDir, errorMatchingDir] = templateDir.evaluate.matchedAllAndGrouped(
+				content,
+				{
+					flags: 'gm',
+					whiteSpaceSensitive: false,
+				}
+			);
+			if (errorMatchingFile || errorMatchingDir || errorMatchingWorker) {
+				throw { errorMatchingFile, errorMatchingDir, errorMatchingWorker };
+			}
+			const {
+				result: { named: namedFile },
+			} = resultMatchingFile;
+			for (let i = 0; i < namedFile.length; i++) {
+				const { path } = namedFile[i];
+				FSInline.vivthFSInlinelists[path] = Buffer.from(await readFile(join(Paths.root, path)));
+			}
+			const {
+				result: { named: namedWorker },
+				regexp,
+			} = resultMatchingWorker;
+
+			for (let i = 0; i < namedWorker.length; i++) {
+				const { path } = namedWorker[i];
+				const fullPath = join(Paths.root, path);
+				const content = await readFile(fullPath, { encoding: 'utf-8' });
+				const [contentBundled, errorBundled] = await EsBundler(
+					{
+						content,
+						// @ts-expect-error
+						extension: extname(path),
+						root: dirname(fullPath),
+					},
+					{
+						minify: true,
+						format,
+					}
+				);
+				if (errorBundled) {
+					continue;
+				}
+				const [trueContent, errorFinal] = await FSInlineAnalyzer.finalContent(
+					contentBundled,
+					format
+				);
+				if (errorFinal) {
+					continue;
+				}
+				FSInline.vivthFSInlinelists[path] = Buffer.from(trueContent);
+			}
+			const {
+				result: { named: namedDir },
+			} = resultMatchingDir;
+			for (let i = 0; i < namedDir.length; i++) {
+				let { path, rule } = namedDir[i];
+				rule = rule.trim();
+				const results = await FSInlineAnalyzer.#dir(join(Paths.root, path), hydrateRegex(rule));
+				for (let j = 0; j < results.length; j++) {
+					const { path, buffer } = results[j];
+					if (path in FSInline.vivthFSInlinelists) {
+						continue;
+					}
+					FSInline.vivthFSInlinelists[path] = buffer;
+				}
+			}
+			return content.replace(
+				/static\s*vivthFSInlinelists(?:;|)/,
+				`static vivthFSInlinelists=${JSON.stringify(FSInline.vivthFSInlinelists)}`
+			);
+		});
+	};
+	/**
+	 * @typedef {{path:string, buffer:Buffer<ArrayBuffer>}[]} _dirReturn
+	 */
+	/**
+	 * @param {string} dirName
+	 * @param {RegExp} ruleForFileFullPath
+	 * @returns {Promise<_dirReturn>}
+	 */
+	static #dir = async (dirName, ruleForFileFullPath) => {
+		/**
+		 * @type {_dirReturn}
+		 */
+		const result = [];
+		/**
+		 * @param {string} current
+		 * @returns {Promise<void>}
+		 */
+		const walk = async (current) => {
+			const entries = await readdir(current, {
+				recursive: false,
+				withFileTypes: true,
+				encoding: 'utf-8',
+			});
+			for (const entry of entries) {
+				const fullPath = Paths.normalize(join(current, entry.name));
+				const relativePath = Paths.normalizesForRoot(relative(Paths.root, fullPath));
+				if (entry.isDirectory()) {
+					await walk(fullPath);
+					continue;
+				}
+				if (entry.isFile() && ruleForFileFullPath.test(fullPath)) {
+					result.push({
+						path: relativePath,
+						buffer: Buffer.from(await readFile(fullPath)),
+					});
+				}
+			}
+		};
+		await walk(dirName);
+		return result;
+	};
+}

package/src/bundler/FSInlineBundled.mjs

@@ -0,0 +1,34 @@
+// @ts-check
+
+import { join } from 'node:path';
+
+import { Paths } from '../class/Paths.mjs';
+
+export class FSInline {
+	static prefix = '';
+	/**
+	 * @param {string} filePathFromProject
+	 * @returns {Promise<Buffer<ArrayBuffer>>}
+	 */
+	static vivthFSInlineFile = async (filePathFromProject) => {
+		filePathFromProject = Paths.normalizesForRoot(filePathFromProject);
+		return Buffer.from(FSInline.vivthFSInlinelists[filePathFromProject]);
+	};
+	/**
+	 * @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 = async (dirPathFromProject) => {
+		dirPathFromProject = Paths.normalizesForRoot(dirPathFromProject);
+		return (path_) => FSInline.vivthFSInlineFile(join(dirPathFromProject, path_));
+	};
+	/**
+	 * - to be used as embed placeholder on `bundled` and `compiled`;
+	 * @type {Record<string, Buffer<ArrayBufferLike>>}
+	 */
+	static vivthFSInlinelists;
+}