@adaas/a-frame 0.0.2

package/src/index.ts

@@ -0,0 +1,24 @@
+// ============================================================================
+// A-Frame CLI Exports
+// ============================================================================
+export { A_Frame_CLIContainer } from './lib/containers/CLI.container';
+
+// ============================================================================
+// A-Frame Index Exports
+// ============================================================================
+export { A_Frame_Index as A_Frame } from './lib/components/Index.component.ts/Index.component';
+export { A_Frame_IndexMeta } from './lib/components/Index.component.ts/Index.meta';
+export { A_Frame_IndexError } from './lib/components/Index.component.ts/Index.error';
+
+// ============================================================================
+// A-Frame Types Exports
+// ============================================================================
+export type {
+    A_Frame_IndexOptions,
+    A_Frame_IndexDecoratorTarget,
+    A_Frame_IndexDecoratorMeta,
+    A_Frame_IndexNamespaceDecoratorTarget
+} from './lib/components/Index.component.ts/Index.types';
+
+// Export the enum as both type and value
+export { A_Frame_IndexTargetType } from './lib/components/Index.component.ts/Index.types';

package/src/lib/components/Index.component.ts/Index.component.ts

@@ -0,0 +1,79 @@
+import { A_Component, A_Meta } from "@adaas/a-concept";
+import { A_Frame_IndexOptions, A_Frame_IndexTargetType } from "./Index.types";
+import { A_Frame_IndexDecorator } from "./decorators/IndexComponent.decorator";
+import { A_Frame_IndexNamespaceDecorator } from "./decorators/IndexNamespace.decorator";
+import { A_Frame_IndexDescribeDecorator } from "./decorators/IndexDescribe.decorator";
+import { A_Frame_IndexMeta } from "./Index.meta";
+
+
+
+@A_Meta.Define(A_Frame_IndexMeta)
+export class A_Frame_Index extends A_Component {
+
+
+    /**
+     * Allows to mark namespace and add it to index structure,
+     */
+    static Namespace(name: string): ClassDecorator & MethodDecorator {
+        return A_Frame_IndexNamespaceDecorator(name) as ClassDecorator & MethodDecorator;
+    }
+
+    /**
+     * Allows to add description to a class and add it to index structure
+     */
+    static Describe(description: string): ClassDecorator & MethodDecorator {
+        return A_Frame_IndexDescribeDecorator(description) as ClassDecorator & MethodDecorator;
+    }
+
+
+
+    /**
+     * Allows to mark component and add it to index structure,
+     */
+    static Component(): ClassDecorator
+    static Component(options: Partial<A_Frame_IndexOptions>): ClassDecorator
+    static Component(options: Partial<A_Frame_IndexOptions> = {}): ClassDecorator {
+        return A_Frame_IndexDecorator(A_Frame_IndexTargetType.COMPONENT, options) as ClassDecorator;
+    }
+
+    /**
+     * Allows to mark container and add it to index structure,
+     */
+    static Container(): ClassDecorator
+    static Container(options: Partial<A_Frame_IndexOptions>): ClassDecorator
+    static Container(options: Partial<A_Frame_IndexOptions> = {}): ClassDecorator {
+        return A_Frame_IndexDecorator(A_Frame_IndexTargetType.CONTAINER, options) as ClassDecorator;
+    }
+
+    /**
+     * Allows to mark entity and add it to index structure, 
+     * so it can be reused in other components or structures
+     */
+    static Entity(): ClassDecorator
+    static Entity(options: Partial<A_Frame_IndexOptions>): ClassDecorator
+    static Entity(options: Partial<A_Frame_IndexOptions> = {}): ClassDecorator {
+        return A_Frame_IndexDecorator(A_Frame_IndexTargetType.ENTITY, options) as ClassDecorator;
+    }
+
+
+    /**
+     * Allows to mark fragment and add it to index structure, 
+     * so it can be reused in other components or structures
+     */
+    static Fragment(): ClassDecorator
+    static Fragment(options: Partial<A_Frame_IndexOptions>): ClassDecorator
+    static Fragment(options: Partial<A_Frame_IndexOptions> = {}): ClassDecorator {
+        return A_Frame_IndexDecorator(A_Frame_IndexTargetType.FRAGMENT, options) as ClassDecorator;
+    }
+
+    /**
+     * Allows to define a reusable AI method from components, 
+     * that can be reused in other components. to build new Features
+     */
+    static Method(): MethodDecorator
+    static Method(options: Partial<A_Frame_IndexOptions>): MethodDecorator
+    static Method(options: Partial<A_Frame_IndexOptions> = {}): MethodDecorator {
+        return A_Frame_IndexDecorator(A_Frame_IndexTargetType.METHOD, options) as MethodDecorator;
+    }
+
+}

