@awesomeness-js/utils 1.0.25 → 1.1.3

package/README.md

@@ -1,44 +1,51 @@
 # Nothing Special
 
-Just some <u>zero dependency</u> utils ...
+Just some <u>zero dependency</u>* utils that every [Awesomeness.js](https://github.com/awesomeness-js) project uses.
 
+**Perfect?** Far from it.
+
+Better than what you have now? For sure.
 
 ---
 
 # 🚀 Auto-Generate API Exports for Your Node.js Project  
 
-
 ## 📌 Why "build" Exists  
 
-When working on a Node.js project, you often need to import multiple functions from a directory and structure them in a clean, accessible way. Webpack is overkill for this—it’s designed for browser bundling, not for generating structured API exports in a Node.js environment.  
+When you’re building a Node.js project, pulling functions together into a clean, predictable API shouldn’t feel like busywork. But maintaining a manual `index.js` is a waste of time, and Webpack? That’s a browser bundler—great for shipping front-end bundles, useless for building a logical backend export layer.  
+
+This script takes that grunt work off your plate and does it **right**:  
 
-This script **automates** that process. It dynamically scans your source directory (`./src`), imports functions, and generates an `index.js` file that:  
+✅ **Consolidates all exports** into a single, perfectly structured API object  
+✅ **Keeps function names and namespaces** exactly as your folder structure dictates—no mystery, no guessing  
+✅ **Pulls in JSDoc comments** so your documentation is baked right into the build. Intellisense loves this.  
+✅ **Runs in plain Node.js**—zero bundlers, zero fluff, zero excuses  
+
+
+Hint: Use the [Awesomeness Intellitip](https://marketplace.visualstudio.com/items?itemName=awesomeness.awesomeness-intellitip) VS Code Extension for classy hover documentation.
 
-✅ **Consolidates all exports** into a structured API object.  
-✅ **Preserves function names and namespaces** based on folder structure.  
-✅ **Extracts JSDoc comments** for better documentation.  
-✅ **Works in plain Node.js**—no need for Webpack or extra dependencies.  
 
 ---
 
-## 🚀 Why Use "build" Instead of Webpack?  
+## 💡 Why Use This Over Webpack or Manual Indexing?  
 
-**Webpack is great for frontend bundling, but it’s not ideal for this use case.** Here’s why this script is a better choice:  
+Webpack is a great bundler, but it’s not suited for building a structured export layer for backend code. This script offers a focused, ergonomic solution:  
 
-✔ **Zero dependencies**—Runs in plain Node.js, no Webpack or config files required.  
-✔ **Automatic function export generation**—No need to manually update an `index.js`.  
+✔ **Automatic export generation** — no more maintaining `index.js` by hand  
 ✔ **JSDoc extraction**—Includes comments directly in the generated file.  
 ✔ **Simple and predictable**—You control how exports are structured.  
 ✔ **Namespace support**—Uses folder structure to organize functions logically.  
+✔ **Minimal setup** — one line to generate your exports  
+✔ **Dev-friendly hot rebuild** — optional file watching with HMR-style rebuilds  
 
-With this script, you can stop wasting time managing exports and focus on writing code.  
+> Uses `chokidar` under the hood for reliable cross-platform file watching.
 
 ---
 
-## ⚡ How It Works  
+## ⚙️ How It Works  
 
-1. **Scans** the `./src` directory for `.js` files.  
-2. **Generates** import statements dynamically.  
+1. **Scans** the `./src` directory for `.js` files  
+2. **Generates** import statements  
 3. **Creates** an API object that mirrors your folder structure.  
 4. **Extracts JSDoc comments** from each file and attaches them to the exports.  
 5. **Outputs** a clean, structured `index.js` file, ready to use.  
@@ -47,103 +54,122 @@ With this script, you can stop wasting time managing exports and focus on writin
 
 ## 🔧 Usage  
 
-Simply run:  
-
-By default, this will:  
-- Scan `./src` for JavaScript files  
-- Generate an `index.js` file  
-- Structure exports based on your folder hierarchy  
-
-```javascript
+To run it:
 
+```js
 import { build } from '@awesomeness-js/utils';
 
-build();
-
+await build();
 ```
 
-If you need custom paths, modify the `src` and `dest` options in the script:  
-
-```javascript
+This will:
+- Scan the `./src` directory
+- Create or overwrite `./index.js`
+- Structure exports based on your file and folder layout
 
-import { build } from '@awesomeness-js/utils';
+Customize it:
 
-build({
-    src: './my-functions',
-    dest: './api.js'
+```js
+await build({
+  src: './my-functions',
+  dest: './api.js',
+  includeComments: true,
+  useTabs: true,
+  hotModuleReload: true // Enable hot reload for dev
 });
 ```
 
 ---
 
-## 📜 Example Output  
+## 📦 Example Output  
 
-If your folder structure looks like this:  
+Given this folder structure:
 
 ```
 src/
-│── utils/
-│   ├── formatDate.js
-│   ├── generateId.js
-│── services/
-│   ├── fetchData.js
-│── calculate.js
+├── roxbury/
+│   ├── didYouJustGrabMyAss.js
+│   ├── areYouGuysBrothers.js
+├── bros/
+│   ├── didWeJustBecomeBestFriends.js
+│   ├── prestigeWorldwide.js
+├── rickyBobby/
+│   ├── iWakeUpAndPissExcellence.js
+│   ├── iRaiseWinners.js
+│   ├── shakeAndBake.js
+├── oldSchool/
+│   ├── youMyBoyBlue.js
+├── news/
+│   ├── thatEscalatedQuickly.js
+│   ├── stayClassy.js
+│   ├── milkWasABadChoice.js
+├── tommy/
+│   ├── roomService.js
+│   ├── fatGuyInALittleCoat.js
+├── menInTights/
+│   ├── youGrewBoobs.js
+│   ├── merryMen/
+│   │   ├── snipTheTip.js
 ```
 
-Your generated `index.js` will look like this:  
-
-```javascript
-/**
- * This file is auto-generated by the build script.
- * It consolidates API functions for use in the application.
- * Do not edit manually.
- */
-
-import utils_formatDate from './src/utils/formatDate.js';
-import utils_generateId from './src/utils/generateId.js';
-import services_fetchData from './src/services/fetchData.js';
-import calculate from './src/calculate.js';
-
-export { calculate };
-export default {
-    utils: {
-        formatDate: utils_formatDate,
-        generateId: utils_generateId
-    },
-    services: {
-        fetchData: services_fetchData
-    },
-    calculate
-};
-```
 
-Your api is now neatly organized and ready to use!
-and will look like this
-```javascript
-import { calculate } from './api.js';
-const result = calculate(5, 10);
-console.log(result);
-```
+#### Use it like:
 
-or 
+```js
+
+// Default import: full API
+import api from './index.js';
+
+// Use the full API
+api.roxbury.didYouJustGrabMyAss();
+
+// perfect for CTRL+F
+api.rickyBobby.shakeAndBake();
+
+// deep
+api.menInTights.youGrewBoobs();
+api.menInTights.merryMen.snipTheTip();
 
-```javascript
-import { utils } from './api.js';
-const id = utils.generateId();
-console.log(id);
 ```
 
+```js
+
+// Named import also work
+import { youMyBoy, roxbury } from './api.js';
 
+// Use the named group
+youMyBoy.blue();
+roxbury.didYouGrabMyAss();
+
+```
 
 ---
 
-## 🚀 Who Should Use This?  
+## 💪 Who’s This For?  
+
+- **Teams** who want **clean and consistent** APIs  
+- **Expert** ~~developers~~ **architects** obsessed with 
+  - organization
+  - hierarchy
+  - explicit namespacing
+  - clean code
+- **Champions** who know CTRL+F `app.roxbury.didYouJustGrabMyAss` will <u>always beat</u> any “magic” refactor tool when it comes to finding **every. single. usage.**  
+- Developers who refuse to hide functions behind lazy aliases, and instead demand predictable, grep-able APIs that tell you **exactly where the code lives.**
+
+If you want a smarter way to manage and structure exports in a Node.js project — without extra tooling bloat — this script was built for you.
 
-- **Node.js developers** who want automatic API exports.  
-- **Backend teams** managing large function directories.  
-- **Anyone tired of manually updating `index.js` files.**  
+If that makes you hard, you’re in the right place. 
 
-If you don’t need Webpack’s **complexity** but want **automatic structured exports**, this script is for you.  
+> If it makes you mad… you’ve probably never built a scalable codebase.
+
+---
 
-👉 **Try it out and let automation handle your exports!** 🚀  
+**Ready to make development great again?**
+👉 [awesomenessjs.com](https://awesomenessjs.com)
 
+--- 
+✱ disclaimer... *Kinda zero dependencies.*
+Zero **prod** dependencies.
+> dev dependencies:
+> `chokidar` for hot module reloading (HMR) 
+> `vitest` for testing

package/build/build.js

@@ -4,10 +4,15 @@ build({
 	src: './src',
 	dest: './index.js',
 	dts: false,
+	hotModuleReload: false,
+	hotCallback: (file) => {
+
+		console.log(`[build callback] processed ${file}`);
+
+	},
 	ignore: [
 		'ignoreMe.js',
 		'ignoreFolder/*',
-		//'namespaceExample/*',
 	],
 });
 

package/index.js

@@ -20,13 +20,12 @@ import _each from './src/each.js';
 import _eachAsync from './src/eachAsync.js';
 import _encrypt from './src/encrypt.js';
 import _getAllFiles from './src/getAllFiles.js';
-import _ignoreFolder_ignoreMe from './src/ignoreFolder/ignoreMe.js';
-import _ignoreMe from './src/ignoreMe.js';
 import _isUUID from './src/isUUID.js';
 import _md5 from './src/md5.js';
 import _password_check from './src/password/check.js';
 import _password_hash from './src/password/hash.js';
 import _setLocalEnvs from './src/setLocalEnvs.js';
+import _shouldIgnore from './src/shouldIgnore.js';
 import _thingType from './src/thingType.js';
 import _toPennies from './src/toPennies.js';
 import _utils_buildExportsTree from './src/utils/buildExportsTree.js';
@@ -39,7 +38,7 @@ import _utils_generateImportStatements from './src/utils/generateImportStatement
 import _utils_generateNamedExports from './src/utils/generateNamedExports.js';
 import _utils_generateNamespaceCode from './src/utils/generateNamespaceCode.js';
 import _utils_generateNamespaceExportLines from './src/utils/generateNamespaceExportLines.js';
-import _utils_shouldIgnore from './src/utils/shouldIgnore.js';
+import _utils_writeHotWrapper from './src/utils/writeHotWrapper.js';
 import _uuid from './src/uuid.js';
 import _validateSchema from './src/validateSchema.js';
 
@@ -52,15 +51,46 @@ export { _each as each };
 export { _eachAsync as eachAsync };
 export { _encrypt as encrypt };
 export { _getAllFiles as getAllFiles };
-export { _ignoreMe as ignoreMe };
 export { _isUUID as isUUID };
 export { _md5 as md5 };
 export { _setLocalEnvs as setLocalEnvs };
+export { _shouldIgnore as shouldIgnore };
 export { _thingType as thingType };
 export { _toPennies as toPennies };
 export { _uuid as uuid };
 export { _validateSchema as validateSchema };
 
+export const clean = {
+	array: _clean_array,
+	boolean: _clean_boolean,
+	integer: _clean_integer,
+	number: _clean_number,
+	object: _clean_object,
+	string: _clean_string,
+	timestamp: _clean_timestamp,
+	uuid: _clean_uuid
+};
+
+export const password = {
+	check: _password_check,
+	hash: _password_hash
+};
+
+export const utils = {
+	buildExportsTree: _utils_buildExportsTree,
+	buildFileDataList: _utils_buildFileDataList,
+	clean: _utils_clean,
+	extractJSDocComment: _utils_extractJSDocComment,
+	generateFile: _utils_generateFile,
+	generateFlatExportLines: _utils_generateFlatExportLines,
+	generateImportStatements: _utils_generateImportStatements,
+	generateNamedExports: _utils_generateNamedExports,
+	generateNamespaceCode: _utils_generateNamespaceCode,
+	generateNamespaceExportLines: _utils_generateNamespaceExportLines,
+	writeHotWrapper: _utils_writeHotWrapper
+};
+
+
 export default {
 	/**
 	 * Builds a file from the specified source directory and writes it to the destination file.
@@ -99,10 +129,10 @@ export default {
 	eachAsync: _eachAsync,
 	encrypt: _encrypt,
 	getAllFiles: _getAllFiles,
-	ignoreMe: _ignoreMe,
 	isUUID: _isUUID,
 	md5: _md5,
 	setLocalEnvs: _setLocalEnvs,
+	shouldIgnore: _shouldIgnore,
 	thingType: _thingType,
 	toPennies: _toPennies,
 	uuid: _uuid,
@@ -117,9 +147,6 @@ export default {
 		timestamp: _clean_timestamp,
 		uuid: _clean_uuid,
 	},
-	ignoreFolder: {
-		ignoreMe: _ignoreFolder_ignoreMe,
-	},
 	password: {
 		check: _password_check,
 		hash: _password_hash,
@@ -135,6 +162,6 @@ export default {
 		generateNamedExports: _utils_generateNamedExports,
 		generateNamespaceCode: _utils_generateNamespaceCode,
 		generateNamespaceExportLines: _utils_generateNamespaceExportLines,
-		shouldIgnore: _utils_shouldIgnore,
+		writeHotWrapper: _utils_writeHotWrapper,
 	},
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@awesomeness-js/utils",
-	"version": "1.0.25",
+	"version": "1.1.3",
 	"description": "Awesomeness - Utils",
 	"repository": {
 		"type": "git",
@@ -21,6 +21,7 @@
 		"access": "public"
 	},
 	"devDependencies": {
-		"vitest": "^3.0.9"
+		"vitest": "^3.0.9",
+		"chokidar": "^4.0.3"
 	}
 }

package/schemas.js

@@ -9,6 +9,7 @@ import _schema2 from './schemas/schema2.js';
 export { _schema1 as schema1 };
 export { _schema2 as schema2 };
 
+
 export default {
 	schema1: _schema1,
 	schema2: _schema2,

package/src/build.js

@@ -12,6 +12,7 @@
  */
 import { writeFileSync } from 'fs';
 import generateFile from './utils/generateFile.js';
+import writeHotWrapper from './utils/writeHotWrapper.js';
 
 async function build({
 	src = './src',
@@ -20,10 +21,85 @@ async function build({
 	ignore = [],
 	includeComments = true,
 	dts = false,
-	useTabs = true
+	useTabs = true,
+	hotModuleReload = false,
+	hotCallback = null,
+	hotSource = './hot-source.js'   // generated only when hot is enabled
 } = {}) {
 
-	writeFileSync(dest, generateFile(src, exportRoots, ignore, includeComments, dts, useTabs));
+	const gen = () => generateFile({
+		src,
+		exportRoots,
+		ignore,
+		includeComments,
+		dts,
+		useTabs 
+	});
+
+	const buildHot = () => {
+
+		// 1) write payload that the wrapper imports
+		writeFileSync(hotSource, gen());
+		console.log(`[build] wrote ${hotSource}`);
+		
+		// 2) ensure index.js is a hot wrapper
+		writeHotWrapper({
+			dest,
+			hotSource 
+		});
+
+		console.log(`[build] ensured hot wrapper ${dest}`);
+	
+	};
+
+	const buildCold = () => {
+
+		// single-file classic output (no second file)
+		writeFileSync(dest, gen());
+		console.log(`[build] wrote ${dest}`);
+	
+	};
+
+	if (hotModuleReload) {
+
+		buildHot();
+
+		// watch only src; each change regenerates hot-source.js (wrapper auto-reloads it)
+		const chokidar = (await import('chokidar')).default;
+
+		console.log(`[build] watching ${src} for changes...`);
+		const watcher = chokidar.watch(src, {
+			ignoreInitial: true,
+			ignored: ignore 
+		});
+
+		let timeout;
+
+		watcher.on('all', (_event, file) => {
+
+			clearTimeout(timeout);
+			timeout = setTimeout(() => {
+
+				console.log(`[build] change detected in ${file}, rebuilding payload...`);
+				writeFileSync(hotSource, gen());
+
+				if(typeof hotCallback === 'function') {
+
+					hotCallback(file);
+				
+				}
+
+				console.log(`[build] ready.`);
+			
+			}, 50);
+		
+		});
+	
+	} else {
+
+		buildCold();
+
+	}
 	
 	return true;
 

package/src/getAllFiles.js

@@ -2,7 +2,7 @@ import {
 	readdirSync, statSync 
 } from 'fs';
 import { join } from 'path';
-import shouldIgnore from './utils/shouldIgnore.js';
+import shouldIgnore from './shouldIgnore.js';
 
 export default function getAllFiles(base, {
 	dir = '.',

package/src/shouldIgnore.js

@@ -0,0 +1,99 @@
+export default function shouldIgnore(filePath, ignorePatterns) {
+
+	const normalizePath = (p) => {
+
+		let v = String(p).replace(/\\/g, '/');      // Windows → POSIX
+
+		v = v.replace(/^\.\/+/, '');                // strip leading ./
+		v = v.replace(/\/+/g, '/');                 // collapse multiple slashes
+		// if the path includes /src/, make it relative to src
+		v = v.replace(/^.*\/src(\/|$)/, '/');       // ".../src/foo" → "/foo"
+		if (!v.startsWith('/')) v = '/' + v;        // ensure leading slash
+		// strip trailing slash except for root
+		if (v.length > 1 && v.endsWith('/')) v = v.slice(0, -1);
+		
+		return v.toLowerCase();                     // case-insensitive
+	
+	};
+
+	const normalizePattern = (p) => {
+
+		let v = String(p).replace(/\\/g, '/').replace(/^\.\/+/, '').replace(/\/+/g, '/');
+
+		if (!v.includes('*') && !v.includes('.') && !v.endsWith('/')) v += '/';
+		if (!v.startsWith('/')) v = '/' + v;
+		
+		return v.toLowerCase();                     // case-insensitive
+	
+	};
+
+	const pathCandidates = (() => {
+
+		const p = normalizePath(filePath);
+		const noSrc = String(filePath).replace(/\\/g, '/').replace(/^\.\/+/, '');
+		const alt = (noSrc.startsWith('/') ? noSrc : '/' + noSrc).toLowerCase();
+
+    
+		return Array.from(new Set([ p, alt ]));
+	
+	})();
+
+	const matches = (fp, pat) => {
+
+		// 1) "*.ext" anywhere
+		if (/^\/\*\.[^/]+$/.test(pat)) {
+
+			const ext = pat.slice(2); // "*.js" -> ".js"
+
+      
+			return fp.endsWith(ext);
+		
+		}
+
+		// 2) "folder/*" => only immediate children (no subfolders)
+		if (pat.endsWith('/*')) {
+
+			const base = pat.slice(0, -2);
+
+      
+			return fp.startsWith(base + '/') && !fp.slice(base.length + 1).includes('/');
+		
+		}
+
+		// 3) "folder/*.ext" => files with ext in that folder (no subfolders)
+		if (pat.includes('/*')) {
+
+			const [ base, tail ] = pat.split('/*');
+
+      
+			return fp.startsWith(base + '/') &&
+             fp.endsWith(tail) &&
+             !fp.slice(base.length + 1).includes('/');
+		
+		}
+
+		// 4) Plain directory "folder/" => whole dir + subdirs
+		if (pat.endsWith('/')) {
+
+			const base = pat.slice(0, -1);
+
+      
+			return fp === base || fp.startsWith(base + '/');
+		
+		}
+
+		// 5) Exact file
+		return fp === pat;
+	
+	};
+
+	return ignorePatterns.some((raw) => {
+
+		const pat = normalizePattern(raw);
+
+    
+		return pathCandidates.some((fp) => matches(fp, pat));
+	
+	});
+
+}

package/src/utils/buildFileDataList.js

@@ -2,7 +2,11 @@ import getAllFiles from '../getAllFiles.js';
 import extractJSDocComment from './extractJSDocComment.js';
 import { join } from 'path';
 
-export default function buildFileDataList(src, ignore, includeComments) {
+export default function buildFileDataList({
+	src, 
+	ignore, 
+	includeComments
+}) {
 
 	const allFiles = getAllFiles(src, { 
 		ignore,