@adaas/a-concept 0.3.6 → 0.3.8

package/benchmarks/helpers.ts

@@ -0,0 +1,97 @@
+import Benchmark from 'benchmark';
+import Table from 'cli-table3';
+
+/**
+ * Result object collected after each benchmark completes
+ */
+export interface BenchResult {
+    name: string;
+    opsPerSec: string;
+    meanMs: string;
+    rme: string;
+    samples: number;
+}
+
+/**
+ * Creates and runs a Benchmark.js suite with formatted table output.
+ *
+ * @param suiteName  — Human-readable group name (printed as header)
+ * @param addBenchmarks — callback that receives `suite.add(...)` bound method
+ * @returns Promise that resolves with collected results
+ */
+export function createSuite(
+    suiteName: string,
+    addBenchmarks: (suite: Benchmark.Suite) => void
+): Promise<BenchResult[]> {
+    return new Promise((resolve) => {
+        const suite = new Benchmark.Suite(suiteName);
+        const results: BenchResult[] = [];
+
+        addBenchmarks(suite);
+
+        suite
+            .on('cycle', (event: Benchmark.Event) => {
+                const bench = event.target as any;
+                results.push({
+                    name: bench.name,
+                    opsPerSec: bench.hz.toFixed(2),
+                    meanMs: (bench.stats.mean * 1000).toFixed(4),
+                    rme: bench.stats.rme.toFixed(2),
+                    samples: bench.stats.sample.length,
+                });
+            })
+            .on('complete', () => {
+                printTable(suiteName, results);
+                resolve(results);
+            })
+            .run({ async: false });
+    });
+}
+
+/**
+ * Prints a formatted table of benchmark results to stdout
+ */
+export function printTable(title: string, results: BenchResult[]) {
+    console.log(`\n${'═'.repeat(70)}`);
+    console.log(`  📊  ${title}`);
+    console.log(`${'═'.repeat(70)}`);
+
+    const table = new Table({
+        head: ['Benchmark', 'ops/sec', 'mean (ms)', '± %', 'samples'],
+        colWidths: [40, 14, 14, 10, 10],
+        style: {
+            head: ['cyan'],
+        },
+    });
+
+    for (const r of results) {
+        table.push([r.name, r.opsPerSec, r.meanMs, `±${r.rme}%`, r.samples]);
+    }
+
+    console.log(table.toString());
+}
+
+/**
+ * Prints a summary comparison table across all suites
+ */
+export function printSummary(allResults: Map<string, BenchResult[]>) {
+    console.log(`\n${'═'.repeat(70)}`);
+    console.log(`  📋  PERFORMANCE SUMMARY`);
+    console.log(`${'═'.repeat(70)}`);
+
+    const table = new Table({
+        head: ['Suite', 'Benchmark', 'ops/sec', 'mean (ms)'],
+        colWidths: [25, 35, 14, 14],
+        style: {
+            head: ['green'],
+        },
+    });
+
+    for (const [suite, results] of allResults) {
+        for (const r of results) {
+            table.push([suite, r.name, r.opsPerSec, r.meanMs]);
+        }
+    }
+
+    console.log(table.toString());
+}

package/benchmarks/run-all.ts

