@adaas/a-utils 0.1.17 → 0.1.19

package/src/lib/A-Operation/A-Operation.context.ts

@@ -0,0 +1,58 @@
+import { A_Error, A_Fragment } from "@adaas/a-concept";
+import { A_Operation_Serialized, A_Operation_Storage } from "./A-Operation.types";
+
+export class A_OperationContext<
+    _AllowedOperations extends string = string,
+    _ParamsType extends Record<string, any> = Record<string, any>,
+    _ResultType = any,
+    _StorageType extends A_Operation_Storage<_ResultType, _ParamsType> = A_Operation_Storage<_ResultType, _ParamsType>
+> extends A_Fragment<
+    _StorageType,
+    A_Operation_Serialized<_ResultType, _ParamsType>
+> {
+
+    constructor(
+        operation: _AllowedOperations,
+        params?: _ParamsType
+    ) {
+        super();
+
+        this.meta.set('name', operation);
+        this.meta.set('params', params || {} as _ParamsType);
+    }
+
+    get name(): _AllowedOperations {
+        return (this._meta.get('name') || this._name) as _AllowedOperations;
+    }
+
+    get result(): _ResultType | undefined {
+        return this._meta.get('result');
+    }
+
+    get error(): A_Error | undefined {
+        return this._meta.get('error');
+    }
+
+    get params(): _ParamsType {
+        return this._meta.get('params') || {} as _ParamsType;
+    }
+
+
+    fail(error: A_Error): void {
+        this._meta.set('error', error);
+    }
+
+    succeed(result: _ResultType): void {
+        this._meta.set('result', result);
+    }
+
+
+    toJSON(): A_Operation_Serialized<_ResultType, _ParamsType> {
+        return {
+            name: this.name,
+            params: this.params,
+            result: this.result || {} as _ResultType,
+            error: this.error?.toJSON(),
+        }
+    }
+}

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

@@ -0,0 +1,47 @@
+import { A_Error, A_TYPES__Error_Serialized } from "@adaas/a-concept"
+
+
+export type A_Operation_Storage<
+    _Result_type extends any = any,
+    _ParamsType extends Record<string, any> = Record<string, any>,
+> = {
+    /**
+     * The name of the operation
+     */
+    name: string,
+    /**
+     * The parameters for the operation
+     */
+    params: _ParamsType,
+    /**
+     * The result of the operation
+     */
+    result: _Result_type,
+    /**
+     * Any error that occurred during the operation
+     */
+    error?: A_Error
+}
+
+
+export type A_Operation_Serialized<
+    _Result_type extends any = any,
+    _ParamsType extends Record<string, any> = Record<string, any>,
+> = {
+    /**
+     * The name of the operation
+     */
+    name: string,
+    /**
+     * The parameters for the operation
+     */
+    params: _ParamsType,
+    /**
+     * The result of the operation
+     */
+    result: _Result_type,
+    /**
+     * Any error that occurred during the operation
+     */
+    error?: A_TYPES__Error_Serialized,
+}

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

