qtools-library-dot-d 1.0.5 → 1.0.6

package/README.md

@@ -1,208 +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.
 
+### 5. **Runtime Flexibility**
 
+Modules can be loaded synchronously or asynchronously, and the library can be sealed to prevent modifications after loading.
 
-SYNCHROMOUS CODE SAMPLE:
+## Real-World Use Cases
 
-const promptObjects = require('qtools-library-dot-d')({
-	libraryName: 'promptObjects',
-});
-promptObjects.setLibraryPath(path.join(__dirname, 'prompts.d'));
+### API Endpoint Management
 
-const passThroughParameters = {};
-promptObjects.loadModules({ passThroughParameters });
-promptObjects.seal(); //make the library immutable
+```javascript
+// endpoints.d/userEndpoints.js
+// endpoints.d/productEndpoints.js  
+// endpoints.d/orderEndpoints.js
+// Each file defines related API endpoints
+```
 
+### Data Access Layer
 
-COMPLETE WORKING CODE SAMPLE
+```javascript
+// accessPoints.d/getUserData.js
+// accessPoints.d/saveUserData.js
+// accessPoints.d/deleteUserData.js
+// Each file handles specific data operations
+```
 
-// ================================================================================
-// index.js for demonstration
+### Business Logic Modules
 
-#!/usr/bin/env node
-'use strict';
-// Suppress punycode deprecation warning
-process.noDeprecation = true;
+```javascript
+// processors.d/validateOrder.js
+// processors.d/calculateTax.js
+// processors.d/sendNotification.js
+// Each file contains specific business logic
+```
 
-const moduleName = __filename.replace(__dirname + '/', '').replace(/.js$/, ''); //this just seems to come in handy a lot
+### CLI Command Tools
 
-// const qt = require('qtools-functional-library'); //also exposes qtLog(); qt.help({printOutput:true, queryString:'.*', sendJson:false});
+```javascript
+// commands.d/deploy.js
+// commands.d/backup.js
+// commands.d/migrate.js
+// Each file implements a CLI command
+```
 
-const os = require('os');
-const path = require('path');
-const fs = require('fs');
+## How It Works
 
+### 1. **Library Creation**
+
+```javascript
 const qtLibDotD = require('qtools-library-dot-d');
+const library = qtLibDotD({ libraryName: 'myLibrary' });
+```
 
-//START OF moduleFunction() ============================================================
-const moduleFunction =
-	({ moduleName } = {}) =>
-	({ unused } = {}) => {
-	
-		// ========================================================================
-		// SYNCHRONOUS DEMO
-
-		const synchronousDemo = () => {
-			const demoDotD = qtLibDotD({
-				libraryName: 'demoDotD',
-			});
-
-			const libraryModulesPath = path.join(__dirname, 'demoModules_DotD');
-
-			const passThroughParameters = {
-				message: 'Hello from a dotDlib module',
-				add: (a, b) => a + b,
-			};
-
-			demoDotD.setLibraryPath(libraryModulesPath);
-			demoDotD.loadModules({ passThroughParameters });
-			demoDotD.seal();
-
-			// console.log(demoDotD.qtdProcessLog());
-			console.log(demoDotD.toString());
-
-			demoDotD.demo1();
-			demoDotD.demo2(10, 7);
-		};
-			console.log(`SYNCHRONOUS DEMO =====================================`);
-			synchronousDemo();
-	
-		// ========================================================================
-		// ASYNCHRONOUS DEMO
-
-		const asynchronousDemo = (callback) => {
-			const localCallback = (err) => {
-				demoDotD.seal();
-				callback(err, demoDotD);
-			};
-
-			const demoDotD = qtLibDotD({
-				libraryName: 'demoDotD',
-			});
-
-			const libraryModulesPath = path.join(__dirname, 'demoModules_DotD');
-
-			const passThroughParameters = {
-				message: 'Hello from a dotDlib module',
-				add: (a, b) => a + b,
-			};
-
-			demoDotD.setLibraryPath(libraryModulesPath);
-			demoDotD.loadModules({ passThroughParameters }, localCallback);
-		};
-
-		console.log(`\n\nASYNCHRONOUS DEMO =====================================`);
-
-		const callback = (err, demoDotD) => {
-			console.log(demoDotD.toString());
-			demoDotD.demo1();
-			demoDotD.demo2(10, 7);
-		};
-		
-		asynchronousDemo(callback);
-	};
-
-
-// ================================================================================
-// demo1.js
-
-#!/usr/bin/env node
-'use strict';
-// Suppress punycode deprecation warning
-process.noDeprecation = true;
-
-const moduleName = __filename.replace(__dirname + '/', '').replace(/.js$/, ''); //this just seems to come in handy a lot
-
-//START OF moduleFunction() ============================================================
-const moduleFunction = ({ moduleName } = {}) => ({ dotD, passThroughParameters } = {}) => {
+### 2. **Module Directory Setup**
+
+```javascript
+library.setLibraryPath('./modules.d');
+```
 
-	const workingFunction = () => {
-		console.log(`${passThroughParameters.message} [${moduleName}]`);
-		return 'hello';
-	};
-	
+### 3. **Shared Resource Definition**
 
-	dotD.library.add(moduleName, workingFunction);
+```javascript
+const passThroughParameters = {
+    config: appConfig,
+    database: dbConnection,
+    logger: logger
 };
+```
 
-//END OF moduleFunction() ============================================================
+### 4. **Module Loading**
 
-module.exports = moduleFunction({ moduleName }); //runs it right now
-//END OF moduleFunction() ============================================================
+```javascript
+// Synchronous
+library.loadModules({ passThroughParameters });
 
-module.exports = moduleFunction({ moduleName })({});
+// Asynchronous
+library.loadModules({ passThroughParameters }, callback);
+```
 
+### 5. **Library Sealing**
 
-// ================================================================================
-//demo2.js
+```javascript
+library.seal(); // Prevents further modifications
+```
 
-#!/usr/bin/env node
-'use strict';
-// Suppress punycode deprecation warning
-process.noDeprecation = true;
+### 6. **Module Usage**
 
-const moduleName = __filename.replace(__dirname + '/', '').replace(/.js$/, ''); //this just seems to come in handy a lot
+```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$/, '');
 
-//START OF moduleFunction() ============================================================
 const moduleFunction = ({ moduleName } = {}) => ({ dotD, passThroughParameters } = {}) => {
 
-	const workingFunction = (arg1, arg2) => {
-		console.log(`Pass Through Function: ${arg1}+${arg2}=${passThroughParameters.add(arg1, arg2)} [${moduleName}]`);
-		return 'hello';
-	};
-	
+    const workingFunction = (/* your parameters */) => {
+        // Access shared resources
+        const config = passThroughParameters.config;
+        const logger = passThroughParameters.logger;
+
+        // Your module logic here
+
+        return result;
+    };
 
-	dotD.library.add(moduleName, workingFunction);
+    // Register the function
+    dotD.library.add(moduleName, workingFunction);
 };
 
-//END OF moduleFunction() ============================================================
+module.exports = moduleFunction({ moduleName });
+```
 
-module.exports = moduleFunction({ moduleName }); //runs it right now
+## 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           |
 
-HISTORY
+## Getting Started
 
-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.
+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
 
-HISTORY
+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.5",
+  "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": {