package/src/lib/components/Index.component.ts/Index.error.ts

@@ -0,0 +1,14 @@
+import { A_Error } from "@adaas/a-concept";
+
+
+export class A_Frame_IndexError extends A_Error {
+
+    static readonly InvalidTarget = 'A-Frame Index Invalid Target Error';
+
+    static readonly InvalidConfiguration = 'A-Frame Index Invalid Configuration Error';
+
+    static readonly IndexDefinitionError = 'A-Frame Index Definition Error';
+    static readonly IndexMetadataError = 'A-Frame Index Metadata Error';
+    static readonly IndexRegistryError = 'A-Frame Index Registry Error';
+    static readonly IndexComponentNotFoundError = 'A-Frame Index Component Not Found Error';
+}

package/src/lib/components/Index.component.ts/Index.guard.ts

@@ -0,0 +1,34 @@
+import { A_CommonHelper, A_TypeGuards } from "@adaas/a-concept";
+import { A_Frame_IndexDecoratorTarget, A_Frame_IndexMetaTarget } from "./Index.types";
+
+
+
+export class A_Frame_IndexTypeGuard {
+    /**
+     * Determines if the target is an allowed type for indexing
+     * 
+     * @param target 
+     * @returns 
+     */
+    static isAllowedTarget(target: any): target is A_Frame_IndexDecoratorTarget {
+        return A_TypeGuards.isEntityConstructor(target)
+            || A_TypeGuards.isComponentConstructor(target)
+            || A_TypeGuards.isContainerConstructor(target)
+            || A_TypeGuards.isFragmentConstructor(target)
+            || A_TypeGuards.isComponentInstance(target)
+            || A_TypeGuards.isContainerInstance(target)
+            || A_TypeGuards.isEntityInstance(target)
+            || A_TypeGuards.isFragmentInstance(target);
+    }
+
+
+
+    static getTargetName(target: A_Frame_IndexDecoratorTarget): string {
+        return A_CommonHelper.getComponentName(target);
+    }
+
+
+    static getTargetConstructor(target: A_Frame_IndexDecoratorTarget): A_Frame_IndexMetaTarget {
+        return typeof target === 'function' ? target : target.constructor as A_Frame_IndexMetaTarget;
+    }
+}

package/src/lib/components/Index.component.ts/Index.meta.ts

@@ -0,0 +1,28 @@
+import { A_ComponentMeta, A_Context, A_Meta } from "@adaas/a-concept";
+import { A_Frame_IndexDecoratorMeta, A_Frame_IndexTargetType, A_Frame_IndexMetaTarget } from "./Index.types";
+import { A_Frame_Index } from "./Index.component";
+import { A_Frame_IndexConfigurationsMeta } from "./IndexConfigurations.meta";
+
+export class A_Frame_IndexMeta extends A_ComponentMeta {
+
+    getMetaFor(target: A_Frame_IndexMetaTarget): A_Frame_IndexConfigurationsMeta {
+
+        const targetSpace = this.get('A_FRAME_INDEX_CONFIGURATIONS_META' as any) || new Map<A_Frame_IndexMetaTarget, A_Frame_IndexConfigurationsMeta>();
+
+        if (!targetSpace.has(target)) {
+            targetSpace.set(target, new A_Frame_IndexConfigurationsMeta());
+            this.set('A_FRAME_INDEX_CONFIGURATIONS_META' as any, targetSpace);
+        }
+
+        return targetSpace.get(target)!;
+    }
+
+
+    seMetaFor(target: A_Frame_IndexMetaTarget, meta: A_Frame_IndexConfigurationsMeta): void {
+        const targetSpace = this.get('A_FRAME_INDEX_CONFIGURATIONS_META' as any) || new Map<A_Frame_IndexMetaTarget, A_Frame_IndexConfigurationsMeta>();
+
+        targetSpace.set(target, meta);
+
+        this.set('A_FRAME_INDEX_CONFIGURATIONS_META' as any, targetSpace);
+    }
+}