@@ -0,0 +1,258 @@
+import { A_Component, A_Context, A_Feature, A_FormatterHelper, A_Scope } from "@adaas/a-concept";
+import { A_StateMachineError } from "./A-StateMachine.error";
+import { A_StateMachineFeatures } from "./A-StateMachine.constants";
+import { A_StateMachineTransition } from "./A-StateMachineTransition.context";
+
+/**
+ * A_StateMachine is a powerful state machine implementation that allows you to define and manage
+ * complex state transitions with validation, hooks, and error handling.
+ * 
+ * @template T - A record type defining the state transitions and their associated data types.
+ *               Each key represents a state name, and the value represents the data type for that state.
+ * 
+ * @example
+ * ```typescript
+ * interface OrderStates {
+ *   pending: { orderId: string };
+ *   processing: { orderId: string; processedBy: string };
+ *   completed: { orderId: string; completedAt: Date };
+ *   cancelled: { orderId: string; reason: string };
+ * }
+ * 
+ * class OrderStateMachine extends A_StateMachine<OrderStates> {
+ *   // Define custom transition logic
+ *   async pending_processing(scope: A_Scope) {
+ *     const operation = scope.resolve(A_StateMachineTransition)!;
+ *     const { orderId } = operation.props;
+ *     // Custom validation and business logic
+ *   }
+ * }
+ * ```
+ */
+export class A_StateMachine<
+    T extends Record<string, any> = Record<string, any>
+> extends A_Component {
+
+    /**
+     * Internal promise that tracks the initialization state of the state machine.
+     * Used to ensure the state machine is properly initialized before allowing transitions.
+     */
+    protected _initialized?: Promise<void>;
+
+    /**
+     * Gets a promise that resolves when the state machine is fully initialized and ready for transitions.
+     * This ensures that all initialization hooks have been executed before allowing state transitions.
+     * 
+     * @returns Promise<void> that resolves when initialization is complete
+     * 
+     * @example
+     * ```typescript
+     * const stateMachine = new MyStateMachine();
+     * await stateMachine.ready; // Wait for initialization
+     * await stateMachine.transition('idle', 'running');
+     * ```
+     */
+    get ready(): Promise<void> {
+        if (!this._initialized) {
+            this._initialized = this.call(A_StateMachineFeatures.onInitialize);
+        }
+
+        return this._initialized;
+    }
+
+
+
+    /**
+     * Initialization hook that runs when the state machine is first created.
+     * This method can be extended to add custom initialization logic.
+     * 
+     * @param args - Variable arguments passed during initialization
+     * @returns Promise<void>
+     * 
+     * @example
+     * ```typescript
+     * class MyStateMachine extends A_StateMachine {
+     *   @A_Feature.Extend()
+     *   async [A_StateMachineFeatures.onInitialize]() {
+     *     // Custom initialization logic
+     *     console.log('State machine initialized');
+     *   }
+     * }
+     * ```
+     */
+    @A_Feature.Extend()
+    async [A_StateMachineFeatures.onInitialize](...args: any[]): Promise<void> {
+        // Initialization logic can be added here
+    }
+
+    /**
+     * Hook that runs before any state transition occurs.
+     * Use this to add validation, logging, or preparation logic that should run for all transitions.
+     * 
+     * @param args - Variable arguments, typically includes the transition scope
+     * @returns Promise<void>
+     * 
+     * @example
+     * ```typescript
+     * class MyStateMachine extends A_StateMachine {
+     *   @A_Feature.Extend()
+     *   async [A_StateMachineFeatures.onBeforeTransition](scope: A_Scope) {
+     *     const operation = scope.resolve(A_StateMachineTransition)!;
+     *     console.log(`Transitioning from ${operation.props.from} to ${operation.props.to}`);
+     *   }
+     * }
+     * ```
+     */
+    @A_Feature.Extend()
+    async [A_StateMachineFeatures.onBeforeTransition](...args: any[]): Promise<void> {
+
+    }
+
+    /**
+     * Hook that runs after a successful state transition.
+     * Use this to add cleanup, logging, or post-transition logic that should run for all transitions.
+     * 
+     * @param args - Variable arguments, typically includes the transition scope
+     * @returns Promise<void>
+     * 
+     * @example
+     * ```typescript
+     * class MyStateMachine extends A_StateMachine {
+     *   @A_Feature.Extend()
+     *   async [A_StateMachineFeatures.onAfterTransition](scope: A_Scope) {
+     *     const operation = scope.resolve(A_StateMachineTransition)!;
+     *     console.log(`Successfully transitioned to ${operation.props.to}`);
+     *   }
+     * }
+     * ```
+     */
+    @A_Feature.Extend()
+    async [A_StateMachineFeatures.onAfterTransition](...args: any[]): Promise<void> {
+
+    }
+
+    /**
+     * Error handling hook that runs when a transition fails.
+     * Use this to add custom error handling, logging, or recovery logic.
+     * 
+     * @param args - Variable arguments, typically includes the error scope
+     * @returns Promise<void>
+     * 
+     * @example
+     * ```typescript
+     * class MyStateMachine extends A_StateMachine {
+     *   @A_Feature.Extend()
+     *   async [A_StateMachineFeatures.onError](scope: A_Scope) {
+     *     const error = scope.resolve(A_StateMachineError);
+     *     console.error('Transition failed:', error?.message);
+     *   }
+     * }
+     * ```
+     */
+    @A_Feature.Extend()
+    async [A_StateMachineFeatures.onError](...args: any[]): Promise<void> {
+        // Default error handling logic can be added here
+    }
+
+
+
+    /**
+     * Executes a state transition from one state to another.
+     * This is the core method of the state machine that handles the complete transition lifecycle.
+     * 
+     * @param from - The state to transition from (must be a key of T)
+     * @param to - The state to transition to (must be a key of T)
+     * @param props - Optional properties to pass to the transition context (should match T[keyof T])
+     * @returns Promise<void> that resolves when the transition is complete
+     * 
+     * @throws {A_StateMachineError} When the transition fails for any reason
+     * 
+     * @example
+     * ```typescript
+     * interface OrderStates {
+     *   pending: { orderId: string };
+     *   processing: { orderId: string; processedBy: string };
+     * }
+     * 
+     * const orderMachine = new A_StateMachine<OrderStates>();
+     * 
+     * // Transition with props
+     * await orderMachine.transition('pending', 'processing', {
+     *   orderId: '12345',
+     *   processedBy: 'user-456'
+     * });
+     * ```
+     * 
+     * The transition process follows this lifecycle:
+     * 1. Wait for state machine initialization (ready)
+     * 2. Create transition name in camelCase format (e.g., "pending_processing")
+     * 3. Create operation context with transition data
+     * 4. Create isolated scope for the transition
+     * 5. Call onBeforeTransition hook
+     * 6. Execute the specific transition method (if defined)
+     * 7. Call onAfterTransition hook
+     * 8. Clean up scope and return result
+     * 
+     * If any step fails, the onError hook is called and a wrapped error is thrown.
+     */
+    async transition(
+        /**
+         * The state to transition from
+         */
+        from: keyof T,
+        /**
+         * The state to transition to
+         */
+        to: keyof T,
+        /**
+         * Optional properties to pass to the transition context
+         */
+        props?: T[keyof T]
+    ): Promise<void> {
+
+        await this.ready;
+
+        const transitionName = `${A_FormatterHelper.toCamelCase(String(from))}_${A_FormatterHelper.toCamelCase(String(to))}`;
+
+        const transition = new A_StateMachineTransition({
+            from: String(from),
+            to: String(to),
+            props
+        });
+
+        const scope = new A_Scope({
+            name: `A-StateMachine-Transition-Scope-${transitionName}`,
+            fragments: [transition]
+        });
+
+        try {
+
+            await this.call(A_StateMachineFeatures.onBeforeTransition, scope);
+
+            await this.call(transitionName, scope);
+
+            await this.call(A_StateMachineFeatures.onAfterTransition, scope);
+
+            scope.destroy();
+
+            return transition.result;
+
+        } catch (error) {
+            const wrappedError = new A_StateMachineError({
+                title: A_StateMachineError.TransitionError,
+                description: `An error occurred while transitioning to "${transitionName}"`,
+                originalError: error
+            });
+
+            scope.register(wrappedError);
+
+            await this.call(A_StateMachineFeatures.onError, scope);
+
+            scope.destroy();
+
+            throw wrappedError;
+        }
+    }
+}
+
+

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

