@adaas/a-utils 0.1.29 → 0.1.31

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

@@ -0,0 +1,195 @@
+import { A_Context, A_Fragment, A_TYPES__Component_Constructor } from "@adaas/a-concept";
+import { A_Signal } from "../entities/A-Signal.entity";
+import { A_SignalVector } from "../entities/A-SignalVector.entity";
+
+/**
+ * A_SignalState manages the latest state of all signals within a given scope.
+ * 
+ * This class maintains a mapping between signal constructors and their most recently emitted values,
+ * providing a centralized state store for signal management within an application context.
+ * 
+ * @template TSignalData - Union type of all possible signal data types that can be stored (must extend Record<string, any>)
+ * 
+ * The generic ensures type safety by maintaining correspondence between:
+ * - Signal constructor types and their data types
+ * - Signal instances and their emitted value types
+ * - Vector structure and the data it contains
+ */
+export class A_SignalState<
+    TSignalData extends Record<string, any> = Record<string, any>
+> extends A_Fragment {
+
+    /**
+     * Internal map storing the relationship between signal constructors and their latest values
+     * Key: Signal constructor function
+     * Value: Latest emitted data from that signal type
+     */
+    protected _state: Map<A_TYPES__Component_Constructor<A_Signal>, A_Signal> = new Map();
+
+    /**
+     * Optional structure defining the ordered list of signal constructors
+     * Used for vector operations and initialization
+     */
+    protected _structure: Array<A_TYPES__Component_Constructor<A_Signal>>;
+
+
+    /**
+     * Gets the ordered structure of signal constructors
+     * @returns Array of signal constructors in their defined order
+     */
+    get structure(): Array<A_TYPES__Component_Constructor<A_Signal>> {
+        return this._structure || [];
+    }
+
+    /**
+     * Creates a new A_SignalState instance
+     * 
+     * @param structure - Optional array defining the ordered structure of signal constructors
+     *                   This structure is used for vector operations and determines the order
+     *                   in which signals are processed and serialized
+     */
+    constructor(
+        structure: A_TYPES__Component_Constructor<A_Signal>[]
+    ) {
+        super({ name: "A_SignalState" });
+
+        this._structure = structure;
+
+        // Initialize the state map with undefined values for each signal in the structure
+        // This ensures all expected signals have entries in the state map from the start
+      
+    }
+
+
+    /**
+     * Sets the latest value for a specific signal type
+     * 
+     * @param signal - The signal constructor to associate the value with
+     * @param value - The data value emitted by the signal
+     */
+    set(
+        signal: A_Signal,
+        value: A_Signal
+    ): void
+    set(
+        signal: A_Signal
+    ): void
+    set(
+        signal: A_TYPES__Component_Constructor<A_Signal>,
+        value: A_Signal
+    ): void
+    set(
+        param1: A_TYPES__Component_Constructor<A_Signal> | A_Signal,
+        param2?: A_Signal
+    ): void {
+        const signal = param1 instanceof A_Signal ? param1.constructor as A_TYPES__Component_Constructor<A_Signal> : param1;
+        const value = param1 instanceof A_Signal ? param1 : param2!;
+
+        this._state.set(signal, value);
+    }
+
+    /**
+     * Retrieves the latest value for a specific signal type
+     * 
+     * @param signal - The signal constructor to get the value for
+     * @returns The latest data value or undefined if no value has been set
+     */
+    get(
+        signal: A_Signal
+    ): A_Signal | undefined
+    get(
+        signal: A_TYPES__Component_Constructor<A_Signal>
+    ): A_Signal | undefined
+    get(
+        param: A_TYPES__Component_Constructor<A_Signal> | A_Signal
+    ): A_Signal | undefined {
+        const signal = param instanceof A_Signal ? param.constructor as A_TYPES__Component_Constructor<A_Signal> : param;
+        return this._state.get(signal);
+    }
+
+    /**
+     * Checks if a signal type has been registered in the state
+     * 
+     * @param signal - The signal constructor to check for
+     * @returns True if the signal type exists in the state map
+     */
+    has(
+        signal: A_Signal
+    ): boolean
+    has(
+        signal: A_TYPES__Component_Constructor<A_Signal>
+    ): boolean
+    has(
+        param: A_TYPES__Component_Constructor<A_Signal> | A_Signal
+    ): boolean {
+        const signal = param instanceof A_Signal ? param.constructor as A_TYPES__Component_Constructor<A_Signal> : param;
+
+        return this.structure.includes(signal);
+    }
+
+    /**
+     * Removes a signal type and its associated value from the state
+     * 
+     * @param signal - The signal constructor to remove
+     * @returns True if the signal was successfully deleted, false if it didn't exist
+     */
+    delete(
+        signal: A_Signal
+    ): boolean
+    delete(
+        signal: A_TYPES__Component_Constructor<A_Signal>
+    ): boolean
+    delete(
+        param: A_TYPES__Component_Constructor<A_Signal> | A_Signal
+    ): boolean {
+        const signal = param instanceof A_Signal ? param.constructor as A_TYPES__Component_Constructor<A_Signal> : param;
+        return this._state.delete(signal);
+    }
+
+
+    /**
+     * Converts the current state to a vector (ordered array) format
+     * 
+     * The order is determined by the structure array provided during construction.
+     * Each position in the vector corresponds to a specific signal type's latest value.
+     * 
+     * @returns Array of signal values in the order defined by the structure
+     * @throws Error if structure is not defined or if any signal value is undefined
+     */
+    toVector(): A_SignalVector {
+        const vector: Array<A_Signal> = [];
+
+        this._state.forEach((value, key) => {
+            vector.push(value);
+        });
+
+        return new A_SignalVector({
+            structure: this.structure,
+            values: vector
+        });
+    }
+
+    /**
+     * Converts the current state to an object with signal constructor names as keys
+     * 
+     * This provides a more readable representation of the state where each signal
+     * type is identified by its constructor name.
+     * 
+     * @returns Object mapping signal constructor names to their latest values
+     * @throws Error if any signal value is undefined
+     */
+    toObject(): Record<string, A_Signal> {
+        const obj: Record<string, A_Signal> = {};
+
+        this.structure.forEach((signalConstructor) => {
+            const value = this._state.get(signalConstructor);
+            if (value === undefined) {
+                throw new Error(`Signal ${signalConstructor.name} has no value in state`);
+            }
+            obj[signalConstructor.name] = value;
+        });
+
+        return obj;
+    }
+
+}

