@adaas/a-concept 0.1.18 → 0.1.19

package/src/global/A-Stage/A-Stage.class.ts

@@ -1,6 +1,7 @@
 import {
-    A_TYPES__A_Stage_JSON, A_TYPES__A_Stage_Status,
-    A_TYPES__A_StageStep, A_TYPES__A_StageStepProcessingExtraParams
+    A_TYPES__A_Stage_Status,
+    A_TYPES__A_StageStep,
+    A_TYPES__Stage_Serialized
 } from "./A-Stage.types";
 import { A_Context } from "../A-Context/A-Context.class";
 import { A_Feature } from "../A-Feature/A-Feature.class";
@@ -16,64 +17,60 @@ import { A_TYPES__Component_Constructor } from "../A-Component/A-Component.types
 
 export class A_Stage {
 
+    /**
+     * The feature that owns this stage
+     */
     private readonly _feature!: A_Feature;
-    private readonly _steps!: A_TYPES__A_StageStep[];
+    /**
+     * Initial Instructions to process the stage
+     */
+    private readonly _definition!: A_TYPES__A_StageStep;
+    /**
+     * Possible errors during stage processing
+     */
     private _error?: Error | A_Error | any;
+    /**
+     * Indicates the current status of the stage
+     */
+    private _status: A_TYPES__A_Stage_Status = A_TYPES__A_Stage_Status.INITIALIZED;
+
+    /**
+     * Promise that will be resolved when the stage is Processed
+     */
+    private _processed: Promise<void> | undefined;
 
 
     /**
-     * A_Stage is a set of A_Functions within A_Feature that should be run in a specific order.
-     * Each stage may contain one or more functions. 
-     * [!] That always run in parallel (in NodeJS asynchronously), independently of each other.
+     * A_Stage is a callable A_Function within A_Feature that should be run with specific parameters.
+     * [!] Depending on the Stage Definition type sync/async function can be executed correspondingly.
      * 
      * A-Stage is a common object that uses to simplify logic and re-use of A-Feature internals for better composition. 
      */
     constructor(
+        /**
+         * The feature that owns this stage
+         */
         feature: A_Feature,
-        steps: A_TYPES__A_StageStep[] = []
+        /**
+         * The step definitions of the stage
+         */
+        step: A_TYPES__A_StageStep
     ) {
         this._feature = feature;
-        this._steps = steps;
+        this._definition = step;
     }
 
-    status: A_TYPES__A_Stage_Status = A_TYPES__A_Stage_Status.INITIALIZED;
-
     /**
-     * Promise that will be resolved when the stage is Processed
+     * Returns the name of the stage
      */
-    processed: Promise<void> | undefined;
-
-
-
-
     get name(): string {
         return this.toString();
     }
-
-    get before(): string[] {
-        return this._steps.reduce((acc, step) => ([
-            ...acc,
-            ...step.before
-        ]), [] as string[]);
-    }
-
-    get after(): string[] {
-        return this._steps.reduce((acc, step) => ([
-            ...acc,
-            ...step.after
-        ]), [] as string[]);
-    }
-
-    get steps(): A_TYPES__A_StageStep[] {
-        return this._steps;
-    }
-
-    get asyncSteps(): A_TYPES__A_StageStep[] {
-        return this._steps.filter(step => step.behavior === 'async');
-    }
-
-    get syncSteps(): A_TYPES__A_StageStep[] {
-        return this._steps.filter(step => step.behavior === 'sync');
+    /**
+     * Returns the current status of the stage
+     */
+    get status(): A_TYPES__A_Stage_Status {
+        return this._status;
     }
 
 
@@ -130,28 +127,13 @@ export class A_Stage {
     }
 
 
-    /**
-     * Adds a step to the stage
-     * 
-     * @param step 
-     * @returns 
-     */
-    add(
-        step: A_TYPES__A_StageStep
-    ): this {
-        this._steps.push(step);
-
-        return this;
-    }
-
-
     /**
      * Resolves the component of the step
      * 
      * @param step 
      * @returns 
      */
-    protected getStepInstance(
+    protected getStepComponent(
         scope: A_Scope,
         step: A_TYPES__A_StageStep
     ) {
@@ -194,15 +176,18 @@ export class A_Stage {
         step: A_TYPES__A_StageStep,
         scope: A_Scope
     ) {
-        const instance = await this.getStepInstance(scope, step);
+        // 1) Resolve component
+        const component = await this.getStepComponent(scope, step);
+        // 2) Resolve arguments
         const callArgs = await this.getStepArgs(scope, step);
 
-        return await instance[step.handler](...callArgs);
+        // 3) Call handler
+        return await component[step.handler](...callArgs);
     }
 
 
     skip() {
-        this.status = A_TYPES__A_Stage_Status.SKIPPED;
+        this._status = A_TYPES__A_Stage_Status.SKIPPED;
     }
 
 
@@ -216,86 +201,44 @@ export class A_Stage {
          * Scope to be used to resolve the steps dependencies
          */
         scope?: A_Scope,
-    ): Promise<void>
-    async process(
-        /**
-         * Extra parameters to control the steps processing
-         */
-        params?: Partial<A_TYPES__A_StageStepProcessingExtraParams>
-    ): Promise<void>
-    async process(
-        /**
-         * Scope to be used to resolve the steps dependencies
-         */
-        param1?: A_Scope | Partial<A_TYPES__A_StageStepProcessingExtraParams>,
-        /**
-         * Extra parameters to control the steps processing
-         */
-        param2?: Partial<A_TYPES__A_StageStepProcessingExtraParams>
     ): Promise<void> {
 
-        const scope = A_TypeGuards.isScopeInstance(param1)
-            ? param1
+        const targetScope = A_TypeGuards.isScopeInstance(scope)
+            ? scope
             : A_Context.scope(this._feature);
 
-        const params = A_TypeGuards.isScopeInstance(param1)
-            ? param2
-            : param1;
-
-
-        if (!this.processed)
-            this.processed = new Promise<void>(
+        if (!this._processed)
+            this._processed = new Promise<void>(
                 async (resolve, reject) => {
                     try {
-                        this.status = A_TYPES__A_Stage_Status.PROCESSING;
-
-                        if (params?.steps && params.steps.length) {
-                            params.steps.forEach(step => this.add(step));
+                        this._status = A_TYPES__A_Stage_Status.PROCESSING;
+
+                        if (this._definition.behavior === 'sync') {
+                            // in case we have to wait for the result
+                            await this.callStepHandler(this._definition, targetScope);
+                        } else {
+                            // in case we don't have to wait for the result
+                            this.callStepHandler(this._definition, targetScope);
                         }
 
-                        const syncSteps = this.syncSteps.filter(params?.filter || (() => true));
-                        const asyncSteps = this.asyncSteps.filter(params?.filter || (() => true));
-
-                        // Run sync _steps
-                        await Promise
-                            .all([
-
-                                // Run async _steps that are independent of each other
-                                ...asyncSteps.map(step => this.callStepHandler(step, scope)),
-
-                                // Run sync _steps that are dependent on each other
-                                new Promise<void>(
-                                    async (r, j) => {
-                                        try {
-                                            for (const step of syncSteps) {
-                                                // console.log(' - -> Processing stage step:', step.handler, ' with Regexp: ', step.name);
-
-                                                await this.callStepHandler(step, scope);
-
-                                                // console.log(' - -> Finished processing stage step:', step.handler);
-                                            }
-
-                                            return r();
-                                        } catch (error) {
-
-                                            return j(error);
-                                        }
-                                    }
-                                )
-                            ]);
-
                         this.completed();
 
                         return resolve();
                     } catch (error) {
-                        this.failed(error);
+                        const wrappedError = new A_Error(error as any);
 
-                        return reject(error);
+                        this.failed(wrappedError);
+
+
+                        if (this._definition.throwOnError) {
+                            return resolve();
+                        } else {
+                            return reject(wrappedError);
+                        }
                     }
                 });
 
-
-        return this.processed;
+        return this._processed;
     }
 
 
@@ -304,7 +247,7 @@ export class A_Stage {
     // ==========================================
 
     protected completed() {
-        this.status = A_TYPES__A_Stage_Status.COMPLETED;
+        this._status = A_TYPES__A_Stage_Status.COMPLETED;
     }
 
     protected failed(
@@ -312,7 +255,7 @@ export class A_Stage {
     ) {
         this._error = error;
 
-        this.status = A_TYPES__A_Stage_Status.FAILED;
+        this._status = A_TYPES__A_Stage_Status.FAILED;
     }
 
 
@@ -324,7 +267,7 @@ export class A_Stage {
      * Serializes the stage to JSON
      * 
      */
-    toJSON(): A_TYPES__A_Stage_JSON {
+    toJSON(): A_TYPES__Stage_Serialized {
         return {
             name: this.name,
             status: this.status,
@@ -337,21 +280,6 @@ export class A_Stage {
      * @returns 
      */
     toString() {
-        return [
-            this._feature.name,
-            '::a-stage:',
-            '[sync:',
-            this
-                .syncSteps
-                .map(s => typeof s.component === 'string' ? s.component : s.component.name + '.' + s.handler)
-                .join(' -> '),
-            ']',
-            '[async:',
-            this
-                .asyncSteps
-                .map(s => typeof s.component === 'string' ? s.component : s.component.name + '.' + s.handler)
-                .join(' -> '),
-            ']'
-        ].join('');
+        return `A-Stage(${this._feature.name}::${this._definition.behavior}@${this._definition.handler})`;
     }
 }   

package/src/global/A-Stage/A-Stage.types.ts

@@ -1,6 +1,5 @@
 import { A_Container } from "../A-Container/A-Container.class"
 import { A_TYPES__Component_Constructor } from "../A-Component/A-Component.types"
-import { A_TYPES__FeatureExtendDecoratorBehaviorConfig } from "../A-Feature/A-Feature.types"
 
 
 
@@ -43,6 +42,8 @@ export enum A_TYPES__A_Stage_Status {
     ABORTED = 'ABORTED'
 }
 
+export type A_TYPES_StageExecutionBehavior = 'async' | 'sync'
+
 
 export type A_TYPES__A_StageStep = {
     /**
@@ -61,11 +62,41 @@ export type A_TYPES__A_StageStep = {
      */
     name: string,
 
-} & A_TYPES__FeatureExtendDecoratorBehaviorConfig
+    /**
+     * In case its async it will be executed independently from the main thread.
+     * 
+     * [!] However, in case of sync, it will be executed in the main thread.in the order of the declaration.
+     * 
+     */
+    behavior: A_TYPES_StageExecutionBehavior
+
+    /**
+     * Allows to define the order of the execution of the method.
+     * 
+     * [!] In case the method has circular dependencies it will Throw an error.
+     * 
+     */
+    before: string[]
+
+    /**
+     * Allows to define the order of the execution of the method.
+     * 
+     * [!] In case the method has circular dependencies it will Throw an error.
+     * 
+     */
+    after: string[],
+
+    /**
+     * Indicates whether to throw an error if the step fails.
+     * 
+     * [!] By default is true
+     */
+    throwOnError: boolean
+}
 
 
 
-export type A_TYPES__A_Stage_JSON = {
+export type A_TYPES__Stage_Serialized = {
 
     /**
      * The name of the stage

package/src/{helpers/A_StepsManager.class.ts → global/A-StepManager/A-StepManager.class.ts}

@@ -1,8 +1,8 @@
-import { A_Error } from "../global/A-Error/A_Error.class";
-import { A_Feature } from "../global/A-Feature/A-Feature.class";
-import { A_TYPES__FeatureDefineDecoratorTemplateItem } from "../global/A-Feature/A-Feature.types";
-import { A_Stage } from "../global/A-Stage/A-Stage.class";
-import { A_TYPES__A_StageStep } from "../global/A-Stage/A-Stage.types";
+import { A_Feature } from "../A-Feature/A-Feature.class";
+import { A_TYPES__FeatureDefineDecoratorTemplateItem } from "../A-Feature/A-Feature.types";
+import { A_Stage } from "../A-Stage/A-Stage.class";
+import { A_TYPES__A_StageStep } from "../A-Stage/A-Stage.types";
+import { A_StepManagerError } from "./A-StepManager.error";
 
 export class A_StepsManager {
 
@@ -13,6 +13,8 @@ export class A_StepsManager {
     public sortedEntities: string[];
 
 
+    private _isBuilt: boolean = false;
+
     constructor(entities: Array<A_TYPES__FeatureDefineDecoratorTemplateItem>) {
         this.entities = this.prepareSteps(entities);
 
@@ -29,10 +31,11 @@ export class A_StepsManager {
         return entities.map(step => {
             return {
                 ...step,
-                
+
                 behavior: step.behavior || 'sync',
                 before: step.before || [],
                 after: step.after || [],
+                throwOnError: false
             };
         });
     }
@@ -42,6 +45,8 @@ export class A_StepsManager {
     }
 
     private buildGraph() {
+        if (this._isBuilt) return;
+        this._isBuilt = true;
         // Initialize graph nodes
         this.entities.forEach(entity => this.graph.set(this.ID(entity), new Set()));
 
@@ -54,7 +59,7 @@ export class A_StepsManager {
             // If entity should execute before targets, then targets depend on entity
             // So we add edges: target -> entity (target depends on entity)
             before.forEach(dep => {
-                const targets = this.matchEntities(dep);
+                const targets = this.matchEntities(entityId, dep);
                 targets.forEach(target => {
                     if (!this.graph.has(target)) this.graph.set(target, new Set());
                     this.graph.get(target)!.add(entityId); // target depends on entity
@@ -65,7 +70,7 @@ export class A_StepsManager {
             // If entity should execute after sources, then entity depends on sources
             // So we add edges: entity -> source (entity depends on source)
             after.forEach(dep => {
-                const sources = this.matchEntities(dep);
+                const sources = this.matchEntities(entityId, dep);
 
                 sources.forEach(source => {
                     if (!this.graph.has(entityId)) this.graph.set(entityId, new Set());
@@ -76,28 +81,51 @@ export class A_StepsManager {
     }
 
     // Match entities by name or regex
-    private matchEntities(pattern: string): string[] {
-        const regex = new RegExp(`^${pattern}$`);
+    private matchEntities(entityId: string, pattern: string): string[] {
+        const regex = new RegExp(pattern);
+
         return this.entities
-            .filter(entity => regex.test(this.ID(entity)))
+            .filter(entity => regex.test(this.ID(entity)) && this.ID(entity) !== entityId)
             .map(entity => this.ID(entity));
     }
 
     // Topological sort with cycle detection
     private visit(node: string): void {
-        if (this.tempMark.has(node)) throw new A_Error("Circular dependency detected");
+        if (this.tempMark.has(node)) {
+            return;
+            // TODO: maybe we have to keep this error but only for partial cases
+            throw new A_StepManagerError(
+                A_StepManagerError.CircularDependencyError,
+                `Circular dependency detected involving step: ${node}. Make sure that your 'before' and 'after' dependencies do not create cycles.`
+            );
+        }
 
         if (!this.visited.has(node)) {
             this.tempMark.add(node);
+
+
             (this.graph.get(node) || []).forEach(neighbor => this.visit(neighbor));
             this.tempMark.delete(node);
             this.visited.add(node);
             this.sortedEntities.push(node);
+
+            // // Visit neighbors in stable order (preserving original order)
+            // const neighbors = Array.from(this.graph.get(node) || []);
+            // // neighbors.sort((a, b) => {
+            // //     const orderA = this.originalOrder.get(a) || 0;
+            // //     const orderB = this.originalOrder.get(b) || 0;
+            // //     return orderA - orderB;
+            // // });
+
+            // neighbors.forEach(neighbor => this.visit(neighbor));
+            // this.tempMark.delete(node);
+            // this.visited.add(node);
+            // this.sortedEntities.push(node);
         }
     }
 
-    // Sort the entities based on dependencies
-    toStages(feature: A_Feature): Array<A_Stage> {
+
+    toSortedArray(): Array<string> {
         this.buildGraph();
 
         // Start topological sort
@@ -105,87 +133,25 @@ export class A_StepsManager {
             if (!this.visited.has(this.ID(entity))) this.visit(this.ID(entity));
         });
 
-        const stages: A_TmpStage[] = [];
-
-        // Map sorted names back to entity objects
-        this.sortedEntities
-            .map(id => {
-                const step = this.entities.find(entity => this.ID(entity) === id)!;
-
-                let stage = stages.find(stage => {
-                    return stage.after.every(after => step.after.includes(after))
-                        && step.before.every(before => stage.after.includes(before));
-                });
-
-
-                if (!stage) {
-                    stage = new A_TmpStage();
-                    stages.push(stage);
-                }
-
-                stage.add(step);
-            });
-
-        return stages.map(stage => new A_Stage(feature, stage.steps));
-    }
-}
-
-
-
-
-
-export class A_TmpStage {
-
-    readonly name: string = 'A_TmpStage';
-
-    private readonly _steps!: A_TYPES__A_StageStep[];
-
-    constructor(
-        _steps: A_TYPES__A_StageStep[] = []
-    ) {
-        this._steps = _steps;
+        return this.sortedEntities;
     }
 
+    // Sort the entities based on dependencies
+    toStages(feature: A_Feature): Array<A_Stage> {
 
-    get before(): string[] {
-        return this._steps.reduce((acc, step) => ([
-            ...acc,
-            ...step.before
-        ]), [] as string[]);
-    }
 
-    get after(): string[] {
-        return this._steps.reduce((acc, step) => ([
-            ...acc,
-            ...step.after
-        ]), [] as string[]);
-    }
+        const sortedNames = this.toSortedArray();
 
-    get steps(): A_TYPES__A_StageStep[] {
-        return this._steps;
-    }
 
+        // Map sorted names back to entity objects
+        return sortedNames
+            .map(id => {
+                const step = this.entities.find(entity => this.ID(entity) === id)!;
 
-    get asyncSteps(): A_TYPES__A_StageStep[] {
-        return this._steps.filter(step => step.behavior === 'async');
-    }
 
-    get syncSteps(): A_TYPES__A_StageStep[] {
-        return this._steps.filter(step => step.behavior === 'sync');
+                return new A_Stage(feature, step);
+            });
     }
+}
 
 
-    /**
-     * Adds a step to the stage
-     * 
-     * @param step 
-     * @returns 
-     */
-    add(
-        step: A_TYPES__A_StageStep
-    ): this {
-        this._steps.push(step);
-
-        return this;
-    }
-}

package/src/global/A-StepManager/A-StepManager.error.ts

@@ -0,0 +1,10 @@
+import { A_Error } from "../A-Error/A_Error.class";
+
+
+
+export class A_StepManagerError extends A_Error {
+
+
+    static readonly CircularDependencyError = 'A-StepManager Circular Dependency Error';
+
+}