qtools-library-dot-d 1.0.4 → 1.0.6

package/README.md

@@ -1,56 +1,241 @@
-# qtools-library-dot-d
+## NAME
 
-# NOT READY. STILL WORKING IT OUT.
+    qtools-library-dot-d is system for creating dynamic, modular libraries in Node.js. The dotD (dot-D) pattern provides a powerful way to build extensible applications through automatic module discovery and loading.
 
-NAME
+## What is qtools-library-dot-d?
 
-    qtools-library-dot-d
+**qtools-library-dot-d** is a Node.js library that enables dynamic module loading from directories. It automatically discovers JavaScript files in specified directories and makes them available as methods on a library object, creating a plugin-like architecture without the complexity of traditional plugin systems.
 
-DESCRIPTION
+## The dotD Pattern
 
-Utility provides tools to scan a directory for NodeJS modules, require() them into existance with tools to connect them to a system.
+The "dotD" naming convention (short for "dot-D") refers to directories that contain dynamically loadable modules:
 
+- `modules.d/` - Directory containing module files
+- `endpoints.d/` - Directory containing API endpoint modules  
+- `accessPoints.d/` - Directory containing data access modules
+- `mappers.d/` - Directory containing data mapping modules
 
+Each `.js` file in a dotD directory becomes a method on the library object, with the filename determining the method name.
 
-First use case is adding endpoints to an expressJS system. When instantiated, qtDotD
+## Why Use Dynamic dotD Libraries?
 
-scans a directory containing modules, dotLib.d. It requires it with two parameters,
+### 1. **Automatic Module Discovery**
 
-dotD and passThroughArgs. For this case, passThrough args has two properties, 
+No need to manually import or register modules. Simply add a `.js` file to the dotD directory and it's automatically available.
 
-expressApp and routingPrefix. The module uses these to construct one or more 
+```javascript
+// Traditional approach - manual imports
+const module1 = require('./modules/module1');
+const module2 = require('./modules/module2');
+const module3 = require('./modules/module3');
 
-expressJS endpoitns.
+// dotD approach - automatic discovery
+const library = qtLibDotD({ libraryName: 'myLibrary' });
+library.setLibraryPath('./modules.d');
+library.loadModules();
+// All modules in modules.d/ are now available as library.moduleName()
+```
 
+### 2. **Plugin Architecture**
 
+Create extensible applications where new functionality can be added by simply dropping files into directories.
 
-the dotD object contains three parameters, add....
+```javascript
+// Add new functionality by creating a new file
+// modules.d/newFeature.js -> library.newFeature()
+```
 
-ASYNCHRONOUS CODE SAMPLE
+### 3. **Shared Resources**
 
-const promptObjects = require('qtools-library-dot-d')({
-	libraryName: 'promptObjects',
-}, callback);
-promptObjects.setLibraryPath(path.join(__dirname, 'prompts.d'), callback);
+Pass common resources (configuration, database connections, utilities) to all modules through `passThroughParameters`.
 
-const passThroughParameters = {};
-promptObjects.loadModules({ passThroughParameters }, callback);
-promptObjects.seal(); //make the library immutable
+```javascript
+const passThroughParameters = {
+    config: getConfig(),
+    database: dbConnection,
+    logger: xLog,
+    utilities: commonUtils
+};
+library.loadModules({ passThroughParameters });
+```
 
+### 4. **Clean Separation of Concerns**
 
+Each module is self-contained and focused on a single responsibility, making code easier to maintain and test.
 
-NEW SYNCHROMOUS CODE SAMPLE:
+### 5. **Runtime Flexibility**
 
-const promptObjects = require('qtools-library-dot-d')({
-	libraryName: 'promptObjects',
-});
-promptObjects.setLibraryPath(path.join(__dirname, 'prompts.d'));
+Modules can be loaded synchronously or asynchronously, and the library can be sealed to prevent modifications after loading.
 
-const passThroughParameters = {};
-promptObjects.loadModules({ passThroughParameters });
-promptObjects.seal(); //make the library immutable
+## Real-World Use Cases
 
+### API Endpoint Management
 
-HISTORY
+```javascript
+// endpoints.d/userEndpoints.js
+// endpoints.d/productEndpoints.js  
+// endpoints.d/orderEndpoints.js
+// Each file defines related API endpoints
+```
 