package/src/lib/components/Index.component.ts/Index.types.ts

@@ -0,0 +1,132 @@
+import { A_Component, A_Container, A_Entity, A_Fragment, A_TYPES__Component_Constructor, A_TYPES__Container_Constructor, A_TYPES__Entity_Constructor, A_TYPES__Fragment_Constructor, A_TYPES__Required } from "@adaas/a-concept"
+import { A_Namespace } from "src/lib/entities/Namespace/Namespace.entity"
+
+
+export type A_Frame_IndexOptions = {
+    name?: string,
+    namespace?: string | A_Namespace
+    description?: string
+}
+
+
+
+export type A_Frame_IndexMetaTarget = A_TYPES__Container_Constructor
+    | A_TYPES__Entity_Constructor
+    | A_TYPES__Component_Constructor
+    | A_TYPES__Fragment_Constructor
+
+
+// ===========================================================================
+// --------------------------- Decorator Types -------------------------------
+// ===========================================================================
+// ---------------------------------------------------------------------------
+// -------------------- A-Frame Index Decorator Types-------------------------
+// ---------------------------------------------------------------------------
+/**
+ * Indicates a type of Feature Define decorator
+ */
+export type A_Frame_IndexDecoratorDescriptor =
+    TypedPropertyDescriptor<(...args: any[]) => any>
+    | TypedPropertyDescriptor<(...args: any[]) => any>
+    | TypedPropertyDescriptor<(...args: any[]) => Promise<any>>
+    | TypedPropertyDescriptor<(...args: any[]) => Promise<any>>
+
+
+/**
+ * Describes a target where Feature Define decorator can be applied
+ * 
+ * [!] The feature can be defined on Container, Entity, Component or Command
+ */
+export type A_Frame_IndexDecoratorTarget = A_Frame_IndexMetaTarget
+    | A_Component
+    | A_Container
+    | A_Entity
+    | A_Fragment
+/**
+ * Targets types that can be indexed
+ */
+export enum A_Frame_IndexTargetType {
+    COMPONENT = 'component',
+    ENTITY = 'entity',
+    CONTAINER = 'container',
+    FRAGMENT = 'fragment',
+    METHOD = 'method'
+}
+
+/**
+ * A type of Meta information stored by Index decorator
+ * This information is used by A-Context to build a proper index structure
+ */
+export type A_Frame_IndexDecoratorMeta = {
+    /**
+     * Component name
+     */
+    name: string,
+    /**
+     * Component description
+     */
+    description?: string,
+    /**
+     * Type of the component
+     */
+    type: A_Frame_IndexTargetType,
+    /**
+     * Namespace for the component
+     */
+    namespace?: string | A_Namespace,
+    /**
+     * Constructor reference
+     */
+    constructor: A_Frame_IndexDecoratorTarget
+}
+
+
+// ---------------------------------------------------------------------------
+// -------------------- A-Frame Index Decorator Types-------------------------
+// ---------------------------------------------------------------------------
+/**
+ * Indicates a type of Feature Define decorator
+ */
+export type A_Frame_IndexNamespaceDecoratorDescriptor =
+    TypedPropertyDescriptor<(...args: any[]) => any>
+    | TypedPropertyDescriptor<(...args: any[]) => any>
+    | TypedPropertyDescriptor<(...args: any[]) => Promise<any>>
+    | TypedPropertyDescriptor<(...args: any[]) => Promise<any>>
+
+
+/**
+ * Describes a target where Feature Define decorator can be applied
+ * 
+ * [!] The feature can be defined on Container, Entity, Component or Command
+ */
+export type A_Frame_IndexNamespaceDecoratorTarget = A_Container
+    | A_Entity
+    | A_Component
+    | A_Fragment
+    | A_TYPES__Fragment_Constructor
+    | A_TYPES__Component_Constructor
+    | A_TYPES__Container_Constructor
+    | A_TYPES__Entity_Constructor
+
+
+
+
+// ---------------------------------------------------------------------------
+// ------------- A-Frame Index Configurations Meta Types----------------------
+// ---------------------------------------------------------------------------
+
+
+export type A_Frame_IndexConfigurationsMetaType = {
+    namespaces: string,
+    descriptions: string,
+    type: string,
+    name: string,
+    methods: Map<string, A_Frame_IndexConfigurationsMetaMethodMeta>
+}
+
+
+export type A_Frame_IndexConfigurationsMetaMethodMeta = {
+    name: string,
+    description?: string,
+    methodName: string
+}