@@ -0,0 +1,58 @@
+/**
+ * ============================================================
+ *  A-Concept Performance Benchmark Runner
+ * ============================================================
+ *
+ * Runs all benchmark suites and outputs a consolidated summary.
+ *
+ * Usage:
+ *   npx ts-node -r tsconfig-paths/register benchmarks/run-all.ts
+ *   npm run bench
+ */
+import { BenchResult, printSummary } from './helpers';
+import { runStepManagerBenchmarks } from './step-manager.bench';
+import { runFeatureTemplateBenchmarks } from './feature-template.bench';
+import { runScopeResolveBenchmarks } from './scope-resolve.bench';
+import { runFeatureLifecycleBenchmarks } from './feature-lifecycle.bench';
+
+
+async function main() {
+    console.log('\n🚀 Starting A-Concept Performance Benchmarks...\n');
+    console.log(`   Node.js ${process.version}`);
+    console.log(`   Date: ${new Date().toISOString()}`);
+    console.log(`   Platform: ${process.platform} ${process.arch}`);
+    console.log('');
+
+    const allSuites = new Map<string, BenchResult[]>();
+
+    // 1) StepManager benchmarks
+    console.log('\n📦 [1/4] A_StepsManager benchmarks...');
+    const smResults = await runStepManagerBenchmarks();
+    allSuites.set('StepManager', smResults);
+
+    // 2) Feature Template benchmarks
+    console.log('\n📦 [2/4] A_Context.featureTemplate benchmarks...');
+    const ftResults = await runFeatureTemplateBenchmarks();
+    allSuites.set('FeatureTemplate', ftResults);
+
+    // 3) Scope Resolve benchmarks
+    console.log('\n📦 [3/4] A_Scope resolve benchmarks...');
+    const srResults = await runScopeResolveBenchmarks();
+    allSuites.set('ScopeResolve', srResults);
+
+    // 4) Feature Lifecycle benchmarks
+    console.log('\n📦 [4/4] A_Feature lifecycle benchmarks...');
+    const flResults = await runFeatureLifecycleBenchmarks();
+    allSuites.set('FeatureLifecycle', flResults);
+
+    // Consolidated summary
+    printSummary(allSuites);
+
+    console.log('\n✅ All benchmarks completed.\n');
+}
+
+
+main().catch((err) => {
+    console.error('❌ Benchmark runner failed:', err);
+    process.exit(1);
+});

package/benchmarks/scope-resolve.bench.ts