@@ -0,0 +1,18 @@
+export enum A_StateMachineFeatures {
+    /**
+     * Allows to extend error handling logic and behavior
+     */
+    onError = 'onError',
+    /**
+     * Allows to extend initialization logic and behavior
+     */
+    onInitialize = 'onInitialize',
+    /**
+     * Allows to extend transition validation logic and behavior
+     */
+    onBeforeTransition = 'onBeforeTransition',
+    /**
+     * Allows to extend post-transition logic and behavior
+     */
+    onAfterTransition = 'onAfterTransition',
+}

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

@@ -0,0 +1,10 @@
+import { A_Error } from "@adaas/a-concept";
+
+
+export class A_StateMachineError extends A_Error {
+
+    static readonly InitializationError = 'A-StateMachine Initialization Error';
+
+    static readonly TransitionError = 'A-StateMachine Transition Error';
+    
+}

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

@@ -0,0 +1,20 @@
+import { A_Operation_Storage } from "../A-Operation/A-Operation.types";
+
+
+export type A_StateMachineTransitionParams<
+    T = any
+> = {
+    from: string;
+    to: string;
+    props?: T
+}
+
+
+
+export type A_StateMachineTransitionStorage<
+    _ResultType extends any = any,
+    _ParamsType extends any = any
+> = {
+    from: string,
+    to: string
+} & A_Operation_Storage<_ResultType, A_StateMachineTransitionParams<_ParamsType>>

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

@@ -0,0 +1,41 @@
+import { A_OperationContext } from "../A-Operation/A-Operation.context";
+import { A_StateMachineTransitionParams, A_StateMachineTransitionStorage } from "./A-StateMachine.types";
+
+
+
+export class A_StateMachineTransition<
+    _ParamsType = any,
+    _ResultType = any
+> extends A_OperationContext<
+    'a-state-machine-transition',
+    A_StateMachineTransitionParams<_ParamsType>,
+    _ResultType,
+    A_StateMachineTransitionStorage<_ResultType, _ParamsType>
+> {
+
+
+    constructor(
+        params: A_StateMachineTransitionParams<_ParamsType>
+    ) {
+        super(
+            'a-state-machine-transition',
+            params
+        );
+
+        this._meta.set('from', params.from);
+        this._meta.set('to', params.to);
+    }
+
+
+
+    get from(): string {
+        return this._meta.get('from')!;
+    }
+
+
+
+    get to(): string {
+        return this._meta.get('to')!;
+    }
+
+}