@adaas/a-concept 0.0.2

package/src/global/A-Concept/A_Concept.class.ts

@@ -0,0 +1,143 @@
+import { A_CONCEPT_LifecycleDeclarationsStorage } from "src/storage/A_Concept.storage";
+import { A_TYPES__A_CONCEPT_RootRunParams, A_TYPES__IConceptConstructor } from "./A_Concept.types";
+import { A_Context } from "../A-Context/A-Context.class";
+import { A_Errors } from "src/containers/A-Errors/A-Errors.namespace";
+
+
+
+/**
+ * A_Concept is a placeholder for the concept of the ani program.
+ * 
+ * Concept - could be any Program regardless environment and it's goal.
+ * It could be mobile, web or simple html page.
+ * All depends on Containers and Components installed and provided in the Concept.
+ * 
+ * 
+ * [!] Concept operates ONLY with all Components and Containers provided to achieve the goal.
+ * 
+ * 
+ */
+export class A_Concept {
+
+
+    /**
+     * Context is a root namespace for the concept.
+     */
+    Context!: typeof A_Context;
+
+    /**
+     * Context provider is a singleton that provides the context for ALL concepts.
+     */
+
+    protected props!: A_TYPES__IConceptConstructor;
+
+    constructor(
+        props: A_TYPES__IConceptConstructor
+    ) {
+        this.props = props;
+
+        this.Context = A_Context;
+    }
+
+
+    get namespace() {
+        return this.Context.root
+    }
+
+
+    /**
+     * Returns true if the class has inherited from the given class.
+     * 
+     * @param cl 
+     * @returns 
+     */
+    private hasInherited(cl: { new(...args: any[]) }): boolean {
+        return this.constructor === cl
+            ? false
+            : true
+    }
+
+
+
+
+    protected async init() {
+        // await this.Context.init();
+
+        // await this.DM.init();
+    }
+
+
+
+    // =======================================================================
+    // ==========================  LIFECYCLE  ================================
+    // =======================================================================
+
+    /**
+     * Run the concept.
+     */
+    async run(
+        params: A_TYPES__A_CONCEPT_RootRunParams = {}
+    ) {
+
+        //  to prevent modification of the method parameters use the A_Context directly without decorators 
+        const [
+            Errors
+        ] = this.Context.resolve([A_Errors]);
+
+        if (this.hasInherited(A_Concept))
+            Errors.throw('[root.run] method can not be overridden in the inherited classes');
+
+
+        // const allRunDeclarations = A_CONCEPT_LifecycleDeclarationsStorage
+        //     .get(A_CONCEPT_STORAGE__DECORATORS_RUN_DECLARATIONS);
+    }
+
+
+    /**
+     * Build the concept.
+     */
+    async build() {
+        //  to prevent modification of the method parameters use the A_Context directly without decorators 
+        const [
+            Errors
+        ] = this.Context.resolve([A_Errors]);
+
+
+        if (this.hasInherited(A_Concept))
+            Errors.throw('[root.build] method can not be overridden in the inherited classes');
+
+    }
+
+
+    // /**
+    //  * Deploy the concept.
+    //  */
+    // async deploy() {
+    //     if (this.hasInherited(A_Concept))
+    //         this.Context.Errors.throw('[root.deploy] method can not be overridden in the inherited classes');
+    // }
+
+
+    // /**
+    //  * Publish the concept.
+    //  */
+    // async publish() {
+    //     if (this.hasInherited(A_Concept))
+    //         this.Context.Errors.throw('[root.publish] method can not be overridden in the inherited classes');
+    // }
+
+
+    /**
+     * Call the specific method of the concept or included modules.
+     */
+    async call() {
+        //  to prevent modification of the method parameters use the A_Context directly without decorators 
+        const [
+            Errors
+        ] = this.Context.resolve([A_Errors]);
+
+        // if (this.hasInherited(A_Concept))
+        //     this.Context.Errors.throw('[root.call] method can not be overridden in the inherited classes');
+    }
+
+}

