@awesomeness-js/utils 1.0.24 → 1.1.2

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  
+To run it:
 
-```javascript
-
-import { build } from '@awesomeness-js/utils';
-
-build();
+```js
+import build from '@awesomeness-js/utils/build.js';
 
+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

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

package/build/postBuild.js

@@ -1,11 +1,11 @@
 import build from '../src/build.js';
 build({ 
-    src: './src', 
-    dest: './types/index.d.ts', 
-    dts: true,
-    ignore: [
-        'ignoreMe.js',
-        'ignoreFolder/*',
-        //'namespaceExample/*',
-    ],
+	src: './src', 
+	dest: './types/index.d.ts', 
+	dts: true,
+	ignore: [
+		'ignoreMe.js',
+		'ignoreFolder/*',
+		//'namespaceExample/*',
+	],
 });

package/eslint.config.js

@@ -0,0 +1,90 @@
+export default [
+	// Here is where we fix "padding-line-between-statements"
+	{
+		rules: {
+			'padding-line-between-statements': [
+				'error',
+				// Insert a blank line **before** any block-like statement
+				{
+					blankLine: 'always',
+					prev: '*',
+					next: 'block-like' 
+				},
+				// Insert a blank line **after** any block-like statement
+				{
+					blankLine: 'always',
+					prev: 'block-like',
+					next: '*' 
+				},
+				// Keep the rest of your rules here as needed...
+				{
+					blankLine: 'always',
+					prev: '*',
+					next: 'function' 
+				},
+				{
+					blankLine: 'always',
+					prev: 'function',
+					next: '*' 
+				},
+				{
+					blankLine: 'always',
+					prev: '*',
+					next: 'throw' 
+				}
+			],
+			'padded-blocks': [
+				'error',
+				{
+					blocks: 'always',
+					classes: 'always',
+					switches: 'always'
+				}
+			],
+
+			"object-curly-newline": [
+				"error",
+				{
+					ObjectExpression: {
+						minProperties: 2,     // If object has 2+ props, break into multiple lines
+						multiline: true,
+						consistent: true
+					},
+					// You can also configure ImportDeclaration, ExportDeclaration, etc.
+					ObjectPattern: {
+						multiline: true,
+						minProperties: 2,
+						consistent: true
+					},
+					ImportDeclaration: {
+						multiline: true,
+						minProperties: 2
+					},
+					ExportDeclaration: {
+						multiline: true,
+						minProperties: 2
+					}
+				}
+			],
+
+			// 2) If the object is multiline, put each property on its own line
+			"object-property-newline": [
+				"error",
+				{
+					allowAllPropertiesOnSameLine: false
+				}
+			],
+
+			indent: [ "error", "tab", { "SwitchCase": 1 } ],
+			semi: [ "error", "always" ],
+			"arrow-parens": [ "error", "always" ],
+			"object-curly-spacing": [ "error", "always" ],
+			"array-bracket-spacing": [ "error", "always" ],
+			'lines-between-class-members': [ 'error', 'always' ],
+			'newline-after-var': [ 'error', 'always' ],
+			'newline-before-return': 'error',
+			'brace-style': [ 'error', '1tbs', { allowSingleLine: false } ],
+			"no-unreachable": "off"
+		}
+	}
+];

package/index.js

@@ -12,6 +12,7 @@ import _clean_object from './src/clean/object.js';
 import _clean_string from './src/clean/string.js';
 import _clean_timestamp from './src/clean/timestamp.js';
 import _clean_uuid from './src/clean/uuid.js';
+import _collectImports from './src/collectImports.js';
 import _combineFiles from './src/combineFiles.js';
 import _convertBytes from './src/convertBytes.js';
 import _decrypt from './src/decrypt.js';
@@ -19,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';
@@ -38,11 +38,12 @@ 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';
 
 export { _build as build };
+export { _collectImports as collectImports };
 export { _combineFiles as combineFiles };
 export { _convertBytes as convertBytes };
 export { _decrypt as decrypt };
