@adaas/a-utils 0.1.40 → 0.2.2

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

@@ -1,10 +1,12 @@
-import { A_Caller, A_Component, A_Context, A_Feature, A_Inject, A_Scope } from "@adaas/a-concept";
-import { A_SignalFeatures } from "../A-Signal.constants";
+import { A_Caller, A_Component, A_Context, A_Dependency, A_Error, A_Feature, A_Inject, A_Scope } from "@adaas/a-concept";
 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";
+import { A_Frame } from "@adaas/a-frame";
+import { A_SignalBusFeatures } from "./A-SignalBus.constants";
+import { A_SignalBusError } from "./A-SignalBus.error";
 
 
 
@@ -18,47 +20,90 @@ import { A_Signal } from "../entities/A-Signal.entity";
  * 
  * The component itself is stateless and all methods uses only parameters (context) is provided with.
  */
+@A_Frame.Component({
+    namespace: 'A-Utils',
+    name: 'A-SignalBus',
+    description: 'Signal bus component that manages the emission and state of signals within a given scope. It listens for emitted signals, updates their state, and forwards them to registered watchers. The bus ensures a consistent signal vector structure based on the defined configuration, facilitating signal management across multiple components.'
+})
 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 
-     */
+    @A_Frame.Method({
+        description: 'Emit multiple signals through the signal bus.'
+    })
+    async next(...signals: A_Signal[]) {
+        const scope = new A_Scope({
+            name: `A_SignalBus-Next-Scope`,
+            entities: signals
+        })
+            .inherit(A_Context.scope(this));
+
+        try {
+            await this.call(A_SignalBusFeatures.onBeforeNext, scope);
+            await this.call(A_SignalBusFeatures.onNext, scope);
+
+            scope.destroy();
+
+        } catch (error) {
+
+            let wrappedError;
+
+            switch (true) {
+                case error instanceof A_SignalBusError:
+                    wrappedError = error;
+                    break;
+
+                case error instanceof A_Error && error.originalError instanceof A_SignalBusError:
+                    wrappedError = error.originalError;
+                    break;
+
+                default:
+                    wrappedError = new A_SignalBusError({
+                        title: A_SignalBusError.SignalProcessingError,
+                        description: `An error occurred while processing the signal.`,
+                        originalError: error
+                    })
+                    break;
+            }
+
+            scope.register(wrappedError);
+
+            await this.call(A_SignalBusFeatures.onError);
+
+            scope.destroy();
+        }
+    }
+
+
+    @A_Feature.Extend({
+        before: /.*/
+    })
+    protected async [A_SignalBusFeatures.onError](
+        @A_Inject(A_Error) error: A_Error,
+        @A_Inject(A_Logger) logger?: A_Logger,
+        ...args: any[]
+    ) {
+        logger?.error(error);
+    }
+
     @A_Feature.Extend({
-        scope: [A_Signal]
+        scope: [A_SignalBus],
+        before: /.*/
     })
-    async [A_SignalFeatures.Next](
-        @A_Inject(A_Caller) signal: A_Signal,
+    async [A_SignalBusFeatures.onBeforeNext](
         @A_Inject(A_Scope) scope: A_Scope,
 
         @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_Logger) logger?: A_Logger,
         @A_Inject(A_SignalConfig) config?: A_SignalConfig,
     ) {
-
-        /*
-        1) create a signal when it occurs via new A_Signal('somedata')
-        2) emit a signal when needed via signal.emit(scope)
-        3) the bus should listen for all emitted signals within the scope
-        4) when a signal is emitted, the bus should store a signal in some place (probably it's memory)
-        */
-
         /**
          * 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
@@ -74,22 +119,61 @@ export class A_SignalBus extends A_Component {
             state = new A_SignalState(config.structure);
             componentContext.register(state);
         }
+    }
+
+    /**
+     * 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 
+     */
+    @A_Feature.Extend({
+        scope: [A_SignalBus],
+        before: /.*/
+    })
+    async [A_SignalBusFeatures.onNext](
+        // @A_Dependency.All()
+        // @A_Inject(A_Signal) signal: A_Signal[],
+        @A_Inject(A_Scope) scope: A_Scope,
+
+        @A_Dependency.Required()
+        @A_Inject(A_SignalState) state: A_SignalState,
+
+        @A_Inject(A_Config) globalConfig?: A_Config<['A_SIGNAL_VECTOR_STRUCTURE']>,
+        @A_Inject(A_Logger) logger?: A_Logger,
+        @A_Inject(A_SignalConfig) config?: A_SignalConfig,
+    ) {
+        /*
+        1) create a signal when it occurs via new A_Signal('somedata')
+        2) emit a signal when needed via bus.next(signal)
+        3) the bus should listen for all emitted signals within the scope
+        4) when a signal is emitted, the bus should store a signal in some place (probably it's memory)
+        */
+        const signals = scope.resolveFlatAll<A_Signal>(A_Signal);
 
+        for (const signal of signals) {
 
-        if (!state.has(signal))
-            return;
+            if (!state.has(signal))
+                return;
 
+            //  ------------------------------------------------------------------
+            //  And finally if all checks are passed, we can update the state
+            //  ------------------------------------------------------------------
 
-        //  ------------------------------------------------------------------
-        //  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);
 
-        logger?.debug(`A_SignalBus: Updating state for signal '${signal.constructor.name}' with data:`, signal.data);
+            state.set(signal);
 
-        state.set(signal);
+            const vector = state.toVector();
 
-        const vector = state.toVector();
+            scope.register(vector);
 
-        await vector.next(scope);
+        }
     }
 }

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

