@adaas/a-concept 0.1.28 → 0.1.30

package/dist/index.d.mts

@@ -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
      *
@@ -2172,7 +2172,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 +2227,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
      *
-     * [!] 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
+     * @param params - Initialization parameters
+     * @param params.name - Optional custom name for the fragment (defaults to class name)
+     *
+     * @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 +2489,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;
 };
 
 /**

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
      *
@@ -2172,7 +2172,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 +2227,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
      *
-     * [!] 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
+     * @param params - Initialization parameters
+     * @param params.name - Optional custom name for the fragment (defaults to class name)
+     *
+     * @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 +2489,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;
 };
 
 /**