@adaas/a-utils 0.1.29 → 0.1.30

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

@@ -16,9 +16,12 @@ The A_Logger component provides comprehensive logging capabilities with:
 ## Features
 
 ### 🎨 Visual Output
-- **Terminal Colors**: Support for 9 different colors (green, blue, red, yellow, gray, magenta, cyan, white, pink)
+- **Extended Color Palette**: Support for 25+ colors including basic colors (red, green, blue) and extended palette (indigo, violet, cornflower, etc.)
+- **Color Enum Support**: Type-safe color specification using A_LoggerColorName enum
 - **Consistent Alignment**: All log messages align properly regardless of scope name length
 - **Structured Formatting**: Multi-line messages with proper indentation and separators
+- **Terminal Width Detection**: Automatic detection of terminal width for optimal formatting
+- **Responsive Text Wrapping**: Intelligent text wrapping based on terminal size
 
 ### 📊 Data Types Support
 - **Strings**: Simple text messages with optional color coding
@@ -31,6 +34,8 @@ The A_Logger component provides comprehensive logging capabilities with:
 - **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
+- **Terminal Adaptation**: Automatic adaptation to different terminal widths and environments
+- **Browser Compatibility**: Optimized formatting for both terminal and browser console environments
 
 ### ⚡ Performance
 - **Efficient Formatting**: Optimized for large objects and rapid logging
@@ -56,10 +61,18 @@ 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.info('Application started');
+logger.info('green', 'Operation successful');
 logger.warning('Resource usage high');
 logger.error('Database connection failed');
+
+// Enhanced color support with type safety
+import { A_LoggerColorName } from "@adaas/a-utils";
+
+logger.info('brightBlue', 'Enhanced blue message');
+logger.info('indigo', 'Deep indigo notification');
+logger.info('cornflower', 'Cornflower blue status');
+logger.debug('gray', 'Debug information');
 ```
 
 ### Object Logging
@@ -75,10 +88,10 @@ const user = {
     }
 };
 
-logger.log('blue', 'User data:', user);
+logger.info('deepBlue', 'User data:', user);
 
 // Multi-argument logging
-logger.log('green', 
+logger.info('green', 
     'Processing complete:',
     'Records:', 150,
     'Errors:', 2,
@@ -124,11 +137,11 @@ class UserService extends A_Component {
     }
 
     async createUser(userData: any) {
-        this.logger.log('green', 'Creating user:', userData);
+        this.logger.info('brightBlue', 'Creating user:', userData);
         
         try {
             // User creation logic
-            this.logger.log('User created successfully');
+            this.logger.info('green', 'User created successfully');
         } catch (error) {
             this.logger.error('User creation failed:', error);
             throw error;
@@ -169,7 +182,7 @@ const services = [
 ];
 
 services.forEach(logger => {
-    logger.log('green', 'Service initialized');
+    logger.info('green', 'Service initialized');
     logger.warning('Configuration check needed');
 });
 
@@ -180,11 +193,85 @@ services.forEach(logger => {
 // [A                   ] |15:42:126| Service initialized
 ```
 
+### Terminal Width and Text Wrapping
+
+The A_Logger automatically detects your terminal width and wraps long messages for optimal readability:
+
+```typescript
+// Long messages are automatically wrapped
+logger.info('cyan', 
+    'This is a very long message that will be automatically wrapped based on your terminal width to ensure optimal readability while maintaining proper formatting and indentation throughout the entire message.'
+);
+
+// Multi-argument messages maintain proper indentation
+logger.info('purple',
+    'First argument that is quite long and demonstrates wrapping behavior',
+    'Second argument with continued proper indentation',
+    {
+        configuration: {
+            terminalWidth: 'auto-detected',
+            wrapping: 'intelligent',
+            fallbacks: ['80 chars', 'browser: 120 chars']
+        }
+    }
+);
+
+// Terminal information logging
+logger.info('steelBlue', 'Terminal info:', {
+    columns: process.stdout?.columns || 'Not detected',
+    environment: process.stdout?.isTTY ? 'TTY' : 'Non-TTY',
+    platform: process.platform
+});
+```
+
+**Terminal Width Features:**
+- **Auto-detection**: Automatically detects terminal width using `process.stdout.columns`
+- **Smart Wrapping**: Wraps text at word boundaries when possible
+- **Consistent Indentation**: Maintains proper indentation for wrapped lines
+- **Environment Aware**: Different defaults for Node.js terminal vs browser console
+- **Fallback Support**: Uses sensible defaults when width cannot be detected
+
 ## Color Reference
 
