@adaas/a-concept 0.3.5 → 0.3.7

package/README.md

@@ -1,99 +1,85 @@
 <img align="left" style="margin-right:40px; margin-bottom:80px;" width="200" height="200" src="https://raw.githubusercontent.com/ADAAS-org/adaas-a-concept/main/docs/a-concept-logo.png" alt="A-Concept Logo">
 
-# A-Concept 
+# A-Concept
 
-🚀 A Paradigm Shift for Software Development in the Age of AI and  [Industry 5.0](https://research-and-innovation.ec.europa.eu/research-area/industrial-research-and-innovation/industry-50_en). 
+**A paradigm shift for software development in the age of AI and [Industry 5.0](https://research-and-innovation.ec.europa.eu/research-area/industrial-research-and-innovation/industry-50_en).**
 
 ![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)
 ![Node.js](https://img.shields.io/badge/Node.js-43853D?style=for-the-badge&logo=node.js&logoColor=white)
 ![npm](https://img.shields.io/badge/npm-CB3837?style=for-the-badge&logo=npm&logoColor=white)
-
 ![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)
 ![Version](https://img.shields.io/npm/v/@adaas/a-concept)
 ![Downloads](https://img.shields.io/npm/dm/@adaas/a-concept)
 ![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
 
+<br clear="left"/>
 
 ---
 
-## 📖 **Table of Contents**
-
-1. [Overview](#-overview)
-2. [Why Choose A-Concept?](#-why-choose-a-concept)
-3. [Core Principles](#-core-principles)
-    - [Technology](#-technology)
-    - [Collaboration](#-collaboration)
-    - [Bridging Architecture & Code](#-bridging-architecture--code)
-4. [Getting Started](#-getting-started)
-5. [Challenges in Modern Development](#-challenges-in-modern-development)
-    - [AI Hallucinations and Incorrect Code Outputs](#-ai-hallucinations-and-incorrect-code-outputs)
-    - [The Gap Between Software Design and Implementation](#-the-gap-between-software-design-and-implementation)
-    - [Scaling and Product Evolution](#-scaling-and-product-evolution)
-    - [Inappropriate Role Combinations and Team Structures](#-inappropriate-role-combinations-and-team-structures)
-    - [Outdated SDLC Methodologies](#-outdated-sdlc-methodologies)
-6. [About the Team](#-about-the-team)
-
----
-
+## Table of Contents
 
-## 📖 Overview
+1. [Overview](#overview)
+2. [Core Principles](#core-principles)
+3. [Getting Started](#getting-started)
+4. [Challenges We Solve](#challenges-we-solve)
+5. [Performance](#performance)
+6. [About the Team](#about-the-team)
+7. [License](#license)
 
-A-Concept is a modern framework created by the ADAAS R&D teams to redefine how we design and develop software in the Industry 5.0 era. It combines:
+---
 
-1. **The A-Concept Paradigm**: A revolutionary architectural framework rooted in an enhanced C4 model, designed to bridge software design and actual development.
+## Overview
 
-2. **The A-Concept Framework**: A robust software development toolkit that brings the paradigm to life. It includes tools, APIs, and integrations to enable developers to implement the A-Concept methodology seamlessly in their projects, regardless of the platform or domain.
+A-Concept is a modern framework built by the ADAAS R&D team to redefine how software is designed and developed in the Industry 5.0 era. It is three things in one:
 
-3. **A-Concept Ecosystem**: A suite of AI-prepared components, libraries, and modules designed to ensure AI-generated code is not only functional but also architecturally sound.
+**The A-Concept Paradigm** — an architectural framework designed to permanently close the gap between software design and actual implementation. Architecture and code are treated as a single artifact, not two separate concerns that drift apart over time.
 
-With A-Concept, developers and businesses can create software that evolves seamlessly, breaking free from outdated methodologies and limitations.
+**The A-Concept Framework** — a software development toolkit that brings the paradigm to life with tools, APIs, and integrations that work across any platform or domain.
 
-## 🌍 Core Principles
+**The A-Concept Ecosystem** — a suite of AI-prepared components, libraries, and modules designed to ensure AI-generated code is not only functional but architecturally sound.
 
-### 🔧 Technology
+---
 
-Unlike traditional frameworks that impose restrictions, A-Concept:
-- Offers tools, not rules.
-- Encourages flexibility to build, combine, and innovate across platforms.
-- Provides AI-ready modules for faster and more accurate development.
+## Core Principles
 
-### 🫠 Collaboration
+### Tools, Not Rules
 
-SCRUM is outdated. Here’s why A-Concept takes a futuristic approach:
-- Simplifies processes for solo entrepreneurs and lean enterprises.
-- Eliminates unnecessary rituals, focusing instead on results and innovation.
-- Enhances developer productivity by automating repetitive tasks, enabling teams to focus on optimized, high-quality code.
+A-Concept does not dictate how you build. It offers composable primitives that give you flexibility to innovate across platforms, while AI-ready modules accelerate development without sacrificing quality.
 
-### 🔽 Bridging Architecture & Code
+### Results Over Ritual
 
-Traditional development often struggles with a disconnect between architecture and code. A-Concept fixes this by:
-- Extending the C4 model to include design capabilities.
-- Ensuring architecture and code stay in sync with AI-assisted tools.
-- Empowering developers to become architects with intuitive and self-documented workflows.
+SCRUM was designed for a different era. A-Concept takes a leaner approach — eliminating unnecessary process overhead, simplifying collaboration for solo engineers and lean teams alike, and focusing effort on code that ships rather than ceremonies that don't.
 
+### Architecture and Code as One
 
-## Problems 
+The persistent disconnect between high-level design and day-to-day implementation is one of the industry's oldest problems. A-Concept solves it by merging the two into a single self-documenting workflow. Architecture stays synchronised with code automatically — giving developers, architects, and stakeholders a single source of truth at all times.
 
+---
 
+## Getting Started
 
-## 📂 Getting Started
+Install the package:
 
 ```bash
 cd /your/project/location
-npm i @adaas/a-concept
+npm install @adaas/a-concept
 ```
-Then export 
 
-```ts 
-import { Concept } from '@adaas/a-concept';
-const concept = new Concept({
+Create a concept:
+
+```typescript
+import { A_Concept } from '@adaas/a-concept';
+
+const concept = new A_Concept({
     name: 'my-concept'
 });
 ```
 
-and extend 
+Extend it with fragments and containers:
+
+```typescript
+import { A_Concept, A_Config, A_ConfigLoader } from '@adaas/a-concept';
 
-```ts
 (async () => {
     const concept = new A_Concept({
         name: 'test-simple',
@@ -118,55 +104,107 @@ and extend
 })();
 ```
 
+---
+
+## Challenges We Solve
+
+### AI Hallucinations and Incorrect Code Outputs
+
+AI code generation tools produce plausible-looking but architecturally flawed output. Without boundaries, AI contributions drift from the intended design.
+
+A-Concept provides self-documenting primitives and well-defined structural contracts that constrain AI to operate within the correct architectural context — making generated code both functional and sound.
 
+### The Gap Between Design and Implementation
 
-## 👨‍💻 About the Team
+Documentation becomes outdated the moment it is written. Architecture diagrams and the actual codebase diverge within weeks, leaving teams navigating an increasingly unreliable map.
 
-The [ADAAS R&D](https://adaas.org) team comprises seasoned developers and architects who’ve been part of software evolution from its early days. We understand the pain points of traditional methodologies and are passionate about creating tools that bridge gaps and propel development into the future.
+A-Concept merges design and implementation into a single process. The framework's self-documenting capabilities keep architecture permanently synchronised with code, providing clarity for developers and stakeholders without any manual upkeep.
 
+### Scaling and Long-term Evolution
 
+As products grow, technical debt compounds. Most frameworks provide no structural answer to this — teams are left to manage accumulating complexity by hand.
 
-## 🗋 Challenges in Modern Development
+A-Concept is built for long-term evolution. Its modular design allows products to adapt, pivot, and scale without compromising the integrity of the underlying architecture.
 
-### 🚀 AI Hallucinations and Incorrect Code Outputs
+### Role Fragmentation and Burnout
 
-The rapid rise of AI tools for code generation has introduced a significant challenge: hallucinations. These occur when AI generates plausible-looking but fundamentally flawed code. While impressive, AI outputs often lack precision and fail to align with the overall architectural vision.
+Developers are routinely expected to operate across every level of abstraction simultaneously — from low-level performance work to high-level product decisions. The result is burnout and consistently suboptimal output at every level.
 
-Solution:
-A-Concept creates an ecosystem where AI operates within clearly defined boundaries, leveraging self-documenting primitives and an extended C4 model. This ensures that AI’s contributions align with the intended design and functionality.
+A-Concept separates concerns clearly: specialists optimise performance, product-focused engineers drive outcomes, and AI handles routine tasks. Each role operates in its natural domain.
 
-### 🔗 The Gap Between Software Design and Implementation
+### Outdated Development Methodologies
 
-One of the most persistent problems in software development is the disconnect between high-level architectural plans and actual implementation. Traditional methodologies often result in documentation that quickly becomes outdated, leading to chaotic, hard-to-maintain codebases.
+SCRUM and Waterfall were created for a world without AI, remote-first teams, or continuous deployment. They are ritual-heavy, slow to adapt, and poorly matched to modern development realities.
 
-Solution:
-A-Concept merges design and implementation into a single, seamless process. The framework’s self-documenting capabilities mean that architecture is always synchronized with the code, offering clarity for both developers and stakeholders.
+A-Concept promotes a streamlined approach — leaner processes, AI-assisted execution, and a clear focus on shipping results rather than attending standups.
 
-### 📈 Scaling and Product Evolution
+---
+
+## Performance
+
+Benchmarks measure the core `A_Feature` primitive that underlies every component operation in the engine. All results are from a Node.js environment on standard developer hardware.
+
+### Construction
+
+| Benchmark | ops/sec | mean (ms) | ± % | samples |
+|-----------|--------:|----------:|----:|--------:|
+| new A_Feature (from component) | 65,413 | 0.0153 | ±11.86% | 47 |
+| new A_Feature (from template, 1 step) | 34,465 | 0.0290 | ±19.72% | 32 |
+| new A_Feature (from template, 5 steps) | 18,255 | 0.0548 | ±22.42% | 61 |
+
+Construction from a component reference is the fastest path at ~0.015ms per instance. Template-based construction adds parsing overhead — roughly 2× for a single step and 3.6× for five steps.
+
+### Sync Execution
+
+| Benchmark | ops/sec | mean (ms) | ± % | samples |
+|-----------|--------:|----------:|----:|--------:|
+| call feature (1 sync step) | 53,673 | 0.0186 | ±4.55% | 84 |
+| call feature (3 sync extensions) | 58,663 | 0.0170 | ±2.52% | 89 |
+| call feature (5 sync extensions) | 35,000 | 0.0286 | ±5.29% | 84 |
 
-Scaling a product over time is a daunting task. As projects grow, technical debt accumulates, making it harder to introduce new features or pivot to meet market demands. Existing frameworks often fail to provide tools that support long-term evolution.
+Sync execution is stable up to 3 extensions with virtually no overhead over a single step. At 5 extensions the cost rises to ~0.029ms — still well within a single 16.6ms frame budget.
 
-Solution:
-A-Concept introduces an ecosystem built with scalability in mind. Its modular design enables projects to adapt, evolve, and scale without compromising the integrity of the underlying architecture.
+### Full Lifecycle (construct + execute)
 
-### 🛠️ Inappropriate Role Combinations and Team Structures
+| Benchmark | ops/sec | mean (ms) | ± % | samples |
+|-----------|--------:|----------:|----:|--------:|
+| construct + process (1 step) | 50,865 | 0.0197 | ±11.32% | 71 |
+| construct + process (3 extensions) | 56,259 | 0.0178 | ±1.53% | 90 |
 
-The industry’s current approach to team roles and responsibilities is often inefficient. Developers juggle multiple hats, ranging from low-level coding to high-level architectural design. This mismatch leads to burnout and suboptimal results.
+The full construct-and-execute lifecycle costs ~0.02ms for both 1 and 3 extensions. The lower variance on the 3-extension run suggests the engine reaches a more stable execution path with multiple extensions.
 
-Solution:
-A-Concept reimagines collaboration by enabling developers to focus on their strengths. The framework’s tools allow low-level specialists to optimize performance while product-focused professionals drive business outcomes. AI handles routine tasks, freeing teams to innovate.
+### Inheritance Impact
 
-### 🗂 Outdated SDLC Methodologies
+| Benchmark | ops/sec | mean (ms) | ± % | samples |
+|-----------|--------:|----------:|----:|--------:|
+| construct + process (base class) | 89,174 | 0.0112 | ±3.17% | 84 |
+| construct + process (1-level child) | 65,307 | 0.0153 | ±1.57% | 91 |
+| construct + process (2-level grandchild) | 61,470 | 0.0163 | ±2.57% | 88 |
 
-Traditional methodologies like SCRUM and Waterfall were revolutionary in their time, but they struggle to meet the demands of modern software development. These methodologies are ritual-heavy, time-consuming, and ill-suited for AI-driven development.
+Each inheritance level adds ~0.004ms. This cost is fixed and does not compound with further depth, making inheritance chains predictable.
 
-Solution:
-A-Concept promotes a streamlined approach. By leveraging AI and rethinking team structures, we eliminate unnecessary rituals and focus on achieving results. This makes the development process leaner, faster, and more aligned with business goals.
+### Summary
 
+| Operation | mean (ms) | ops per 60fps frame |
+|-----------|----------:|--------------------:|
+| Fastest construction | 0.011ms | ~1,500 |
+| Template construction (5 steps) | 0.055ms | ~300 |
+| Full lifecycle (3 extensions) | 0.018ms | ~900 |
+| 2-level inheritance | 0.016ms | ~1,000 |
+
+All operations complete well within a single 16.6ms frame budget.
+
+---
+
+## About the Team
+
+The [ADAAS R&D](https://adaas.org) team is made up of engineers and architects who have lived through decades of evolving software practices. We built A-Concept out of genuine frustration with tools and methodologies that stopped serving developers — and a conviction that the industry deserves something better.
+
+---
 
 ## License
 
 This project is licensed under the [Apache License 2.0](LICENSE).
 
-© 2025 ADAAS YAZILIM LİMİTED ŞİRKETİ All rights reserved.  
-All original code and concepts are the intellectual property of ADAAS YAZILIM LİMİTED ŞİRKETİ
+© 2025 ADAAS YAZILIM LİMİTED ŞİRKETİ. All rights reserved.  
+All original code and concepts are the intellectual property of ADAAS YAZILIM LİMİTED ŞİRKETİ.

package/benchmarks/feature-lifecycle.bench.ts

@@ -0,0 +1,245 @@
+/**
+ * ============================================================
+ *  A_Feature Lifecycle Performance Benchmarks
+ * ============================================================
+ *
+ * Measures end-to-end performance of feature creation and execution:
+ *  - Feature initialization from component
+ *  - Feature initialization from template
+ *  - Feature process() execution (sync steps)
+ *  - Full decorator → resolve → template → process pipeline
+ *  - Scaling with number of extensions
+ */
+import { A_Component } from "@adaas/a-concept/a-component";
+import { A_Feature } from "@adaas/a-concept/a-feature";
+import { A_Scope } from "@adaas/a-concept/a-scope";
+import { A_Dependency } from "@adaas/a-concept/a-dependency";
+import { A_Inject } from "@adaas/a-concept/a-inject";
+import { A_Caller } from "@adaas/a-concept/a-caller";
+import { createSuite, BenchResult } from './helpers';
+
+
+// ──────────────────────────────────────────────────────────────
+// Fixture Components
+// ──────────────────────────────────────────────────────────────
+
+// Simple sync component for pure overhead measurement
+class SimpleComponent extends A_Component {
+    counter: number = 0;
+
+    @A_Feature.Define({ invoke: true })
+    @A_Feature.Extend({ name: 'simpleFeature' })
+    simpleMethod() {
+        this.counter++;
+    }
+}
+
+// Component with multiple sync extensions
+class ExtA extends A_Component {
+    @A_Feature.Extend({ name: 'multiFeature' })
+    stepA() { }
+}
+
+class ExtB extends A_Component {
+    @A_Feature.Extend({ name: 'multiFeature' })
+    stepB() { }
+}
+
+class ExtC extends A_Component {
+    @A_Feature.Extend({ name: 'multiFeature' })
+    stepC() { }
+}
+
+class ExtD extends A_Component {
+    @A_Feature.Extend({ name: 'multiFeature' })
+    stepD() { }
+}
+
+class ExtE extends A_Component {
+    @A_Feature.Extend({ name: 'multiFeature' })
+    stepE() { }
+}
+
+// Component that defines the multi-feature
+class MultiComponent extends A_Component {
+    @A_Feature.Define({ invoke: false })
+    async multiFeature() {
+        await this.call('multiFeature');
+    }
+}
+
+// Inheritance chain for testing feature inheritance overhead
+class BaseComp extends A_Component {
+    @A_Feature.Define({ invoke: false })
+    async inheritedFeature() {
+        await this.call('inheritedFeature');
+    }
+
+    @A_Feature.Extend({ name: 'inheritedFeature' })
+    baseStep() { }
+}
+
+class ChildComp extends BaseComp {
+    @A_Feature.Extend({ name: 'inheritedFeature' })
+    childStep() { }
+}
+
+class GrandchildComp extends ChildComp { }
+
+
+// ──────────────────────────────────────────────────────────────
+// Benchmark Suites
+// ──────────────────────────────────────────────────────────────
+
+export async function runFeatureLifecycleBenchmarks(): Promise<BenchResult[]> {
+    const allResults: BenchResult[] = [];
+
+    // Suite 1: Feature Construction
+    const constructionResults = await createSuite('A_Feature — Construction', (suite) => {
+        const scope = new A_Scope({ name: 'ConstructScope', components: [SimpleComponent] });
+        const comp = scope.resolve(SimpleComponent)!;
+
+        const templateSteps = [
+            {
+                name: 'SimpleComponent.simpleMethod',
+                dependency: new A_Dependency(SimpleComponent),
+                handler: 'simpleMethod',
+            }
+        ];
+
+        suite
+            .add('new A_Feature (from component)', () => {
+                new A_Feature({
+                    name: 'simpleFeature',
+                    component: comp,
+                });
+            })
+            .add('new A_Feature (from template, 1 step)', () => {
+                new A_Feature({
+                    name: 'benchFeature',
+                    scope: new A_Scope(),
+                    template: templateSteps,
+                });
+            })
+            .add('new A_Feature (from template, 5 steps)', () => {
+                new A_Feature({
+                    name: 'benchFeature',
+                    scope: new A_Scope(),
+                    template: [
+                        ...templateSteps,
+                        { name: 's2', dependency: new A_Dependency(SimpleComponent), handler: 's2' },
+                        { name: 's3', dependency: new A_Dependency(SimpleComponent), handler: 's3' },
+                        { name: 's4', dependency: new A_Dependency(SimpleComponent), handler: 's4' },
+                        { name: 's5', dependency: new A_Dependency(SimpleComponent), handler: 's5' },
+                    ],
+                });
+            });
+    });
+    allResults.push(...constructionResults);
+
+    // Suite 2: Feature Execution (sync)
+    const execResults = await createSuite('A_Feature — Sync Execution', (suite) => {
+        // 1-step feature
+        const scope1 = new A_Scope({ name: 'ExecScope1', components: [SimpleComponent] });
+        const comp1 = scope1.resolve(SimpleComponent)!;
+
+        // Multi-step feature (3 extensions)
+        const scope3 = new A_Scope({
+            name: 'ExecScope3',
+            components: [MultiComponent, ExtA, ExtB, ExtC]
+        });
+        const comp3 = scope3.resolve(MultiComponent)!;
+
+        // Multi-step feature (5 extensions)
+        const scope5 = new A_Scope({
+            name: 'ExecScope5',
+            components: [MultiComponent, ExtA, ExtB, ExtC, ExtD, ExtE]
+        });
+        const comp5 = scope5.resolve(MultiComponent)!;
+
+        suite
+            .add('call feature (1 sync step)', () => {
+                comp1.call('simpleFeature');
+            })
+            .add('call feature (3 sync extensions)', () => {
+                comp3.call('multiFeature');
+            })
+            .add('call feature (5 sync extensions)', () => {
+                comp5.call('multiFeature');
+            });
+    });
+    allResults.push(...execResults);
+
+    // Suite 3: Full lifecycle — construction + execution
+    const fullResults = await createSuite('A_Feature — Full Lifecycle (construct + execute)', (suite) => {
+        const scope = new A_Scope({ name: 'FullScope', components: [SimpleComponent] });
+        const comp = scope.resolve(SimpleComponent)!;
+
+        const scope3 = new A_Scope({
+            name: 'FullScope3',
+            components: [MultiComponent, ExtA, ExtB, ExtC]
+        });
+        const comp3 = scope3.resolve(MultiComponent)!;
+
+        suite
+            .add('construct + process (1 step)', () => {
+                const feature = new A_Feature({
+                    name: 'simpleFeature',
+                    component: comp,
+                });
+                feature.process();
+            })
+            .add('construct + process (3 extensions)', () => {
+                const feature = new A_Feature({
+                    name: 'multiFeature',
+                    component: comp3,
+                });
+                feature.process();
+            });
+    });
+    allResults.push(...fullResults);
+
+    // Suite 4: Inheritance depth impact on feature lifecycle
+    const inheritResults = await createSuite('A_Feature — Inheritance Impact', (suite) => {
+        const scopeBase = new A_Scope({ name: 'BaseScope', components: [BaseComp] });
+        const compBase = scopeBase.resolve(BaseComp)!;
+
+        const scopeChild = new A_Scope({ name: 'ChildScope', components: [ChildComp] });
+        const compChild = scopeChild.resolve(ChildComp)!;
+
+        const scopeGrand = new A_Scope({ name: 'GrandScope', components: [GrandchildComp] });
+        const compGrand = scopeGrand.resolve(GrandchildComp)!;
+
+        suite
+            .add('construct + process (base class)', () => {
+                const feature = new A_Feature({
+                    name: 'inheritedFeature',
+                    component: compBase,
+                });
+                feature.process();
+            })
+            .add('construct + process (1-level child)', () => {
+                const feature = new A_Feature({
+                    name: 'inheritedFeature',
+                    component: compChild,
+                });
+                feature.process();
+            })
+            .add('construct + process (2-level grandchild)', () => {
+                const feature = new A_Feature({
+                    name: 'inheritedFeature',
+                    component: compGrand,
+                });
+                feature.process();
+            });
+    });
+    allResults.push(...inheritResults);
+
+    return allResults;
+}
+
+
+// Run standalone
+if (require.main === module) {
+    runFeatureLifecycleBenchmarks().catch(console.error);
+}