@@ -0,0 +1,7 @@
+
+export enum A_SignalBusFeatures {
+    onBeforeNext = '_A_SignalBusFeatures_onBeforeNext',
+    onNext = '_A_SignalBusFeatures_onNext',
+
+    onError = '_A_SignalBusFeatures_onError',
+}

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

@@ -0,0 +1,9 @@
+import { A_Error } from "@adaas/a-concept";
+
+
+
+export class A_SignalBusError extends A_Error {
+
+
+    static readonly SignalProcessingError = 'Signal processing error';
+}

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

@@ -1,6 +1,7 @@
 import { A_CommonHelper, 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";
+import { A_Frame } from "@adaas/a-frame";
 
 
 
@@ -11,6 +12,11 @@ import { A_Signal } from "../entities/A-Signal.entity";
  * e.g. [A_RouterWatcher, A_ScopeWatcher, A_LoggerWatcher]
  * This structure then should be used for any further processing of signals within the scope.
  */
+@A_Frame.Fragment({
+    namespace: 'A-Utils',
+    name: 'A-SignalConfig',
+    description: 'Signal configuration fragment that defines the structure and types of signals within a given scope. It allows specifying the expected signal constructors and their order, facilitating consistent signal management and processing across components that emit or listen to signals.'
+})
 export class A_SignalConfig extends A_Fragment {
 
     protected _structure?: Array<A_TYPES__Entity_Constructor<A_Signal>>;

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

@@ -1,6 +1,7 @@
 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";
+import { A_Frame } from "@adaas/a-frame";
 
 /**
  * A_SignalState manages the latest state of all signals within a given scope.
@@ -15,6 +16,11 @@ import { A_SignalVector } from "../entities/A-SignalVector.entity";
  * - Signal instances and their emitted value types
  * - Vector structure and the data it contains
  */
+@A_Frame.Fragment({
+    namespace: 'A-Utils',
+    name: 'A-SignalState',
+    description: 'Manages the latest state of all signals within a given scope, maintaining a mapping between signal constructors and their most recently emitted values.'
+})
 export class A_SignalState<
     TSignalData extends Record<string, any> = Record<string, any>
 > extends A_Fragment {

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

@@ -1,6 +1,6 @@
 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";
+import { A_Frame } from "@adaas/a-frame";
 
 /**
  * A Signal Entity is an individual signal instance that carries data.
@@ -15,6 +15,11 @@ import { A_SignalFeatures } from "../A-Signal.constants";
  * 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.
  */
+@A_Frame.Entity({
+    namespace: 'A-Utils',
+    name: 'A-Signal',
+    description: 'A Signal Entity represents an individual signal instance that carries data, used for managing state within an application context. Signals are designed to reflect the current state rather than individual events, making them suitable for scenarios where state monitoring and real-time updates are essential.'
+})
 export class A_Signal<
     _TSignalDataType extends Record<string, any> = Record<string, any>
 > extends A_Entity<A_Signal_Init<_TSignalDataType>, A_Signal_Serialized<_TSignalDataType>> {
@@ -46,17 +51,6 @@ export class A_Signal<
         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 next(scope: A_Scope) {
-        await this.call(A_SignalFeatures.Next, scope);
-    }
 
 
     toJSON(): A_Signal_Serialized<_TSignalDataType> {

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

@@ -1,7 +1,7 @@
 import { A_Entity, A_Scope, 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";
-import { A_SignalVectorFeatures } from "../A-Signal.constants";
+import { A_Frame } from "@adaas/a-frame";
 
 
 /**
@@ -14,6 +14,11 @@ import { A_SignalVectorFeatures } from "../A-Signal.constants";
  * @template TSignalsConstructors - Array of signal constructor types (e.g., [typeof MySignal, typeof CustomSignal])
  * @template TSignals - Array of signal instances derived from constructors
  */
+@A_Frame.Entity({
+    namespace: 'A-Utils',
+    name: 'A-SignalVector',
+    description: 'A Signal Vector Entity represents a collection of signals structured in a specific way, allowing for batch processing and transmission of related signals as a unified state representation.'
+})
 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
@@ -88,15 +93,6 @@ export class A_SignalVector<
     }
 
 
-    /**
-     * Emits the signal vector to the specified scope.
-     * 
-     * @param scope
-     */
-    async next(scope: A_Scope): Promise<void> {
-        return await this.call(A_SignalVectorFeatures.Next, scope);
-    }
-
     
     /**
      * Checks if the vector contains a signal of the specified type.

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

@@ -2,6 +2,7 @@ import { A_Component, A_Context, A_Feature, A_FormatterHelper, A_Scope } from "@
 import { A_StateMachineError } from "./A-StateMachine.error";
 import { A_StateMachineFeatures } from "./A-StateMachine.constants";
 import { A_StateMachineTransition } from "./A-StateMachineTransition.context";
+import { A_Frame } from "@adaas/a-frame";
 
 /**
  * A_StateMachine is a powerful state machine implementation that allows you to define and manage
@@ -29,6 +30,12 @@ import { A_StateMachineTransition } from "./A-StateMachineTransition.context";
  * }
  * ```
  */
+
+@A_Frame.Namespace('A-Utils')
+@A_Frame.Component({
+    name: 'A-StateMachine',
+    description: 'A powerful state machine component for managing complex state transitions.'
+})
 export class A_StateMachine<
     T extends Record<string, any> = Record<string, any>
 > extends A_Component {
@@ -195,6 +202,10 @@ export class A_StateMachine<
      * 
      * If any step fails, the onError hook is called and a wrapped error is thrown.
      */
+    @A_Frame.Method({
+        name: 'transition',
+        description: 'Executes a state transition from one state to another.'
+    })
     async transition(
         /**
          * The state to transition from

package/src/lib/A-StateMachine/A-StateMachineTransition.context.ts

@@ -1,8 +1,13 @@
+import { A_Frame } from "@adaas/a-frame";
 import { A_OperationContext } from "../A-Operation/A-Operation.context";
 import { A_StateMachineTransitionParams, A_StateMachineTransitionStorage } from "./A-StateMachine.types";
 
 
 
+@A_Frame.Fragment({
+    name: 'A-StateMachineTransition',
+    description: 'Context for managing state machine transitions.'
+})
 export class A_StateMachineTransition<
     _ParamsType = any,
     _ResultType = any
@@ -13,7 +18,6 @@ export class A_StateMachineTransition<
     A_StateMachineTransitionStorage<_ResultType, _ParamsType>
 > {
 
-
     constructor(
         params: A_StateMachineTransitionParams<_ParamsType>
     ) {
@@ -26,14 +30,16 @@ export class A_StateMachineTransition<
         this._meta.set('to', params.to);
     }
 
-
-
+    /**
+     * The state to transition from
+     */
     get from(): string {
         return this._meta.get('from')!;
     }
 
-
-
+    /**
+     * The state to transition to
+     */
     get to(): string {
         return this._meta.get('to')!;
     }

package/tests/A-Signal.test.ts

@@ -1,6 +1,6 @@
-import { A_Caller, A_Component, A_Concept, A_Container, A_Context, A_Feature, A_Inject, A_Scope } from "@adaas/a-concept";
-import { A_SignalVectorFeatures } from "@adaas/a-utils/lib/A-Signal/A-Signal.constants";
+import { A_Component, A_Concept, A_Container, A_Context, A_Feature, A_Inject, A_Scope } from "@adaas/a-concept";
 import { A_SignalBus } from "@adaas/a-utils/lib/A-Signal/components/A-SignalBus.component";
+import { A_SignalBusFeatures } from "@adaas/a-utils/lib/A-Signal/components/A-SignalBus.constants";
 import { A_SignalConfig } from "@adaas/a-utils/lib/A-Signal/context/A-SignalConfig.context";
 import { A_Signal } from "@adaas/a-utils/lib/A-Signal/entities/A-Signal.entity";
 import { A_SignalVector } from "@adaas/a-utils/lib/A-Signal/entities/A-SignalVector.entity";
@@ -71,23 +71,19 @@ describe('A-Signal tests', () => {
         class UserIntentionListener extends A_Component {
             @A_Concept.Start()
             async start(
-                @A_Inject(A_Scope) scope: A_Scope,
                 @A_Inject(A_SignalBus) bus: A_SignalBus
             ) {
-
-
-                const signal = new A_Signal({
+                await bus.next(new A_Signal({
                     data: {
                         buttonId: 'submit-order'
                     }
-                })
-                await signal.next(scope)
+                }))
             }
 
 
             @A_Feature.Extend()
-            async [A_SignalVectorFeatures.Next](
-                @A_Inject(A_Caller) vector: A_SignalVector
+            async [A_SignalBusFeatures.onNext](
+                @A_Inject(A_SignalVector) vector: A_SignalVector
             ) {
                 result = vector;
             }
@@ -145,13 +141,13 @@ describe('A-Signal tests', () => {
                     }
                 })
 
-                await signal.next(scope)
+                await bus.next(signal)
             }
 
 
             @A_Feature.Extend()
-            async [A_SignalVectorFeatures.Next](
-                @A_Inject(A_Caller) vector: A_SignalVector
+            async [A_SignalBusFeatures.onNext](
+                @A_Inject(A_SignalVector) vector: A_SignalVector
             ) {
                 result = vector;
             }