@adaas/a-concept 0.3.6 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaas/a-concept",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "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,13 @@
   },
   "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:feature-optimize": "ts-node -r tsconfig-paths/register benchmarks/feature-optimize.bench.ts",
+    "bench:feature-chaining": "ts-node -r tsconfig-paths/register benchmarks/feature-chaining.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 +74,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-Entity/A-Entity.class.ts

@@ -269,17 +269,17 @@ export class A_Entity<
      * @param lifecycleMethod 
      * @param args 
      */
-    async call(
+     call(
         feature: string,
         scope?: A_Scope
-    ) {
+    ): Promise<any> | void {
         const newFeature = new A_Feature({
             name: feature,
             component: this,
             scope
         });
 
-        return await newFeature.process(scope);
+        return  newFeature.process(scope);
     }
 
 

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

@@ -12,7 +12,7 @@ import {
     A_StageError
 } from "@adaas/a-concept/a-stage";
 import { A_StepsManager } from "@adaas/a-concept/a-step-manager";
-import { A_TypeGuards} from "@adaas/a-concept/helpers/A_TypeGuards.helper";
+import { A_TypeGuards } from "@adaas/a-concept/helpers/A_TypeGuards.helper";
 import { A_FeatureError } from "./A-Feature.error";
 import { A_Context } from "@adaas/a-concept/a-context";
 import { A_Caller } from "@adaas/a-concept/a-caller";
@@ -203,7 +203,7 @@ export class A_Feature<T extends A_TYPES__FeatureAvailableComponents = A_TYPES__
         if (!params || typeof params !== 'object') {
             throw new A_FeatureError(
                 A_FeatureError.FeatureInitializationError,
-                `Invalid A-Feature initialization parameters of type: ${typeof params} with value: ${JSON.stringify(params).slice(0, 100)}...`
+                `Invalid A-Feature initialization parameters of type: ${typeof params} with value: ${JSON.stringify(params)?.slice(0, 100)}...`
             );
         }
     }
@@ -226,7 +226,7 @@ export class A_Feature<T extends A_TYPES__FeatureAvailableComponents = A_TYPES__
             default:
                 throw new A_FeatureError(
                     A_FeatureError.FeatureInitializationError,
-                    `Invalid A-Feature initialization parameters of type: ${typeof params} with value: ${JSON.stringify(params).slice(0, 100)}...`
+                    `Invalid A-Feature initialization parameters of type: ${typeof params} with value: ${JSON.stringify(params)?.slice(0, 100)}...`
                 );
         }
     }
@@ -241,14 +241,14 @@ export class A_Feature<T extends A_TYPES__FeatureAvailableComponents = A_TYPES__
         if (!params.template || !Array.isArray(params.template)) {
             throw new A_FeatureError(
                 A_FeatureError.FeatureInitializationError,
-                `Invalid A-Feature template provided of type: ${typeof params.template} with value: ${JSON.stringify(params.template).slice(0, 100)}...`
+                `Invalid A-Feature template provided of type: ${typeof params.template} with value: ${JSON.stringify(params.template)?.slice(0, 100)}...`
             );
         }
 
         if (!params.component && (!params.scope || !(params.scope instanceof A_Scope))) {
             throw new A_FeatureError(
                 A_FeatureError.FeatureInitializationError,
-                `Invalid A-Feature scope provided of type: ${typeof params.scope} with value: ${JSON.stringify(params.scope).slice(0, 100)}...`
+                `Invalid A-Feature scope provided of type: ${typeof params.scope} with value: ${JSON.stringify(params.scope)?.slice(0, 100)}...`
             );
         }
 
@@ -304,7 +304,7 @@ export class A_Feature<T extends A_TYPES__FeatureAvailableComponents = A_TYPES__
         if (!params.component || !A_TypeGuards.isAllowedForFeatureDefinition(params.component)) {
             throw new A_FeatureError(
                 A_FeatureError.FeatureInitializationError,
-                `Invalid A-Feature component provided of type: ${typeof params.component} with value: ${JSON.stringify(params.component).slice(0, 100)}...`
+                `Invalid A-Feature component provided of type: ${typeof params.component} with value: ${JSON.stringify(params.component)?.slice(0, 100)}...`
             );
         }
 
@@ -398,52 +398,57 @@ export class A_Feature<T extends A_TYPES__FeatureAvailableComponents = A_TYPES__
         scope: A_Scope | undefined,
         index: number
     ): Promise<void> | void {
-        try {
-            // Check if feature has been interrupted before processing next stage
-            if (this.state === A_TYPES__FeatureState.INTERRUPTED) {
-                return;
-            }
 
-            // If we've processed all stages, complete the feature
-            if (index >= stages.length) {
-                this.completed();
-                return;
-            }
+        // ── Sync loop — avoids stack overflow for all-sync chains ────────────────
+        while (index < stages.length) {
+
+            if (this.state === A_TYPES__FeatureState.INTERRUPTED) return
 
-            const stage = stages[index];
-            const result = stage.process(scope);
+            const stage = stages[index]
+            let result: Promise<void> | void
 
+            try {
+                result = stage.process(scope)
+            } catch (error) {
+                throw this.createStageError(error, stage)
+            }
+
+            // ── Async stage — hand off to promise chain ───────────────────────────
             if (A_TypeGuards.isPromiseInstance(result)) {
-                // Async stage - return promise that processes remaining stages
                 return result
                     .then(() => {
-                        // Check for interruption after async stage completes
-                        if (this.state === A_TYPES__FeatureState.INTERRUPTED) {
-                            return;
-                        }
-                        return this.processStagesSequentially(stages, scope, index + 1);
+                        if (this.state === A_TYPES__FeatureState.INTERRUPTED) return
+                        return this.processStagesSequentially(stages, scope, index + 1)
                     })
                     .catch(error => {
-                        throw this.failed(new A_FeatureError({
-                            title: A_FeatureError.FeatureProcessingError,
-                            description: `An error occurred while processing the A-Feature: ${this.name}. Failed at stage: ${stage.name}.`,
-                            stage: stage,
-                            originalError: error
-                        }));
-                    });
-            } else {
-                // Sync stage - continue to next stage immediately
-                return this.processStagesSequentially(stages, scope, index + 1);
+                        throw this.createStageError(error, stage)
+                    })
             }
-        } catch (error) {
-            throw this.failed(new A_FeatureError({
-                title: A_FeatureError.FeatureProcessingError,
-                description: `An error occurred while processing the A-Feature: ${this.name}. Failed at stage: ${this.stage?.name || 'N/A'}.`,
-                stage: this.stage,
-                originalError: error
-            }));
+
+            index++
+        }
+
+        // ── All stages complete ───────────────────────────────────────────────────
+        if (this.state !== A_TYPES__FeatureState.INTERRUPTED) {
+            this.completed()
         }
     }
+
+    private createStageError(error: unknown, stage: A_Stage): A_FeatureError {
+        this.failed(new A_FeatureError({
+            title: A_FeatureError.FeatureProcessingError,
+            description: `An error occurred while processing the A-Feature: ${this.name}. Failed at stage: ${stage.name}.`,
+            stage,
+            originalError: error,
+        }))
+
+        return new A_FeatureError({
+            title: A_FeatureError.FeatureProcessingError,
+            description: `An error occurred while processing the A-Feature: ${this.name}. Failed at stage: ${stage.name}.`,
+            stage,
+            originalError: error,
+        })
+    }
     /**
      * This method moves the feature to the next stage
      * 

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.