package/src/lib/components/Index.component.ts/IndexConfigurations.meta.ts

@@ -0,0 +1,78 @@
+import { A_Meta } from "@adaas/a-concept";
+import { A_Namespace } from "../../entities/Namespace/Namespace.entity";
+import { A_Frame_IndexConfigurationsMetaMethodMeta, A_Frame_IndexConfigurationsMetaType } from "./Index.types";
+
+
+
+export class A_Frame_IndexConfigurationsMeta extends A_Meta<Partial<A_Frame_IndexConfigurationsMetaType>> {
+
+    get name(): string | undefined {
+        return this.get('name');
+    }
+
+    set name(value: string | undefined) {
+        if (value)
+            this.set('name', value);
+    }
+
+
+    get type(): string | undefined {
+        return this.get('type');
+    }
+
+    set type(value: string | undefined) {
+        if (value)
+            this.set('type', value);
+    }
+
+
+    get namespace(): string | undefined {
+        return this.get('namespaces');
+    }
+
+    set namespace(value: string | undefined | A_Namespace) {
+        if (value) {
+            const target = value instanceof A_Namespace ? value.aseid.toString() : value;
+            this.set('namespaces', target);
+        }
+    }
+
+
+    get description(): string | undefined {
+        return this.get('descriptions');
+    }
+
+    set description(value: string | undefined) {
+        if (value)
+            this.set('descriptions', value);
+    }
+
+
+
+    get methods(): Map<string, A_Frame_IndexConfigurationsMetaMethodMeta> {
+        if (!this.get('methods')) {
+            this.set('methods', new Map());
+        }
+
+        return this.get('methods')!;
+    }
+
+
+    clear(): void {
+        this.set('name', undefined);
+        this.set('type', undefined);
+        this.set('namespaces', undefined);
+        this.set('descriptions', undefined);
+        this.set('methods', new Map());
+    }
+
+
+    addMethod(methodMeta: A_Frame_IndexConfigurationsMetaMethodMeta): void {
+        const methods = this.methods;
+
+        if (!methods.has(methodMeta.name)) {
+            methods.set(methodMeta.name, methodMeta);
+            this.set('methods', methods);
+        }
+    }
+}

package/src/lib/components/Index.component.ts/decorators/IndexComponent.decorator.ts

