Author: Nikola Hristov

CHANGELOG.md

@@ -1,3 +1,5 @@
+## 0.2.3
+
 ## 0.2.2
 
 ### Change

README.md

@@ -7,27 +7,36 @@ capabilities of the `TypeScript` compiler.
 ## Feature 📦
 
 - Fast compilation using `ESBuild`
-- `TypeScript` support with type-checking
-- Watch mode for development
-- Customizable `ESBuild` configuration
+- `TypeScript` support with type-checking (`tsc` & `tsc-alias`)
+- Watch mode for development (`--Watch`)
+- Customizable `ESBuild` configuration via object or function (`--ESBuild`)
 - Supports both `CommonJS` and `ES` modules
+- Glob pattern support for input files
+- Exclusion patterns for input files
 
 ## Installation 🚀
 
 Install the package as a development dependency:
 
 ```sh
+# Using npm
 npm install -D -E @playform/build
+
+# Or using yarn
+# yarn add -D -E @playform/build
+
+# Or using pnpm
+# pnpm add -D -E @playform/build
 ```
 
 ## Usage 🛠️
 
 ### Command Line
 
-Run the build tool from the command line:
+Run the build tool from the command line, providing file patterns:
 
 ```sh
-npx @playform/build 'Source/**/*.ts'
+npx @playform/build 'Source/**/*.ts' 'OtherSource/**/*.mts'
 ```
 
 ### CLI Options
@@ -36,13 +45,13 @@ npx @playform/build 'Source/**/*.ts'
 Usage: Build [options] <File...>
 
 Arguments:
-  File                      File patterns to build 📝
+  File                      One or more glob patterns matching files to build 📝
 
 Options:
   -V, --version             Output the version number
-  -ES, --ESBuild <File>     Custom `ESBuild` configuration file 📜
-  -TS, --TypeScript <File>  Custom `TypeScript` configuration file (default: "tsconfig.json") 📜
-  -W, --Watch               Watch mode: rebuild on file changes 👁️
+  -E, --ESBuild <File>      Path to a custom ESBuild configuration file (exports an object or a function) 📜
+  -T, --TypeScript <File>   Path to a custom TypeScript configuration file (default: "tsconfig.json") 📜
+  -W, --Watch               Enable watch mode: rebuild on file changes 👁️
   -h, --help                Display help information
 ```
 
@@ -62,59 +71,171 @@ Add `Build` to your `package.json` scripts:
 
 ## Configuration ⚙️
 
-### ESBuild Configuration 📜
+### ESBuild Configuration (`--ESBuild`) 📜
+
+You can provide a custom configuration file to modify the default ESBuild
+options used by `@playform/build`. This file (e.g., `ESBuild.js` or
+`esbuild.config.ts`) should use `export default` with **either** a configuration
+object **or** a function.
 
-Create a custom `ESBuild` configuration file (e.g., `ESBuild.ts`):
+**1. Exporting an Object:**
+
+Provide an object with ESBuild options. These will be merged with the base
+configuration.
 
 ```javascript
