@adaas/a-utils 0.1.15 → 0.1.17

package/src/lib/A-Logger/README.md

@@ -0,0 +1,383 @@
+# A-Logger Component
+
+A sophisticated logging component for ADAAS applications with advanced formatting, scope-based organization, and configurable output levels.
+
+## Overview
+
+The A_Logger component provides comprehensive logging capabilities with:
+
+- **Scope-based Formatting**: Consistent message alignment regardless of scope name length
+- **Color-coded Output**: Terminal color support for visual distinction
+- **Object Formatting**: Pretty-printing of JSON objects with proper indentation
+- **Error Handling**: Special formatting for A_Error and standard Error objects
+- **Log Level Filtering**: Configurable filtering based on severity levels
+- **Performance Optimized**: Efficient handling of large objects and rapid logging
+
+## Features
+
+### 🎨 Visual Output
+- **Terminal Colors**: Support for 9 different colors (green, blue, red, yellow, gray, magenta, cyan, white, pink)
+- **Consistent Alignment**: All log messages align properly regardless of scope name length
+- **Structured Formatting**: Multi-line messages with proper indentation and separators
+
+### 📊 Data Types Support
+- **Strings**: Simple text messages with optional color coding
+- **Objects**: Pretty-printed JSON with nested structure support
+- **Arrays**: Formatted array output with proper indentation
+- **Errors**: Special handling for both A_Error and standard Error objects
+- **Multi-arguments**: Support for logging multiple values in a single call
+
+### 🔧 Configuration
+- **Log Levels**: debug, info, warn, error, all
+- **Environment Variables**: Configurable via A_LOGGER_LEVEL environment variable
+- **Scope Integration**: Seamless integration with A_Scope for context
+
+### ⚡ Performance
+- **Efficient Formatting**: Optimized for large objects and rapid logging
+- **Memory Conscious**: Minimal memory overhead for formatting operations
+- **Non-blocking**: Asynchronous-friendly design
+
+## Installation
+
+```bash
+npm install @adaas/a-utils
+```
+
+## Basic Usage
+
+### Simple Logging
+
+```typescript
+import { A_Scope } from "@adaas/a-concept";
+import { A_Logger } from "@adaas/a-utils";
+
+// Create scope and logger
+const scope = new A_Scope({ name: 'MyService' });
+const logger = new A_Logger(scope);
+
+// Basic logging
+logger.log('Application started');
+logger.log('green', 'Operation successful');
+logger.warning('Resource usage high');
+logger.error('Database connection failed');
+```
+
+### Object Logging
+
+```typescript
+// Log complex objects
+const user = {
+    id: 123,
+    name: 'John Doe',
+    preferences: {
+        theme: 'dark',
+        notifications: true
+    }
+};
+
+logger.log('blue', 'User data:', user);
+
+// Multi-argument logging
+logger.log('green', 
+    'Processing complete:',
+    'Records:', 150,
+    'Errors:', 2,
+    'Success rate:', '98.7%'
+);
+```
+
+### Error Handling
+
+```typescript
+// Standard JavaScript errors
+try {
+    throw new Error('Database timeout');
+} catch (error) {
+    logger.error('Database operation failed:', error);
+}
+
+// A_Error instances
+const validationError = new A_Error('Validation failed');
+logger.error('Request validation:', validationError);
+
+// Error with context
+logger.error(
+    'Operation failed:',
+    error,
+    'Context:', { userId: '123', operation: 'update' },
+    'Additional info:', 'User may need admin privileges'
+);
+```
+
+## Advanced Usage
+
+### Dependency Injection
+
+```typescript
+import { A_Inject, A_Component } from "@adaas/a-concept";
+
+class UserService extends A_Component {
+    constructor(
+        @A_Inject(A_Logger) private logger: A_Logger
+    ) {
+        super();
+    }
+
+    async createUser(userData: any) {
+        this.logger.log('green', 'Creating user:', userData);
+        
+        try {
+            // User creation logic
+            this.logger.log('User created successfully');
+        } catch (error) {
+            this.logger.error('User creation failed:', error);
+            throw error;
+        }
+    }
+}
+```
+
+### Log Level Configuration
+
+```typescript
+import { A_Config } from "@adaas/a-utils";
+
+// Configure log level via environment variable
+// A_LOGGER_LEVEL=warn
+
+// Or via config injection
+const config = new A_Config();
+const logger = new A_Logger(scope, config);
+
+// Different log levels:
+// - 'debug': Shows all messages
+// - 'info': Shows info, warning, and error messages  
+// - 'warn': Shows warning and error messages only
+// - 'error': Shows error messages only
+// - 'all': Shows all messages (default)
+```
+
+### Scope Alignment Demonstration
+
+```typescript
+// Different scope lengths - all align consistently
+const services = [
+    new A_Logger(new A_Scope({ name: 'API' })),
+    new A_Logger(new A_Scope({ name: 'Authentication' })),
+    new A_Logger(new A_Scope({ name: 'DatabaseConnectionPool' })),
+    new A_Logger(new A_Scope({ name: 'A' }))
+];
+
+services.forEach(logger => {
+    logger.log('green', 'Service initialized');
+    logger.warning('Configuration check needed');
+});
+
+// Output shows consistent alignment:
+// [API                 ] |15:42:123| Service initialized
+// [Authentication      ] |15:42:124| Service initialized  
+// [DatabaseConnectionPool] |15:42:125| Service initialized
+// [A                   ] |15:42:126| Service initialized
+```
+
+## Color Reference
+
+| Color   | Use Case | Code |
+|---------|----------|------|
+| `green` | Success, completion | 32 |
+| `blue` | Info, general messages | 34 |
+| `red` | Errors, critical issues | 31 |
+| `yellow` | Warnings, caution | 33 |
+| `gray` | Debug, less important | 90 |
+| `magenta` | Special highlighting | 35 |
+| `cyan` | Headers, titles | 36 |
+| `white` | Default text | 37 |
+| `pink` | Custom highlighting | 95 |
+
+## Log Level Hierarchy
+
+| Level | Shows |
+|-------|-------|
+| `debug` | All messages (debug, info, warning, error) |
+| `info` | Info, warning, and error messages |
+| `warn` | Warning and error messages only |
+| `error` | Error messages only |
+| `all` | All messages (alias for debug) |
+
+## Output Format
+
+### Standard Message Format
+```
+[ScopeName          ] |MM:SS:mmm| Message content
+```
+
+### Multi-line Object Format  
+```
+[ScopeName          ] |MM:SS:mmm|
+                     |-------------------------------
+                     | {
+                     |   "key": "value",
+                     |   "nested": {
+                     |     "data": true
+                     |   }
+                     | }
+                     |-------------------------------
+```
+
+### Error Format
+```
+[ScopeName          ] |MM:SS:mmm|
+                     |-------------------------------
+                     |  Error:  | ERROR_CODE
+                     |-------------------------------
+                     |          | Error message
+                     |          | Error description
+                     |-------------------------------
+                     | Stack trace...
+                     |-------------------------------
+```
+
+## Performance Considerations
+
+- **Large Objects**: Efficiently handles objects with 100+ properties
+- **Rapid Logging**: Supports 100+ log calls per second without performance degradation
+- **Memory Usage**: Minimal memory overhead for formatting operations
+- **String Processing**: Optimized string concatenation and replacement
+
+## Testing
+
+The component includes comprehensive tests covering:
+
+- Basic logging functionality
+- Scope formatting and alignment  
+- Object and data type handling
+- Error formatting
+- Color support
+- Log level filtering
+- Performance characteristics
+- Edge cases and error conditions
+
+Run tests:
+```bash
+npm test A-Logger.test.ts
+```
+
+## Examples
+
+See `examples/A-Logger-examples.ts` for comprehensive usage examples including:
+
+- Basic logging patterns
+- Scope alignment demonstration
+- Object and data logging
+- Error handling scenarios
+- Color usage examples
+- Performance logging simulation
+- Real-world service logging
+
+## API Reference
+
+### Constructor
+
+```typescript
+constructor(
+    scope: A_Scope,
+    config?: A_Config<A_LoggerEnvVariablesType>
+)
+```
+
+### Methods
+
+#### `log(message: any, ...args: any[]): void`
+#### `log(color: ColorKey, message: any, ...args: any[]): void`
+Log general messages with optional color specification.
+
+#### `warning(...args: any[]): void`
+Log warning messages with yellow color coding.
+
+#### `error(...args: any[]): void`  
+Log error messages with red color coding.
+
+### Properties
+
+#### `colors: readonly object`
+Available color codes for terminal output.
+
+#### `scopeLength: number`
+Calculated scope length for consistent formatting.
+
+#### `formattedScope: string`
+Padded scope name for consistent alignment.
+
+## Environment Variables
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `A_LOGGER_LEVEL` | string | 'all' | Log level filter (debug, info, warn, error, all) |
+
+## Best Practices
+
+### 1. Use Appropriate Colors
+```typescript
+logger.log('green', 'Operation successful');    // Success
+logger.log('blue', 'Processing data...');       // Info
+logger.warning('Resource usage high');          // Warning  
+logger.error('Operation failed');               // Error
+```
+
+### 2. Provide Context
+```typescript
+logger.log('blue', 'User operation:', {
+    userId: user.id,
+    operation: 'profile-update',
+    timestamp: new Date().toISOString()
+});
+```
+
+### 3. Use Appropriate Log Levels
+```typescript
+// Development
+A_LOGGER_LEVEL=debug
+
+// Production  
+A_LOGGER_LEVEL=warn
+```
+
+### 4. Structure Multi-argument Logs
+```typescript
+logger.log('green',
+    'Operation completed:',
+    'Duration:', `${duration}ms`,
+    'Records processed:', count,
+    'Status:', 'success'
+);
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Q: Log messages not appearing**
+A: Check the `A_LOGGER_LEVEL` environment variable. Set to 'debug' or 'all' to see all messages.
+
+**Q: Scope names not aligning**  
+A: This is handled automatically. The component uses a standard scope length (20 characters) for consistent alignment.
+
+**Q: Colors not showing in terminal**
+A: Ensure your terminal supports ANSI color codes. Most modern terminals do.
+
+**Q: Performance issues with large objects**
+A: The component is optimized for large objects. If issues persist, consider logging object summaries instead of full objects.
+
+## Contributing
+
+When contributing to the A-Logger component:
+
+1. Add comprehensive tests for new features
+2. Update documentation and examples
+3. Ensure consistent formatting and alignment
+4. Test with various scope name lengths
+5. Verify color support across different terminals
+
+## License
+
+Part of the ADAAS ecosystem. See main project license for details.

package/src/lib/A-Manifest/A-Manifest.types.ts

@@ -1,5 +1,4 @@
-import { A_Component, A_Container, A_TYPES__Component_Constructor, A_TYPES__Entity_Constructor, A_TYPES__Fragment_Constructor } from "@adaas/a-concept"
-import { A_TYPES__Container_Constructor } from "@adaas/a-concept/dist/src/global/A-Container/A-Container.types"
+import { A_Component, A_TYPES__Component_Constructor, A_TYPES__Container_Constructor, A_TYPES__Entity_Constructor, A_TYPES__Fragment_Constructor } from "@adaas/a-concept"
 
 
 export type A_UTILS_TYPES__Manifest_Init = Array<A_UTILS_TYPES__Manifest_ComponentLevelConfig>

package/src/lib/A-Memory/A-Memory.context.ts

@@ -41,7 +41,7 @@ export class A_Memory<
      * @param requiredKeys 
      * @returns 
      */
-    async verifyPrerequisites(
+    async prerequisites(
         requiredKeys: Array<keyof _MemoryType>
     ): Promise<boolean> {
         return requiredKeys.every(key => this._memory.has(key));

package/tests/A-Command.test.ts

@@ -1,5 +1,5 @@
 import { A_Command } from '@adaas/a-utils/lib/A-Command/A-Command.entity';
-import { A_CONSTANTS__A_Command_Status, A_CONSTANTS_A_Command_Features } from '@adaas/a-utils/lib/A-Command/A-Command.constants';
+import { A_CONSTANTS__A_Command_Status, A_CommandFeatures } from '@adaas/a-utils/lib/A-Command/A-Command.constants';
 import { A_Component, A_Context, A_Error, A_Feature, A_Inject, A_Scope } from '@adaas/a-concept';
 import { A_Memory } from '@adaas/a-utils/lib/A-Memory/A-Memory.context';
 
@@ -44,7 +44,7 @@ describe('A-Command tests', () => {
         A_Context.root.register(command);
 
         command.emit('A_CUSTOM_EVENT_1');
-        command.emit('compile');
+        command.emit('onCompile');
 
         expect(command).toBeInstanceOf(A_Command);
         expect(command.code).toBe('my-command');
@@ -94,7 +94,7 @@ describe('A-Command tests', () => {
         class MyComponent extends A_Component {
 
             @A_Feature.Extend({ scope: [MyCommand] })
-            async [A_CONSTANTS_A_Command_Features.EXECUTE](
+            async [A_CommandFeatures.onExecute](
                 @A_Inject(A_Memory) context: A_Memory<resultType>
             ) {
                 context.set('bar', 'baz');
@@ -131,7 +131,7 @@ describe('A-Command tests', () => {
         class MyComponent extends A_Component {
 
             @A_Feature.Extend({ scope: [MyCommand] })
-            async [A_CONSTANTS_A_Command_Features.EXECUTE](
+            async [A_CommandFeatures.onExecute](
                 @A_Inject(A_Memory) context: A_Memory<resultType>
             ) {
                 context.error(new A_Error({ title: 'Test error' }));
@@ -170,11 +170,11 @@ describe('A-Command tests', () => {
             A_Context.root.register(command);
             
             // Track lifecycle events
-            command.on('init', () => lifecycleOrder.push('init'));
-            command.on('compile', () => lifecycleOrder.push('compile'));
-            command.on('execute', () => lifecycleOrder.push('execute'));
-            command.on('complete', () => lifecycleOrder.push('complete'));
-            command.on('fail', () => lifecycleOrder.push('fail'));
+            command.on(A_CommandFeatures.onInit, () => lifecycleOrder.push('init'));
+            command.on(A_CommandFeatures.onCompile, () => lifecycleOrder.push('compile'));
+            command.on(A_CommandFeatures.onExecute, () => lifecycleOrder.push('execute'));
+            command.on(A_CommandFeatures.onComplete, () => lifecycleOrder.push('complete'));
+            command.on(A_CommandFeatures.onFail, () => lifecycleOrder.push('fail'));
 
             await command.execute();
 
@@ -221,7 +221,7 @@ describe('A-Command tests', () => {
             
             class FailingComponent extends A_Component {
                 @A_Feature.Extend({ scope: [FailingCommand] })
-                async [A_CONSTANTS_A_Command_Features.EXECUTE]() {
+                async [A_CommandFeatures.onExecute]() {
                     throw new A_Error({ title: 'Execution failed' });
                 }
             }
@@ -232,11 +232,11 @@ describe('A-Command tests', () => {
             A_Context.root.register(command);
 
             const lifecycleOrder: string[] = [];
-            command.on('init', () => lifecycleOrder.push('init'));
-            command.on('compile', () => lifecycleOrder.push('compile'));
-            command.on('execute', () => lifecycleOrder.push('execute'));
-            command.on('complete', () => lifecycleOrder.push('complete'));
-            command.on('fail', () => lifecycleOrder.push('fail'));
+            command.on(A_CommandFeatures.onInit, () => lifecycleOrder.push('init'));
+            command.on(A_CommandFeatures.onCompile, () => lifecycleOrder.push('compile'));
+            command.on(A_CommandFeatures.onExecute, () => lifecycleOrder.push('execute'));
+            command.on(A_CommandFeatures.onComplete, () => lifecycleOrder.push('complete'));
+            command.on(A_CommandFeatures.onFail, () => lifecycleOrder.push('fail'));
 
             await command.execute();
 
@@ -279,8 +279,8 @@ describe('A-Command tests', () => {
             const listener1Calls: number[] = [];
             const listener2Calls: number[] = [];
 
-            command.on('init', () => listener1Calls.push(1));
-            command.on('init', () => listener2Calls.push(2));
+            command.on(A_CommandFeatures.onInit, () => listener1Calls.push(1));
+            command.on(A_CommandFeatures.onInit, () => listener2Calls.push(2));
 
             await command.init();
 
@@ -317,12 +317,12 @@ describe('A-Command tests', () => {
             const listenerCalls: number[] = [];
             const listener = () => listenerCalls.push(1);
 
-            command.on('init', listener);
+            command.on(A_CommandFeatures.onInit, listener);
             await command.init();
             expect(listenerCalls).toEqual([1]);
 
             // Remove listener and verify it's not called again
-            command.off('init', listener);
+            command.off(A_CommandFeatures.onInit, listener);
             
             // Reset to call init again
             (command as any)._status = A_CONSTANTS__A_Command_Status.CREATED;
@@ -336,7 +336,7 @@ describe('A-Command tests', () => {
 
             let receivedCommand: A_Command<any, any, any> | undefined = undefined;
 
-            command.on('init', (cmd) => {
+            command.on(A_CommandFeatures.onInit, (cmd) => {
                 receivedCommand = cmd;
             });
 
@@ -352,10 +352,10 @@ describe('A-Command tests', () => {
 
             const successfulCalls: number[] = [];
 
-            command.on('init', () => {
+            command.on(A_CommandFeatures.onInit, () => {
                 throw new Error('Listener error');
             });
-            command.on('init', () => successfulCalls.push(1));
+            command.on(A_CommandFeatures.onInit, () => successfulCalls.push(1));
 
             // Listener errors are propagated and will cause the command to fail
             await expect(command.init()).rejects.toThrow('Listener error');
@@ -429,7 +429,7 @@ describe('A-Command tests', () => {
 
             class ResultProcessor extends A_Component {
                 @A_Feature.Extend({ scope: [ResultCommand] })
-                async [A_CONSTANTS_A_Command_Features.EXECUTE](
+                async [A_CommandFeatures.onExecute](
                     @A_Inject(A_Memory) memory: A_Memory<TestResult>
                 ) {
                     memory.set('processedData', 'processed-input');
@@ -457,7 +457,7 @@ describe('A-Command tests', () => {
 
             // Test deserialization - result is restored to memory and accessible through get method
             const deserializedCommand = new ResultCommand(serialized);
-            const deserializedMemory = deserializedCommand.scope.resolve(A_Memory);
+            const deserializedMemory = deserializedCommand.scope.resolve(A_Memory)!;
             expect(deserializedMemory.get('processedData')).toBe('processed-input');
             expect(deserializedMemory.get('count')).toBe(100);
             expect(deserializedMemory.get('metadata')).toEqual(serialized.result?.metadata);
@@ -470,7 +470,7 @@ describe('A-Command tests', () => {
 
             class ErrorComponent extends A_Component {
                 @A_Feature.Extend({ scope: [ErrorCommand] })
-                async [A_CONSTANTS_A_Command_Features.EXECUTE](
+                async [A_CommandFeatures.onExecute](
                     @A_Inject(A_Memory) memory: A_Memory<{ output: string }>
                 ) {
                     memory.error(new A_Error({ 
@@ -503,7 +503,7 @@ describe('A-Command tests', () => {
 
             // Test deserialization - errors are restored to memory
             const deserializedCommand = new ErrorCommand(serialized);
-            const deserializedMemory = deserializedCommand.scope.resolve(A_Memory);
+            const deserializedMemory = deserializedCommand.scope.resolve(A_Memory)!;
             expect(deserializedMemory.Errors?.size).toBe(2);
             const errorArray = Array.from(deserializedMemory.Errors?.values() || []);
             expect(errorArray[0].title).toBe('First error');