package/src/lib/A-Signal/entities/A-Signal.entity.ts

@@ -0,0 +1,69 @@
+import { A_Entity, A_Scope } from "@adaas/a-concept";
+import { A_Signal_Init, A_Signal_Serialized } from "../A-Signal.types";
+import { A_SignalFeatures } from "../A-Signal.constants";
+
+/**
+ * A Signal Entity is an individual signal instance that carries data.
+ * Signals is a event types that uses for vectors of signals to be used for further processing. 
+ * 
+ * Comparing to standard events, signals should be used in case when the event impacts some "state" 
+ * and the state should be used instead of the event itself.
+ * 
+ * For example, a signal can represent the current status of a user (online/offline/away), 
+ * while an event would represent a single action (user logged in/logged out).
+ * 
+ * Signals are typically used in scenarios where the current state is more important than individual events, 
+ * such as monitoring systems, real-time dashboards, or stateful applications.
+ */
+export class A_Signal<
+    _TSignalDataType extends Record<string, any> = Record<string, any>
+> extends A_Entity<A_Signal_Init<_TSignalDataType>, A_Signal_Serialized<_TSignalDataType>> {
+
+    data!: _TSignalDataType;
+
+
+    /**
+     * Allows to define default data for the signal.
+     * 
+     * If no data is provided during initialization, the default data will be used.
+     * 
+     * @returns 
+     */
+    static async default(): Promise<A_Signal | undefined> {
+        return undefined;
+    }
+
+
+
+    fromJSON(serializedEntity: A_Signal_Serialized<_TSignalDataType>): void {
+        super.fromJSON(serializedEntity);
+        this.data = serializedEntity.data;
+    }
+
+
+    fromNew(newEntity: A_Signal_Init<_TSignalDataType>): void {
+        this.aseid = this.generateASEID({ entity: newEntity.name });
+        this.data = newEntity.data;
+    }
+
+    /**
+     * Emits this signal within the provided scope.
+     * 
+     * Scope is mandatory since signal itself should not be registered in the scope, 
+     * but should use particular scope context to use proper set of components
+     * 
+     * @param scope 
+     */
+    async emit(scope: A_Scope) {
+        await this.call(A_SignalFeatures.Emit, scope);
+    }
+
+
+    toJSON(): A_Signal_Serialized<_TSignalDataType> {
+        return {
+            ...super.toJSON(),
+            data: this.data
+        };
+    }
+
+}

