@adaas/are 0.0.2 → 0.0.4

package/src/lib/AreEngine/AreEngine.component.ts

@@ -0,0 +1,317 @@
+import { A_CommonHelper, A_Component, A_Context, A_Dependency, A_Feature, A_FormatterHelper, A_Inject, A_Scope, A_TYPES__A_DependencyInjectable, A_TYPES__Ctor } from "@adaas/a-concept";
+import { AreSyntax } from "@adaas/are/syntax/AreSyntax.context";
+import { A_ServiceFeatures } from "@adaas/a-utils/a-service";
+import { A_Logger } from "@adaas/a-utils/a-logger";
+import { AreCompiler } from "@adaas/are/compiler/AreCompiler.component";
+import { AreTransformer } from "@adaas/are/transformer/AreTransformer.component";
+import { AreLoader } from "@adaas/are/loader/AreLoader.component";
+import { AreInterpreter } from "@adaas/are/interpreter/AreInterpreter.component";
+import { AreEngineError } from "./AreEngine.error";
+import { AreLifecycle } from "@adaas/are/lifecycle/AreLifecycle.component";
+import { AreEngineFeatures } from "./AreEngine.constants";
+import { AreContext } from "@adaas/are/component/Are.context";
+import { A_Frame } from "@adaas/a-frame";
+import { AreTokenizer } from "@adaas/are/tokenizer/AreTokenizer.component";
+import { AreEngineDependencies } from "./AreEngine.types";
+import { AreSignals } from "@adaas/are/signals/AreSignals.component";
+import { AreInit } from "@adaas/are/signals/entities/AreInit.signal";
+import { A_SignalBus } from "@adaas/a-utils/a-signal";
+
+
+
+
+@A_Frame.Component({
+    namespace: 'A-ARE',
+    name: 'AreEngine',
+    description: 'Core rendering engine for A-Concept Rendering Engine (ARE), responsible for orchestrating the loading, building, and execution of the rendering process. It manages the lifecycle of root nodes, coordinates the interactions between syntax, transformer, loader, compiler, and interpreter components, and ensures the proper initialization and mounting of the UI application.'
+})
+export class AreEngine extends A_Component {
+
+    /**
+     * Feature decorator for the load method, which is responsible for the initial loading phase of the engine. This method is where the engine reads the source template, tokenizes it, and prepares the initial context for building the scene. The decorator allows for extending or overriding the default loading behavior by attaching additional functionality before or after the load process.
+     */
+    static get Load() {
+        return (target: any, propertyKey: string, descriptor: PropertyDescriptor) => {
+            return A_Feature.Extend({
+                name: AreEngineFeatures.Load,
+                scope: [target.constructor],
+                override: ['defaultLoad']
+            })(target, propertyKey, descriptor);
+        }
+    }
+    /**
+     * Feature decorator for the build method, which is responsible for constructing the scene based on the loaded context. This method typically involves initializing root nodes, applying transformations, and compiling the scene into a format that can be executed by the interpreter. The decorator allows for customizing the build process by adding additional steps or modifying the existing behavior.
+     */
+    static get Build() {
+        return (target: any, propertyKey: string, descriptor: PropertyDescriptor) => {
+            return A_Feature.Extend({
+                name: AreEngineFeatures.Build,
+                scope: [target.constructor],
+                override: ['defaultBuild']
+            })(target, propertyKey, descriptor);
+        }
+    }
+    /**
+     * Feature decorator for the execute method, which is responsible for the final execution phase of the engine. This method typically involves mounting the root nodes to the DOM and starting the reactive update cycle based on signals and state changes. The decorator allows for customizing the execution process by adding additional steps or modifying the existing behavior.
+     */
+    static get Execute() {
+        return (target: any, propertyKey: string, descriptor: PropertyDescriptor) => {
+            return A_Feature.Extend({
+                name: AreEngineFeatures.Execute,
+                scope: [target.constructor],
+                override: ['defaultExecute']
+            })(target, propertyKey, descriptor);
+        }
+    }
+
+
+    // ==========================================================================================
+    // -----------------------------------ARE Engine Features------------------------------------
+    // ==========================================================================================
+
+    /**
+     * Method to start the engine, which involves loading necessary resources, building the scene, and executing the rendering process. It accepts an optional scope parameter that can be used to provide a custom scope for the engine's operations, allowing for greater flexibility in how dependencies are managed and accessed during the rendering lifecycle.
+     * 
+     * @param scope 
+     * @returns 
+     */
+    @A_Frame.Method({
+        description: 'Method does engine loading, first read of the source and tokenization.'
+    })
+    async load(scope?: A_Scope) {
+        const context = scope?.resolve(AreContext) || A_Context.scope(this).resolve(AreContext);
+
+        context?.startPerformance();
+
+        await this.call(AreEngineFeatures.Load, scope || A_Context.scope(this));
+    }
+
+    /**
+     * Method responsible for building the scene, which includes initializing root nodes, loading necessary data, applying transformations, and compiling the scene into a format that can be executed by the interpreter.
+     * 
+     * @param context 
+     * @param logger 
+     */
+    @A_Frame.Method({
+        description: 'Method responsible for building the scene, which includes initializing root nodes, loading necessary data, applying transformations, and compiling the scene into a format that can be executed by the interpreter.'
+    })
+    async build(scope?: A_Scope) {
+        const context = scope?.resolve(AreContext) || A_Context.scope(this).resolve(AreContext);
+        context?.startPerformance('Build Total');
+
+        await this.call(AreEngineFeatures.Build, scope || A_Context.scope(this));
+
+        context?.endPerformance('Build Total');
+    }
+
+    /**
+     * Method responsible for executing the rendering process, which involves mounting the root nodes to the DOM and starting the reactive update cycle based on signals and state changes.
+     * 
+     * @param context 
+     * @param logger 
+     */
+    @A_Frame.Method({
+        description: 'Method responsible for executing the rendering process, which involves mounting the root nodes to the DOM and starting the reactive update cycle based on signals and state changes.'
+    })
+    async execute(scope?: A_Scope) {
+        const context = scope?.resolve(AreContext) || A_Context.scope(this).resolve(AreContext);
+
+        context?.startPerformance('Execute Total');
+
+        await this.call(AreEngineFeatures.Execute, scope || A_Context.scope(this));
+
+        context?.endPerformance('Execute Total');
+        context?.endPerformance('Total');
+    }
+
+    // ==========================================================================================
+    // ----------------------------ARE Engine Default Methods------------------------------------
+    // ==========================================================================================
+    @A_Feature.Extend({
+        name: AreEngineFeatures.Build,
+        before: /.*/
+    })
+    protected async defaultBuild(
+        @A_Dependency.Required()
+        @A_Inject(AreContext) context: AreContext,
+        @A_Inject(A_Logger) logger?: A_Logger,
+    ) {
+        logger?.debug('cyan', 'Starting to build the scene...');
+
+        for (const root of context.roots) {
+
+            context.startPerformance(`Init root <${root.aseid.id}>`);
+            root.init();
+            context.endPerformance(`Init root <${root.aseid.id}>`);
+
+            context.startPerformance(`Load root <${root.aseid.id}>`);
+            await root.load();
+            context.endPerformance(`Load root <${root.aseid.id}>`);
+
+            context.startPerformance(`Transform root <${root.aseid.id}>`);
+            root.transform();
+            context.endPerformance(`Transform root <${root.aseid.id}>`);
+
+            context.startPerformance(`Compile root <${root.aseid.id}>`);
+            root.compile();
+            context.endPerformance(`Compile root <${root.aseid.id}>`);
+
+            context.endPerformance(`Root <${root.aseid.id}> Total`);
+        }
+    }
+    @A_Feature.Extend({
+        name: AreEngineFeatures.Execute,
+        before: /.*/
+    })
+    protected async defaultExecute(
+        @A_Dependency.Required()
+        @A_Inject(AreContext) context: AreContext,
+        @A_Inject(A_SignalBus) bus?: A_SignalBus,
+        @A_Inject(A_Logger) logger?: A_Logger,
+    ) {
+        logger?.debug('cyan', 'Starting to execute the scene and mount root nodes...');
+
+        for (const root of context.roots) {
+
+            context.startPerformance(`Mount root <${root.aseid.id}>`);
+
+            root.mount();
+
+            context.endPerformance(`Mount root <${root.aseid.id}>`);
+        }
+
+        logger?.debug('cyan', 'Emitting AreInit signal to start the reactive update cycle...');
+
+        await bus?.next(new AreInit())
+    }
+
+    @A_Feature.Extend({
+        name: AreEngineFeatures.Load,
+        before: /.*/
+    })
+    async init(
+        @A_Inject(A_Scope) scope: A_Scope,
+    ) {
+        this.package(scope);
+    }
+
+    @A_Feature.Extend({
+        name: AreEngineFeatures.Load,
+        before: /.*/
+    })
+    async verify(
+        @A_Inject(A_Scope) scope: A_Scope,
+        @A_Inject(AreSyntax) syntax?: AreSyntax,
+        @A_Inject(AreSyntax) syntaxContext?: AreSyntax,
+        @A_Inject(AreTransformer) transformer?: AreTransformer,
+        @A_Inject(AreLoader) loader?: AreLoader,
+        @A_Inject(AreCompiler) compiler?: AreCompiler,
+        @A_Inject(AreInterpreter) interpreter?: AreInterpreter,
+        @A_Inject(AreLifecycle) lifecycle?: AreLifecycle,
+        @A_Inject(A_Logger) logger?: A_Logger,
+    ) {
+        if (!syntax)
+            throw new AreEngineError({
+                title: AreEngineError.MissedRequiredDependency,
+                description: `AreSyntax or its inherited variation is a required dependency for ${this.constructor.name}. Please ensure that it is registered in the container scope before starting the engine.`
+            });
+
+        if (!syntaxContext)
+            throw new AreEngineError({
+                title: AreEngineError.MissedRequiredDependency,
+                description: `AreSyntax or its inherited variation is a required dependency for ${this.constructor.name}. Please ensure that it is registered in the container scope before starting the engine.`
+            });
+
+
+        if (!loader)
+            throw new AreEngineError({
+                title: AreEngineError.MissedRequiredDependency,
+                description: `AreLoader or its inherited variation is a required dependency for ${this.constructor.name}. Please ensure that it is registered in the container scope before starting the engine.`
+            });
+
+        if (!transformer)
+            throw new AreEngineError({
+                title: AreEngineError.MissedRequiredDependency,
+                description: `AreTransformer or its inherited variation is a required dependency for ${this.constructor.name}. Please ensure that it is registered in the container scope before starting the engine.`
+            });
+
+        if (!compiler)
+            throw new AreEngineError({
+                title: AreEngineError.MissedRequiredDependency,
+                description: `AreCompiler or its inherited variation is a required dependency for ${this.constructor.name}. Please ensure that it is registered in the container scope before starting the engine.`
+            });
+
+        if (!interpreter)
+            throw new AreEngineError({
+                title: AreEngineError.MissedRequiredDependency,
+                description: `AreInterpreter or its inherited variation is a required dependency for ${this.constructor.name}. Please ensure that it is registered in the container scope before starting the engine.`
+            });
+
+        if (!lifecycle)
+            throw new AreEngineError({
+                title: AreEngineError.MissedRequiredDependency,
+                description: `AreLifecycle or its inherited variation is a required dependency for ${this.constructor.name}. Please ensure that it is registered in the container scope before starting the engine.`
+            });
+    }
+
+
+    /**
+     * Method to pack all necessary dependencies for the engine. This method is called during the initialization phase of the engine and ensures that all required components are registered in the container scope, allowing for proper dependency injection and management throughout the engine's lifecycle.
+     * 
+     * @param scope 
+     * @param dependencies 
+     */
+    @A_Frame.Method({
+        description: 'Method to pack all necessary dependencies for the engine. This method is called during the initialization phase of the engine and ensures that all required components are registered in the container scope, allowing for proper dependency injection and management throughout the engine\'s lifecycle.'
+    })
+    protected package(
+        scope: A_Scope,
+        dependencies?: Partial<AreEngineDependencies>
+    ) {
+        const { context, syntax, loader, tokenizer, compiler, transformer, interpreter, lifecycle, signals } = dependencies || {};
+        const existedContext = scope.resolveConstructor(AreContext);
+        const existedSyntax = scope.resolveConstructor(AreSyntax);
+        const existedLoader = scope.resolveConstructor(AreLoader);
+        const existedTokenizer = scope.resolveConstructor(AreTokenizer);
+        const existedCompiler = scope.resolveConstructor(AreCompiler);
+        const existedInterpreter = scope.resolveConstructor(AreInterpreter);
+        const existedLifecycle = scope.resolveConstructor(AreLifecycle);
+        const existedTransformer = scope.resolveConstructor(AreTransformer);
+        const existedSignals = scope.resolveConstructor(AreSignals);
+
+
+        this.packDependency(scope, context || AreContext, existedContext);
+        this.packDependency(scope, syntax || AreSyntax, existedSyntax);
+        this.packDependency(scope, tokenizer || AreTokenizer, existedTokenizer);
+        this.packDependency(scope, loader || AreLoader, existedLoader);
+        this.packDependency(scope, compiler || AreCompiler, existedCompiler);
+        this.packDependency(scope, transformer || AreTransformer, existedTransformer);
+        this.packDependency(scope, interpreter || AreInterpreter, existedInterpreter);
+        this.packDependency(scope, lifecycle || AreLifecycle, existedLifecycle);
+        this.packDependency(scope, signals || AreSignals, existedSignals);
+
+    }
+
+    protected packDependency<T extends A_TYPES__A_DependencyInjectable>(
+        scope: A_Scope,
+        dependency: T | A_TYPES__Ctor<T>,
+        existed?: A_TYPES__Ctor<T>
+    ) {
+        const logger = scope.resolve(A_Logger);
+        const thisName = A_CommonHelper.getComponentName(this);
+        const scopeIssuerName = A_CommonHelper.getComponentName(scope.issuer());
+        const dependencyName = A_CommonHelper.getComponentName(dependency);
+
+        if (existed) {
+            logger?.debug('cyan', `Dependency ${dependencyName} already exists in ${scopeIssuerName} scope. Skipping injection.`);
+
+            return existed;
+        } else {
+            logger?.debug('cyan', `Injecting ${dependencyName} into ${scopeIssuerName} scope for ${thisName}...`);
+            scope.register(dependency);
+
+            return dependency;
+        }
+    }
+
+}