@@ -0,0 +1,97 @@
+import { A_CommonHelper, A_Context, A_Meta } from "@adaas/a-concept";
+import { A_Frame_IndexError } from "../Index.error";
+import { A_Frame_IndexDecoratorTarget, A_Frame_IndexOptions, A_Frame_IndexTargetType, A_Frame_IndexDecoratorDescriptor, A_Frame_IndexMetaTarget } from "../Index.types";
+import { A_Frame_Index } from "../Index.component";
+import { A_Frame_IndexMeta } from "../Index.meta";
+import { A_Frame_IndexTypeGuard } from "../Index.guard";
+
+export function A_Frame_IndexDecorator(
+    componentType: A_Frame_IndexTargetType,
+    config: Partial<A_Frame_IndexOptions> = {}
+) {
+    return function (
+        target: A_Frame_IndexDecoratorTarget,
+        propertyKey?: string | symbol,
+        descriptor?: A_Frame_IndexDecoratorDescriptor
+    ): any {
+
+        // Handle method decorator case
+        if (propertyKey && descriptor && componentType === A_Frame_IndexTargetType.METHOD) {
+            // For methods, target is the class prototype
+            const targetClass = target.constructor as A_Frame_IndexMetaTarget;
+            const methodName = String(propertyKey);
+
+            try {
+                const indexMeta: A_Frame_IndexMeta = A_Context.meta(A_Frame_Index) as any;
+                const targetMeta = indexMeta.getMetaFor(targetClass);
+
+
+                if (!!config.namespace && !!targetMeta.namespace && config.namespace !== targetMeta.namespace) {
+                    throw new A_Frame_IndexError(
+                        A_Frame_IndexError.InvalidConfiguration,
+                        `Method namespace '${config.namespace}' does not match target class namespace '${targetMeta.namespace}'.`
+                    );
+                }
+
+                // Store method information
+                const methodInfo = {
+                    name: config.name || methodName,
+                    description: config.description,
+                    namespace: config.namespace || targetMeta.namespace,
+                    methodName: methodName
+                };
+
+                // Add to methods array
+                targetMeta.addMethod(methodInfo);
+
+                indexMeta.seMetaFor(targetClass, targetMeta);
+
+                return descriptor;
+
+            } catch (error) {
+
+                throw new A_Frame_IndexError(
+                    A_Frame_IndexError.IndexDefinitionError,
+                    `Unable to apply @A_Frame_Index.Method decorator on '${targetClass.name}.${methodName}': ${error instanceof Error ? error.message : 'Unknown error'}`
+                );
+
+            }
+        }
+
+        // Handle class decorator case
+        if (!A_Frame_IndexTypeGuard.isAllowedTarget(target)) {
+            throw new A_Frame_IndexError(
+                A_Frame_IndexError.InvalidTarget,
+                `@A_Frame_Index.${componentType} decorator can only be applied to allowed targets.`
+            );
+        }
+
+        // for error messages
+        const componentName = A_CommonHelper.getComponentName(target);
+
+        try {
+            // Get the index meta for the global A_Frame_Index component
+            const indexMeta: A_Frame_IndexMeta = A_Context.meta(A_Frame_Index) as any;
+
+            const targetClass = A_Frame_IndexTypeGuard.getTargetConstructor(target);
+
+            // Check for pending namespace and description from other decorators
+            const targetMeta = indexMeta.getMetaFor(targetClass);
+
+            targetMeta.name = config.name || componentName;
+            targetMeta.description = config.description;
+            targetMeta.namespace = config.namespace;
+            targetMeta.type = componentType;
+
+            indexMeta.seMetaFor(targetClass, targetMeta);
+
+            return target;
+
+        } catch (error) {
+            throw new A_Frame_IndexError(
+                A_Frame_IndexError.IndexDefinitionError,
+                `Unable to apply @A_Frame_Index.${componentType} decorator on '${componentName}': ${error instanceof Error ? error.message : 'Unknown error'}`
+            );
+        }
+    };
+}

package/src/lib/components/Index.component.ts/decorators/IndexDescribe.decorator.ts

@@ -0,0 +1,59 @@
+import { A_CommonHelper, A_Context } from "@adaas/a-concept";
+import { A_Frame_IndexDecoratorDescriptor, A_Frame_IndexDecoratorTarget, A_Frame_IndexNamespaceDecoratorTarget } from "../Index.types";
+import { A_Frame_Index } from "../Index.component";
+import { A_Frame_IndexMeta } from "../Index.meta";
+import { A_Frame_IndexTypeGuard } from "../Index.guard";
+import { A_Frame_IndexError } from "../Index.error";
+
+export function A_Frame_IndexDescribeDecorator(description: string) {
+    return function (
+        target: A_Frame_IndexDecoratorTarget,
+        propertyKey?: string | symbol,
+        descriptor?: A_Frame_IndexDecoratorDescriptor
+
+    ): A_Frame_IndexDecoratorTarget {
+        const componentName = A_CommonHelper.getComponentName(target);
+
+        if (!A_Frame_IndexTypeGuard.isAllowedTarget(target)) {
+            throw new A_Frame_IndexError(
+                A_Frame_IndexError.InvalidTarget,
+                `Unable Apply Describe Index Decorator for '${componentName}': Target type is not allowed.`
+            );
+        }
+
+        // for error messages
+
+        // for error messages
+
+        try {
+            // Get the index meta for the global A_Frame_Index component
+            //  TODO: Type casting hack to avoid circular dependency issues
+            const indexMeta: A_Frame_IndexMeta = A_Context.meta(A_Frame_Index) as any;
+
+            const targetClass = A_Frame_IndexTypeGuard.getTargetConstructor(target);
+
+            // Check for pending namespace and description from other decorators
+            const targetMeta = indexMeta.getMetaFor(targetClass)
+            if (!!propertyKey || !!descriptor) {
+
+                const targetMethodName = propertyKey ? propertyKey.toString() : '';
+
+                const methodMeta = targetMeta.methods.get(targetMethodName);
+                if (!!methodMeta) {
+                    methodMeta.description = description;
+                    targetMeta.methods.set(targetMethodName, methodMeta);
+                }
+
+            } else {
+                targetMeta.description = description;
+
+                indexMeta.seMetaFor(targetClass, targetMeta);
+            }
+
+            return target;
+
+        } catch (error) {
+            throw new A_Frame_IndexError(error);
+        }
+    };
+}