package/src/lib/A-Signal/entities/A-SignalVector.entity.ts

@@ -0,0 +1,198 @@
+import { A_Entity, A_TYPES__Component_Constructor, A_TYPES__Entity_Constructor } from "@adaas/a-concept";
+import { A_SignalVector_Serialized, A_SignalVector_Init } from "../A-Signal.types";
+import { A_Signal } from "./A-Signal.entity";
+
+
+/**
+ * A Signal Vector Entity is a collection of signals structured in a specific way.
+ * It allows grouping multiple signals together for batch processing or transmission.
+ * 
+ * Signal Vectors are useful in scenarios where multiple related signals need to be handled together,
+ * as a state of the system or a snapshot of various parameters at a given time.
+ * 
+ * @template TSignalsConstructors - Array of signal constructor types (e.g., [typeof MySignal, typeof CustomSignal])
+ * @template TSignals - Array of signal instances derived from constructors
+ */
+export class A_SignalVector<
+    TSignals extends Array<A_Signal> = Array<A_Signal>,
+    TSignalsConstructors extends Array<A_TYPES__Entity_Constructor<A_Signal>> = TSignals extends Array<infer U> ? U extends A_Signal ? A_TYPES__Entity_Constructor<U>[] : never : never
+> extends A_Entity<A_SignalVector_Init<TSignals[number][], TSignalsConstructors>, A_SignalVector_Serialized> {
+
+    /**
+     * The structure of the signal vector, defining the types of signals it contains.
+     * 
+     * For example:
+     * [UserSignInSignal, UserStatusSignal, UserActivitySignal]
+     * 
+     * [!] if not provided, it will be derived from the signals values.
+     */
+    protected _structure?: TSignalsConstructors;
+    /**
+     * It's actual vector Values of Signals like :
+     * [UserActionSignal, UserMousePositionSignal, ExternalDependencySignal]
+     */
+    protected _signals!: TSignals[number][]
+
+
+    fromNew(newEntity: A_SignalVector_Init<TSignals[number][], TSignalsConstructors>): void {
+        super.fromNew(newEntity);
+        this._structure = newEntity.structure;
+        this._signals = newEntity.values;
+    }
+
+    /**
+     * The structure of the signal vector, defining the types of signals it contains.
+     * 
+     * For example:
+     * [UserSignInSignal, UserStatusSignal, UserActivitySignal]
+     * 
+     */
+    get structure(): TSignalsConstructors {
+        return this._structure || this._signals.map(s => s.constructor as A_TYPES__Entity_Constructor<A_Signal>) as TSignalsConstructors;
+    }
+
+
+    get length(): number {
+        return this.structure.length;
+    }
+
+
+    /**
+     * Checks if the vector contains a signal of the specified type.
+     * 
+     * @param signal 
+     */
+    has(signal: A_Signal): boolean
+    has(signalConstructor: A_TYPES__Component_Constructor<A_Signal>): boolean
+    has(param1: A_Signal | A_TYPES__Component_Constructor<A_Signal>): boolean {
+        let signalConstructor: A_TYPES__Component_Constructor<A_Signal>;
+        if (param1 instanceof A_Entity) {
+            signalConstructor = param1.constructor as A_TYPES__Component_Constructor<A_Signal>;
+        } else {
+            signalConstructor = param1;
+        }
+        return this.structure.includes(signalConstructor);
+    }
+
+    get(signal: A_Signal): Record<string, any> | undefined
+    get(signalConstructor: A_TYPES__Component_Constructor<A_Signal>): Record<string, any> | undefined
+    get(param1: A_Signal | A_TYPES__Component_Constructor<A_Signal>): Record<string, any> | undefined {
+        let signalConstructor: A_TYPES__Component_Constructor<A_Signal>;
+
+        if (param1 instanceof A_Entity) {
+            signalConstructor = param1.constructor as A_TYPES__Component_Constructor<A_Signal>;
+        } else {
+            signalConstructor = param1;
+        }
+
+        const index = this._signals.findIndex(s => s.constructor === signalConstructor);
+        if (index === -1) {
+            return undefined;
+        }
+        return this._signals[index];
+    }
+
+
+    /**
+     * Converts to Array of values of signals in the vector
+     * Maintains the order specified in the structure/generic type
+     * 
+     * @param structure - Optional structure to override the default ordering
+     * @returns Array of signal instances in the specified order
+     */
+    async toVector<
+        T extends Array<A_Signal> = TSignals,
+    >(
+        structure?: { [K in keyof T]: T[K] extends A_Signal ? A_TYPES__Entity_Constructor<T[K]> : never }
+    ): Promise<{ [K in keyof T]: T[K] }> {
+        const usedStructure = structure || this.structure;
+
+        return usedStructure.map((signalConstructor) => {
+            const signalIndex = this._signals.findIndex(s => s.constructor === signalConstructor);
+            return signalIndex !== -1 ? this._signals[signalIndex] : undefined;
+        }) as { [K in keyof T]: T[K] };
+    }
+
+
+    /**
+     * Converts to Array of data of signals in the vector
+     * Maintains the order specified in the structure/generic type
+     * 
+     * @param structure - Optional structure to override the default ordering
+     * @returns Array of serialized signal data in the specified order
+     */
+    async toDataVector<
+        T extends Array<A_Signal> = TSignals,
+    >(
+        structure?: { [K in keyof T]: T[K] extends A_Signal ? A_TYPES__Entity_Constructor<T[K]> : never }
+    ): Promise<{ [K in keyof T]: T[K] extends A_Signal<infer D> ? D | undefined : never }> {
+
+        const usedStructure = structure || this.structure;
+
+        const results: Array<any> = [];
+
+        for (const signalConstructor of usedStructure) {
+            const signalIndex = this._signals.findIndex(s => s.constructor === signalConstructor);
+            let data: any;
+            if (signalIndex === -1) {
+
+                data = await (signalConstructor as typeof A_Signal).default()
+
+            } else {
+                const signal = this._signals[signalIndex];
+                data = signal;
+            }
+
+
+            results.push(data?.toJSON().data);
+        }
+
+        return results as { [K in keyof T]: T[K] extends A_Signal<infer D> ? D | undefined : never };
+    }
+
+    /**
+     * Converts to Object with signal constructor names as keys and their corresponding data values
+     * Uses the structure ordering to ensure consistent key ordering
+     * 
+     * @returns Object with signal constructor names as keys and signal data as values
+     */
+    async toObject<
+        T extends Array<A_Signal> = TSignals,
+    >(
+        structure?: { [K in keyof T]: T[K] extends A_Signal ? A_TYPES__Entity_Constructor<T[K]> : never }
+    ): Promise<{ [key: string]: T[number] extends A_Signal<infer D> ? D | undefined : never }> {
+
+        const usedStructure = structure || this.structure;
+
+        const obj: { [key: string]: T[number] extends A_Signal<infer D> ? D | undefined : never } = {};
+        usedStructure.forEach((signalConstructor) => {
+            const signalName = signalConstructor.name;
+            const signalIndex = this._signals.findIndex(s => s.constructor === signalConstructor);
+
+            if (signalIndex !== -1) {
+                const signal = this._signals[signalIndex];
+                obj[signalName] = signal.toJSON().data as any;
+            } else {
+                obj[signalName] = undefined as any;
+            }
+        });
+
+        return obj;
+    }
+
+
+    /**
+     * Serializes the Signal Vector to a JSON-compatible format.
+     * 
+     * 
+     * @returns 
+     */
+    toJSON(): A_SignalVector_Serialized {
+        return {
+            ...super.toJSON(),
+            structure: this.structure.map(s => s.name),
+            values: this._signals.map(s => s.toJSON())
+        };
+    }
+}
+

