@adaas/a-concept 0.1.29 → 0.1.31

package/dist/index.d.ts

@@ -1186,7 +1186,7 @@ declare class A_Stage {
      * @param step
      * @returns
      */
-    protected getStepArgs(scope: A_Scope, step: A_TYPES__A_StageStep): Promise<(A_Container | A_Component | A_Entity<any, A_TYPES__Entity_Serialized> | A_Scope<A_TYPES__Component_Constructor[], A_TYPES__Error_Constructor[], A_TYPES__Entity_Constructor[], A_Fragment<any>[]> | A_Feature<A_TYPES__FeatureAvailableComponents> | A_Fragment<any> | A_TYPES__ScopeResolvableComponents[] | undefined)[]>;
+    protected getStepArgs(scope: A_Scope, step: A_TYPES__A_StageStep): Promise<(A_Container | A_Component | A_Entity<any, A_TYPES__Entity_Serialized> | A_Scope<A_TYPES__Component_Constructor[], A_TYPES__Error_Constructor[], A_TYPES__Entity_Constructor[], A_Fragment<any, any>[]> | A_Feature<A_TYPES__FeatureAvailableComponents> | A_Fragment<any, any> | A_TYPES__ScopeResolvableComponents[] | undefined)[]>;
     /**
      * Resolves the component of the step
      *
@@ -1249,7 +1249,7 @@ declare class A_StageError extends A_Error {
     static get CompileError(): string;
 }
 
-declare class A_FeatureError extends A_Error {
+declare class A_FeatureError extends A_Error<A_TYPES__FeatureError_Init> {
     /**
      * Indicates that the Feature has been interrupted
      */
@@ -1260,6 +1260,12 @@ declare class A_FeatureError extends A_Error {
      * Failed during the A-Feature initialization process
      */
     static readonly FeatureInitializationError = "Unable to initialize A-Feature";
+    /**
+     * Indicates that there was an error processing the Feature
+     *
+     * Failed during the A-Feature processing
+     */
+    static readonly FeatureProcessingError = "Error occurred during A-Feature processing";
     /**
      * Indicates that there was an error defining the Feature
      *
@@ -1272,6 +1278,11 @@ declare class A_FeatureError extends A_Error {
      * Failed during the @A_Feature.Extend() decorator execution
      */
     static readonly FeatureExtensionError = "Unable to extend A-Feature";
+    /**
+     * Stage where the error occurred
+     */
+    stage?: A_Stage;
+    protected fromConstructor(params: A_TYPES__FeatureError_Init): void;
 }
 
 /**
@@ -1464,6 +1475,13 @@ declare class A_Feature<T extends A_TYPES__FeatureAvailableComponents = A_TYPES_
      * @returns
      */
     completed(): Promise<void>;
+    /**
+     * This method marks the feature as failed and throws an error
+     * Uses to mark the feature as failed
+     *
+     * @param error
+     */
+    failed(error: A_FeatureError): Promise<void>;
     /**
      * This method marks the feature as failed and throws an error
      * Uses to interrupt or end the feature processing
@@ -1558,8 +1576,18 @@ declare enum A_TYPES__FeatureState {
     /**
      * The feature has been interrupted
      */
-    INTERRUPTED = "INTERRUPTED"
+    INTERRUPTED = "INTERRUPTED",
+    /**
+     * The feature has failed
+     */
+    FAILED = "FAILED"
 }
+type A_TYPES__FeatureError_Init = {
+    /**
+     * Stage where the error occurred
+     */
+    stage?: A_Stage;
+} & A_TYPES__Error_Init;
 /**
  * A list of component where features can be Defined
  *
@@ -2172,7 +2200,7 @@ declare class A_Concept<_Imports extends A_Container[] = A_Container[]> {
     /**
      * The primary Root scope of the concept.
      */
-    get scope(): A_Scope<A_TYPES__Component_Constructor[], A_TYPES__Error_Constructor[], A_TYPES__Entity_Constructor[], A_Fragment<any>[]>;
+    get scope(): A_Scope<A_TYPES__Component_Constructor[], A_TYPES__Error_Constructor[], A_TYPES__Entity_Constructor[], A_Fragment<any, any>[]>;
     /**
      * Register a class or value in the concept scope.
      */