package/src/lib/AreEngine/AreEngine.constants.ts

@@ -0,0 +1,7 @@
+
+
+export const AreEngineFeatures = {
+    Load: '_AreEngine_Load',
+    Build: '_AreEngine_Build',
+    Execute: '_AreEngine_Execute',
+}

package/src/lib/AreEngine/AreEngine.error.ts

@@ -0,0 +1,9 @@
+import { A_Error } from "@adaas/a-concept"
+
+
+
+export class AreEngineError extends A_Error{
+
+
+    static readonly MissedRequiredDependency = 'A Required Dependency is missing in AreEngine';
+}

package/src/lib/AreEngine/AreEngine.types.ts

@@ -0,0 +1,24 @@
+import { A_TYPES__Component_Constructor, A_TYPES__Fragment_Constructor } from "@adaas/a-concept"
+import type { AreCompiler } from "@adaas/are/compiler/AreCompiler.component"
+import type { AreContext } from "@adaas/are/component/Are.context"
+import type { AreLoader } from "@adaas/are/loader/AreLoader.component"
+import type { AreSyntax } from "@adaas/are/syntax/AreSyntax.context"
+import type { AreTokenizer } from "@adaas/are/tokenizer/AreTokenizer.component"
+import type { AreTransformer } from "@adaas/are/transformer/AreTransformer.component"
+import type { AreInterpreter } from "@adaas/are/interpreter/AreInterpreter.component"
+import type { AreLifecycle } from "@adaas/are/lifecycle/AreLifecycle.component"
+import { AreSignals } from "@adaas/are/signals/AreSignals.component"
+
+
+
+export type AreEngineDependencies = {
+    context: AreContext,
+    syntax: AreSyntax,
+    loader: A_TYPES__Component_Constructor<AreLoader>,
+    tokenizer: A_TYPES__Component_Constructor<AreTokenizer>,
+    compiler: A_TYPES__Component_Constructor<AreCompiler>,
+    transformer: A_TYPES__Component_Constructor<AreTransformer>,
+    interpreter: A_TYPES__Component_Constructor<AreInterpreter>,
+    lifecycle: A_TYPES__Component_Constructor<AreLifecycle>,
+    signals: A_TYPES__Component_Constructor<AreSignals>
+}

