@adaas/a-concept 0.1.17 → 0.1.19

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

@@ -1,4 +1,4 @@
-import { A_TYPES__A_StageStep } from "../A-Stage/A-Stage.types"
+import { A_TYPES__A_StageStep, A_TYPES_StageExecutionBehavior } from "../A-Stage/A-Stage.types"
 import { A_Fragment } from "../A-Fragment/A-Fragment.class"
 import { A_Entity } from "@adaas/a-concept/global/A-Entity/A-Entity.class"
 import { A_Container } from "../A-Container/A-Container.class"
@@ -206,23 +206,11 @@ export type A_TYPES__FeatureExtendDecoratorDescriptor =
  * [!] Can be applied only on A-Components
  */
 export type A_TYPES__FeatureExtendDecoratorTarget = A_Component
-/**
- * Meta type for A_Extend decorator
- */
-export type A_TYPES__FeatureExtendDecoratorMeta = {
-    /**
-     * Original Feature Extension name
-     * 
-     * [!] could be string or regex
-     */
-    name: string,
-    /**
-     * Actual method name in the class
-     */
-    handler: string
-} & A_TYPES__FeatureExtendDecoratorBehaviorConfig
+
 /**
  * Configuration type for A_Extend decorator
+ * 
+ * This is an INPUT parameter provided by the user
  */
 export type A_TYPES__FeatureExtendDecoratorConfig = {
     /**
@@ -253,7 +241,54 @@ export type A_TYPES__FeatureExtendDecoratorConfig = {
      * ```
      */
     scope: Array<A_TYPES__FeatureExtendDecoratorScopeItem> | Partial<A_TYPES__FeatureExtendDecoratorScopeConfig>,
-} & A_TYPES__FeatureExtendDecoratorBehaviorConfig
+    /**
+     * The behavior of the method. 
+     * 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.
+     * 
+     * [!] It applies for the following structure :'Component.methodName'
+     * [!] In case the method has circular dependencies it will Throw an error.
+     * 
+     * Example:
+     * ```ts
+     *  @A_Feature.Extend({
+     *      name: 'load',
+     *      before: ['Component1.methodName', /Component2\..+/]
+     *  })
+     * ```
+     */
+    before: Array<string | RegExp>
+
+    /**
+     * Allows to define the order of the execution of the method.
+     * 
+     * [!] It applies for the following structure :'Component.methodName'
+     * [!] In case the method has circular dependencies it will Throw an error.
+     * 
+     * Example:
+     * ```ts
+     *  @A_Feature.Extend({
+     *      name: 'load',
+     *      before: ['Component1.methodName', /Component2\..+/]
+     *  })
+     * ```
+     * 
+     */
+    after: Array<string | RegExp>
+
+    /**
+     * Indicates whether to throw an error if the step fails.
+     * 
+     * [!] By default is true
+     */
+    throwOnError: boolean
+}
 /**
  * Scope item that can be used in A_Extend decorator configuration
  */
@@ -270,13 +305,29 @@ export type A_TYPES__FeatureExtendDecoratorScopeConfig = {
 /**
  * A single item that can be used in scope configuration
  */
-export type A_TYPES__FeatureExtendDecoratorScopeItem = { new(...args: any[]): A_Container }
-    | { new(...args: any[]): A_Entity }
-    | { new(...args: any[]): A_Component }
+export type A_TYPES__FeatureExtendDecoratorScopeItem = A_TYPES__Container_Constructor
+    | A_TYPES__Entity_Constructor
+    | A_TYPES__Component_Constructor
+
+
+
+// =======================================================================
+// --------------------------META TYPES-----------------------------------
+// =======================================================================
 /**
- * Behavior configuration for A_Extend decorator
+ * Meta type for A_Extend decorator
  */
-export type A_TYPES__FeatureExtendDecoratorBehaviorConfig = {
+export type A_TYPES__FeatureExtendDecoratorMeta = {
+    /**
+     * Original Feature Extension name
+     * 
+     * [!] could be string or regex
+     */
+    name: string,
+    /**
+     * Actual method name in the class
+     */
+    handler: string
     /**
      * The behavior of the method. 
      * In case its async it will be executed independently from the main thread.
@@ -284,9 +335,7 @@ export type A_TYPES__FeatureExtendDecoratorBehaviorConfig = {
      * [!] However, in case of sync, it will be executed in the main thread.in the order of the declaration.
      * 
      */
-    behavior: 'async' | 'sync'
-
-
+    behavior: A_TYPES_StageExecutionBehavior
     /**
      * Allows to define the order of the execution of the method.
      * 
@@ -294,7 +343,6 @@ export type A_TYPES__FeatureExtendDecoratorBehaviorConfig = {
      * 
      */
     before: string[]
-
     /**
      * Allows to define the order of the execution of the method.
      * 
@@ -302,13 +350,12 @@ export type A_TYPES__FeatureExtendDecoratorBehaviorConfig = {
      * 
      */
     after: string[]
+    /**
+     * Indicates whether to throw an error if the step fails.
+     * 
+     * [!] By default is true
+     */
+    throwOnError: boolean
 }
 
 
-
-
-
-
-
-
-

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