@awesomeness-js/utils 1.0.12 → 1.0.14

package/README.md

@@ -1,16 +1,149 @@
 # Nothing Special
 
-Just some utils...
+Just some <u>zero dependency</u> utils ...
+
+
+---
+
+# 🚀 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.  
+
+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 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?  
+
+**Webpack is great for frontend bundling, but it’s not ideal for this use case.** Here’s why this script is a better choice:  
+
+✔ **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`.  
+✔ **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.  
+
+With this script, you can stop wasting time managing exports and focus on writing code.  
+
+---
+
+## ⚡ How It Works  
+
+1. **Scans** the `./src` directory for `.js` files.  
+2. **Generates** import statements dynamically.  
+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.  
+
+---
+
+## 🔧 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
+
+import { build } from '@awesomeness-js/utils';
+
+build();
+
+```
+
+If you need custom paths, modify the `src` and `dest` options in the script:  
+
+```javascript
 
-example usage:
-```javascript   
 import { build } from '@awesomeness-js/utils';
 
-const built = build({
-    src: './src',
-    dest: ['./', 'index.js']
+build({
+    src: './my-functions',
+    dest: './api.js'
 });
+```
+
+---
+
+## 📜 Example Output  
+
+If your folder structure looks like this:  
+
+```
+src/
+│── utils/
+│   ├── formatDate.js
+│   ├── generateId.js
+│── services/
+│   ├── fetchData.js
+│── calculate.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);
+```
+
+or 
+
+```javascript
+import { utils } from './api.js';
+const id = utils.generateId();
+console.log(id);
+```
+
+
+
+---
+
+## 🚀 Who Should Use This?  
+
+- **Node.js developers** who want automatic API exports.  
+- **Backend teams** managing large function directories.  
+- **Anyone tired of manually updating `index.js` files.**  
+
+If you don’t need Webpack’s **complexity** but want **automatic structured exports**, this script is for you.  
 
-console.log({ built });
+👉 **Try it out and let automation handle your exports!** 🚀  
 
-```

package/build.js

@@ -2,5 +2,10 @@ import build from './src/build.js';
 
 build({
     src: './src',
-    dest: './index.js'
+    dest: './index.js',
+    ignore: [
+        'ignoreMe.js',
+        'ignoreFolder/*',
+        'namespaceExample/*',
+    ],
 });

package/index.js

@@ -28,16 +28,16 @@ export { _toPennies as toPennies };
 export { _uuid as uuid };
 
 export default {
+    /**${match[1]}*/
+    build: _build,
+    combineFiles: _combineFiles,
     /**
-     * Generates a output file that consolidates all src functions.
+     * Converts a given number of bytes into a more readable string format with appropriate units.
      *
-     * @param {Object} [options] - The options for generating the output file.
-     * @param {string} [options.src='./src'] - The source directory.
-     * @param {array} [options.dest=['./', 'index.js']] - The destination file.
-     * @returns {bool} - Returns true if the output file is generated successfully.
+     * @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.
      */
-    build: _build,
-    combineFiles: _combineFiles,
     convertBytes: _convertBytes,
     each: _each,
     eachAsync: _eachAsync,
@@ -46,5 +46,5 @@ export default {
     md5: _md5,
     setLocalEnvs: _setLocalEnvs,
     toPennies: _toPennies,
-    uuid: _uuid
+    uuid: _uuid,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@awesomeness-js/utils",
-    "version": "1.0.12",
+    "version": "1.0.14",
     "description": "Awesomeness - Utils",
     "repository": {
       "type": "git",

package/src/build.js

@@ -1,115 +1,161 @@
 import { readdirSync, statSync, writeFileSync, readFileSync } from 'fs';
 import { join, sep } from 'path';
 
-/**
- * Generates a output file that consolidates all src functions.
- *
- * @param {Object} [options] - The options for generating the output file.
- * @param {string} [options.src='./src'] - The source directory.
- * @param {array} [options.dest=['./', 'index.js']] - The destination file.
- * @returns {bool} - Returns true if the output file is generated successfully.
- */
-
+function shouldIgnore(filePath, ignorePatterns) {
+    const ignore = ignorePatterns.some(pattern => {
+        const normalizedPath = filePath.replace(/\\/g, '/');
+        const normalizedPattern = pattern.replace(/\\/g, '/');
+        if (normalizedPath === normalizedPattern) return true;
+        if (normalizedPattern.endsWith('/*')) {
+            const baseDir = normalizedPattern.slice(0, -2);
+            return normalizedPath.startsWith(baseDir + '/');
+        }
+        if (normalizedPattern.endsWith('/')) {
+            return normalizedPath === normalizedPattern.slice(0, -1) ||
+                   normalizedPath.startsWith(normalizedPattern);
+        }
+        return false;
+    });
+    //console.log('shouldIgnore', filePath, ignore);
+    return ignore;
+}
 
-function getAllFiles(base, dir, files = []) {
+function getAllFiles(base, dir, files = [], ignore = []) {
     const directory = join(base, dir);
-	let sortedFiles = readdirSync(directory).sort();
+    const normalizedDir = dir.replace(/\\/g, '/');
+    if (ignore.some(pattern => normalizedDir.startsWith(pattern.replace(/\/\*$/, '')))) {
+        //.log('Ignoring folder:', normalizedDir);
+        return files;
+    }
+    let sortedFiles = readdirSync(directory).sort();
     sortedFiles.forEach(file => {
         const fullPath = join(directory, file);
-
-        if (
-            statSync(fullPath).isDirectory() &&
-            file !== '_template'
-        ) {
-            files = getAllFiles(base, join(dir, file), files);
-        } else if (file.endsWith('.js') && !file.match(/\..*\./)) { // Exclude files with two or more dots
-            files.push(join(dir, file));
+        const relativePath = join(dir, file).replace(/\\/g, '/');
+        if (shouldIgnore(relativePath, ignore)) {
+            //console.log('Ignoring file:', relativePath);
+            return;
         }
-    });
-    return files;
-}
-
-
-function objectToString(obj, allComments, indent = 4, level = 1) {
-    const spaces = ' '.repeat(indent * level);
-    const entries = Object.entries(obj).map(([key, value]) => {
-
-        if (typeof value === 'object') {
-            return `${spaces}${key}: ${objectToString(value, allComments, indent, level + 1)}`;
+        if (statSync(fullPath).isDirectory() && file !== '_template') {
+            getAllFiles(base, join(dir, file), files, ignore);
+        } else if (file.endsWith('.js') && !file.match(/\..*\./)) {
+            files.push(relativePath);
         }
-
-		if(key.startsWith('___')){
-			let realKey = key.replace('___', '');
-
-			// split comment based on lines and insert spaces
-			let comment = allComments[value];
-			comment = comment.split('\n').map((line) => `${spaces.replace(' ', '')} ${line}`).join('\n');
-
-			return `${comment}\n${spaces}${realKey}: ${value}`;
-		} else {
-			return `${spaces}${key}: ${value}`;
-		}
-		
     });
-
-	return `{\n${entries.join(',\n')}\n${' '.repeat(indent * (level - 1))}}`;
-
+    return files;
 }
 
-
 function extractJSDocComment(filePath) {
     const fileContent = readFileSync(filePath, 'utf8');
     const match = fileContent.match(/\/\*\*([\s\S]*?)\*\//);
     return match ? `/**${match[1]}*/` : '';
 }
 
+/**
+ * Generates the export file contents.
+ *
+ * For each file, if includeComments is true, its JSDoc comment is placed
+ * immediately above its key in the default export object.
+ */
+function generateExports(src, exportRoots, ignore, includeComments = false) {
+    const allFiles = getAllFiles(src, '.', [], ignore);
+    let importStatements = '';
+    let flatExports = [];
+    let nestedExports = {}; // Build a tree for nested exports
+
+    // Create file info objects
+    const fileDataList = allFiles.map(file => {
+        const normalizedFile = file.replace(/\\/g, '/');
+        const parts = normalizedFile.split('/');
+        const fileName = parts.pop();
+        const functionName = fileName.replace(/\.js$/, '');
+        const namespaceParts = parts;
+        const importVarName = namespaceParts.length > 0
+            ? '_' + [...namespaceParts, functionName].join('_')
+            : '_' + functionName;
+        const importPath = src + '/' + normalizedFile.replace(/\.js$/, '');
+        const jsDocComment = includeComments ? extractJSDocComment(join(src, normalizedFile)) : '';
+        return { normalizedFile, parts: namespaceParts, functionName, importVarName, importPath, jsDocComment };
+    });
 
-function generateExports(src, exportRoots) {
-    const allFiles = [];
-    const fnFiles = getAllFiles(src, '.');
-    allFiles.push(...fnFiles);
-
-    let imports = '';
-    let allExports = '';
-    let apiObject = {};
-
-	let allComments = {};
-
+    // Generate import statements (without comments)
+    fileDataList.forEach(({ importVarName, importPath }) => {
+        importStatements += `import ${importVarName} from '${importPath}.js';\n`;
+    });
 
-    for (const file of allFiles) {
-        const parts = file.split(sep).filter(p => p !== '.');
-        const functionName = parts.pop().replace('.js', '');
-        const namespace = parts.join('_');
-        const importPath = src + '/' + file.replace(/\.js$/, '').replace(/\\/g, '/');
-        const filePath = join(src, file);
+    // Build flat exports and nested export tree.
+    fileDataList.forEach(({ parts, functionName, importVarName, jsDocComment }) => {
+        if (parts.length === 0) {
+            flatExports.push({ functionName, importVarName, jsDocComment });
+        } else {
+            let current = nestedExports;
+            parts.forEach(part => {
+                if (!current[part]) {
+                    current[part] = {};
+                }
+                current = current[part];
+            });
+            // Store the leaf export along with its JSDoc comment.
+            current[functionName] = { importVarName, jsDocComment };
+        }
+    });
 
-        // Extract JSDoc comment, if present
-		let hasComment = '';
-        const jsDocComment = extractJSDocComment(filePath);
-		if(jsDocComment){
-			allComments[`${namespace}_${functionName}`] = jsDocComment
-			hasComment = '___'
-		}
+    // Generate flat export statements for default export object.
+    let flatExportLines = '';
+    flatExports.forEach(({ functionName, importVarName, jsDocComment }) => {
+        if (exportRoots) {
+            if (includeComments && jsDocComment) {
+                // Indent each comment line by 4 spaces.
+                const indentedComment = jsDocComment.split('\n').map(line => '    ' + line).join('\n');
+                flatExportLines += indentedComment + '\n';
+            }
+            flatExportLines += `    ${functionName}: ${importVarName},\n`;
+        }
+    });
 
+    // Recursively generate code for nested namespaces,
+    // placing JSDoc comments above each leaf key.
+    function generateNamespaceCode(nsObj, indentLevel) {
+        const indent = '    '.repeat(indentLevel);
+        let lines = ['{'];
+        for (const key in nsObj) {
+            const value = nsObj[key];
+            if (typeof value === 'object' && value.hasOwnProperty('importVarName')) {
+                // Leaf node.
+                if (includeComments && value.jsDocComment) {
+                    const indentedComment = value.jsDocComment.split('\n').map(line => indent + '    ' + line).join('\n');
+                    lines.push(indentedComment);
+                }
+                lines.push(`${indent}    ${key}: ${value.importVarName},`);
+            } else {
+                // Nested namespace.
+                const nestedCode = generateNamespaceCode(value, indentLevel + 1);
+                lines.push(`${indent}    ${key}: ${nestedCode},`);
+            }
+        }
+        lines.push(indent + '}');
+        return lines.join('\n');
+    }
 
-        // Generate import statement with JSDoc comment if available
-        imports += `import ${namespace}_${functionName} from '${importPath}.js';\n`;
+    // Generate the default export object.
+    let namespaceExportLines = '';
+    for (const ns in nestedExports) {
+        const nsCode = generateNamespaceCode(nestedExports[ns], 1);
+        namespaceExportLines += `    ${ns}: ${nsCode},\n`;
+    }
 
-        // generate exports
-        if(exportRoots && !namespace){ allExports += `export { _${functionName} as ${functionName} };\n`; }
+    const defaultExportCode = 'export default {\n' +
+        flatExportLines +
+        namespaceExportLines +
+        '};';
 
-        // Populate the API object structure
-        let current = apiObject;
-        for (const part of parts) {
-            current[part] = current[part] || {};
-            current = current[part];
+    // Generate individual flat export statements.
+    let flatExportStatements = '';
+    flatExports.forEach(({ functionName, importVarName }) => {
+        if (exportRoots) {
+            flatExportStatements += `export { ${importVarName} as ${functionName} };\n`;
         }
-        current[`${hasComment}${functionName}`] = `${namespace}_${functionName}`;
-    }
-
-    const apiContent = 'export default ' + objectToString(apiObject, allComments) + ';';
+    });
 
-    // Add a header comment
     const headerComment = `/**
  * This file is auto-generated by the build script.
  * It consolidates API functions for use in the application.
@@ -117,16 +163,21 @@ function generateExports(src, exportRoots) {
  */
 `;
 
-    return headerComment + imports + '\n' + allExports + '\n' + apiContent;
+    return headerComment +
+           importStatements + '\n' +
+           flatExportStatements +
+           '\n' +
+           defaultExportCode;
 }
 
-
 async function build({
     src = './src',
     dest = './index.js',
-    exportRoots = true
+    exportRoots = true,
+    ignore = [],
+    includeComments = true
 } = {}) {
-    const indexContent = generateExports(src, exportRoots);
+    const indexContent = generateExports(src, exportRoots, ignore, includeComments);
     writeFileSync(dest, indexContent);
     return true;
 }

package/src/convertBytes.js

@@ -1,3 +1,11 @@
+
+/**
+ * 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.
+ */
 export default function convertBytes(bytes, precision = 2) {
     const units = ['B', 'KB', 'MB', 'GB', 'TB'];
     bytes = Math.max(bytes, 0);

package/src/ignoreFolder/ignoreMe.js

@@ -0,0 +1,3 @@
+export default function ignoreMeTest() {
+    console.log('I should not be in the build!');
+};

package/src/ignoreMe.js

@@ -0,0 +1,3 @@
+export default function ignoreMeTest() {
+    console.log('I should not be in the build!');
+};

package/src/namespaceExample/deep/deep.js

@@ -0,0 +1,10 @@
+
+/**
+ * A function that returns the input value.
+ *
+ * @param {*} something - The input value to be returned.
+ * @returns {*} The same value that was passed as input.
+ */
+export default function deep(something) {
+    return something;
+}

package/src/namespaceExample/example.js

@@ -0,0 +1,3 @@
+export default function example() {
+    return true
+}

package/test.js

@@ -9,6 +9,9 @@ console.log({md5Test});
 let uuidTest = utils.uuid();
 console.log({uuidTest});
 
+let convertBytesTest = utils.convertBytes(1024);
+console.log({convertBytesTest});
+
 let isUUIDTest = utils.isUUID(uuidTest);
 console.log({isUUIDTest});