+### Basic Colors
 | Color   | Use Case | Code |
 |---------|----------|------|
+| `red` | Errors, critical issues | 31 |
+| `yellow` | Warnings, cautions | 33 |
 | `green` | Success, completion | 32 |
+| `blue` | Information, general | 34 |
+| `cyan` | Headers, highlights | 36 |
+| `magenta` | Special emphasis | 35 |
+| `gray` | Debug, less important | 90 |
+
+### Extended Color Palette
+| Color   | Description | Code |
+|---------|-------------|------|
+| `brightBlue` | Enhanced blue variant | 94 |
+| `brightCyan` | Enhanced cyan variant | 96 |
+| `brightMagenta` | Enhanced magenta variant | 95 |
+| `indigo` | Deep indigo | 38;5;54 |
+| `violet` | Violet | 38;5;93 |
+| `purple` | Purple | 38;5;129 |
+| `lavender` | Lavender | 38;5;183 |
+| `skyBlue` | Sky blue | 38;5;117 |
+| `steelBlue` | Steel blue | 38;5;67 |
+| `slateBlue` | Slate blue | 38;5;62 |
+| `deepBlue` | Deep blue | 38;5;18 |
+| `lightBlue` | Light blue | 38;5;153 |
+| `periwinkle` | Periwinkle | 38;5;111 |
+| `cornflower` | Cornflower blue | 38;5;69 |
+| `powder` | Powder blue | 38;5;152 |
+
+### Grayscale Colors
+| Color   | Description | Code |
+|---------|-------------|------|
+| `darkGray` | Dark gray | 30 |
+| `lightGray` | Light gray | 37 |
+| `charcoal` | Charcoal | 38;5;236 |
+| `silver` | Silver | 38;5;250 |
+| `smoke` | Smoke gray | 38;5;244 |
+| `slate` | Slate gray | 38;5;240 |
 | `blue` | Info, general messages | 34 |
 | `red` | Errors, critical issues | 31 |
 | `yellow` | Warnings, caution | 33 |
@@ -318,15 +405,15 @@ Padded scope name for consistent alignment.
 
 ### 1. Use Appropriate Colors
 ```typescript
-logger.log('green', 'Operation successful');    // Success
-logger.log('blue', 'Processing data...');       // Info
+logger.info('green', 'Operation successful');    // Success
+logger.info('brightBlue', 'Processing data...');       // Info
 logger.warning('Resource usage high');          // Warning  
 logger.error('Operation failed');               // Error
 ```
 
 ### 2. Provide Context
 ```typescript
-logger.log('blue', 'User operation:', {
+logger.info('steelBlue', 'User operation:', {
     userId: user.id,
     operation: 'profile-update',
     timestamp: new Date().toISOString()
@@ -344,7 +431,7 @@ A_LOGGER_LEVEL=warn
 
 ### 4. Structure Multi-argument Logs
 ```typescript
