@adaas/are 0.0.2 → 0.0.3

package/src/lib/AreInstruction/AreInstruction.types.ts

@@ -0,0 +1,63 @@
+import { A_TYPES__Entity_Serialized } from "@adaas/a-concept";
+import { AreInstruction } from "./AreInstruction.entity";
+import { AreNode } from "@adaas/are/node/AreNode.entity";
+
+export type AreInstructionNewProps<T extends any = Record<string, any>> = {
+    /**
+     * The deduplication ID that prevents duplicated instruction within the same node. 
+     * 
+     * For example to prevent duplicated AddAttribute instruction for the same attribute, we can use the attribute name as the deduplication ID, so if we have two AddAttribute instructions with the same attribute name, only the first one will be applied, and the second one will be ignored.
+     * 
+     * 
+     * [!] Note; By default it uses action name and group if provided
+     */
+    // id?: Array<any>;
+    /**
+     * the Host operation to be performed. Exactly this name will be used to call a method from the Host class. 
+     */
+    name: string;
+    /**
+     * 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.
+     */
+    parent?: AreInstruction | undefined;
+    /**
+     * 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.
+     */
+    group?: AreInstruction | undefined;
+    /**
+     * A set of additional parameters that may be needed for the rendering purpose. 
+     * 
+     * For example: for AddAttribute instruction, we may need to provide the attribute name and value as a payload, so the Host can use this information to add the attribute to the node.
+     */
+    payload?: T;
+};
+
+
+export type AreInstructionSerialized<T extends any = Record<string, any>> = {
+    /**
+     * The name of the instruction, which corresponds to the operation that should be performed in the Host. This name is used to identify the specific method in the Host that should be called to execute the instruction, allowing for a clear mapping between instructions and their corresponding actions in the rendering process.
+     */
+    name: string;
+    /**
+     * The type of the instruction, which can be used to categorize instructions and determine how they should be processed. For example, we can have different types for declaration instructions (e.g., DeclarationInstruction or CreateElement) and mutation instructions (e.g., AddAttribute), allowing for better organization and management of instructions based on their purpose and behavior in the scene.
+     */
+    type: string
+    /**
+     * 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.
+     */
+    parent?: string | undefined;
+    /**
+     * 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. 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.
+     */
+    group?: string | undefined;
+    /**
+     * A set of additional parameters that may be needed for the rendering purpose. For example: for AddAttribute instruction, we may need to provide the attribute name and value as a payload, so the Host can use this information to add the attribute to the node.
+     */
+    payload: T;
+} & A_TYPES__Entity_Serialized

package/src/lib/AreInstruction/types/AreDeclaration.instruction.ts

@@ -0,0 +1,77 @@
+import { A_IdentityHelper } from "@adaas/a-concept";
+import { A_Frame } from "@adaas/a-frame";
+import { AreInstruction } from "@adaas/are/instruction/AreInstruction.entity";
+import { AreInstructionNewProps, AreInstructionSerialized } from "@adaas/are/instruction/AreInstruction.types";
+import { AreInstructionDefaultNames } from "@adaas/are/instruction/AreInstruction.constants";
+
+
+/**
+ * This is a top-level instruction that represents the creation of a new element in the scene. It contains all the necessary information to create a new element, such as its tag and parent. This instruction can be applied to the scene to create a new element and can be reverted to remove the created element.
+ */
+@A_Frame.Entity({
+    namespace: 'A-ARE',
+    name: 'AreDeclaration',
+    description: 'AreDeclaration is a top-level rendering instruction that represents the creation of a new element in the ARE scene. It carries the target tag name and parent reference needed by the Host to construct the DOM element, and can be applied or reverted to manage element creation and removal deterministically.'
+})
+export class AreDeclaration<
+    T extends Record<string, any> = Record<string, any>,
+    S extends AreInstructionSerialized<T> = AreInstructionSerialized<T>
+> extends AreInstruction<T, S> {
+
+    constructor(
+        /**
+         * Serialized form of the instruction, used for deserialization and reconstruction of the instruction instance. This allows for the instruction to be easily stored, transmitted, and recreated in different contexts or at different times, while maintaining all the necessary information and relationships intact.
+         */
+        serialized: AreInstructionSerialized,
+    )
+    constructor(
+        /**
+         * The name of the operation to be performed in Host. For example, for CreateElement instruction, the name can be "createElement", so the Host can have a method with the same name to handle this instruction.
+         */
+        name: string,
+        /**
+         * In case this is a child instruction that is related to a declaration instruction, we can pass the parent declaration instruction to establish the relationship between them. This allows us to manage related instructions together and ensure that they are executed in the correct order in the scene.
+         */
+        parent: AreDeclaration,
+        /**
+         * A set of additional parameters 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.
+         */
+        payload: T,
+    )
+    constructor(
+        /**
+         * The name of the operation to be performed in Host. For example, for CreateElement instruction, the name can be "createElement", so the Host can have a method with the same name to handle this instruction.
+         */
+        name?: string,
+        /**
+         * A set of additional parameters 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.
+         */
+        payload?: T,
+    )
+    constructor(
+        /**
+         * The name of the operation to be performed in Host. For example, for CreateElement instruction, the name can be "createElement", so the Host can have a method with the same name to handle this instruction.
+         */
+        param1?: string | S,
+        /**
+         * A set of additional parameters 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.
+         */
+        param2?: T | AreDeclaration,
+        /**
+         * In case this is a child instruction that is related to a declaration instruction, we can pass the parent declaration instruction to establish the relationship between them. This allows us to manage related instructions together and ensure that they are executed in the correct order in the scene.
+         */
+        param3?: AreDeclaration | T,
+    ) {
+        if (typeof param1 === 'object' && 'aseid' in param1)
+            super(param1);
+        else
+            super({
+                name: param1 || AreInstructionDefaultNames.Default,
+                parent: param2 instanceof AreDeclaration ? param2 : undefined,
+                group: param2 instanceof AreDeclaration ? param2.group : undefined,
+                payload: param2 instanceof AreDeclaration ? (param3 || {}) as T : (param2 || {}) as T,
+                // id: [param1, A_IdentityHelper.generateTimeId(), param2 instanceof AreDeclaration ? (param3 || {}) as T : (param2 || {}) as T]
+            } as AreInstructionNewProps<T>);
+    }
+
+}