package/tests/A-Logger.test.ts

@@ -215,7 +215,8 @@ describe('A_Logger Component', () => {
             
             const logs = getCapturedLogs();
             expect(logs[0]).toContain('Test error message');
-            expect(logs[0]).toContain('"name": "Error"');
+            expect(logs[0]).toContain('ERROR: Error');
+            expect(logs[0]).toContain('STACK TRACE:');
         });
 
         test('should format A_Error instances with special formatting', () => {
@@ -253,7 +254,7 @@ describe('A_Logger Component', () => {
 
             colors.forEach(color => {
                 clearCapturedLogs();
-                logger.log(color, `${color} message`);
+                logger.info(color, `${color} message`);
                 
                 const logs = getCapturedLogs();
                 expect(logs[0]).toContain(`${color} message`);
@@ -261,6 +262,26 @@ describe('A_Logger Component', () => {
             });
         });
 
+        test('should support extended color palette from A_LoggerColorName enum', () => {
+            const extendedColors: Array<keyof typeof A_LOGGER_COLORS> = [
+                'brightBlue', 'brightCyan', 'brightMagenta',
+                'indigo', 'violet', 'purple', 'lavender',
+                'skyBlue', 'steelBlue', 'slateBlue', 'deepBlue',
+                'lightBlue', 'periwinkle', 'cornflower', 'powder',
+                'darkGray', 'lightGray', 'charcoal', 'silver', 'smoke', 'slate'
+            ];
+
+            extendedColors.forEach(color => {
+                clearCapturedLogs();
+                logger.info(color, `Extended ${color} message`);
+                
+                const logs = getCapturedLogs();
+                // Clean the output to handle line wrapping
+                const cleanedOutput = logs[0].replace(/\n\s*\|\s*/g, ' ').replace(/\s+/g, ' ');
+                expect(cleanedOutput).toContain(`Extended ${color} message`);
+            });
+        });
+
         test('should default to blue color when no color specified', () => {
             logger.log('Default color message');
             
@@ -409,13 +430,19 @@ describe('A_Logger Component', () => {
             expect(logs[0]).toContain('[Circular Reference]');
         });
 
-        test('should handle very long strings', () => {
+        test('should handle very long strings with wrapping', () => {
             const longString = 'A'.repeat(1000);
             
-            logger.log('Long string:', longString);
+            logger.info('Long string:', longString);
             
             const logs = getCapturedLogs();
-            expect(logs[0]).toContain(longString);
+            // The logger now wraps long strings, so we check for the presence of parts of the string
+            // rather than the entire string in one line
+            expect(logs[0]).toContain('Long string:');
+            expect(logs[0]).toContain('AAAAAAAAAAA'); // Should contain many A's
+            // The string should be wrapped across multiple lines
+            const logLines = logs[0].split('\n');
+            expect(logLines.length).toBeGreaterThan(5); // Should be wrapped into multiple lines
         });
 
         test('should handle empty scope name', () => {
@@ -466,6 +493,64 @@ describe('A_Logger Component', () => {
             expect(endTime - startTime).toBeLessThan(500); // Should complete within 500ms
         });
     });
+
+    // =============================================
+    // Terminal Width and Formatting Tests
+    // =============================================
+
+    describe('Terminal Width Detection and Formatting', () => {
+        test('should detect terminal width in Node.js environment', () => {
+            // The logger should initialize without errors and handle terminal width detection
+            expect(() => {
+                const testScope = new A_Scope({ name: 'TerminalTest' });
+                const terminalLogger = new A_Logger(testScope);
+                terminalLogger.info('Terminal width test message');
+            }).not.toThrow();
+        });
+
+        test('should wrap long messages appropriately', () => {
+            // Create a message that's extremely long to ensure wrapping even on wide terminals
+            // The message needs to be longer than most reasonable terminal widths (200+ chars)
+            const extremelyLongMessage = 'This is an extraordinarily and exceptionally long message designed specifically for testing text wrapping functionality in the A_Logger component, containing numerous words and phrases that together form a sentence of considerable length that should definitely exceed the available width in most terminal configurations, thereby demonstrating the logger\'s sophisticated text wrapping capabilities and ensuring proper formatting across diverse environments with varying screen sizes and terminal window dimensions, while maintaining readability and professional presentation standards.';
+            
+            logger.info('cyan', extremelyLongMessage);
+            
+            const logs = getCapturedLogs();
+            
+            // Remove all newlines and extra spaces to get the actual content for verification
+            const cleanedOutput = logs[0].replace(/\n\s*\|\s*/g, ' ').replace(/\s+/g, ' ');
+            
+            // Verify the message content is preserved regardless of wrapping
+            expect(cleanedOutput).toContain('extraordinarily and exceptionally long message');
+            expect(cleanedOutput).toContain('readability and professional presentation');
+            
+            // The message should either be wrapped with newlines OR be very long on one line
+            const logOutput = logs[0];
+            const hasWrapping = logOutput.includes('\n') && logOutput.includes('|'); // Continuation markers
+            const isSingleLongLine = logOutput.length > 300; // Very long single line
+            
+            // In narrow terminals, wrapping occurs with continuation markers
+            // In wide terminals, the message appears as one very long line
+            expect(hasWrapping || isSingleLongLine).toBe(true);
+            
+            // Ensure the complete message is present (checking cleaned version)
+            expect(cleanedOutput).toContain('extraordinarily and exceptionally long message');
+            expect(cleanedOutput).toContain('professional presentation standards');
+        });
+
+        test('should handle multi-argument messages with proper indentation', () => {
+            logger.info('brightMagenta', 
+                'First long argument that might wrap across lines',
+                'Second argument for testing indentation',
+                { complexObject: 'with nested data for formatting tests' }
+            );
+            
+            const logs = getCapturedLogs();
+            expect(logs[0]).toContain('First long argument');
+            expect(logs[0]).toContain('Second argument');
+            expect(logs[0]).toContain('complexObject');
+        });
+    });
 });
 
 // =============================================

package/tests/A-Route.test.ts

@@ -0,0 +1,34 @@
+import { A_Route } from "@adaas/a-utils/lib/A-Route/A-Route.entity";
+
+
+
+
+jest.retryTimes(0);
+
+describe('A-Route tests', () => {
+    it('Should Allow to create a new A-Route', async () => {
+        let route = new A_Route('/test/route');
+
+        expect(route).toBeInstanceOf(A_Route);
+        expect(route.path).toBe('/test/route');
+    });
+    it('Should properly parse and extract path params', async () => {
+        let route = new A_Route('/test/route/:param1/:param2');
+
+        expect(route).toBeInstanceOf(A_Route);
+        expect(route.path).toBe('/test/route/:param1/:param2');
+        expect(route.params).toEqual(['param1', 'param2']);
+
+        const extractedParams = route.extractParams('/test/route/value1/value2');
+        expect(extractedParams).toEqual({ param1: 'value1', param2: 'value2' });
+    });
+    it('Should properly parse received URL', async () => {
+        let route = new A_Route('https://example.com/test/route?param1=value1&param2=value2');
+
+        expect(route).toBeInstanceOf(A_Route);
+        expect(route.path).toBe('/test/route');
+        const query = route.extractQuery('https://example.com/test/route?param1=value1&param2=value2');
+        expect(query).toEqual({ param1: 'value1', param2: 'value2' });
+    });
+
+})