@@ -0,0 +1,245 @@
+/**
+ * ============================================================
+ *  A_Scope Resolve Operations Performance Benchmarks
+ * ============================================================
+ *
+ * Measures:
+ *  - resolve() — single instance resolution (with parent chain traversal)
+ *  - resolveConstructor() — constructor lookup by name or type
+ *  - resolveAll() — batch resolution across scope hierarchy
+ *  - resolveDependency() — full dependency pipeline (filters, pagination)
+ *  - has() — existence checking with inheritance
+ *  - register() — registration performance
+ */
+import { A_Component } from "@adaas/a-concept/a-component";
+import { A_Entity } from "@adaas/a-concept/a-entity";
+import { A_Fragment } from "@adaas/a-concept/a-fragment";
+import { A_Scope } from "@adaas/a-concept/a-scope";
+import { A_Dependency } from "@adaas/a-concept/a-dependency";
+import { createSuite, BenchResult } from './helpers';
+
+
+// ──────────────────────────────────────────────────────────────
+// Fixture Classes
+// ──────────────────────────────────────────────────────────────
+
+class ComponentA extends A_Component { }
+class ComponentB extends A_Component { }
+class ComponentC extends A_Component { }
+class ComponentD extends A_Component { }
+class ComponentE extends A_Component { }
+
+class BaseComponent extends A_Component { }
+class DerivedComponent_A extends BaseComponent { }
+class DerivedComponent_B extends BaseComponent { }
+class DerivedComponent_C extends DerivedComponent_A { }
+
+class TestEntity extends A_Entity<{ foo: string }> {
+    public foo: string = 'default';
+
+    fromNew(params: { foo: string }) {
+        this.aseid = this.generateASEID();
+        this.foo = params.foo;
+    }
+}
+
+class TestFragment extends A_Fragment { }
+
+
+// ──────────────────────────────────────────────────────────────
+// Benchmark Suites
+// ──────────────────────────────────────────────────────────────
+
+export async function runScopeResolveBenchmarks(): Promise<BenchResult[]> {
+    const allResults: BenchResult[] = [];
+
+    // Suite 1: resolve() — single instance
+    const resolveResults = await createSuite('A_Scope.resolve — Single Instance', (suite) => {
+        // Flat scope
+        const flatScope = new A_Scope({
+            name: 'FlatScope',
+            components: [ComponentA, ComponentB, ComponentC, ComponentD, ComponentE]
+        });
+
+        // Nested scopes (3 levels)
+        const grandParent = new A_Scope({ name: 'GrandParent', components: [ComponentA] });
+        const parent = new A_Scope({ name: 'Parent', components: [ComponentB] });
+        const child = new A_Scope({ name: 'Child', components: [ComponentC] });
+        child.inherit(parent);
+        parent.inherit(grandParent);
+
+        suite
+            .add('resolve (flat, first component)', () => {
+                flatScope.resolve(ComponentA);
+            })
+            .add('resolve (flat, last component)', () => {
+                flatScope.resolve(ComponentE);
+            })
+            .add('resolve (nested, found in current)', () => {
+                child.resolve(ComponentC);
+            })
+            .add('resolve (nested, found in parent)', () => {
+                child.resolve(ComponentB);
+            })
+            .add('resolve (nested, found in grandparent)', () => {
+                child.resolve(ComponentA);
+            })
+            .add('resolve (not found)', () => {
+                flatScope.resolve(DerivedComponent_C);
+            });
+    });
+    allResults.push(...resolveResults);
+
+    // Suite 2: resolveConstructor()
+    const constructorResults = await createSuite('A_Scope.resolveConstructor', (suite) => {
+        const scope = new A_Scope({
+            name: 'ConstructorScope',
+            components: [ComponentA, DerivedComponent_A, DerivedComponent_B]
+        });
+
+        suite
+            .add('resolveConstructor (by class ref)', () => {
+                scope.resolveConstructor(ComponentA);
+            })
+            .add('resolveConstructor (by PascalCase name)', () => {
+                scope.resolveConstructor<ComponentA>('ComponentA');
+            })
+            .add('resolveConstructor (inherited class)', () => {
+                scope.resolveConstructor(BaseComponent);
+            })
+            .add('resolveConstructor (not found)', () => {
+                scope.resolveConstructor<ComponentE>('ComponentE');
+            });
+    });
+    allResults.push(...constructorResults);
+
+    // Suite 3: has() — existence checks
+    const hasResults = await createSuite('A_Scope.has — Existence Check', (suite) => {
+        const parentScope = new A_Scope({
+            name: 'ParentScope',
+            components: [ComponentA, ComponentB]
+        });
+        const childScope = new A_Scope({
+            name: 'ChildScope',
+            components: [ComponentC, ComponentD]
+        });
+        childScope.inherit(parentScope);
+
+        suite
+            .add('has (found in current scope)', () => {
+                childScope.has(ComponentC);
+            })
+            .add('has (found in parent scope)', () => {
+                childScope.has(ComponentA);
+            })
+            .add('has (not found anywhere)', () => {
+                childScope.has(ComponentE);
+            })
+            .add('has (by inheritance)', () => {
+                const scope = new A_Scope({
+                    name: 'InheritScope',
+                    components: [DerivedComponent_A]
+                });
+                scope.has(BaseComponent);
+            });
+    });
+    allResults.push(...hasResults);
+
+    // Suite 4: resolveAll() — batch resolution
+    const resolveAllResults = await createSuite('A_Scope.resolveAll — Batch Resolution', (suite) => {
+        const scope = new A_Scope({
+            name: 'BatchScope',
+            components: [DerivedComponent_A, DerivedComponent_B, DerivedComponent_C, ComponentE]
+        });
+
+        // Scope with entities
+        const entityScope = new A_Scope({ name: 'EntityScope' });
+        entityScope.register(TestEntity);
+        for (let i = 0; i < 20; i++) {
+            entityScope.register(new TestEntity({ foo: `val${i}` }));
+        }
+
+        // Nested scopes for resolveAll
+        const parentBatch = new A_Scope({
+            name: 'ParentBatch',
+            components: [DerivedComponent_A]
+        });
+        const childBatch = new A_Scope({
+            name: 'ChildBatch',
+            components: [DerivedComponent_B, DerivedComponent_C]
+        });
+        childBatch.inherit(parentBatch);
+
+        suite
+            .add('resolveAll (4 components, base class)', () => {
+                scope.resolveAll(BaseComponent);
+            })
+            .add('resolveAll (20 entities)', () => {
+                entityScope.resolveAll(TestEntity);
+            })
+            .add('resolveAll (nested scope)', () => {
+                childBatch.resolveAll(BaseComponent);
+            });
+    });
+    allResults.push(...resolveAllResults);
+
+    // Suite 5: resolveDependency() — full pipeline
+    const depResults = await createSuite('A_Scope.resolveDependency — Full Pipeline', (suite) => {
+        const scope = new A_Scope({
+            name: 'DepScope',
+            components: [ComponentA, ComponentB, ComponentC]
+        });
+
+        const entityScope = new A_Scope({ name: 'EntityDepScope' });
+        entityScope.register(TestEntity);
+        for (let i = 0; i < 10; i++) {
+            entityScope.register(new TestEntity({ foo: i < 5 ? 'bar' : 'baz' }));
+        }
+
+        const simpleDep = new A_Dependency(ComponentA);
+        const queryDep = new A_Dependency(TestEntity, { query: { foo: 'baz' } });
+        const paginatedDep = new A_Dependency(TestEntity, { pagination: { count: 5 } });
+
+        suite
+            .add('resolveDependency (simple)', () => {
+                scope.resolveDependency(simpleDep);
+            })
+            .add('resolveDependency (with query)', () => {
+                entityScope.resolveDependency(queryDep);
+            })
+            .add('resolveDependency (with pagination)', () => {
+                entityScope.resolveDependency(paginatedDep);
+            });
+    });
+    allResults.push(...depResults);
+
+    // Suite 6: register() performance
+    const registerResults = await createSuite('A_Scope.register — Registration', (suite) => {
+        suite
+            .add('register component (class)', () => {
+                const scope = new A_Scope({ name: 'RegScope' });
+                scope.register(ComponentA);
+            })
+            .add('register entity (instance)', () => {
+                const scope = new A_Scope({ name: 'RegScope' });
+                scope.register(new TestEntity({ foo: 'test' }));
+            })
+            .add('register 5 components', () => {
+                const scope = new A_Scope({ name: 'RegScope' });
+                scope.register(ComponentA);
+                scope.register(ComponentB);
+                scope.register(ComponentC);
+                scope.register(ComponentD);
+                scope.register(ComponentE);
+            });
+    });
+    allResults.push(...registerResults);
+
+    return allResults;
+}
+
+
+// Run standalone
+if (require.main === module) {
+    runScopeResolveBenchmarks().catch(console.error);
+}