package/src/global/A-Concept/A_Concept.types.ts

@@ -0,0 +1,44 @@
+import { A_Concept } from "./A_Concept.class";
+import { A_Namespace } from "../A-Namespace/A_Namespace.class";
+import { A_Container } from "../A-Container/A-Container.class";
+
+
+export interface A_TYPES__IConceptConstructor {
+    name: string,
+    description?: string,
+
+    /**
+     * A set of Namespaces that the concept depends on. 
+     * These namespaces will create a new Context for the concept.
+     * 
+     */
+    context?: Array<A_Namespace>,
+
+
+    /**
+     * A set of Containers that the concept depends on. 
+     * These containers will create a new Container for the concept.
+     */
+    containers?: Array<{ new(...args: any[]): A_Container }>,
+
+
+    /**
+     * A set of external Concepts that can be used in the current Concept. 
+     * To provide additional functionality or extend the current Concept.
+     */
+    import?: Array<A_Concept>
+}
+
+
+
+
+// =======================================================================
+// =======================================================================
+// ===================== A CONCEPT LIFE CYCLE ============================
+// =======================================================================
+// =======================================================================
+
+export type A_TYPES__A_CONCEPT_RootRunParams = {
+
+
+}

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

@@ -0,0 +1,39 @@
+import { A_Namespace } from "../A-Namespace/A_Namespace.class";
+
+
+
+/**
+ * This class should combine Components to achieve the goal withing Context 
+ * Container could be interpreted as any Structure Entity, or Abstract Entity
+ * For example:
+ * - Controller (all Controllers with base logic)
+ * - Service (all Services with base logic)
+ * - Module (all Modules with base logic)
+ * - etc.
+ */
+export class A_Container<T extends A_Namespace = A_Namespace> {
+
+    protected readonly namespace!: T;
+
+
+    constructor(
+        namespace?: T
+    ) {
+        if (namespace) {
+            this.namespace = namespace;
+        }
+    }
+
+
+    // bind(
+    //     Context: T,
+    //     /**
+    //      * Context provider from parent Concept
+    //      * It's possible to use the same ContextProvider for all Containers
+    //      */
+    //     ContextProvider: A_ContextProvider
+    // ) {
+    //     this.Context = Context;
+    // }
+
+}

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

