@adaas/a-concept 0.3.5 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaas/a-concept",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "A-Concept is a framework of the new generation that is tailored to use AI, enabling developers to create AI-powered applications with ease. It provides a structured approach to building, managing, and deploying AI-driven solutions.",
   "license": "Apache-2.0",
   "author": {
@@ -55,6 +55,11 @@
   },
   "scripts": {
     "test": "jest --detectOpenHandles",
+    "bench": "ts-node -r tsconfig-paths/register benchmarks/run-all.ts",
+    "bench:step-manager": "ts-node -r tsconfig-paths/register benchmarks/step-manager.bench.ts",
+    "bench:feature-template": "ts-node -r tsconfig-paths/register benchmarks/feature-template.bench.ts",
+    "bench:scope-resolve": "ts-node -r tsconfig-paths/register benchmarks/scope-resolve.bench.ts",
+    "bench:feature-lifecycle": "ts-node -r tsconfig-paths/register benchmarks/feature-lifecycle.bench.ts",
     "start": "nodemon ./tests/example-usage.ts",
     "example:simple": "nodemon ./examples/simple/concept.ts",
     "example:http": "nodemon ./examples/simple-http-server/concept.ts",
@@ -67,11 +72,14 @@
     "test:simple": "nodemon ./examples/simple/concept.ts"
   },
   "devDependencies": {
+    "@types/benchmark": "^2.1.5",
     "@types/chai": "^4.3.14",
     "@types/jest": "^29.5.14",
     "@types/mocha": "^10.0.6",
     "@types/node": "^24.9.1",
+    "benchmark": "^2.1.4",
     "chai": "^5.1.0",
+    "cli-table3": "^0.6.5",
     "dotenv": "^16.4.5",
     "jest": "^29.7.0",
     "mocha": "^10.4.0",

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

@@ -119,6 +119,26 @@ export class A_Context {
      */
     protected _metaStorage: Map<A_TYPES__MetaLinkedComponentConstructors, A_Meta> = new Map();
 
+    /**
+     * Monotonically increasing version counter for _metaStorage.
+     * Incremented whenever a new entry is added to _metaStorage so that
+     * caches depending on meta content can detect staleness.
+     */
+    protected _metaVersion: number = 0;
+
+    /**
+     * Cache for featureExtensions results.
+     * Key format: `${featureName}::${componentConstructorName}::${scopeVersion}::${metaVersion}`
+     * Automatically invalidated when scope version or meta version changes.
+     */
+    protected _featureExtensionsCache: Map<string, Array<A_TYPES__A_StageStep>> = new Map();
+
+    /**
+     * Maximum number of entries in the featureExtensions cache.
+     * When exceeded, the entire cache is cleared to prevent unbounded growth.
+     */
+    protected static readonly FEATURE_EXTENSIONS_CACHE_MAX_SIZE = 1024;
+
 
 
 
@@ -547,6 +567,7 @@ export class A_Context {
                 inheritedMeta = new metaType();
 
             instance._metaStorage.set(property, inheritedMeta.clone());
+            instance._metaVersion++;
         }
 
         // Return the meta for the property
@@ -590,6 +611,7 @@ export class A_Context {
             : param1.constructor as A_TYPES__MetaLinkedComponentConstructors;
 
         instance._metaStorage.set(constructor, existingMeta ? meta.from(existingMeta) : meta);
+        instance._metaVersion++;
     }
 
 
@@ -743,16 +765,13 @@ export class A_Context {
          */
         scope: A_Scope = this.scope(component)
     ): Array<A_TYPES__A_StageStep> {
-        // name for error messages
-        const componentName = A_CommonHelper.getComponentName(component);
-
-        // Input validation
+        // Input validation (defer expensive getComponentName to error paths only)
         if (!component) throw new A_ContextError(A_ContextError.InvalidFeatureTemplateParameterError, `Unable to get feature template. Component cannot be null or undefined.`);
         if (!name) throw new A_ContextError(A_ContextError.InvalidFeatureTemplateParameterError, `Unable to get feature template. Feature name cannot be null or undefined.`);
 
         // Check if the parameter is allowed for feature definition
         if (!A_TypeGuards.isAllowedForFeatureDefinition(component))
-            throw new A_ContextError(A_ContextError.InvalidFeatureTemplateParameterError, `Unable to get feature template. Component of type ${componentName} is not allowed for feature definition.`);
+            throw new A_ContextError(A_ContextError.InvalidFeatureTemplateParameterError, `Unable to get feature template. Component of type ${A_CommonHelper.getComponentName(component)} is not allowed for feature definition.`);
 
         const steps: A_TYPES__A_StageStep[] = [
             // 1) Get the base feature definition from the component
@@ -791,76 +810,124 @@ export class A_Context {
     ): Array<A_TYPES__A_StageStep> {
 
         const instance = this.getInstance();
-        // name for error messages
-        const componentName = A_CommonHelper.getComponentName(component);
 
-        // Input validation
+        // Input validation (defer expensive getComponentName to error paths only)
         if (!component) throw new A_ContextError(A_ContextError.InvalidFeatureExtensionParameterError, `Unable to get feature template. Component cannot be null or undefined.`);
         if (!name) throw new A_ContextError(A_ContextError.InvalidFeatureExtensionParameterError, `Unable to get feature template. Feature name cannot be null or undefined.`);
 
         // Check if the parameter is allowed for feature definition
         if (!A_TypeGuards.isAllowedForFeatureDefinition(component))
-            throw new A_ContextError(A_ContextError.InvalidFeatureExtensionParameterError, `Unable to get feature template. Component of type ${componentName} is not allowed for feature definition.`);
-
+            throw new A_ContextError(A_ContextError.InvalidFeatureExtensionParameterError, `Unable to get feature template. Component of type ${A_CommonHelper.getComponentName(component)} is not allowed for feature definition.`);
+
+        // ---- Optimization 1: Check featureExtensions cache ----
+        // Use the effective scope for cache key — the scope that actually contains registered components.
+        // Feature scopes are ephemeral (unique uid per call) and only inherit from the component scope,
+        // so use the parent scope identity when available to enable cache hits across feature calls.
+        const componentCtor = typeof component === 'function' ? component : component.constructor;
+        const effectiveScope = scope.parent || scope;
+        const cacheKey = `${String(name)}::${componentCtor.name}::s${effectiveScope.uid}v${effectiveScope.version}::m${instance._metaVersion}`;
+
+        const cached = instance._featureExtensionsCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
 
         const callNames = A_CommonHelper.getClassInheritanceChain(component)
             .filter(c => c !== A_Component && c !== A_Container && c !== A_Entity)
             .map(c => `${c.name}.${name}`);
 
-        // const callNames = [`${A_CommonHelper.getComponentName(component)}.${name}`];
-        // const callNames = [`BaseComponent.testFeature`];
-
         const steps: Map<string, A_TYPES__A_StageStep> = new Map();
 
         const allowedComponents: Set<A_TYPES__MetaLinkedComponentConstructors> = new Set();
 
-        for (const callName of callNames) {
-            // We need to get all components that has extensions for the feature in component
-            for (const [cmp, meta] of instance._metaStorage) {
-                // Just try to make sure that component not only Indexed but also presented in scope
-                if (scope.has(cmp) && (
-                    A_TypeGuards.isComponentMetaInstance(meta)
-                    ||
-                    A_TypeGuards.isContainerMetaInstance(meta)
-                )) {
-                    allowedComponents.add(cmp);
-                    // Get all extensions for the feature
-                    meta
-                        .extensions(callName)
-                        .forEach((declaration) => {
-                            const inherited = Array.from(allowedComponents).reverse().find(c => A_CommonHelper.isInheritedFrom(cmp, c) && c !== cmp);
-
-                            if (inherited) {
-                                steps.delete(`${A_CommonHelper.getComponentName(inherited)}.${declaration.handler}`);
-                            }
+        // ---- Optimization 2: Pre-cache component names and dependencies ----
+        // Avoid repeated getComponentName() and new A_Dependency() for the same constructor
+        const componentNameCache = new Map<A_TYPES__MetaLinkedComponentConstructors, string>();
+        const dependencyCache = new Map<A_TYPES__MetaLinkedComponentConstructors, A_Dependency>();
+        const getNameCached = (cmp: A_TYPES__MetaLinkedComponentConstructors): string => {
+            let n = componentNameCache.get(cmp);
+            if (n === undefined) {
+                n = A_CommonHelper.getComponentName(cmp);
+                componentNameCache.set(cmp, n);
+            }
+            return n;
+        };
+        const getDependencyCached = (cmp: A_TYPES__MetaLinkedComponentConstructors): A_Dependency => {
+            let d = dependencyCache.get(cmp);
+            if (!d) {
+                d = new A_Dependency(cmp);
+                dependencyCache.set(cmp, d);
+            }
+            return d;
+        };
+
+        // ---- Optimization 3: Build a local set of metas that are in scope ----
+        // Pre-filter _metaStorage entries to only those present in scope,
+        // avoiding repeated scope.has() calls per callName iteration.
+        const scopeFilteredMetas: Array<[A_TYPES__MetaLinkedComponentConstructors, A_ComponentMeta | A_ContainerMeta]> = [];
+        for (const [cmp, meta] of instance._metaStorage) {
+            if (scope.has(cmp) && (
+                A_TypeGuards.isComponentMetaInstance(meta)
+                ||
+                A_TypeGuards.isContainerMetaInstance(meta)
+            )) {
+                scopeFilteredMetas.push([cmp, meta as A_ComponentMeta | A_ContainerMeta]);
+            }
+        }
 
-                            // Check if the declaration has an override regexp and remove matching steps
-                            // Match against both the full step key (Component.handler) and the handler alone
-                            if (declaration.override) {
-                                const overrideRegexp = new RegExp(declaration.override);
-                                for (const [stepKey, step] of steps) {
-                                    if (overrideRegexp.test(stepKey) || overrideRegexp.test(step.handler)) {
-                                        steps.delete(stepKey);
-                                    }
-                                }
+        for (const callName of callNames) {
+            // Use pre-filtered list instead of iterating all _metaStorage
+            for (const [cmp, meta] of scopeFilteredMetas) {
+                allowedComponents.add(cmp);
+                // Get all extensions for the feature
+                const extensions = meta.extensions(callName);
+
+                for (let i = 0; i < extensions.length; i++) {
+                    const declaration = extensions[i];
+                    const inherited = Array.from(allowedComponents).reverse().find(c => A_CommonHelper.isInheritedFrom(cmp, c) && c !== cmp);
+
+                    if (inherited) {
+                        steps.delete(`${getNameCached(inherited)}.${declaration.handler}`);
+                    }
+
+                    // Check if the declaration has an override regexp and remove matching steps
+                    // Match against both the full step key (Component.handler) and the handler alone
+                    if (declaration.override) {
+                        const overrideRegexp = new RegExp(declaration.override);
+                        for (const [stepKey, step] of steps) {
+                            if (overrideRegexp.test(stepKey) || overrideRegexp.test(step.handler)) {
+                                steps.delete(stepKey);
                             }
+                        }
+                    }
 
-                            steps.set(`${A_CommonHelper.getComponentName(cmp)}.${declaration.handler}`, {
-                                dependency: new A_Dependency(cmp),
-                                ...declaration
-                            });
-                        });
+                    steps.set(`${getNameCached(cmp)}.${declaration.handler}`, {
+                        dependency: getDependencyCached(cmp),
+                        ...declaration
+                    });
                 }
             }
         }
 
-        return instance.filterToMostDerived(scope, Array.from(steps.values()));
+        const result = instance.filterToMostDerived(scope, Array.from(steps.values()));
+
+        // ---- Store result in cache ----
+        if (instance._featureExtensionsCache.size >= A_Context.FEATURE_EXTENSIONS_CACHE_MAX_SIZE) {
+            instance._featureExtensionsCache.clear();
+        }
+        instance._featureExtensionsCache.set(cacheKey, result);
+
+        return result;
     }
 
 
     /**
      * method helps to filter steps in a way that only the most derived classes are kept.
      * 
+     * Optimized: Uses a pre-built constructor→class map and single-pass prototype chain
+     * walk to eliminate parent classes in O(n·d) where d is inheritance depth,
+     * instead of the previous O(n²) with isPrototypeOf checks.
+     * 
      * @param scope 
      * @param items 
      * @returns 
@@ -868,24 +935,50 @@ export class A_Context {
     private filterToMostDerived(
         scope: A_Scope,
         items: A_TYPES__A_StageStep[]): Array<A_TYPES__A_StageStep> {
-        return items.filter(item => {
-            // const currentClass = scope.resolveConstructor(item.dependency.name)
-            const currentClass = scope.resolveConstructor(item.dependency.name)
 
-            // Check if this class is parent of any other in the list
-            const isParentOfAnother = items.some(other => {
-                if (other === item) return false;
+        if (items.length <= 1) return items;
+
+        // 1) Resolve all dependency names to actual constructor classes
+        //    and build a Set of dependency names present in the items list
+        const resolvedClasses = new Map<string, Function | undefined>();
+        const presentNames = new Set<string>();
+
+        for (const item of items) {
+            const depName = item.dependency.name;
+            if (!resolvedClasses.has(depName)) {
+                resolvedClasses.set(depName, scope.resolveConstructor(depName) as Function | undefined);
+            }
+            presentNames.add(depName);
+        }
+
+        // 2) Build a set of dependency names that are parents of at least one other item.
+        //    For each resolved class, walk up its prototype chain and mark any ancestor
+        //    that also appears in presentNames as "is parent of another".
+        const parentNames = new Set<string>();
 
-                const otherClass = scope.resolveConstructor(other.dependency.name);
+        // Build reverse map: constructor → dependency name (for fast lookup when walking prototypes)
+        const ctorToName = new Map<Function, string>();
+        for (const [depName, ctor] of resolvedClasses) {
+            if (ctor) ctorToName.set(ctor, depName);
+        }
 
-                if (!currentClass || !otherClass) return false;
+        for (const [depName, ctor] of resolvedClasses) {
+            if (!ctor) continue;
 
-                return currentClass.prototype.isPrototypeOf(otherClass.prototype);
-            });
+            // Walk prototype chain of this class's prototype to find ancestors
+            let ancestor = Object.getPrototypeOf(ctor.prototype);
+            while (ancestor && ancestor !== Object.prototype) {
+                const ancestorCtor = ancestor.constructor;
+                const ancestorName = ctorToName.get(ancestorCtor);
+                if (ancestorName && ancestorName !== depName && presentNames.has(ancestorName)) {
+                    parentNames.add(ancestorName);
+                }
+                ancestor = Object.getPrototypeOf(ancestor);
+            }
+        }
 
-            // Keep only classes that are not parent of any other
-            return !isParentOfAnother;
-        });
+        // 3) Filter: keep only items whose dependency name is NOT in parentNames
+        return items.filter(item => !parentNames.has(item.dependency.name));
     }
 
 
@@ -1070,6 +1163,8 @@ export class A_Context {
         const instance = A_Context.getInstance();
 
         instance._registry = new WeakMap();
+        instance._featureExtensionsCache.clear();
+        instance._metaVersion++;
 
         const name = String(A_CONCEPT_ENV.A_CONCEPT_ROOT_SCOPE) || 'root';
 

package/src/lib/A-Feature/A-Feature-Extend.decorator.ts

@@ -177,18 +177,34 @@ export function A_Feature_Extend(
         ];
 
         //  ensure that other regexps are preserved
+        //  Only remove the handler from another regexp if that regexp targets
+        //  the SAME feature name (i.e., same feature, different scope — inheritance case).
+        //  If the other regexp targets a DIFFERENT feature, leave it alone so that
+        //  the same method can serve multiple features.
+        const currentFeatureName = (param1 && typeof param1 === 'object' && !A_TypeGuards.isRegExp(param1) && (param1 as Partial<A_TYPES__FeatureExtendDecoratorConfig>).name)
+            || propertyKey;
+
         for (const [key, handlers] of existedMeta.entries()) {
 
             const indexInAnother = handlers.findIndex(item => item.handler === propertyKey);
 
-            //  if the same handler exists in another regexp, remove it
+            //  if the same handler exists in another regexp, check if it's the same feature
             if (key !== targetRegexp.source && indexInAnother !== -1) {
-                handlers.splice(indexInAnother, 1);
-                //  if no handlers left for this regexp, remove the regexp entry
-                if (handlers.length === 0) {
-                    existedMeta.delete(key);
-                } else {
-                    existedMeta.set(key, handlers);
+                //  Extract the feature name from the other regexp key
+                //  Regexp keys are built as: ^...\.featureName$ or .*\.featureName$
+                const keyStr = String(key);
+                const featureNameMatch = keyStr.match(/\\\.\s*([^\\.$]+)\$$/);
+                const otherFeatureName = featureNameMatch ? featureNameMatch[1] : null;
+
+                //  Only clean up if the other regexp targets the same feature name
+                if (otherFeatureName === currentFeatureName) {
+                    handlers.splice(indexInAnother, 1);
+                    //  if no handlers left for this regexp, remove the regexp entry
+                    if (handlers.length === 0) {
+                        existedMeta.delete(key);
+                    } else {
+                        existedMeta.set(key, handlers);
+                    }
                 }
             }
         }

package/src/lib/A-Feature/A-Feature.types.ts

@@ -159,12 +159,10 @@ export type A_TYPES__FeatureAvailableConstructors = A_TYPES__Component_Construct
 // ---------------------------------------------------------------------------
 /**
  * Indicates a type of Feature Define decorator
+ * 
+ * [!] Uses a single generic descriptor to support both sync and async methods
  */
-export type A_TYPES__FeatureDefineDecoratorDescriptor =
-    TypedPropertyDescriptor<(...args: any[]) => any>
-    | TypedPropertyDescriptor<(...args: any[]) => any>
-    | TypedPropertyDescriptor<(...args: any[]) => Promise<any>>
-    | TypedPropertyDescriptor<(...args: any[]) => Promise<any>>
+export type A_TYPES__FeatureDefineDecoratorDescriptor = TypedPropertyDescriptor<(...args: any[]) => any>
 /**
  * Describes additional configuration properties to be used in Feature Define decorator
  */
@@ -230,12 +228,10 @@ export type A_TYPES__FeatureDefineDecoratorMeta = {
 // ---------------------------------------------------------------------------
 /**
  * Descriptor type for A_Extend decorator
+ * 
+ * [!] Uses a single generic descriptor to support both sync and async methods
  */
-export type A_TYPES__FeatureExtendDecoratorDescriptor =
-    TypedPropertyDescriptor<() => any>
-    | TypedPropertyDescriptor<(...args: any[]) => any>
-    | TypedPropertyDescriptor<(...args: any[]) => Promise<any>>
-    | TypedPropertyDescriptor<() => Promise<any>>
+export type A_TYPES__FeatureExtendDecoratorDescriptor = TypedPropertyDescriptor<(...args: any[]) => any>
 /**
  * Target type for A_Extend decorator
  * 

package/src/lib/A-Meta/A-Meta.class.ts

@@ -130,10 +130,25 @@ export class A_Meta<
      * @param key 
      * @returns 
      */
+    /**
+     * Cache for compiled RegExp instances keyed by their string source.
+     * Avoids re-compiling the same regex pattern on every find() call.
+     */
+    private _regExpCache?: Map<string, RegExp>;
+
     private convertToRegExp(key: string | RegExp): RegExp {
-        return key instanceof RegExp
-            ? key
-            : new RegExp(key);
+        if (key instanceof RegExp) return key;
+
+        // Use cache to avoid re-compiling the same regex pattern repeatedly
+        if (!this._regExpCache) {
+            this._regExpCache = new Map();
+        }
+        let cached = this._regExpCache.get(key);
+        if (!cached) {
+            cached = new RegExp(key);
+            this._regExpCache.set(key, cached);
+        }
+        return cached;
     }
     /**
      * Method to find values in the map by name.