package/src/lib/AreInstruction/types/AreMutation.instruction.ts

@@ -0,0 +1,87 @@
+import { title } from "process";
+import { A_Frame } from "@adaas/a-frame";
+import { AreInstructionDefaultNames } from "@adaas/are/instruction/AreInstruction.constants";
+import { AreInstruction } from "@adaas/are/instruction/AreInstruction.entity";
+import { AreInstructionError } from "@adaas/are/instruction/AreInstruction.error";
+import { AreInstructionNewProps, AreInstructionSerialized } from "@adaas/are/instruction/AreInstruction.types";
+import { AreDeclaration } from "./AreDeclaration.instruction";
+
+
+
+@A_Frame.Entity({
+    namespace: 'A-ARE',
+    name: 'AreMutation',
+    description: 'AreMutation is a rendering instruction that represents a reversible change applied to an existing declaration node in the ARE scene — such as updating an attribute, modifying content, or altering child structure. It references a parent AreDeclaration and is grouped with related mutations for coordinated apply and revert operations.'
+})
+export class AreMutation<
+    T extends Record<string, any> = Record<string, any>,
+    S extends AreInstructionSerialized<T> = AreInstructionSerialized<T>
+> extends AreInstruction<T, S> {
+
+    get parent(): string {
+        return this._parent!;
+    }
+
+
+    get group(): string {
+        return this._group || this.parent;
+    }
+
+    constructor(
+        /**
+         * Serialized form of the instruction, used for deserialization and reconstruction of the instruction instance. This allows for the instruction to be easily stored, transmitted, and recreated in different contexts or at different times, while maintaining all the necessary information and relationships intact.
+         */
+        serialized: S,
+    )
+    constructor(
+        /**
+         * The name of the operation to be performed in Host.
+         */
+        name: string,
+        /**
+         * Parent instruction for grouping in case of mutations related to a specific declaration. This allows for better organization and management of instructions in the scene, as all mutations related to the same declaration will be executed together.
+         */
+        parent: AreDeclaration,
+        /**
+         * A set of additional parameters that may be needed for the rendering purpose. For example, for AddAttribute instruction, the payload can contain the attribute name and value as a payload, so the Host can use this information to add the attribute to the node.
+         */
+        payload?: T,
+    )
+    constructor(
+        /**
+         * The name of the operation to be performed in Host.
+         */
+        param1: string | S,
+        /**
+         * Parent instruction for grouping in case of mutations related to a specific declaration. This allows for better organization and management of instructions in the scene, as all mutations related to the same declaration will be executed together.
+         */
+        param2?: AreDeclaration,
+        /**
+         * A set of additional parameters that may be needed for the rendering purpose. For example, for AddAttribute instruction, the payload can contain the attribute name and value as a payload, so the Host can use this information to add the attribute to the node.
+         */
+        param3?: T,
+    ) {
+        if (typeof param1 === 'object' && 'aseid' in param1)
+            super(param1);
+        else
+            super({
+                name: param1 || AreInstructionDefaultNames.Mutation,
+                group: param2,
+                parent: param2,
+                payload: param3,
+                // id: [param1, param3, param2?.group]
+            } as AreInstructionNewProps<T>);
+    }
+
+
+
+    fromNew(newEntity: AreInstructionNewProps<T>): void {
+        if (!newEntity.parent)
+            throw new AreInstructionError({
+                title: "Mutation instruction must have a parent declaration instruction",
+                description: `Mutation instruction with name ${newEntity.name} must have a parent declaration instruction for grouping and organization purposes. Please provide a parent declaration instruction when creating this mutation instruction.`
+            });
+
+        super.fromNew(newEntity);
+    }
+}