@@ -0,0 +1,230 @@
+import { A_CommonHelper, A_Polyfills } from "@adaas/a-utils";
+import { A_Namespace } from "../A-Namespace/A_Namespace.class";
+import { A_Component } from "../A-Component/A-Component.class";
+
+
+/**
+ * Namespace Provider is responsible for providing the Namespace to the Containers and other Namespaces.
+ * This class stores all Namespaces across the Program.
+ *  
+ * Namespace provider is a singleton class that is used to store all the Namespaces in the program.
+ * 
+ */
+export class A_Context {
+
+
+    static instance: A_Context;
+
+    /**
+     * Stores all the Namespaces by namespace.
+     * There might be a Namespaces of the same type but with different namespaces.
+     * That might be useful for the cases when you need to have multiple instances of the same Namespace e.g.
+     * - multiple http servers
+     * - multitenant applications
+     * - etc.
+     */
+    namespaced: Map<string, A_Namespace> = new Map();
+
+    /**
+     * Stores the singleton Namespaces. 
+     * Singleton Namespaces are the Namespaces that are used only once in the program.
+     * In most cases, the singleton Namespace is the main Namespace of the program.
+     * It could be :
+     * - the main Namespace of the Program
+     * - the authentication Namespace
+     * - the main database Namespace
+     * - etc.
+     */
+    singleton: WeakMap<{ new(...args: any[]): A_Namespace }, A_Namespace> = new WeakMap();
+
+
+    /**
+     * Stores the components that are used in the program.
+     */
+    components: Map<string, any> = new Map();
+
+    /**
+     * Root Namespace is a Namespace that is used to run the program.
+     */
+    private _root!: string
+
+
+    private constructor() {
+
+    }
+
+    /**
+     * Get the instance of the Namespace Provider.
+     * 
+     * @returns 
+     */
+    static getInstance() {
+        if (!A_Context.instance) {
+            A_Context.instance = new A_Context();
+        }
+
+        return A_Context.instance;
+    }
+
+    static get root(): string {
+        return this.getInstance()._root;
+    }
+
+    static get environment(): 'server' | 'browser' {
+        return A_Polyfills.env;
+    }
+
+    /**
+     * Register a Namespace in the provider.
+     * @param Namespace 
+     */
+    static register(Namespace: A_Namespace): string
+    static register(
+        Namespace: A_Namespace,
+        namespace?: string
+    ): string
+    static register(
+        param1: A_Namespace,
+        param2?: A_Namespace | string,
+    ): string {
+
+        const instance = this.getInstance();
+
+        let Namespace: A_Namespace;
+        let namespace: string;
+
+        if (typeof param2 === 'string') {
+            namespace = param2;
+            Namespace = param1;
+        } else {
+            Namespace = param1 as A_Namespace;
+            namespace = Namespace.name;
+        }
+
+        /**
+         * If the namespace is not provided, then use the root namespace.
+         * If the root namespace is not provided, then use the default namespace.
+         */
+        if (!namespace)
+            namespace = this.root
+                || process.env.ADAAS_NAMESPACE
+                || process.env.A_NAMESPACE
+                || process.env.ADAAS_APP_NAMESPACE
+                || 'a-concept'
+
+
+
+        if (!this.root)
+            instance._root = namespace;
+
+        instance.namespaced.set(namespace, Namespace);
+
+        return namespace;
+    }
+
+
+
+
+
+
+    /**
+     * Get the Namespace by namespace.
+     * @param namespace 
+     */
+    static get(namespace: string) {
+        const instance = this.getInstance();
+
+        return instance.namespaced.get(namespace)
+    }
+
+
+
+
+
+    /**
+     * Resolve the Component by Class. 
+     * 
+     * @param component 
+     */
+    static resolve<T extends A_Component>(
+        component: { new(...args: any[]): T }
+    ): T
+    static resolve<T extends A_Namespace>(
+        namespace: { new(...args: any[]): T }
+    ): T
+    static resolve<
+        T extends A_Namespace,
+    >(
+        namespaces: Array<{ new(...args: any[]): T }>
+    ): Array<T>
+    static resolve<T extends A_Namespace>(
+        namespace: { new(...args: any[]): T },
+        name: string
+    ): T
+    static resolve<
+        T extends A_Namespace,
+        K extends A_Component,
+    >(
+        param1: { new(...args: any[]): T } | { new(...args: any[]): K } | Array<{ new(...args: any[]): T }>,
+        param2?: string
+    ): T | K | Array<T> {
+
+        switch (true) {
+
+            // If the first parameter is a Namespace 
+            case Array.isArray(param1) && param1.every(namespace => A_CommonHelper.isInheritedFrom(namespace, A_Namespace)):
+                return param1.map(namespace => this.resolveNamespace(namespace));
+
+            // If the first parameter is a Namespace and the second parameter is a string
+            case !!param2 && typeof param1 === 'function' && A_CommonHelper.isInheritedFrom(param1, A_Namespace):
+                return this.resolveNamespace(param1 as typeof A_Namespace, param2) as T;
+
+            // If the first parameter is a Component
+            case !!param2 && typeof param1 === 'function' && A_CommonHelper.isInheritedFrom(param1, A_Component):
+                return this.resolveComponent(param1 as { new(...args: any[]): A_Component }) as K;
+
+            default:
+                throw new Error(`[!] A-Concept Context: Unknown type of the parameter.`);
+        }
+    }
+
+
+
+    private static resolveComponent<T extends A_Component>(
+        component: { new(...args: any[]): T }
+    ): T {
+        const instance = this.getInstance();
+
+        return instance.components.get(component.name) as T;
+    }
+
+
+
+    /**
+     * 
+     * Allowing to resolve the Namespace by Class and Name.
+     * 
+     * @param namespace 
+     * @param name 
+     */
+    private static resolveNamespace<T extends A_Namespace>(
+        namespace: { new(...args: any[]): T },
+        name: string
+    ): T
+    private static resolveNamespace<T extends A_Namespace>(
+        namespace: { new(...args: any[]): T }
+    ): T
+    private static resolveNamespace<T extends A_Namespace>(
+        param1: { new(...args: any[]): T },
+        param2?: string
+    ): T {
+        const instance = this.getInstance();
+
+        return instance.namespaced.get(
+            param2 || param1.name
+        ) as T;
+    }
+
+
+
+}