package/benchmarks/step-manager.bench.ts

@@ -0,0 +1,146 @@
+/**
+ * ============================================================
+ *  A_StepsManager Performance Benchmarks
+ * ============================================================
+ * 
+ * Measures:
+ *  - Constructor + unique ID assignment
+ *  - Graph building + topological sort (toSortedArray)
+ *  - Full pipeline: steps → stages (toStages)
+ *  - Scaling behavior with increasing step counts
+ */
+import { A_Component } from "@adaas/a-concept/a-component";
+import { A_Dependency } from "@adaas/a-concept/a-dependency";
+import { A_StepsManager } from "@adaas/a-concept/a-step-manager";
+import { A_Feature } from "@adaas/a-concept/a-feature";
+import { A_Scope } from "@adaas/a-concept/a-scope";
+import { createSuite, BenchResult } from './helpers';
+
+
+// ──────────────────────────────────────────────────────────────
+// Fixture Helpers
+// ──────────────────────────────────────────────────────────────
+
+class BenchComponent extends A_Component {
+    async step1() { }
+    async step2() { }
+    async step3() { }
+    async step4() { }
+    async step5() { }
+    async step6() { }
+    async step7() { }
+    async step8() { }
+    async step9() { }
+    async step10() { }
+}
+
+function makeSteps(count: number, opts: { withDeps?: boolean } = {}) {
+    const steps: any[] = [];
+    for (let i = 0; i < count; i++) {
+        const step: any = {
+            name: `step${i}`,
+            dependency: new A_Dependency(BenchComponent),
+            handler: `step${i}`,
+        };
+        if (opts.withDeps && i > 0) {
+            step.after = `BenchComponent.step${i - 1}`;
+        }
+        steps.push(step);
+    }
+    return steps;
+}
+
+
+// ──────────────────────────────────────────────────────────────
+// Benchmark Suites
+// ──────────────────────────────────────────────────────────────
+
+export async function runStepManagerBenchmarks(): Promise<BenchResult[]> {
+    const allResults: BenchResult[] = [];
+
+    // Suite 1: Constructor performance
+    const constructorResults = await createSuite('A_StepsManager — Constructor', (suite) => {
+        const steps6 = makeSteps(6);
+        const steps20 = makeSteps(20);
+        const steps50 = makeSteps(50);
+
+        suite
+            .add('new A_StepsManager(6 steps)', () => {
+                new A_StepsManager(steps6);
+            })
+            .add('new A_StepsManager(20 steps)', () => {
+                new A_StepsManager(steps20);
+            })
+            .add('new A_StepsManager(50 steps)', () => {
+                new A_StepsManager(steps50);
+            });
+    });
+    allResults.push(...constructorResults);
+
+    // Suite 2: Topological sort
+    const sortResults = await createSuite('A_StepsManager — toSortedArray', (suite) => {
+        const steps6 = makeSteps(6);
+        const steps6Deps = makeSteps(6, { withDeps: true });
+        const steps20 = makeSteps(20);
+        const steps20Deps = makeSteps(20, { withDeps: true });
+        const steps50 = makeSteps(50);
+
+        suite
+            .add('toSortedArray (6 steps, no deps)', () => {
+                const sm = new A_StepsManager(steps6);
+                sm.toSortedArray();
+            })
+            .add('toSortedArray (6 steps, chained)', () => {
+                const sm = new A_StepsManager(steps6Deps);
+                sm.toSortedArray();
+            })
+            .add('toSortedArray (20 steps, no deps)', () => {
+                const sm = new A_StepsManager(steps20);
+                sm.toSortedArray();
+            })
+            .add('toSortedArray (20 steps, chained)', () => {
+                const sm = new A_StepsManager(steps20Deps);
+                sm.toSortedArray();
+            })
+            .add('toSortedArray (50 steps, no deps)', () => {
+                const sm = new A_StepsManager(steps50);
+                sm.toSortedArray();
+            });
+    });
+    allResults.push(...sortResults);
+
+    // Suite 3: toStages (full pipeline)
+    const stagesResults = await createSuite('A_StepsManager — toStages', (suite) => {
+        const scope = new A_Scope({ name: 'BenchScope', components: [BenchComponent] });
+        const steps6 = makeSteps(6);
+        const steps20 = makeSteps(20);
+
+        suite
+            .add('toStages (6 steps)', () => {
+                const component = scope.resolve(BenchComponent)!;
+                const feature = new A_Feature({
+                    name: 'benchFeature',
+                    scope: new A_Scope(),
+                    template: steps6,
+                });
+                // toStages is called internally during construction
+            })
+            .add('toStages (20 steps)', () => {
+                const component = scope.resolve(BenchComponent)!;
+                const feature = new A_Feature({
+                    name: 'benchFeature',
+                    scope: new A_Scope(),
+                    template: steps20,
+                });
+            });
+    });
+    allResults.push(...stagesResults);
+
+    return allResults;
+}
+
+
+// Run standalone
+if (require.main === module) {
+    runStepManagerBenchmarks().catch(console.error);
+}