package/src/lib/AreEvent/AreEvent.context.ts

@@ -1,8 +1,5 @@
-import { A_Fragment } from "@adaas/a-concept"
 import { A_Frame } from "@adaas/a-frame"
-import type { AreNode } from "@adaas/are/node"
-import { AreEventProps } from "./AreEvent.types"
-
+import { A_ExecutionContext } from "@adaas/a-utils/a-execution"
 
 
 @A_Frame.Fragment({
@@ -11,28 +8,7 @@ import { AreEventProps } from "./AreEvent.types"
     description: 'Event context for managing events within the A-Concept Rendering Engine (ARE) framework, encapsulating event data and associated nodes to facilitate event-driven interactions.'
 })
 export class AreEvent<
-    T extends any = any
-> extends A_Fragment {
-
-
-    protected _node?: AreNode
-
-    protected _props: AreEventProps<T>
-
-    constructor(eventName: string, props: AreEventProps<T>) {
-        super({ name: eventName })
-
-
-        this._props = props;
-    }
-
-    get data(): T {
-        return this._props.data
-    }
-
-    get event(): string {
-        return this._props.event
-    }
-
+    T extends Record<string, any> = Record<string, any>
+> extends A_ExecutionContext<T> {
 
 }

package/src/lib/AreInstruction/AreInstruction.constants.ts

@@ -0,0 +1,23 @@
+
+
+export const AreInstructionFeatures = {
+    /**
+     * The 'Apply' feature indicates that the instruction has been applied to the scene or component, meaning that its effects have been executed and are now reflected in the state of the scene or component. This status is typically used to track the lifecycle of an instruction, allowing for proper management and potential reversal of changes if needed.
+     */
+    Apply: '_AreInstruction_Apply',
+    /**
+     * The 'Update' feature indicates that the instruction has been updated, meaning that its properties or effects have been modified after it was initially applied. This status is important for managing dynamic changes in the scene or component, allowing for adjustments to be made to the instruction's behavior or effects without needing to revert and reapply it entirely.
+     */
+    Update: '_AreInstruction_Update',
+    /**
+     * The 'Revert' feature indicates that the instruction has been reverted, meaning that any changes or effects that were applied by the instruction have been undone, and the scene or component has been returned to its previous state before the instruction was applied. This status is crucial for managing the state of the scene or component, especially in cases where an instruction needs to be rolled back due to errors or changes in requirements.
+     */
+    Revert: '_AreInstruction_Revert'
+} as const
+
+
+export const AreInstructionDefaultNames = {
+    Default: '_Are_DefaultInstruction',
+    Declaration: '_Are_DeclarationInstruction',
+    Mutation: '_Are_MutationInstruction',
+} as const

package/src/lib/AreInstruction/AreInstruction.entity.ts

@@ -0,0 +1,207 @@
+
+import { A_Context, A_Entity, A_Error, A_FormatterHelper, A_Scope } from "@adaas/a-concept";
+import { A_Frame } from "@adaas/a-frame";
+import type { AreNode } from "@adaas/are/node/AreNode.entity";
+import { AreInstructionNewProps, AreInstructionSerialized } from "./AreInstruction.types";
+import { AreInstructionFeatures } from "./AreInstruction.constants";
+import { AreStoreWatchingEntity } from "@adaas/are/store/AreStore.types";
+
+
+@A_Frame.Entity({
+    namespace: 'A-ARE',
+    name: 'AreInstruction',
+    description: 'AreInstruction is the base entity for all rendering instructions in the ARE framework. It represents a serializable, reversible operation (such as creating or mutating a DOM element) that can be applied to and tracked within the AreScene, enabling deterministic rendering and undo/redo capabilities.'
+})
+export class AreInstruction<
+    T extends Record<string, any> = Record<string, any>,
+    S extends AreInstructionSerialized<T> = AreInstructionSerialized<T>
+> extends A_Entity<AreInstructionNewProps<T>, S> implements AreStoreWatchingEntity {
+    /**
+     * The name of the instruction, for example "CreateElement", "AddAttribute", "RemoveNode", etc. This is used to identify the type of the instruction and how to process it. The name should be in PascalCase format, and should be unique across all instruction types. It is recommended to use a prefix that indicates the category of the instruction, for example "CreateElement" for instructions that create new elements, "UpdateAttribute" for instructions that update attributes, etc.
+     */
+    protected _name!: string
+    /**
+     * The payload of the instruction, which can contain any additional information that may be needed for the rendering purpose. For example, for CreateElement instruction, the payload can contain the tag name and parent information, so the Host can use this information to create the element in the correct place in the scene. The payload is optional and can be an empty object if no additional information is needed.
+     */
+    protected _payload?: T
+    /**
+     * Group is an optional property that can be used to group instructions together. For example a set of instructions that depend on create CreateElement instruction can be grouped together with the same group name, so if the CreateElement instruction is reverted, all the instructions in the same group will be reverted as well, and so on. This can be useful to manage complex changes that involve multiple instructions. 
+     * 
+     * [!] Note, the best option is to use ASEID of the Instruction as a group, so all instructions with the same ASEID will be treated as a single change, and will be applied and reverted together.
+     */
+    protected _group: string | undefined
+    /**
+     * The parent instruction that created this instruction. For example, if we have a CreateElement instruction that creates a new element, and then we have an AddAttribute instruction that adds an attribute to that element, the AddAttribute instruction would have the CreateElement instruction as its parent. This can be used to track the hierarchy of instructions and their dependencies.
+     */
+    protected _parent: string | undefined
+
+    /**
+     * A set of properties that influence the behavior of the instruction, for example, for AddTextInstruction, we can interpolation dependent on some key in the store, so we can have a property called "interpolationKey" that will be used to track the dependencies of the instruction, and when the value of this key changes in the scope, we can update the instruction accordingly.
+     */
+    protected _props!: Set<string>
+
+
+    /**
+     * The name of the instruction, for example "CreateElement", "AddAttribute", "RemoveNode", etc. This is used to identify the type of the instruction and how to process it. The name should be in PascalCase format, and should be unique across all instruction types. It is recommended to use a prefix that indicates the category of the instruction, for example "CreateElement" for instructions that create new elements, "UpdateAttribute" for instructions that update attributes, etc.
+     */
+    get name(): string {
+        return this._name;
+    }
+    /**
+     * The payload of the instruction, which can contain any additional information that may be needed for the rendering purpose. For example, for CreateElement instruction, the payload can contain the tag name and parent information, so the Host can use this information to create the element in the correct place in the scene. The payload is optional and can be an empty object if no additional information is needed. 
+     * 
+     * [!] Note, the payload should be serializable, so it can be stored and transmitted easily. It is recommended to use simple data structures for the payload, such as objects, arrays, strings, numbers, etc., and avoid using complex data types that may not be easily serializable.
+     */
+    get payload(): T {
+        return this._payload || {} as T;
+    }
+
+    /**
+     * Group is an optional property that can be used to group instructions together. For example a set of instructions that depend on create CreateElement instruction can be grouped together with the same group name, so if the CreateElement instruction is reverted, all the instructions in the same group will be reverted as well, and so on. This can be useful to manage complex changes that involve multiple instructions. 
+     * 
+     * [!] Note, the best option is to use ASEID of the Instruction as a group, so all instructions with the same ASEID will be treated as a single change, and will be applied and reverted together.
+     */
+    get group(): string | undefined {
+        return this._group;
+    }
+    /**
+     * The parent instruction ASEID that created this instruction. For example, if we have a CreateElement instruction that creates a new element, and then we have an AddAttribute instruction that adds an attribute to that element, the AddAttribute instruction would have the CreateElement instruction as its parent. This can be used to track the hierarchy of instructions and their dependencies.
+     * 
+     * [!] Note, the parent should be provided as an ASEID string, so it can be easily referenced and tracked across different contexts and times.
+     */
+    get parent(): string | undefined {
+        return this._parent;
+    }
+
+    get id(): string {
+        return this.aseid.id;
+    }
+
+    get owner(): AreNode {
+        return A_Context.scope(this).issuer<AreNode>()!;
+    }
+
+
+    fromNew(newEntity: AreInstructionNewProps<T>): void {
+
+        // TODO: Verify if deduplication ID is needed
+        // const identity = newEntity.id || {
+        //     name: newEntity.name,
+        // };
+
+        // const id = AreCacheHelper.createHash(identity);
+
+        this.aseid = this.generateASEID({
+            // shard: newEntity.node.id,
+            entity: A_FormatterHelper.toKebabCase(newEntity.name),
+            // id: id,
+        });
+
+        this._name = newEntity.name;
+        this._payload = newEntity.payload
+        this._group = newEntity.group?.aseid.toString();
+        this._parent = newEntity.parent?.aseid.toString();
+    }
+
+
+    fromUndefined(): void {
+        throw new A_Error({
+            title: "Cannot create an instruction without properties",
+            description: "AreInstruction cannot be created without properties. Please provide the necessary properties to create an instruction.",
+        })
+    }
+
+
+    // ===============================================================================
+    // ----------------------------Instruction Operations ------------------------------
+    // ===============================================================================
+
+    /**
+     * Group this instruction with another instruction. This means that when one of the instructions in the group is applied or reverted, all the instructions in the same group will be applied or reverted together. This can be useful to manage complex changes that involve multiple instructions. 
+     * 
+     * For example, if we have a CreateElement instruction that creates a new element, and then we have an AddAttribute instruction that adds an attribute to that element, we can group them together with the same group name, so if we revert the CreateElement instruction, the AddAttribute instruction will be reverted as well, and so on.
+     * 
+     * @param instruction 
+     * @returns 
+     */
+    groupWith(instruction: AreInstruction): this {
+        this._group = instruction.id;
+        return this;
+    }
+    /**
+     * Ungroup this instruction from any group. This means that this instruction will be treated as an independent instruction, and will not be applied or reverted together with any other instructions. This can be useful when you want to separate an instruction from a group, so it can be applied or reverted independently.
+     * 
+     * @returns 
+     */
+    unGroup(): this {
+        this._group = undefined;
+        return this;
+    }
+    /**
+     * Attach this instruction to a parent instruction. This means that this instruction will be considered as a child of the parent instruction, and can be used to track the hierarchy of instructions and their dependencies. 
+     * 
+     * For example, if we have a CreateElement instruction that creates a new element, and then we have an AddAttribute instruction that adds an attribute to that element, we can attach the AddAttribute instruction to the CreateElement instruction as its parent, so we can track that the AddAttribute instruction is related to the CreateElement instruction.
+     * 
+     * @param parent 
+     * @returns 
+     */
+    attachTo(parent: AreInstruction): this {
+        this._parent = parent.id;
+        return this;
+    }
+    /**
+     * Detach this instruction from its parent instruction. This means that this instruction will no longer be considered as a child of the parent instruction, and will not be related to it in any way. This can be useful when you want to separate an instruction from its parent, so it can be treated as an independent instruction.
+     * 
+     * @returns 
+     */
+    detach(): this {
+        this._parent = undefined;
+        return this;
+    }
+
+
+    // ===============================================================================
+    // ----------------------------Instruction Features ------------------------------
+    // ===============================================================================
+    /**
+     * Apply this instruction to the scene. This means that the changes represented by this instruction will be applied to the scene, and the Host will perform the necessary operations to reflect these changes in the rendered output. 
+     * 
+     * For example, if this instruction is a CreateElement instruction, when we apply it, the Host will create a new element in the scene according to the information provided in the payload of the instruction. If this instruction is an AddAttribute instruction, when we apply it, the Host will add the specified attribute to the target element in the scene. The apply method can also accept an optional scope parameter, which can be used to provide additional context or information that may be needed for applying the instruction.
+     * 
+     * @param scope 
+     */
+    apply(
+        scope?: A_Scope
+    ): void {
+        this.call(AreInstructionFeatures.Apply, scope);
+    }   
+    /**
+     * Update this instruction in the scene. This means that the changes represented by this instruction will be updated in the scene, and the Host will perform the necessary operations to reflect these changes in the rendered output. This is particularly useful for instructions that have dynamic properties or effects that may change over time, allowing for adjustments to be made to the instruction's behavior or effects without needing to revert and reapply it entirely. The update method can also accept an optional scope parameter, which can be used to provide additional context or information that may be needed for updating the instruction.
+     * 
+     * @param scope 
+     */
+    update(
+        scope?: A_Scope
+    ): void {
+        this.call(AreInstructionFeatures.Update, scope);
+    }
+    /**
+     * Revert this instruction from the scene. This means that the changes represented by this instruction will be reverted from the scene, and the Host will perform the necessary operations to undo these changes in the rendered output.
+     * 
+     * @param scope 
+     */
+    revert(
+        scope?: A_Scope
+    ): void {
+        this.call(AreInstructionFeatures.Revert, scope);
+    }
+
+}
+
+
+
+
+
+
+
+

package/src/lib/AreInstruction/AreInstruction.error.ts

@@ -0,0 +1,7 @@
+import { A_Error } from "@adaas/a-concept"
+
+
+
+export class AreInstructionError extends A_Error{
+    
+}