package/src/global/A-Dependency/A-DependencyReference.class.ts

@@ -0,0 +1,61 @@
+class RealDependency {
+    constructor(private name: string) { }
+
+    getName() {
+        return this.name;
+    }
+
+    performAction() {
+        console.log(`${this.name} is performing an action.`);
+    }
+}
+
+class DependencyReference<T> {
+    private proxyInstance: T | null = null;
+    private realInstance: T | null = null;
+
+    constructor(private realClass: { new(...args: any[]): T }, private args: any[]) { }
+
+    // Simulate async loading (e.g., dynamic imports, API calls, etc.)
+    private async loadInstance(): Promise<T> {
+        if (!this.realInstance) {
+            console.log('Loading real dependency...');
+            // Simulate async loading with a delay
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+            this.realInstance = new this.realClass(...this.args);
+        }
+        return this.realInstance;
+    }
+
+    public async resolve(): Promise<T> {
+        if (!this.proxyInstance) {
+            const realInstance = await this.loadInstance();
+
+            this.proxyInstance = new Proxy({}, {
+                get: (target, prop) => {
+                    const value = (realInstance as any)[prop];
+
+                    // If the property is a method, return a bound function
+                    if (typeof value === 'function') {
+                        return value.bind(realInstance);
+                    }
+                    return value;
+                }
+            }) as T;
+        }
+
+        return this.proxyInstance;
+    }
+}
+
+
+// Example usage:
+(async () => {
+    const lazyDependency = new DependencyReference(RealDependency, ['ComponentA']);
+
+    const proxy = await lazyDependency.resolve();  // Loads the instance asynchronously
+
+    proxy.performAction();  // Will call the method on the real instance
+
+    console.log(proxy.getName());  // Calls method on the real instance
+})();

package/src/global/A-Dependency/A-DependencyReference.types.ts

@@ -0,0 +1,61 @@
+import { A_Namespace } from "@adaas/a-concept/global/A-Namespace/A_Namespace.class"
+
+
+export type A_TYPES__A_DependencyReferenceConstructor = {
+    /**
+     * The name of the dependency 
+     */
+    name: string
+    /**
+     * The version of the module 
+     * By default it is 1.0.0
+     */
+    version: string
+    /**
+     * The dependencies of the module 
+     * Could be:
+     * - other Modules
+     * - other Contexts
+     * 
+     */
+    dependencies: Array<typeof A_Namespace>
+    /**
+     * The source of the dependency 
+     * Could be:
+     * - a string representing the path to the module
+     * - a module class  (in case when config should be provided via the module constructor)
+     * - a module class constructor
+     * - a context class (in case when config should be provided via the context constructor)
+     * - a context class constructor
+     * 
+     */
+    // source: A_Module | A_Context | typeof A_Module | typeof A_Context | string
+    source: A_Namespace
+}
+
+
+export type A_TYPES__A_DependencyReferenceConstructorConfig = {
+    /**
+     * Sync  - blocks A-Express Application initialization until module is ready 
+     * Async - allows to initialize module after A-Express Application initialization
+     */
+    behavior: 'async' | 'sync',
+
+    /**
+     * Allows to define a scheme of retries
+     */
+    retries: {
+        /**
+         * The number of retries
+         * Default is 3
+         */
+        n: number,
+        /**
+         * The timeout between retries
+         * Multiplied by the number of retries 
+         * So after each retry the timeout is increased e.g. 1000ms * 1, 1000ms * 2, 1000ms * 3
+         * Default is 1000
+         */
+        timeout: number
+    }
+}

