@adaas/a-concept 0.1.29 → 0.1.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaas/a-concept",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "description": "A-Concept is a framework to build new Applications within or outside the ADAAS ecosystem. This framework is designed to be modular structure regardless environment and program goal.",
   "license": "Apache-2.0",
   "main": "./dist/index.cjs",

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

@@ -1,62 +1,317 @@
+import { A_TYPES__DeepPartial } from "@adaas/a-concept/types/A_Common.types";
 import { A_Meta } from "../A-Meta/A-Meta.class";
-import { A_TYPES__Fragment_Init } from "./A-Fragment.types";
-
+import { A_TYPES__Fragment_Init, A_TYPES__Fragment_Serialized } from "./A-Fragment.types";
 
 
+/**
+ * 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')}`
+ *     };
+ *   }
+ * }
+ * ```
+ */
 export class A_Fragment<
-    _MemoryItems extends Record<string, any> = any
+    _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> = new A_Meta<_MemoryItems>();
+    protected _meta: A_Meta<_MetaItems> = new 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> = {}) {
-        /**
-         * Register the Namespace in the global Namespace provider
-         */
-        this.name = params.name || this.constructor.name;
+        this._name = params.name || this.constructor.name;
+    }
+
+    /**
+     * Gets the fragment's unique name/identifier.
+     * 
+     * @returns The fragment name
+     */
+    get name(): string {
+        return this._name;
     }
 
     /**
-     * Returns the Meta object that allows to store data in the Fragment memory
+     * 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();
+     * ```
      */