package/src/lib/components/Index.component.ts/decorators/IndexNamespace.decorator.ts

@@ -0,0 +1,57 @@
+import { A_CommonHelper, A_Context } from "@adaas/a-concept";
+import { A_Frame_IndexDecoratorDescriptor, A_Frame_IndexDecoratorTarget, A_Frame_IndexNamespaceDecoratorTarget } from "../Index.types";
+import { A_Frame_Index } from "../Index.component";
+import { A_Frame_IndexTypeGuard } from "../Index.guard";
+import { A_Frame_IndexMeta } from "../Index.meta";
+import { A_Frame_IndexError } from "../Index.error";
+
+export function A_Frame_IndexNamespaceDecorator(name?: string) {
+    return function (
+        target: A_Frame_IndexDecoratorTarget,
+        propertyKey?: string | symbol,
+        descriptor?: A_Frame_IndexDecoratorDescriptor
+
+    ): A_Frame_IndexDecoratorTarget {
+        const componentName = A_CommonHelper.getComponentName(target);
+
+        if (!A_Frame_IndexTypeGuard.isAllowedTarget(target)) {
+            throw new A_Frame_IndexError(
+                A_Frame_IndexError.InvalidTarget,
+                `Unable Apply Describe Index Decorator for '${componentName}': Target type is not allowed.`
+            );
+        }
+
+        // for error messages
+
+        try {
+            // Get the index meta for the global A_Frame_Index component
+            //  TODO: Type casting hack to avoid circular dependency issues
+            const indexMeta: A_Frame_IndexMeta = A_Context.meta(A_Frame_Index) as any;
+
+            const targetClass = A_Frame_IndexTypeGuard.getTargetConstructor(target);
+
+            // Check for pending namespace and description from other decorators
+            const targetMeta = indexMeta.getMetaFor(targetClass)
+            if (!!propertyKey || !!descriptor) {
+
+                // const targetMethodName = propertyKey ? propertyKey.toString() : '';
+
+                // const methodMeta = targetMeta.methods.get(targetMethodName);
+                // if (!!methodMeta) {
+                //     methodMeta.namespace = name;
+                //     targetMeta.methods.set(targetMethodName, methodMeta);
+                // }
+
+            } else {
+                targetMeta.namespace = name;
+
+                indexMeta.seMetaFor(targetClass, targetMeta);
+            }
+
+            return target;
+
+        } catch (error) {
+            throw new A_Frame_IndexError(error);
+        }
+    };
+}

package/src/lib/containers/CLI.container.ts

@@ -0,0 +1,27 @@
+import { A_Concept, A_Container, A_Context, A_Error } from "@adaas/a-concept";
+
+
+export class A_Frame_CLIContainer extends A_Container {
+
+
+
+    @A_Concept.Load()
+    async initialize() {
+        if (A_Context.environment !== 'server') {
+            throw new A_Error('A-Frame CLI can only be used in Node.js environment.');
+        }
+    }
+
+
+    @A_Concept.Start()
+    async readCommandParams() {
+        console.log('Reading command parameters from CLI...');
+
+        const args = process.argv.slice(2);
+
+        console.log('Command Line Arguments:', args);
+
+        // Here you can parse the args and set them to the container's state or properties as needed
+    }
+
+}

package/src/lib/entities/Namespace/Namespace.entity.ts

@@ -0,0 +1,8 @@
+import { A_Entity } from "@adaas/a-concept";
+
+
+export class A_Namespace extends A_Entity {
+
+
+    
+}