package/src/global/A-Namespace/A_Namespace.class.ts

@@ -0,0 +1,128 @@
+import { A_Polyfills } from '@adaas/a-utils';
+import {
+    A_TYPES__NamespaceConstructor,
+    A_TYPES__INamespace,
+} from './A_Namespace.types';
+import { A_Context } from '../A-Context/A-Context.class';
+
+
+/**
+ * A_Namespace is a base class for all Namespaces in the A
+ * 
+ * Namespace is a shared object within some environment, service or Application. 
+ * It is used to share some data, configuration, dependencies, etc. between different parts of the application.
+ * 
+ * Namespace allow to :
+ * - share some data between different parts of the application, 
+ * - share some configuration between different parts of the application,
+ * - share some dependencies between different parts of the application,
+ * - extend the capabilities of the application by adding new features or modifying existing ones into base classes
+ *
+ */
+export class A_Namespace<
+    _ConstructorConfigType extends A_TYPES__NamespaceConstructor = any
+> implements A_TYPES__INamespace {
+
+    /**
+     * Namespace namespace
+     */
+    name!: string;
+
+    /**
+     * Ready Promise to ensure the SDK is ready to use
+     */
+    ready!: Promise<void>;
+
+    constructor(
+        protected config?: _ConstructorConfigType
+    ) {
+        /**
+         * Register the Namespace in the global Namespace provider
+         */
+        this.name = A_Context
+            .register(
+                this,
+                config?.name
+            );
+
+        /**
+         * Run Async Initialization
+         */
+        this.init();
+    }
+
+
+
+    private hasInherited(cl: { new(...args: any[]) }): boolean {
+        return this.constructor === cl
+            ? false
+            : true
+    }
+
+    /**
+     * Initializes the Namespace or can be used to reinitialize the Namespace
+     */
+    protected async init() {
+        if (!this.ready)
+            this.ready = new Promise(async (resolve, reject) => {
+                try {
+                    await this.onBeforeInit();
+
+                    await this.onInit();
+
+                    await this.onAfterInit();
+
+                    return resolve();
+                } catch (error) {
+                    return reject(error);
+                }
+            });
+        else
+            await this.ready;
+    }
+
+
+
+    // ==============================================================
+    // ======================= HOOKS ================================
+    // ==============================================================
+
+    /**
+     *  Before init hook to be used in inherited classes
+     * 
+     * @returns 
+     */
+    protected async onBeforeInit() {
+        return;
+    }
+
+    /**
+     * Main initialization method for the SDK
+     */
+    protected async onInit() {
+
+        // global logger configuration
+        if (A_Context.environment === 'server' && !this.hasInherited(A_Namespace)) {
+            // eslint-disable-next-line no-use-before-define
+            // process.on('uncaughtException', (error) => {
+            //     // log only in case of A_AUTH_Error
+            //     if (error instanceof A_Error)
+            //         this.Logger.error(error);
+            // });
+            // // eslint-disable-next-line no-use-before-define
+            // process.on('unhandledRejection', (error) => {
+            //     if (error instanceof A_Error)
+            //         this.Logger.error(error);
+            // });
+        }
+    }
+
+    /**
+     *  After init hook to be used in inherited classes
+     * 
+     * @returns 
+     */
+    protected async onAfterInit() {
+        return;
+    }
+}