-    get memory(): A_Meta<_MemoryItems> {
+    get meta(): A_Meta<_MetaItems> {
         return this._meta;
     }
 
+    /**
+     * 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 {
+        return this._meta.has(param);
+    }
+
+    /**
+     * 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 {
+        return this._meta.get(param);
+    }
+
+    /**
+     * 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 {
+        this._meta.set(param, value);
+    }
+
+    /**
+     * 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 {
+        this._meta.delete(param);
+    }
+
+    /**
+     * 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 {
+        this._meta.clear();
+    }
+
+    /**
+     * 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 {
+        return this._meta.size();
+    }
+
+    /**
+     * 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)[] {
+        return this._meta.toArray().map(([key]) => key);
+    }
+
+    /**
+     * 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 {
+        Object.entries(data).forEach(([key, value]) => {
+            if (value !== undefined) {
+                this._meta.set(key as keyof _MetaItems, value);
+            }
+        });
+    }
 
+    /**
+     * 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> {
+        const cloned = new (this.constructor as any)({ 
+            name: newName || `${this._name}_copy` 
+        });
+        
+        // Copy all meta data
+        this._meta.toArray().forEach(([key, value]) => {
+            cloned.set(key, value);
+        });
+        
+        return cloned;
+    }
 
 
     /**
-     * Returns the JSON representation of the Fragment
+     * 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
      * 
-     * @returns 
+     * @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(): _MemoryItems & { name: string } {
-        return {
+    toJSON(): _SerializedType {
+        const result = {
             name: this.name,
-            ...this.memory.toArray().reduce((acc, [key, value]) => {
+
+            ...this.meta.toArray().reduce((acc, [key, value]) => {
                 acc[key] = value;
                 return acc;
-            }, {} as _MemoryItems)
+            }, {} as _MetaItems)
         };
-    }
 
+        return result as unknown as _SerializedType;
+    }
 }

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

@@ -20,9 +20,9 @@ export type A_TYPES__Fragment_Init = {
  */
 export type A_TYPES__Fragment_Serialized = {
     /**
-     * The ASEID of the fragment
+     * The Name of the fragment
      */
-    aseid: string
+    name: string
 };
 
 

package/tests/A-Fragment.test.ts

@@ -0,0 +1,290 @@
+import { A_Fragment } from "@adaas/a-concept/global/A-Fragment/A-Fragment.class";
+
+jest.retryTimes(0);
+
+describe('A-Fragment Tests', () => {
+
+    it('It Should be possible to create an A_Fragment instance', async () => {
+
+        const fragment = new A_Fragment();
+
+        expect(fragment).toBeDefined();
+        expect(fragment.name).toBe('A_Fragment');
+        expect(fragment.size()).toBe(0);
+    });
+
+    it('It Should be possible to create an A_Fragment instance with custom name', async () => {
+
+        const fragment = new A_Fragment({ name: 'CustomFragment' });
+
+        expect(fragment).toBeDefined();
+        expect(fragment.name).toBe('CustomFragment');
+        expect(fragment.size()).toBe(0);
+    });
+
+    it('It Should be possible to create a typed A_Fragment instance', async () => {
+
+        const fragment = new A_Fragment<{ userId: string; role: string }>({
+            name: 'UserFragment'
+        });
+
+        expect(fragment).toBeDefined();
+        expect(fragment.name).toBe('UserFragment');
+        expect(fragment.size()).toBe(0);
+    });
+
+    it('It Should be possible to store and retrieve data from fragment meta', async () => {
+
+        const fragment = new A_Fragment<{ userId: string; role: string }>({
+            name: 'UserFragment'
+        });
+
+        fragment.set('userId', '12345');
+        fragment.set('role', 'admin');
+
+        expect(fragment.get('userId')).toBe('12345');
+        expect(fragment.get('role')).toBe('admin');
+        expect(fragment.has('userId')).toBe(true);
+        expect(fragment.has('role')).toBe(true);
+        expect(fragment.size()).toBe(2);
+    });
+
+    it('It Should be possible to check if keys exist in fragment meta', async () => {
+
+        const fragment = new A_Fragment<{ test: string; value: number }>();
+
+        expect(fragment.has('test')).toBe(false);
+        expect(fragment.has('value')).toBe(false);
+
+        fragment.set('test', 'hello');
+
+        expect(fragment.has('test')).toBe(true);
+        expect(fragment.has('value')).toBe(false);
+    });
+
+    it('It Should be possible to get all keys from fragment meta', async () => {
+
+        const fragment = new A_Fragment<{ userId: string; role: string; lastLogin: Date }>();
+
+        fragment.set('userId', '12345');
+        fragment.set('role', 'admin');
+
+        const keys = fragment.keys();
+
+        expect(keys).toContain('userId');
+        expect(keys).toContain('role');
+        expect(keys).not.toContain('lastLogin');
+        expect(keys.length).toBe(2);
+    });
+
+    it('It Should be possible to set multiple values at once', async () => {
+
+        const fragment = new A_Fragment<{ userId: string; role: string; isActive: boolean }>();
+
+        fragment.setMultiple({
+            userId: '12345',
+            role: 'admin',
+            isActive: true
+        });
+
+        expect(fragment.get('userId')).toBe('12345');
+        expect(fragment.get('role')).toBe('admin');
+        expect(fragment.get('isActive')).toBe(true);
+        expect(fragment.size()).toBe(3);
+    });
+
+    it('It Should be possible to drop specific keys from fragment meta', async () => {
+
+        const fragment = new A_Fragment<{ userId: string; role: string; temp: string }>();
+
+        fragment.set('userId', '12345');
+        fragment.set('role', 'admin');
+        fragment.set('temp', 'temporary');
+
+        expect(fragment.size()).toBe(3);
+
+        fragment.drop('temp');
+
+        expect(fragment.has('temp')).toBe(false);
+        expect(fragment.has('userId')).toBe(true);
+        expect(fragment.has('role')).toBe(true);
+        expect(fragment.size()).toBe(2);
+    });
+
+    it('It Should be possible to clear all data from fragment meta', async () => {
+
+        const fragment = new A_Fragment<{ userId: string; role: string }>();
+
+        fragment.set('userId', '12345');
+        fragment.set('role', 'admin');
+
+        expect(fragment.size()).toBe(2);
+
+        fragment.clear();
+
+        expect(fragment.size()).toBe(0);
+        expect(fragment.has('userId')).toBe(false);
+        expect(fragment.has('role')).toBe(false);
+    });
+
+    it('It Should be possible to clone a fragment with its data', async () => {
+
+        const original = new A_Fragment<{ userId: string; role: string }>({
+            name: 'OriginalFragment'
+        });
+
+        original.set('userId', '12345');
+        original.set('role', 'admin');
+
+        const clone = original.clone('ClonedFragment');
+
+        expect(clone).toBeDefined();
+        expect(clone.name).toBe('ClonedFragment');
+        expect(clone.get('userId')).toBe('12345');
+        expect(clone.get('role')).toBe('admin');
+        expect(clone.size()).toBe(2);
+
+        // Verify they are separate instances
+        clone.set('userId', '67890');
+        expect(original.get('userId')).toBe('12345');
+        expect(clone.get('userId')).toBe('67890');
+    });
+
+    it('It Should be possible to clone a fragment with auto-generated name', async () => {
+
+        const original = new A_Fragment<{ test: string }>({
+            name: 'TestFragment'
+        });
+
+        original.set('test', 'value');
+
+        const clone = original.clone();
+
+        expect(clone.name).toBe('TestFragment_copy');
+        expect(clone.get('test')).toBe('value');
+    });
+
+    it('It Should be possible to serialize a fragment to JSON', async () => {
+
+        const fragment = new A_Fragment<{ userId: string; role: string }>({
+            name: 'UserFragment'
+        });
+
+        fragment.set('userId', '12345');
+        fragment.set('role', 'admin');
+
+        const json = fragment.toJSON();
+
+        expect(json).toBeDefined();
+        expect(json.name).toBe('UserFragment');
+        expect(json.userId).toBe('12345');
+        expect(json.role).toBe('admin');
+    });
+
+    it('It Should be possible to create an inherited A_Fragment instance', async () => {
+        
+        class CustomFragment extends A_Fragment<{ sessionId: string; timestamp: number }> {
+            constructor() {
+                super({ name: 'CustomFragment' });
+            }
+
+            getSessionInfo(): string {
+                const sessionId = this.get('sessionId') || 'unknown';
+                const timestamp = this.get('timestamp') || 0;
+                return `${sessionId}-${timestamp}`;
+            }
+        }
+
+        const fragment = new CustomFragment();
+
+        expect(fragment).toBeDefined();
+        expect(fragment.name).toBe('CustomFragment');
+        expect(fragment instanceof A_Fragment).toBe(true);
+        expect(fragment instanceof CustomFragment).toBe(true);
+
+        fragment.set('sessionId', 'sess123');
+        fragment.set('timestamp', 1698765432);
+
+        expect(fragment.getSessionInfo()).toBe('sess123-1698765432');
+    });
+
+    it('It Should be possible to create a fragment with custom serialization', async () => {
+        
+        class SessionFragment extends A_Fragment<
+            { sessionId: string; timestamp: number },
+            { name: string; sessionData: string }
+        > {
+            constructor() {
+                super({ name: 'SessionFragment' });
+            }
+
+            toJSON(): { name: string; sessionData: string } {
+                const sessionId = this.get('sessionId') || 'unknown';
+                const timestamp = this.get('timestamp') || 0;
+                return {
+                    name: this.name,
+                    sessionData: `${sessionId}-${timestamp}`
+                };
+            }
+        }
+
+        const fragment = new SessionFragment();
+        fragment.set('sessionId', 'sess123');
+        fragment.set('timestamp', 1698765432);
+
+        const json = fragment.toJSON();
+
+        expect(json).toBeDefined();
+        expect(json.name).toBe('SessionFragment');
+        expect(json.sessionData).toBe('sess123-1698765432');
+        expect(json).not.toHaveProperty('sessionId');
+        expect(json).not.toHaveProperty('timestamp');
+    });
+
+    it('It Should be possible to access the underlying meta object', async () => {
+
+        const fragment = new A_Fragment<{ test: string; value: number }>();
+
+        expect(fragment.meta).toBeDefined();
+        expect(fragment.meta.size()).toBe(0);
+
+        fragment.set('test', 'hello');
+        fragment.set('value', 42);
+
+        expect(fragment.meta.size()).toBe(2);
+        expect(fragment.meta.has('test')).toBe(true);
+        expect(fragment.meta.get('test')).toBe('hello');
+    });
+
+    it('It Should handle undefined values correctly', async () => {
+
+        const fragment = new A_Fragment<{ optional?: string; required: string }>();
+
+        expect(fragment.get('optional')).toBeUndefined();
+        expect(fragment.get('required')).toBeUndefined();
+
+        fragment.set('required', 'value');
+
+        expect(fragment.get('required')).toBe('value');
+        expect(fragment.get('optional')).toBeUndefined();
+        expect(fragment.has('required')).toBe(true);
+        expect(fragment.has('optional')).toBe(false);
+    });
+
+    it('It Should handle setMultiple with undefined values correctly', async () => {
+
+        const fragment = new A_Fragment<{ a?: string; b?: number; c: boolean }>();
+
+        fragment.setMultiple({
+            a: 'test',
+            b: undefined, // Should be ignored
+            c: true
+        });
+
+        expect(fragment.has('a')).toBe(true);
+        expect(fragment.has('b')).toBe(false);
+        expect(fragment.has('c')).toBe(true);
+        expect(fragment.size()).toBe(2);
+    });
+
+});