@@ -50,88 +51,117 @@ 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.
-     *
-     * @param {Object} options - The options for the build process.
-     * @param {string} [options.src='./src'] - The source directory to build from.
-     * @param {string} [options.dest='./index.js'] - The destination file to write the built content to.
-     * @param {boolean} [options.exportRoots=true] - Whether to export root files.
-     * @param {string[]} [options.ignore=[]] - An array of file patterns to ignore.
-     * @param {boolean} [options.includeComments=true] - Whether to include comments in the generated file.
-     * @param {boolean} [options.dts=false] - Whether to generate TypeScript declaration files.
-     * @returns {Promise<boolean>} A promise that resolves to true when the build is complete.
-     */
-    build: _build,
-    combineFiles: _combineFiles,
-    /**
-     * Converts a given number of bytes into a more readable string format with appropriate units.
-     *
-     * @param {number} bytes - The number of bytes to convert.
-     * @param {number} [precision=2] - The number of decimal places to include in the result.
-     * @returns {string} The converted bytes in a string format with appropriate units.
-     */
-    convertBytes: _convertBytes,
-    decrypt: _decrypt,
-    /**
-     * Iterates over elements of an array or properties of an object, invoking a callback for each element/property.
-     * The iteration stops if the callback returns `false`.
-     *
-     * @example each({ a: 1, b: 2 }, (value, key) => { console.log(value, key); });
-     * @param {Object|Array} objectOrArray - The object or array to iterate over.
-     * @param {Function} callback - The function to invoke per iteration. It is invoked with two arguments: (value, key/index).
-     * @returns {void}
-     */
-    each: _each,
-    eachAsync: _eachAsync,
-    encrypt: _encrypt,
-    getAllFiles: _getAllFiles,
-    ignoreMe: _ignoreMe,
-    isUUID: _isUUID,
-    md5: _md5,
-    setLocalEnvs: _setLocalEnvs,
-    thingType: _thingType,
-    toPennies: _toPennies,
-    uuid: _uuid,
-    validateSchema: _validateSchema,
-    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,
-    },
-    ignoreFolder: {
-        ignoreMe: _ignoreFolder_ignoreMe,
-    },
-    password: {
-        check: _password_check,
-        hash: _password_hash,
-    },
-    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,
-        shouldIgnore: _utils_shouldIgnore,
-    },
+	/**
+	 * Builds a file from the specified source directory and writes it to the destination file.
+	 *
+	 * @param {Object} options - The options for the build process.
+	 * @param {string} [options.src='./src'] - The source directory to build from.
+	 * @param {string} [options.dest='./index.js'] - The destination file to write the built content to.
+	 * @param {boolean} [options.exportRoots=true] - Whether to export root files.
+	 * @param {string[]} [options.ignore=[]] - An array of file patterns to ignore.
+	 * @param {boolean} [options.includeComments=true] - Whether to include comments in the generated file.
+	 * @param {boolean} [options.dts=false] - Whether to generate TypeScript declaration files.
+	 * @returns {Promise<boolean>} A promise that resolves to true when the build is complete.
+	 */
+	build: _build,
+	collectImports: _collectImports,
+	combineFiles: _combineFiles,
+	/**
+	 * Converts a given number of bytes into a more readable string format with appropriate units.
+	 *
+	 * @param {number} bytes - The number of bytes to convert.
+	 * @param {number} [precision=2] - The number of decimal places to include in the result.
+	 * @returns {string} The converted bytes in a string format with appropriate units.
+	 */
+	convertBytes: _convertBytes,
+	decrypt: _decrypt,
+	/**
+	 * Iterates over elements of an array or properties of an object, invoking a callback for each element/property.
+	 * The iteration stops if the callback returns `false`.
+	 *
+	 * @example each({ a: 1, b: 2 }, (value, key) => { console.log(value, key); });
+	 * @param {Object|Array} objectOrArray - The object or array to iterate over.
+	 * @param {Function} callback - The function to invoke per iteration. It is invoked with two arguments: (value, key/index).
+	 * @returns {void}
+	 */
+	each: _each,
+	eachAsync: _eachAsync,
+	encrypt: _encrypt,
+	getAllFiles: _getAllFiles,
+	isUUID: _isUUID,
+	md5: _md5,
+	setLocalEnvs: _setLocalEnvs,
+	shouldIgnore: _shouldIgnore,
+	thingType: _thingType,
+	toPennies: _toPennies,
+	uuid: _uuid,
+	validateSchema: _validateSchema,
+	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,
+	},
+	password: {
+		check: _password_check,
+		hash: _password_hash,
+	},
+	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,
+	},
 };