-export default {
+// ESBuild.js
+/** @type {import('esbuild').BuildOptions} */
+const config = {
 	minify: true,
-	sourcemap: true,
+	sourcemap: "external",
+	platform: "node",
 	// Add other esbuild options here
 };
+
+export default config;
+```
+
+**2. Exporting a Function:**
+
+Provide a function that receives the _current_ ESBuild configuration object
+(`BuildOptions` from `esbuild`) as its argument. You can modify this object
+directly **or** return a new (partial) object containing options to be merged.
+This allows for dynamic configuration, such as filtering entry points.
+
+```javascript
+// ESBuild.js
+/**
+ * @param {import('esbuild').BuildOptions} Current The configuration object before this function runs.
+ * @returns {import('esbuild').BuildOptions | void} Return changes to merge, or modify Current directly.
+ */
+export default (Current) => {
+	console.log("Applying custom ESBuild function...");
+
+	// Example: Filter out test files from entry points
+	if (Array.isArray(Current.entryPoints)) {
+		Current.entryPoints = Current.entryPoints.filter(
+			(entry) => !/\.(test|spec)\.[mc]?[jt]s$/.test(entry),
+		);
+
+		console.log("Filtered entry points:", Current.entryPoints);
+	}
+
+	// Example: Modify the config directly
+	Current.define = {
+		...(Current.define ?? {}), // Preserve existing defines
+		"process.env.BUILD_TIME": `"${new Date().toISOString()}"`,
+	};
+
+	// Example: Return additional options to merge
+	return {
+		banner: {
+			js: "// Generated by @playform/build",
+		},
+		logLevel: "info",
+	};
+
+	// If you only modify 'Current' directly, you can simply have no return:
+	// return;
+
+	// or return undefined;
+};
 ```
 
-Use the custom configuration:
+**Usage:**
+
+Specify the path to your configuration file using the `--ESBuild` option:
 
 ```sh
 npx @playform/build 'Source/**/*.ts' --ESBuild ESBuild.ts
 ```
 
-See an example of a configuration file in
-[`ESBuild.ts`](Source/Variable/ESBuild.ts)
+See the base configuration used internally in
+[`Source/Variable/ESBuild.ts`](Source/Variable/ESBuild.ts) (link might need
+adjustment based on your actual path).
 
-### TypeScript Configuration 📜
+### TypeScript Configuration (`--TypeScript`) 📜
 
-Create a `tsconfig.json` file in your project root:
+By default, `Build` looks for `tsconfig.json` in the current working directory.
+You can specify a different path using the `--TypeScript` option. This
+`tsconfig.json` is used by `ESBuild` for path resolution and by the `tsc` and
+`tsc-alias` commands run after the build for type checking and path alias
+replacement.
+
+A typical `tsconfig.json` might look like this:
 
 ```json
+// tsconfig.json
 {
 	"compilerOptions": {
-		"outDir": "Target",
-		"rootDir": "Source",
-		"strict": true
+		// --- Essential for tsc/tsc-alias ---
+		"outDir": "Target", // Must match esbuild's outdir/outfile directory
+		"rootDir": "Source", // Or your source root
+		"baseUrl": ".", // Often needed for path aliases
+		"paths": {
+			// Example alias - must match esbuild alias config if used
+			"@/*": ["Source/*"]
+		},
+		// --- Type Checking Options ---
+		"strict": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		// --- Module Settings (match esbuild target/format) ---
+		"target": "ES2020",
+		"module": "ESNext", // or CommonJS
+		"moduleResolution": "node", // or node16/nodenext
+		// --- Interoperability ---
+		"esModuleInterop": true,
+		"allowSyntheticDefaultImports": true,
+		// --- Other ---
+		"resolveJsonModule": true,
+		"isolatedModules": true, // Good practice with transpilers like esbuild
+		"noEmit": true // Important: Set noEmit to true as esbuild handles file emission
 	},
-	"extends": "@playform/build/tsconfig",
-	"include": ["Source"]
+	// Use @playform/build's base config for sensible defaults (optional)
+	// "extends": "@playform/build/tsconfig",
+	"include": ["Source/**/*"], // Files to be type-checked
+	"exclude": ["node_modules", "Target"] // Exclude output and dependencies
 }
 ```
 
-### JSConfig Configuration 📜 (optional)
+**Important:** Ensure `compilerOptions.outDir` in your `tsconfig.json` aligns
+with the output directory configured for `ESBuild` (either via the default
+`Source/Variable/ESBuild.ts` or your custom `--ESBuild` config). Also, set
+`"noEmit": true` as `esbuild` handles the file generation; `tsc` is only used
+for type checking here.
 
-For `JavaScript` projects using `JSDoc` comments, create a `jsconfig.json`:
+### JSConfig Configuration (Optional) 📜
+
+If you are working with JavaScript and JSDoc for type checking, you can use a
+`jsconfig.json` file instead of `tsconfig.json`. The principles are similar.
 
 ```json
+// jsconfig.json
 {
 	"compilerOptions": {
 		"outDir": "Target",
 		"rootDir": "Source",
-		"checkJs": true
+		"checkJs": true, // Enable type checking for JS files
+		"target": "ES2020",
+		"module": "ESNext", // or CommonJS
+		"moduleResolution": "node", // or node16/nodenext
+		"baseUrl": ".",
+		"paths": {
+			"@/*": ["Source/*"]
+		},
+		"noEmit": true // Still important
 	},
-	"extends": "@playform/build/jsconfig",
-	"include": ["Source"]
+	"extends": "@playform/build/jsconfig", // If you provide a base jsconfig
+	"include": ["Source/**/*"],
+	"exclude": ["node_modules", "Target"]
 }
 ```
 
+Remember to pass the path to this file if it's not named `tsconfig.json` (even
+if it's a JS project, the default flag might still look for `tsconfig.json`
+unless you explicitly pass `--TypeScript jsconfig.json`).
+
 ## Contributing 🤝
 
 Contributions are welcome! Please see [`CONTRIBUTING.md`](CONTRIBUTING.md) for
@@ -124,6 +245,6 @@ guidelines and feel free to submit a Pull Request.
 
 See [`CHANGELOG.md`](CHANGELOG.md) for a history of changes to this component.
 
-[ESBuild]: HTTPS://NPMJS.Org/esbuild
-[TypeDoc]: HTTPS://NPMJS.Org/typedoc
-[Build]: HTTPS://NPMJS.Org/@playform/build
+[ESBuild]: HTTPS://esbuild.github.io/
+[TypeScript]: HTTPS://www.typescriptlang.org/
+[Build]: HTTPS://www.npmjs.com/package/@playform/build

Source/Function/Build.ts

@@ -1,4 +1,7 @@
+import type { BuildOptions } from "esbuild";
+
 import type Interface from "../Interface/Build.js";
+import type Set from "../Interface/Build/Set.js";
 
 /**
  * @module Build
@@ -24,44 +27,85 @@ export default (async (...[File, Option]) => {
 	});
 
 	if (Option?.ESBuild) {
-		Merge(
-			Configuration,
-			await (await import("@Function/File.js")).default(Option.ESBuild),
-		);
+		const Export = await (
+			await import("@Function/File.js")
+		).default(Option.ESBuild);
+
+		let Change: Partial<BuildOptions> | undefined;
+
+		if (typeof Export === "function") {
+			const Result = await (Export as Set)(Configuration);
+
+			if (Result && typeof Result === "object") {
+				Change = Result;
+			}
+		} else if (
+			Export &&
+			typeof Export === "object" &&
+			!Array.isArray(Export)
+		) {
+			Change = Export as Partial<BuildOptions>;
+		}
+
+		if (Change) {
+			Merge(Configuration, Change);
+		}
+
+		if (
+			!Configuration.entryPoints ||
+			!Array.isArray(Configuration.entryPoints)
+		) {
+			Configuration.entryPoints = [...Pipe];
+		}
 	}
 
 	Merge(Configuration, {
 		tsconfig: Option?.TypeScript ?? "tsconfig.json",
 	});
 
-	if (!Configuration.plugins && !Array.isArray(Configuration.plugins)) {
+	if (!Configuration.plugins) {
+		Configuration.plugins = [];
+	} else if (!Array.isArray(Configuration.plugins)) {
 		Configuration.plugins = [];
 	}
 
-	Configuration.plugins?.push({
+	Configuration.plugins.push({
 		name: "TypeScript",
 		setup({ onEnd }) {
 			onEnd(async () => {
-				await Exec(`tsc -p ${Configuration.tsconfig}`);
-				await Exec(`tsc-alias -f -p ${Configuration.tsconfig}`);
+				if (
+					!Configuration.tsconfig ||
+					typeof Configuration.tsconfig !== "string"
+				) {
+					return;
+				}
+
+				try {
+					await Exec(`tsc -p ${Configuration.tsconfig}`);
+
+					await Exec(`tsc-alias -f -p ${Configuration.tsconfig}`);
+				} catch (_Error) {
+					console.error(_Error);
+				}
 			});
 		},
 	});
 
 	if (Option?.Watch) {
 		await (await (await import("esbuild")).context(Configuration)).watch();
 	} else {
-		console.log(
-			await (
-				await import("esbuild")
-			).analyzeMetafile(
-				(await (await import("esbuild")).build(Configuration))
-					?.metafile ?? "",
-				{
+		const Result = await (await import("esbuild")).build(Configuration);
+
+		if (Result.metafile) {
+			console.log(
+				await (
+					await import("esbuild")
+				).analyzeMetafile(Result.metafile, {
 					verbose: true,
-				},
-			),
-		);
+					color: false,
+				}),
+			);
+		}
 	}
 }) satisfies Interface as Interface;
 

Source/Function/Merge.ts

@@ -2,7 +2,6 @@
  * @module Merge
  *
  */
-export default <T extends object>(Target: T, Source: T) =>
-	Into(Target, Source) as unknown as T;
-
-export const { default: Into } = await import("./Merge/Into.js");
+export default (await import("deepmerge-ts")).deepmergeIntoCustom({
+	mergeArrays: false,
+});