@@ -2227,39 +2255,250 @@ declare class A_Concept<_Imports extends A_Container[] = A_Container[]> {
     container: _Imports[number]): Promise<void>;
 }
 
-declare class A_Fragment<_MemoryItems extends Record<string, any> = any> {
+/**
+ * A_Fragment is a core architectural component that represents a singleton execution context
+ * within the A-Concept framework. It serves as a shared memory container that can be passed
+ * between Components, Entities, and Commands throughout the application pipeline.
+ *
+ * Key Features:
+ * - Singleton pattern: Only one instance per fragment type per scope
+ * - Meta storage: Built-in key-value storage for pipeline data
+ * - Type-safe: Full TypeScript generics support for meta items and serialization
+ * - Serializable: Can be converted to JSON for persistence or transmission
+ *
+ * @template _MetaItems - Type definition for the meta storage structure
+ * @template _SerializedType - Type definition for the serialized output format
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with typed meta
+ * class UserFragment extends A_Fragment<{ userId: string; role: string }> {
+ *   constructor() {
+ *     super({ name: 'UserFragment' });
+ *   }
+ * }
+ *
+ * // Custom serialization
+ * class SessionFragment extends A_Fragment<
+ *   { sessionId: string; timestamp: number },
+ *   { name: string; sessionData: string }
+ * > {
+ *   toJSON() {
+ *     return {
+ *       name: this.name,
+ *       sessionData: `${this.get('sessionId')}-${this.get('timestamp')}`
+ *     };
+ *   }
+ * }
+ * ```
+ */
+declare class A_Fragment<_MetaItems extends Record<string, any> = any, _SerializedType extends A_TYPES__Fragment_Serialized = A_TYPES__Fragment_Serialized & _MetaItems> {
     /**
-     * Fragment Name
+     * The unique identifier/name for this fragment instance.
+     * Used for identification and debugging purposes.
      */
-    name: string;
+    protected _name: string;
     /**
-     * Memory storage for the Fragment instance
+     * Internal meta storage using A_Meta for type-safe key-value operations.
+     * This stores all the fragment's runtime data that can be accessed and modified
+     * throughout the execution pipeline.
      */
-    protected _meta: A_Meta<_MemoryItems>;
+    protected _meta: A_Meta<_MetaItems>;
     /**
-     * A-Fragment is a singleton, a piece of execution Context that can be shared between the Components/Entities/Commands
-     * For every A_Scope can be defined only One A_Fragment of the same type.
-     * This class is useful for the design purpose and maintainance of the application
+     * Creates a new A_Fragment instance.
+     *
+     * A_Fragment implements the singleton pattern for execution contexts, allowing
+     * shared state management across different parts of the application pipeline.
+     * Each fragment serves as a memory container that can store typed data and be
+     * serialized for persistence or transmission.
+     *
+     * Key Benefits:
+     * - Centralized state management for related operations
+     * - Type-safe meta operations with full IntelliSense support
+     * - Serialization support for data persistence
+     * - Singleton pattern ensures consistent state within scope
      *
+     * @param params - Initialization parameters
+     * @param params.name - Optional custom name for the fragment (defaults to class name)
      *
-     * [!] Every A_Fragment is a Memory Class that can store data in memory between the steps of the pipeline.
-     * [!] So if it necessary to store some information in the Execution Context - use memory of the Fragment
+     * @example
+     * ```typescript
+     * const fragment = new A_Fragment<{ userId: string }>({
+     *   name: 'UserSessionFragment'
+     * });
+     * fragment.set('userId', '12345');
+     * ```
      */
     constructor(params?: Partial<A_TYPES__Fragment_Init>);
     /**
-     * Returns the Meta object that allows to store data in the Fragment memory
+     * Gets the fragment's unique name/identifier.
      *
-     * @returns
+     * @returns The fragment name
      */
-    get memory(): A_Meta<_MemoryItems>;
+    get name(): string;
     /**
-     * Returns the JSON representation of the Fragment
+     * Gets direct access to the underlying Meta object for advanced meta operations.
      *
-     * @returns
+     * Use this when you need to perform bulk operations or access Meta-specific methods.
+     * For simple get/set operations, prefer using the direct methods on the fragment.
+     *
+     * @returns The Meta instance containing the fragment's meta
+     *
+     * @example
+     * ```typescript
+     * const fragment = new A_Fragment<{ users: string[], count: number }>();
+     *
+     * // Advanced operations using meta
+     * fragment.meta.setMultiple({
+     *   users: ['alice', 'bob'],
+     *   count: 2
+     * });
+     *
+     * // Get all keys
+     * const keys = fragment.meta.keys();
+     * ```
      */
-    toJSON(): _MemoryItems & {
-        name: string;
-    };
+    get meta(): A_Meta<_MetaItems>;
+    /**
+     * Checks if a specific meta key exists in the fragment.
+     *
+     * @param param - The key to check for existence
+     * @returns True if the key exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (fragment.has('userId')) {
+     *   console.log('User ID is set');
+     * }
+     * ```
+     */
+    has(param: keyof _MetaItems): boolean;
+    /**
+     * Retrieves a value from the fragment's meta.
+     *
+     * @param param - The key to retrieve
+     * @returns The value associated with the key, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const userId = fragment.get('userId');
+     * if (userId) {
+     *   console.log(`Current user: ${userId}`);
+     * }
+     * ```
+     */
+    get<K extends keyof _MetaItems>(param: K): _MetaItems[K] | undefined;
+    /**
+     * Stores a value in the fragment's meta.
+     *
+     * @param param - The key to store the value under
+     * @param value - The value to store
+     *
+     * @example
+     * ```typescript
+     * fragment.set('userId', '12345');
+     * fragment.set('role', 'admin');
+     * ```
+     */
+    set<K extends keyof _MetaItems>(param: K, value: _MetaItems[K]): void;
+    /**
+     * Removes a specific key from the fragment's meta.
+     *
+     * @param param - The key to remove
+     *
+     * @example
+     * ```typescript
+     * fragment.drop('temporaryData');
+     * ```
+     */
+    drop(param: keyof _MetaItems): void;
+    /**
+     * Clears all data from the fragment's meta.
+     *
+     * Use with caution as this will remove all stored data in the fragment.
+     *
+     * @example
+     * ```typescript
+     * fragment.clear(); // All meta data is now gone
+     * ```
+     */
+    clear(): void;
+    /**
+     * Gets the number of items stored in the fragment's meta.
+     *
+     * @returns The count of stored meta items
+     *
+     * @example
+     * ```typescript
+     * console.log(`Fragment contains ${fragment.size()} items`);
+     * ```
+     */
+    size(): number;
+    /**
+     * Gets all keys currently stored in the fragment's meta.
+     *
+     * @returns Array of all meta keys
+     *
+     * @example
+     * ```typescript
+     * const keys = fragment.keys();
+     * console.log('Stored keys:', keys);
+     * ```
+     */
+    keys(): (keyof _MetaItems)[];
+    /**
+     * Sets multiple values at once in the fragment's meta.
+     *
+     * @param data - Object containing key-value pairs to set
+     *
+     * @example
+     * ```typescript
+     * fragment.setMultiple({
+     *   userId: '12345',
+     *   role: 'admin',
+     *   lastLogin: new Date()
+     * });
+     * ```
+     */
+    setMultiple(data: A_TYPES__DeepPartial<_MetaItems>): void;
+    /**
+     * Creates a shallow copy of the fragment with the same meta data.
+     *
+     * @param newName - Optional new name for the cloned fragment
+     * @returns A new fragment instance with copied meta
+     *
+     * @example
+     * ```typescript
+     * const original = new A_Fragment<{ data: string }>({ name: 'original' });
+     * original.set('data', 'test');
+     *
+     * const clone = original.clone('cloned');
+     * console.log(clone.get('data')); // 'test'
+     * ```
+     */
+    clone(newName?: string): A_Fragment<_MetaItems, _SerializedType>;
+    /**
+     * Serializes the fragment to a JSON-compatible object.
+     *
+     * This method combines the fragment's name with all meta data to create
+     * a serializable representation. The return type is determined by the
+     * _SerializedType generic parameter, allowing for custom serialization formats.
+     *
+     * @returns A serialized representation of the fragment
+     *
+     * @example
+     * ```typescript
+     * const fragment = new A_Fragment<{ userId: string, role: string }>({
+     *   name: 'UserFragment'
+     * });
+     * fragment.set('userId', '12345');
+     * fragment.set('role', 'admin');
+     *
+     * const json = fragment.toJSON();
+     * // Result: { name: 'UserFragment', userId: '12345', role: 'admin' }
+     * ```
+     */
+    toJSON(): _SerializedType;
 }
 
 /**
@@ -2278,9 +2517,9 @@ type A_TYPES__Fragment_Init = {
  */
 type A_TYPES__Fragment_Serialized = {
     /**
-     * The ASEID of the fragment
+     * The Name of the fragment
      */
-    aseid: string;
+    name: string;
 };
 
 /**
@@ -3958,4 +4197,4 @@ declare class A_TypeGuards {
     static isConstructorType<T extends A_TYPES__Error_Init>(param: any): param is T;
 }
 
-export { ASEID, ASEID_Error, A_Abstraction, A_AbstractionError, A_Abstraction_Extend, A_CONSTANTS__DEFAULT_ENV_VARIABLES, A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY, A_Caller, A_CallerError, A_CommonHelper, A_Component, A_ComponentMeta, A_Concept, A_ConceptMeta, A_Container, A_ContainerMeta, A_Context, A_Dependency, A_DependencyError, A_Dependency_Default, A_Dependency_Load, A_Dependency_Require, A_Entity, A_Error, A_Feature, A_FeatureError, A_Feature_Define, A_Feature_Extend, A_FormatterHelper, A_Fragment, type A_ID_TYPES__TimeId_Parts, A_IdentityHelper, A_Inject, A_Meta, A_Scope, A_ScopeError, A_Stage, A_StageError, A_StepManagerError, A_StepsManager, type A_TYPES_ScopeDependentComponents, type A_TYPES_ScopeIndependentComponents, type A_TYPES_StageExecutionBehavior, type A_TYPES__ASEID_Constructor, type A_TYPES__ASEID_ConstructorConfig, type A_TYPES__ASEID_JSON, type A_TYPES__A_Dependency_DefaultDecoratorReturn, type A_TYPES__A_Dependency_LoadDecoratorReturn, type A_TYPES__A_Dependency_RequireDecoratorReturn, type A_TYPES__A_InjectDecoratorDescriptor, type A_TYPES__A_InjectDecoratorReturn, type A_TYPES__A_InjectDecorator_EntityInjectionInstructions, type A_TYPES__A_InjectDecorator_EntityInjectionPagination, type A_TYPES__A_InjectDecorator_EntityInjectionQuery, type A_TYPES__A_InjectDecorator_Meta, type A_TYPES__A_StageStep, type A_TYPES__A_StageStepProcessingExtraParams, A_TYPES__A_Stage_Status, type A_TYPES__AbstractionAvailableComponents, type A_TYPES__AbstractionDecoratorConfig, type A_TYPES__AbstractionDecoratorDescriptor, type A_TYPES__Abstraction_Constructor, type A_TYPES__Abstraction_Init, type A_TYPES__Abstraction_Serialized, type A_TYPES__CallerComponent, type A_TYPES__Caller_Constructor, type A_TYPES__Caller_Init, type A_TYPES__Caller_Serialized, type A_TYPES__ComponentMeta, type A_TYPES__ComponentMetaExtension, type A_TYPES__Component_Constructor, type A_TYPES__Component_Init, type A_TYPES__Component_Serialized, type A_TYPES__ConceptAbstraction, type A_TYPES__ConceptAbstractionMeta, type A_TYPES__ConceptENVVariables, type A_TYPES__Concept_Constructor, type A_TYPES__Concept_Init, type A_TYPES__Concept_Serialized, type A_TYPES__ContainerMeta, type A_TYPES__ContainerMetaExtension, type A_TYPES__Container_Constructor, type A_TYPES__Container_Init, type A_TYPES__Container_Serialized, type A_TYPES__ContextEnvironment, type A_TYPES__DeepPartial, type A_TYPES__Dictionary, type A_TYPES__EntityMeta, type A_TYPES__Entity_Constructor, type A_TYPES__Entity_Init, type A_TYPES__Entity_Serialized, type A_TYPES__Error_Constructor, type A_TYPES__Error_Init, type A_TYPES__Error_Serialized, type A_TYPES__ExtractNested, type A_TYPES__ExtractProperties, type A_TYPES__FeatureAvailableComponents, type A_TYPES__FeatureAvailableConstructors, type A_TYPES__FeatureDefineDecoratorConfig, type A_TYPES__FeatureDefineDecoratorDescriptor, type A_TYPES__FeatureDefineDecoratorMeta, type A_TYPES__FeatureDefineDecoratorTarget, type A_TYPES__FeatureDefineDecoratorTemplateItem, type A_TYPES__FeatureExtendDecoratorConfig, type A_TYPES__FeatureExtendDecoratorDescriptor, type A_TYPES__FeatureExtendDecoratorMeta, type A_TYPES__FeatureExtendDecoratorScopeConfig, type A_TYPES__FeatureExtendDecoratorScopeItem, type A_TYPES__FeatureExtendDecoratorTarget, type A_TYPES__FeatureExtendableMeta, A_TYPES__FeatureState, type A_TYPES__Feature_Constructor, type A_TYPES__Feature_Init, type A_TYPES__Feature_InitWithComponent, type A_TYPES__Feature_InitWithTemplate, type A_TYPES__Feature_Serialized, type A_TYPES__Fragment_Constructor, type A_TYPES__Fragment_Init, type A_TYPES__Fragment_Serialized, type A_TYPES__IEntity, type A_TYPES__InjectableConstructors, type A_TYPES__InjectableTargets, type A_TYPES__MetaLinkedComponentConstructors, type A_TYPES__MetaLinkedComponents, type A_TYPES__NonObjectPaths, type A_TYPES__ObjectKeyEnum, type A_TYPES__Paths, type A_TYPES__PathsToObject, type A_TYPES__Required, type A_TYPES__ScopeConfig, type A_TYPES__ScopeLinkedComponents, type A_TYPES__ScopeLinkedConstructors, type A_TYPES__ScopeResolvableComponents, type A_TYPES__Scope_Constructor, type A_TYPES__Scope_Init, type A_TYPES__Scope_Serialized, type A_TYPES__Stage_Serialized, type A_TYPES__UnionToIntersection, A_TypeGuards };
+export { ASEID, ASEID_Error, A_Abstraction, A_AbstractionError, A_Abstraction_Extend, A_CONSTANTS__DEFAULT_ENV_VARIABLES, A_CONSTANTS__DEFAULT_ENV_VARIABLES_ARRAY, A_Caller, A_CallerError, A_CommonHelper, A_Component, A_ComponentMeta, A_Concept, A_ConceptMeta, A_Container, A_ContainerMeta, A_Context, A_Dependency, A_DependencyError, A_Dependency_Default, A_Dependency_Load, A_Dependency_Require, A_Entity, A_Error, A_Feature, A_FeatureError, A_Feature_Define, A_Feature_Extend, A_FormatterHelper, A_Fragment, type A_ID_TYPES__TimeId_Parts, A_IdentityHelper, A_Inject, A_Meta, A_Scope, A_ScopeError, A_Stage, A_StageError, A_StepManagerError, A_StepsManager, type A_TYPES_ScopeDependentComponents, type A_TYPES_ScopeIndependentComponents, type A_TYPES_StageExecutionBehavior, type A_TYPES__ASEID_Constructor, type A_TYPES__ASEID_ConstructorConfig, type A_TYPES__ASEID_JSON, type A_TYPES__A_Dependency_DefaultDecoratorReturn, type A_TYPES__A_Dependency_LoadDecoratorReturn, type A_TYPES__A_Dependency_RequireDecoratorReturn, type A_TYPES__A_InjectDecoratorDescriptor, type A_TYPES__A_InjectDecoratorReturn, type A_TYPES__A_InjectDecorator_EntityInjectionInstructions, type A_TYPES__A_InjectDecorator_EntityInjectionPagination, type A_TYPES__A_InjectDecorator_EntityInjectionQuery, type A_TYPES__A_InjectDecorator_Meta, type A_TYPES__A_StageStep, type A_TYPES__A_StageStepProcessingExtraParams, A_TYPES__A_Stage_Status, type A_TYPES__AbstractionAvailableComponents, type A_TYPES__AbstractionDecoratorConfig, type A_TYPES__AbstractionDecoratorDescriptor, type A_TYPES__Abstraction_Constructor, type A_TYPES__Abstraction_Init, type A_TYPES__Abstraction_Serialized, type A_TYPES__CallerComponent, type A_TYPES__Caller_Constructor, type A_TYPES__Caller_Init, type A_TYPES__Caller_Serialized, type A_TYPES__ComponentMeta, type A_TYPES__ComponentMetaExtension, type A_TYPES__Component_Constructor, type A_TYPES__Component_Init, type A_TYPES__Component_Serialized, type A_TYPES__ConceptAbstraction, type A_TYPES__ConceptAbstractionMeta, type A_TYPES__ConceptENVVariables, type A_TYPES__Concept_Constructor, type A_TYPES__Concept_Init, type A_TYPES__Concept_Serialized, type A_TYPES__ContainerMeta, type A_TYPES__ContainerMetaExtension, type A_TYPES__Container_Constructor, type A_TYPES__Container_Init, type A_TYPES__Container_Serialized, type A_TYPES__ContextEnvironment, type A_TYPES__DeepPartial, type A_TYPES__Dictionary, type A_TYPES__EntityMeta, type A_TYPES__Entity_Constructor, type A_TYPES__Entity_Init, type A_TYPES__Entity_Serialized, type A_TYPES__Error_Constructor, type A_TYPES__Error_Init, type A_TYPES__Error_Serialized, type A_TYPES__ExtractNested, type A_TYPES__ExtractProperties, type A_TYPES__FeatureAvailableComponents, type A_TYPES__FeatureAvailableConstructors, type A_TYPES__FeatureDefineDecoratorConfig, type A_TYPES__FeatureDefineDecoratorDescriptor, type A_TYPES__FeatureDefineDecoratorMeta, type A_TYPES__FeatureDefineDecoratorTarget, type A_TYPES__FeatureDefineDecoratorTemplateItem, type A_TYPES__FeatureError_Init, type A_TYPES__FeatureExtendDecoratorConfig, type A_TYPES__FeatureExtendDecoratorDescriptor, type A_TYPES__FeatureExtendDecoratorMeta, type A_TYPES__FeatureExtendDecoratorScopeConfig, type A_TYPES__FeatureExtendDecoratorScopeItem, type A_TYPES__FeatureExtendDecoratorTarget, type A_TYPES__FeatureExtendableMeta, A_TYPES__FeatureState, type A_TYPES__Feature_Constructor, type A_TYPES__Feature_Init, type A_TYPES__Feature_InitWithComponent, type A_TYPES__Feature_InitWithTemplate, type A_TYPES__Feature_Serialized, type A_TYPES__Fragment_Constructor, type A_TYPES__Fragment_Init, type A_TYPES__Fragment_Serialized, type A_TYPES__IEntity, type A_TYPES__InjectableConstructors, type A_TYPES__InjectableTargets, type A_TYPES__MetaLinkedComponentConstructors, type A_TYPES__MetaLinkedComponents, type A_TYPES__NonObjectPaths, type A_TYPES__ObjectKeyEnum, type A_TYPES__Paths, type A_TYPES__PathsToObject, type A_TYPES__Required, type A_TYPES__ScopeConfig, type A_TYPES__ScopeLinkedComponents, type A_TYPES__ScopeLinkedConstructors, type A_TYPES__ScopeResolvableComponents, type A_TYPES__Scope_Constructor, type A_TYPES__Scope_Init, type A_TYPES__Scope_Serialized, type A_TYPES__Stage_Serialized, type A_TYPES__UnionToIntersection, A_TypeGuards };