-logger.log('green',
+logger.info('green',
     'Operation completed:',
     'Duration:', `${duration}ms`,
     'Records processed:', count,
@@ -352,6 +439,17 @@ logger.log('green',
 );
 ```
 
+### 5. Leverage Terminal Width Awareness
+```typescript
+// Long messages are automatically wrapped
+logger.info('cyan', 'Very long status message that will automatically wrap based on terminal width while maintaining proper formatting');
+
+// Use appropriate colors from the extended palette
+logger.info('indigo', 'Service initialization complete');
+logger.debug('charcoal', 'Detailed debug information');
+logger.info('cornflower', 'Processing pipeline status');
+```
+
 ## Troubleshooting
 
 ### Common Issues
@@ -368,6 +466,12 @@ 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.
 
+**Q: Messages not wrapping correctly in terminal**
+A: The logger automatically detects terminal width via `process.stdout.columns`. If detection fails, it uses defaults (80 chars for terminal, 120 for browser).
+
+**Q: Text wrapping behavior inconsistent**
+A: Terminal width detection depends on the environment. In non-TTY environments or when columns cannot be detected, the logger falls back to default widths.
+
 ## Contributing
 
 When contributing to the A-Logger component:

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

@@ -103,9 +103,6 @@ export class A_Memory<
         @A_Inject(A_Scope) scope: A_Scope,
         ...args: any[]
     ): Promise<void> {
-        console.log('A_Memory onSet called with key:', scope.name);
-        console.log('A_Memory onSet called with key:', scope.parent?.name);
-
         // Handle set operation
         context.set(operation.params.key, operation.params.value);
     }

package/src/lib/A-Route/A-Route.entity.ts

@@ -0,0 +1,136 @@
+import { A_Fragment } from '@adaas/a-concept';
+
+
+
+export class A_Route<
+    _TParams extends Record<string, any> = Record<string, any>,
+    _TQuery extends Record<string, any> = Record<string, any>
+> extends A_Fragment {
+
+    public url!: string;
+
+
+    constructor(
+        url: string | RegExp,
+    ) {
+        super();
+        this.url = url instanceof RegExp ? url.source : url;
+    }
+
+    /**
+     * Returns path only without query and hash
+     */
+    get path(): string {
+        const p = this.url.split('?')[0].split('#')[0];
+
+
+        //  ensure that last char is not /
+        //  and remove protocol and domain if present
+        if (p.includes('://')) {
+            const pathStartIndex = p.indexOf('/', p.indexOf('://') + 3);
+            if (pathStartIndex === -1) {
+                return '/';
+            } else {
+                const path = p.slice(pathStartIndex);
+                return path.endsWith('/') ? path.slice(0, -1) : path;
+            }
+        }
+        return p.endsWith('/') ? p.slice(0, -1) : p;
+    }
+    /**
+     * Returns array of parameter names in the route path
+     */
+    get params(): string[] {
+        return this.path
+            .match(/:([^\/]+)/g)
+            ?.map((param) => param.slice(1))
+            || [];
+    }
+
+
+    /**
+     * Returns protocol based on URL scheme
+     */
+    get protocol(): string {
+        switch (true) {
+            case this.url.startsWith('http://'):
+                return 'http';
+            case this.url.startsWith('https://'):
+                return 'https';
+            case this.url.startsWith('ws://'):
+                return 'ws';
+            case this.url.startsWith('wss://'):
+                return 'wss';
+            default:
+                return this.url.includes('://') ? this.url.split('://')[0] : 'http';
+        }
+    }
+
+
+    extractParams(url: string): _TParams {
+        // Remove query string (anything after ?)
+        const cleanUrl = url.split('?')[0];
+
+        const urlSegments = cleanUrl.split('/').filter(Boolean);
+        const maskSegments = this.path.split('/').filter(Boolean);
+
+        const params = {};
+
+        for (let i = 0; i < maskSegments.length; i++) {
+
+            const maskSegment = maskSegments[i];
+            const urlSegment = urlSegments[i];
+
+            if (maskSegment.startsWith(':')) {
+                const paramName = maskSegment.slice(1); // Remove ':' from mask
+                params[paramName] = urlSegment;
+            } else if (maskSegment !== urlSegment) {
+                // If static segments don’t match → fail
+                return {} as _TParams;
+            }
+        }
+
+        return params as _TParams;
+    }
+
+    extractQuery(url: string): _TQuery {
+        const query: Record<string, string> = {};
+
+        // Take only the part after "?"
+        const queryString = url.split('?')[1];
+        if (!queryString) return query as _TQuery;
+
+        // Remove fragment (#...) if present
+        const cleanQuery = queryString.split('#')[0];
+
+        // Split into key=value pairs
+        for (const pair of cleanQuery.split('&')) {
+            if (!pair) continue;
+            const [key, value = ''] = pair.split('=');
+            query[decodeURIComponent(key)] = decodeURIComponent(value);
+        }
+
+        return query as _TQuery;
+    }
+
+
+
+    toString(): string {
+        // path can be like /api/v1/users/:id
+        // and because of that :id we need to replace it with regex that matches chars and numbers only   
+        return `${this.path}`;
+        // .replace(/\/:([^\/]+)/g, '\\/([^\/]+)')
+    }
+
+    toRegExp(): RegExp {
+        return new RegExp(`^${this.path.replace(/\/:([^\/]+)/g, '/([^/]+)')}$`);
+    }
+
+    toAFeatureExtension(extensionScope: Array<string> = []): RegExp {
+        return new RegExp(`^${extensionScope.length
+            ? `(${extensionScope.join('|')})`
+            : '.*'
+            }\\.${this.path.replace(/\/:([^\/]+)/g, '/([^/]+)')}$`);
+    }
+}
+

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

@@ -0,0 +1 @@
+

package/src/lib/A-Signal/A-Signal.constants.ts

@@ -0,0 +1,10 @@
+
+export enum A_SignalFeatures {
+    Emit = '_A_SignalFeatures_Emit',
+}
+
+
+
+export enum A_SignalBusFeatures {
+    Emit = '_A_SignalBusFeatures_Emit',
+}

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

@@ -0,0 +1,47 @@
+import { A_TYPES__Component_Constructor, A_TYPES__Entity_Constructor, A_TYPES__Entity_Init, A_TYPES__Entity_Serialized } from "@adaas/a-concept"
+import { A_Signal } from "./entities/A-Signal.entity"
+
+
+export type A_SignalConfig_Init = {
+    /**
+     * An array defining the structure of the signal vector.
+     * 
+     * Each entry corresponds to a signal component constructor.
+     */
+    structure?: Array<A_TYPES__Entity_Constructor<A_Signal>>
+    /**
+     * A string representation of the structure for easier DI resolution.
+     * Each signal's constructor name is used to form this string.
+     * e.g. "['A_RouterWatcher', 'A_ScopeWatcher', 'A_LoggerWatcher']"
+     * OR "A_RouterWatcher,A_ScopeWatcher,A_LoggerWatcher"
+     */
+    stringStructure?: string
+}
+
+
+
+export type A_SignalVector_Init<
+    TSignalData extends Record<string, any> = Record<string, any>
+> = {
+    structure: Array<A_TYPES__Entity_Constructor<A_Signal>>,
+    values: TSignalData[]
+}
+
+
+export type A_SignalVector_Serialized = A_TYPES__Entity_Serialized & {
+    structure: string[],
+    values: Array<Record<string, any>>
+} & A_TYPES__Entity_Serialized
+
+
+
+export type A_Signal_Init<T extends Record<string, any> = Record<string, any>> = {
+    /**
+     * The signal name
+     */
+    name?: string,
+    /**
+     * The signal data
+     */
+    data: T
+}

package/src/lib/A-Signal/components/A-SignalBus.component.ts

@@ -0,0 +1,103 @@
+import { A_Caller, A_Component, A_Context, A_Feature, A_Inject, A_Scope } from "@adaas/a-concept";
+import { A_SignalBusFeatures, A_SignalFeatures } from "../A-Signal.constants";
+import { A_SignalState } from "../context/A-SignalState.context";
+import { A_SignalConfig } from "../context/A-SignalConfig.context";
+import { A_Config } from "../../A-Config/A-Config.context";
+import { A_Logger } from "../../A-Logger/A-Logger.component";
+import { A_Signal } from "../entities/A-Signal.entity";
+
+
+
+/**
+ * This component should listen for all available signal watchers components in this and all parent scopes. 
+ * When a signal is emitted, it should forward the signal to all registered watchers.
+ * 
+ * A_SignalBus should always return the same vector structure of the signals, and that's why it should store the state of the latest behavior. 
+ * For example if there are 3 watchers registered, the bus should always return a vector of 3 elements, based on the A_SignalConfig structure.
+ * 
+ * 
+ * The component itself is stateless and all methods uses only parameters (context) is provided with.
+ */
+export class A_SignalBus extends A_Component {
+
+
+    /**
+     * This methods extends A-Signal Emit feature to handle signal emission within the bus.
+     * 
+     * It updates the signal state and emits the updated signal vector.
+     * 
+     * @param signal 
+     * @param globalConfig 
+     * @param logger 
+     * @param state 
+     * @param config 
+     * @returns 
+     */u
+    @A_Feature.Extend({
+        scope: [A_Signal]
+    })
+    async [A_SignalFeatures.Emit](
+        @A_Inject(A_Caller) signal: A_Signal,
+
+        @A_Inject(A_Config) globalConfig?: A_Config<['A_SIGNAL_VECTOR_STRUCTURE']>,
+        @A_Inject(A_Logger) logger?: A_Logger,
+        @A_Inject(A_SignalState) state?: A_SignalState,
+        @A_Inject(A_SignalConfig) config?: A_SignalConfig,
+    ) {
+
+        /**
+         * We need a context where component is registered, to prevent any duplicate registrations
+         */
+        const componentContext = A_Context.scope(this)
+
+        if (!config) {
+            config = new A_SignalConfig({
+                stringStructure: globalConfig?.get('A_SIGNAL_VECTOR_STRUCTURE') || undefined
+            });
+
+            componentContext.register(config);
+        }
+
+        if (!config.ready)
+            await config.initialize();
+
+        if (!state) {
+            state = new A_SignalState(config.structure);
+            componentContext.register(state);
+        }
+
+        if (!state.has(signal))
+            return;
+
+        //  ------------------------------------------------------------------
+        //  And finally if all checks are passed, we can update the state
+        //  ------------------------------------------------------------------
+
+        logger?.debug(`A_SignalBus: Updating state for signal '${signal.constructor.name}' with data:`, signal.data);
+
+        state.set(signal, signal.data);
+
+        const vector = state.toVector();
+
+        const nextScope = new A_Scope({
+            name: `A_SignalBus_Next_Scope_of_${this.constructor.name}`,
+            entities: [vector]
+        })
+            .inherit(A_Context.scope(this));
+
+
+        try {
+
+            await this.call(A_SignalBusFeatures.Emit, nextScope);
+
+            nextScope.destroy();
+
+        } catch (error) {
+
+            nextScope.destroy();
+
+            throw error;
+        }
+    }
+
+}

package/src/lib/A-Signal/context/A-SignalConfig.context.ts

@@ -0,0 +1,81 @@
+import { A_Context, A_Fragment, A_TYPES__Component_Constructor, A_TYPES__Entity_Constructor } from "@adaas/a-concept";
+import { A_SignalConfig_Init } from "../A-Signal.types";
+import { A_Signal } from "../entities/A-Signal.entity";
+
+
+
+/**
+ * This component should dictate a structure of the vector for all signals within a given scope.
+ * so if there're multiple signals it should say what type at what position should be expected.
+ * 
+ * e.g. [A_RouterWatcher, A_ScopeWatcher, A_LoggerWatcher]
+ * This structure then should be used for any further processing of signals within the scope.
+ */
+export class A_SignalConfig extends A_Fragment {
+
+    protected _structure?: Array<A_TYPES__Entity_Constructor<A_Signal>>;
+
+    protected _config: A_SignalConfig_Init
+
+    protected _ready?: Promise<void>;
+
+    get structure(): Array<A_TYPES__Entity_Constructor<A_Signal>> {
+        if (this._structure) {
+            return this._structure;
+        }
+
+        const scope = A_Context.scope(this);
+        const signalConfigs = scope.allowedEntities;
+
+        //  just sort by constructor name to have consistent order
+        return [...scope.allowedEntities]
+            .sort((a, b) => a.constructor.name.localeCompare(b.constructor.name))
+            .map(s => scope.resolveConstructor<A_Signal>(s.constructor.name));
+    }
+
+    /**
+     * Uses for synchronization to ensure the config is initialized.
+     * 
+     * @returns True if the configuration has been initialized.
+     */
+    get ready() {
+        return this._ready;
+    }
+
+    constructor(
+        params: A_SignalConfig_Init
+    ) {
+        super({ name: "A_SignalConfig" });
+        this._config = params;
+    }
+
+
+    /**
+     * Initializes the signal configuration if not already initialized.
+     * 
+     * @returns 
+     */
+    async initialize() {
+        if (!this._ready) {
+            this._ready = this._initialize();
+        }
+        return this._ready;
+    }
+
+    /**
+     * Initializes the signal configuration by processing the provided structure or string representation.
+     * This method sets up the internal structure of signal constructors based on the configuration.
+     */
+    protected async _initialize() {
+        if (this._config.structure) {
+            this._structure = this._config.structure;
+        } else if (this._config.stringStructure) {
+            const stringStructure = this._config.stringStructure.split(',').map(s => s.trim());
+            this._structure = stringStructure
+                .map(name => A_Context.scope(this).resolveConstructor<A_Signal>(name))
+                .filter(s => s);
+        }
+
+    }
+
+}