package/src/lib/AreInterpreter/AreInterpreter.component.ts

@@ -0,0 +1,208 @@
+import { A_Caller, A_Component, A_Feature, A_Inject, A_Scope, A_TYPES__Entity_Constructor } from "@adaas/a-concept";
+import { A_Frame } from "@adaas/a-frame";
+import { AreScene } from "@adaas/are/scene/AreScene.context";
+import { AreNode } from "@adaas/are/node/AreNode.entity";
+import { AreNodeFeatures } from "@adaas/are/node/AreNode.constants";
+import { AreInstructionFeatures } from "@adaas/are/instruction/AreInstruction.constants";
+import { AreInstruction } from "@adaas/are/instruction/AreInstruction.entity";
+import { AreStore } from "@adaas/are/store/AreStore.context";
+import { A_Logger } from "@adaas/a-utils/a-logger";
+
+
+
+@A_Frame.Component({
+    description: 'Stateless executor that reads the Scene and translates its instructions into operations on a rendering target. Computes the diff between applied and planned, calls revert on removed instructions and apply on added ones. Owns no state of its own — all state lives in the Scene. Can be swapped for any target implementation (DOMInterpreter, SSRInterpreter, CanvasInterpreter) without touching any other part of the pipeline.'
+})
+export class AreInterpreter extends A_Component {
+    /**
+     * Decorator to mark a method as an instruction Apply handler for the specific instruction type. The method will be called during the render phase of the ARE component when the corresponding instruction needs to be applied. The method should contain logic to perform the necessary operations on the rendering target based on the instruction's content and context.
+     * 
+     * @param action 
+     * @returns 
+     */
+    static Apply(action: string) {
+        const name = action + AreInstructionFeatures.Apply
+
+        return (target: any, propertyKey: string, descriptor: PropertyDescriptor) => {
+            return A_Feature.Extend({
+                name,
+                scope: [target.constructor],
+            })(target, propertyKey, descriptor);
+        }
+    }
+    /**
+     * Decorator to mark a method as an instruction Update handler for the specific instruction type. The method will be called during the render phase of the ARE component when the corresponding instruction has been updated. The method should contain logic to perform the necessary operations on the rendering target to update the effects of the instruction based on its new content and context.
+     * 
+     * @param action 
+     * @returns 
+     */
+    static Update(action: string) {
+        const name = action + AreInstructionFeatures.Update
+
+        return (target: any, propertyKey: string, descriptor: PropertyDescriptor) => {
+            return A_Feature.Extend({
+                name,
+                scope: [target.constructor],
+            })(target, propertyKey, descriptor);
+        }
+    }
+    /**
+     * Decorator to mark a method as an instruction Revert handler for the specific instruction type. The method will be called during the render phase of the ARE component when the corresponding instruction needs to be reverted. The method should contain logic to perform the necessary operations on the rendering target to undo the effects of the instruction based on its content and context.
+     * 
+     * @param action 
+     * @returns 
+     */
+    static Revert(action: string) {
+
+        const name = action + AreInstructionFeatures.Revert
+
+        return (target: any, propertyKey: string, descriptor: PropertyDescriptor) => {
+            return A_Feature.Extend({
+                name,
+                scope: [target.constructor],
+            })(target, propertyKey, descriptor);
+        }
+    }
+    /**
+     * The method responsible for executing the render operation based on the current state of the Scene. It processes the instructions that need to be applied and reverted, ensuring that the rendering target is updated accordingly. The method handles any errors that may occur during the application or reversion of instructions, maintaining the integrity of the rendering process.
+     * 
+     * @param scene 
+     */
+    @A_Feature.Extend({
+        name: AreNodeFeatures.onInterpret,
+        scope: [AreNode]
+    })
+    interpret(
+        @A_Inject(AreScene) scene: AreScene,
+    ) {
+        /**
+          * 1. First we need to get all changes to be applied and reverted during render operation
+          */
+        const { toApply, toRevert } = scene.changes
+
+        /**
+         * 2. Then we need to revert all instructions from scene
+         */
+        for (const instruction of toRevert) {
+            try {
+                instruction.revert();
+                scene.unApply(instruction);
+            } catch (error) {
+                instruction.apply();
+                scene.apply(instruction);
+            }
+        }
+        /**
+         * 3. Finally we should apply everything that needs to be applied
+         */
+        for (const instruction of toApply) {
+            try {
+                /**
+                 * 3.1. if everything went well then just simply apply and attach to state this instruction
+                 */
+                instruction.apply();
+                scene.apply(instruction);
+            } catch (error) {
+                /**
+                 * 2.2. if any error happened we simply revert the instruction and remove it from the state
+                 */
+                instruction.revert();
+                scene.unApply(instruction);
+            }
+        }
+    }
+
+    // -----------------------------------------------------------------------------------------
+    // ----------------------------Are-Instruction Section----------------------------------------
+    // -----------------------------------------------------------------------------------------
+
+    @A_Feature.Extend({
+        name: AreInstructionFeatures.Apply,
+        scope: [AreInstruction]
+    })
+    protected applyInstruction(
+        @A_Inject(A_Caller) instruction: AreInstruction,
+        @A_Inject(AreInterpreter) interpreter: AreInterpreter,
+        @A_Inject(AreStore) store: AreStore,
+        @A_Inject(A_Scope) scope: A_Scope,
+        @A_Inject(A_Feature) feature: A_Feature,
+        ...args: any[]
+    ) {
+        try {
+            /**
+             * 1. uses to track all calls to Store
+             */
+            store.watch(instruction);
+            /**
+             * So we're looking for any instruction name in the interpreter to be executed.
+             */
+            feature.chain(interpreter, instruction.name + AreInstructionFeatures.Apply, scope);
+
+            store.unwatch(instruction);
+        } catch (error) {
+            store.unwatch(instruction);
+            throw error;
+        }
+
+    }
+
+    @A_Feature.Extend({
+        name: AreInstructionFeatures.Update,
+        scope: [AreInstruction]
+    })
+    protected updateInstruction(
+        @A_Inject(A_Caller) instruction: AreInstruction,
+        @A_Inject(AreInterpreter) interpreter: AreInterpreter,
+        @A_Inject(AreStore) store: AreStore,
+        @A_Inject(A_Scope) scope: A_Scope,
+        @A_Inject(A_Feature) feature: A_Feature,
+        ...args: any[]
+    ) {
+        try {
+            /**
+             * 1. uses to track all calls to Store
+             */
+            store.watch(instruction);
+            /**
+             * So we're looking for any instruction name in the interpreter to be executed.
+             */
+            feature.chain(interpreter, instruction.name + AreInstructionFeatures.Update, scope);
+
+            store.unwatch(instruction);
+        } catch (error) {
+            store.unwatch(instruction);
+            throw error;
+        }
+
+    }
+
+
+    @A_Feature.Extend({
+        name: AreInstructionFeatures.Revert,
+        scope: [AreInstruction]
+    })
+    protected revertInstruction(
+        @A_Inject(A_Caller) instruction: AreInstruction,
+        @A_Inject(AreInterpreter) interpreter: AreInterpreter,
+        @A_Inject(AreStore) store: AreStore,
+        @A_Inject(A_Scope) scope: A_Scope,
+        @A_Inject(A_Feature) feature: A_Feature,
+        ...args: any[]
+    ) {
+        try {
+            /**
+             * 1. uses to track all calls to Store
+             */
+            // store.watch(instruction);
+            /**
+             * So we're looking for any instruction name in the interpreter to be executed.
+             */
+            feature.chain(interpreter, instruction.name + AreInstructionFeatures.Revert, scope);
+
+            // store.unwatch(instruction);
+        } catch (error) {
+            // store.unwatch(instruction);
+            throw error;
+        }
+    }
+}

package/src/lib/AreInterpreter/AreInterpreter.error.ts

@@ -0,0 +1,6 @@
+import { A_Error } from "@adaas/a-concept";
+
+
+export class AreInterpreterError extends A_Error {
+
+}