+### Data Access Layer
+
+```javascript
+// accessPoints.d/getUserData.js
+// accessPoints.d/saveUserData.js
+// accessPoints.d/deleteUserData.js
+// Each file handles specific data operations
+```
+
+### Business Logic Modules
+
+```javascript
+// processors.d/validateOrder.js
+// processors.d/calculateTax.js
+// processors.d/sendNotification.js
+// Each file contains specific business logic
+```
+
+### CLI Command Tools
+
+```javascript
+// commands.d/deploy.js
+// commands.d/backup.js
+// commands.d/migrate.js
+// Each file implements a CLI command
+```
+
+## How It Works
+
+### 1. **Library Creation**
+
+```javascript
+const qtLibDotD = require('qtools-library-dot-d');
+const library = qtLibDotD({ libraryName: 'myLibrary' });
+```
+
+### 2. **Module Directory Setup**
+
+```javascript
+library.setLibraryPath('./modules.d');
+```
+
+### 3. **Shared Resource Definition**
+
+```javascript
+const passThroughParameters = {
+    config: appConfig,
+    database: dbConnection,
+    logger: logger
+};
+```
+
+### 4. **Module Loading**
+
+```javascript
+// Synchronous
+library.loadModules({ passThroughParameters });
+
+// Asynchronous
+library.loadModules({ passThroughParameters }, callback);
+```
+
+### 5. **Library Sealing**
+
+```javascript
+library.seal(); // Prevents further modifications
+```
+
+### 6. **Module Usage**
+
+```javascript
+// If you have modules.d/processOrder.js
+library.processOrder(orderData);
+
+// If you have modules.d/sendEmail.js  
+library.sendEmail(recipient, message);
+```
+
+## Module Structure
+
+Every dotD module follows this pattern:
+
+```javascript
+const moduleName = __filename.replace(__dirname + '/', '').replace(/.js$/, '');
+
+const moduleFunction = ({ moduleName } = {}) => ({ dotD, passThroughParameters } = {}) => {
+
+    const workingFunction = (/* your parameters */) => {
+        // Access shared resources
+        const config = passThroughParameters.config;
+        const logger = passThroughParameters.logger;
+
+        // Your module logic here
+
+        return result;
+    };
+
+    // Register the function
+    dotD.library.add(moduleName, workingFunction);
+};
+
+module.exports = moduleFunction({ moduleName });
+```
+
+## Benefits Over Traditional Approaches
+
+| Traditional           | dotD Libraries              |
+| --------------------- | --------------------------- |
+| Manual imports        | Automatic discovery         |
+| Tight coupling        | Loose coupling              |
+| Hard to extend        | Easy to extend              |
+| Configuration in code | Configuration through files |
+| Monolithic            | Modular                     |
+| Static structure      | Dynamic structure           |
+
+## Getting Started
+
+1. **Install the dependency:**
+   
+   ```bash
+   npm install qtools-library-dot-d
+   ```
+
+2. **Run the example:**
+   
+   ```bash
+   npm start
+   ```
+
+3. **Create your own modules:**
+   
+   - Add `.js` files to `demoModules_DotD/`
+   - Follow the module pattern shown in the examples
+   - Access shared resources via `passThroughParameters`
+
+## Advanced Features
+
+- **Async module loading** for modules that need initialization
+- **Error handling** during module loading
+- **Library introspection** with `toString()` and `qtdProcessLog()`
+- **Multiple libraries** in the same application
+- **Nested module structures** for complex applications
+
+## Integration with Larger Systems
+
+The dotD pattern works particularly well in:
+
+- **Web frameworks** (Express, Koa) for route organization
+- **API systems** for endpoint management
+- **CLI tools** for command organization  
+- **Microservices** for feature modularity
+- **Plugin systems** for extensible applications
+
+This pattern is used extensively in the qtools ecosystem for building scalable, maintainable Node.js applications.
+
+## HISTORY
+
+v1.06 - updated README
+v1.05 - cleaned up toString() report, returns exception list (or err if callback) if needed, added qtools-functional-library
 v1.04 - Now tolerates (and reports) directories and files that are not modules.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qtools-library-dot-d",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Scan a directory for JS modules that can execute and addMe() that attaches it to some form of name/value list, eg, a Map() with functions as values or an xPressJS route/endpoint list.",
   "main": "qtools-library-dot-d.js",
   "scripts": {
@@ -9,6 +9,7 @@
   "author": "TQ White II",
   "license": "ISC",
   "dependencies": {
-    "qtools-asynchronous-pipe-plus": "^1.0.2"
+    "qtools-asynchronous-pipe-plus": "^1.0.2",
+    "qtools-functional-library": "^2.0.4"
   }
 }

package/qtools-library-dot-d.js

@@ -9,6 +9,8 @@ const os = require('os');
 const path = require('path');
 const fs = require('fs');
 
+const qt = require('qtools-functional-library');
+
 //START OF moduleFunction() ============================================================
 const moduleFunction =
 	({ moduleName } = {}) =>
@@ -98,7 +100,8 @@ const moduleFunction =
 				let outString = typeof item;
 				if (typeof item == 'function') {
 					const result = item.toString().match(/\((?<args>.*?\))/);
-					outString = `(${result.qtGetSurePath('groups.args', 'function')})`;
+					const args = result.qtGetSurePath('groups.args', 'function');
+					outString = `(${args == ')' ? args + ' # function takes no arguments' : args}`;
 				}
 				return outString;
 			};
@@ -111,7 +114,7 @@ const moduleFunction =
 								? libraryObject[name]
 								: formatProperty(libraryObject[name])
 						}\n\t`,
-					`\n${libraryName} Library\n\t`,
+					`\n${libraryName} Library Elements\n\t`,
 				)
 				.replace(/\n\t$/, '');
 
@@ -204,10 +207,17 @@ const moduleFunction =
 			// INIT AND EXECUTE THE PIPELINE
 
 			if (typeof callback == 'function') {
-				callback();
+				if (exceptionList.length) {
+					callback(exceptionList);
+				} else {
+					callback();
+				}
 			} else {
-				return;
-			}
+				if (exceptionList.length) {
+					return exceptionList;
+				} else {
+					return;
+				}}
 		};
 
 		const externalElements = {