What Is Composition? - Learning Module

Loading content...

0/246

Building Complex Objects from Simple Ones

The Art of Compositional Construction

Consider how complex physical systems are built. An airplane isn't manufactured as a single piece—it's assembled from fuselage sections, wings, engines, landing gear, avionics systems, and thousands of smaller components. Each component is itself assembled from simpler parts. This hierarchical construction allows specialization, parallel manufacturing, quality testing at multiple levels, and the ability to upgrade individual subsystems without rebuilding the entire aircraft.

Software composition follows the same principle. Complex objects are constructed by combining simpler objects, which are themselves constructed from even simpler objects. This hierarchical assembly enables the same benefits: specialization, parallel development, isolated testing, and incremental evolution.

What You Will Learn

By the end of this page, you will master the techniques for building complex objects from simple ones—including compositional hierarchies, the Builder pattern, fluent construction interfaces, and factory-based assembly. You'll understand how to design objects that are easy to construct, test, and evolve.

The Principle of Compositional Construction

At its core, compositional construction is based on a simple but powerful principle:

The key insight: Instead of building one monolithic object that understands everything, build a network of focused objects that collaborate. Each object is simple enough to understand, test, and maintain individually—complexity emerges from composition, not from bloated classes.

Let's contrast the approaches:

Monolithic Construction

•Single class with 50+ methods
•Hard to understand any single method
•Testing requires the entire object
•Changes risk breaking unrelated features
•Cannot reuse parts elsewhere

Compositional Construction

•Many classes with 5-10 methods each
•Each class has clear, focused purpose
•Components tested in isolation
•Changes contained to relevant component
•Components reusable across contexts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
// MONOLITHIC: One massive class doing everything
class MonolithicECommerceSystem {
    // 2000+ lines handling:
    // - User management
    // - Product catalog
    // - Shopping cart
    // - Checkout
    // - Payment processing
    // - Order fulfillment
    // - Notifications
    // - Analytics
    // - Reporting
    // All tightly coupled, impossible to test in isolation
}
 
// COMPOSITIONAL: Focused components assembled together
class ECommerceSystem {
    private users: UserService;
    private catalog: ProductCatalog;
    private cart: ShoppingCart;
    private checkout: CheckoutService;
    private payments: PaymentGateway;
    private fulfillment: FulfillmentService;
    private notifications: NotificationService;
    private analytics: AnalyticsTracker;
    
    constructor(/* all components injected */) {
        // Each component ~100-200 lines, single responsibility
        // Easy to understand, test, replace, or extend individually
    }
    
    // Methods coordinate between components
    async purchaseItem(userId: string, productId: string): Promise<OrderConfirmation> {
        const user = await this.users.getById(userId);
        const product = await this.catalog.getById(productId);
        await this.cart.addItem(user.cartId, product);
        const order = await this.checkout.process(user.cartId);
        await this.payments.charge(user, order.total);
        await this.fulfillment.scheduleShipment(order);
        await this.notifications.sendConfirmation(user, order);
        this.analytics.trackPurchase(user, order);
        return order.confirmation;
    }
}

Hierarchical Composition: Objects Within Objects Within Objects

Real-world composites aren't flat—they're hierarchical. A component at one level can itself be a composite of smaller components. This nesting creates a tree structure of composition, where complexity is managed at each level.

Consider a typical web application structure:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// Level 1: Top-level Application
class Application {
    private server: HttpServer;
    private apiLayer: ApiLayer;
    private services: ServiceLayer;
    private dataSources: DataLayer;
}
 
// Level 2: Each layer is itself a composite
class ApiLayer {
    private router: Router;
    private middleware: MiddlewareStack;
    private controllers: Map<string, Controller>;
    private validators: RequestValidators;
}
 
class ServiceLayer {
    private userService: UserService;
    private orderService: OrderService;
    private paymentService: PaymentService;
    private inventoryService: InventoryService;
}
 
// Level 3: Services contain their own collaborators
class OrderService {
    private repository: OrderRepository;
    private eventPublisher: EventPublisher;
    private priceCalculator: PriceCalculator;
    private discountEngine: DiscountEngine;
}
 
// Level 4: Even these have internal structure
class PriceCalculator {
    private taxCalculator: TaxCalculator;
    private shippingCalculator: ShippingCalculator;
    private currencyConverter: CurrencyConverter;
}

The benefits of hierarchical composition:

Benefits of Hierarchical Composition
Benefit	Description
Abstraction at each level	Each layer hides the complexity of its components. `Application` knows it has an `ApiLayer`, not that ApiLayer has routers, middleware, controllers, etc.
Manageable cognitive load	Developers only need to understand the level they're working at. Modifying the `TaxCalculator` doesn't require understanding the entire application.
Isolated testing	Each level can be tested independently. Unit test `TaxCalculator`, integration test `PriceCalculator`, system test `OrderService`.
Parallel development	Different teams can work on different branches of the hierarchy simultaneously.
Incremental replacement	Replace a subtree without affecting siblings. Swap `PaymentService` implementations without touching `OrderService`.

The Composite Pattern

The Composite design pattern formalizes one aspect of hierarchical composition: when individual objects and compositions of objects should be treated uniformly. A FileSystemEntry might be a File (leaf) or a Directory (composite containing other entries). Both implement the same interface, allowing recursive operations.

Bottom-Up vs Top-Down Construction

When building complex composite objects, you can approach construction from two directions:

Bottom-Up Construction

•Build leaf components first
•Compose them into higher-level objects
•Continue until reaching root
•Best when components are reusable
•Good for library/framework development

Top-Down Construction

•Define high-level structure first
•Identify needed components
•Implement components to fit structure
•Best for application-specific design
•Good for product development

Bottom-Up Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Bottom-Up: Start with primitives, compose upward
 
// Step 1: Build primitive components
const taxCalc = new TaxCalculator(taxRates);
const shipCalc = new ShippingCalculator(shippingRules);
const currencyConv = new CurrencyConverter(exchangeRates);
 
// Step 2: Compose into mid-level components
const priceCalc = new PriceCalculator(taxCalc, shipCalc, currencyConv);
const discountEngine = new DiscountEngine(promoRules);
 
// Step 3: Compose into higher-level components
const orderService = new OrderService(
    orderRepo,
    priceCalc,
    discountEngine,
    eventPublisher
);
 
// Step 4: Compose into top-level
const apiLayer = new ApiLayer(router, middleware, { orders: orderController });
const serviceLayer = new ServiceLayer(orderService, userService, paymentService);
const app = new Application(httpServer, apiLayer, serviceLayer, dataLayer);

Top-Down Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// Top-Down: Start with structure, define components as needed
 
// Step 1: Define the high-level structure (may use interfaces initially)
interface IOrderService {
    createOrder(cart: Cart): Promise<Order>;
    getOrder(id: string): Promise<Order>;
}
 
class Application {
    constructor(
        private orderService: IOrderService,
        private userService: IUserService,
        // ... other high-level dependencies
    ) {}
}
 
// Step 2: Implement high-level components, discover sub-needs
class OrderService implements IOrderService {
    constructor(
        private priceCalculator: IPriceCalculator, // Need this!
        private discountEngine: IDiscountEngine,   // And this!
        // ...
    ) {}
}
 
// Step 3: Implement sub-components as their responsibilities become clear
class PriceCalculator implements IPriceCalculator {
    // Implementation driven by OrderService's needs
}

In Practice: Meet in the Middle

Real projects often use both approaches. Top-down thinking helps you understand what you need to build; bottom-up building lets you create reusable, tested components. Experienced engineers mentally sketch the hierarchy (top-down) while building components that can stand alone (bottom-up).

The Builder Pattern: Constructing Complex Objects Step by Step

When an object has many components—especially when some are optional or there are multiple valid configurations—constructor parameters become unwieldy. The Builder pattern solves this by separating construction from representation, allowing step-by-step object construction with a fluent interface.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// The problem: Constructor with many parameters
class HttpClientBadConstructor {
    constructor(
        baseUrl: string,
        timeout: number,
        retries: number,
        retryDelay: number,
        maxConnections: number,
        headers: Record<string, string>,
        interceptors: RequestInterceptor[],
        logger: Logger | null,
        cache: CacheService | null,
        metrics: MetricsCollector | null,
        certificatePath: string | null,
        proxy: ProxyConfig | null
    ) {
        // 12 parameters is unreadable, error-prone
    }
}
 
// Which of these is the retry delay? Which is maxConnections?
const client = new HttpClientBadConstructor(
    'https://api.example.com', 
    5000, 3, 1000, 10, // What do these numbers mean?
    {}, [], null, null, null, null, null
);

The Builder solution:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
// Builder pattern: Step-by-step construction with clarity
class HttpClientBuilder {
    private baseUrl: string = '';
    private timeout: number = 30000;
    private retries: number = 0;
    private retryDelay: number = 1000;
    private maxConnections: number = 5;
    private headers: Record<string, string> = {};
    private interceptors: RequestInterceptor[] = [];
    private logger: Logger | null = null;
    private cache: CacheService | null = null;
    private metrics: MetricsCollector | null = null;
    private certificate: string | null = null;
    private proxy: ProxyConfig | null = null;
    
    // Required configuration
    setBaseUrl(url: string): this {
        this.baseUrl = url;
        return this;
    }
    
    // Optional configuration with descriptive names
    withTimeout(milliseconds: number): this {
        this.timeout = milliseconds;
        return this;
    }
    
    withRetries(count: number, delayMs: number = 1000): this {
        this.retries = count;
        this.retryDelay = delayMs;
        return this;
    }
    
    withMaxConnections(count: number): this {
        this.maxConnections = count;
        return this;
    }
    
    withHeaders(headers: Record<string, string>): this {
        this.headers = { ...this.headers, ...headers };
        return this;
    }
    
    addInterceptor(interceptor: RequestInterceptor): this {
        this.interceptors.push(interceptor);
        return this;
    }
    
    withLogging(logger: Logger): this {
        this.logger = logger;
        return this;
    }
    
    withCaching(cache: CacheService): this {
        this.cache = cache;
        return this;
    }
    
    withMetrics(metrics: MetricsCollector): this {
        this.metrics = metrics;
        return this;
    }
    
    withCertificate(path: string): this {
        this.certificate = path;
        return this;
    }
    
    withProxy(config: ProxyConfig): this {
        this.proxy = config;
        return this;
    }
    
    // Final construction with validation
    build(): HttpClient {
        if (!this.baseUrl) {
            throw new Error('Base URL is required');
        }
        
        // Compose the final object from accumulated configuration
        return new HttpClient(
            new ConnectionPool(this.maxConnections),
            new RetryHandler(this.retries, this.retryDelay),
            new RequestPipeline(this.interceptors),
            {
                baseUrl: this.baseUrl,
                timeout: this.timeout,
                headers: this.headers,
                logger: this.logger,
                cache: this.cache,
                metrics: this.metrics,
                certificate: this.certificate,
                proxy: this.proxy
            }
        );
    }
}
 
// Usage: Clear, self-documenting, impossible to get wrong
const client = new HttpClientBuilder()
    .setBaseUrl('https://api.example.com')
    .withTimeout(5000)
    .withRetries(3, 1000)
    .withMaxConnections(10)
    .withHeaders({ 'Authorization': 'Bearer token' })
    .addInterceptor(loggingInterceptor)
    .withLogging(console)
    .withCaching(redisCache)
    .build();

Builder Benefits

Builders make construction readable (method names self-document), safe (required vs optional is clear), flexible (different configurations from same builder), and testable (you can build partially configured objects for tests). Use builders when an object has 4+ parameters, especially with optional ones.

Factory-Based Assembly: Centralizing Construction Logic

When objects have complex construction logic—creating components, wiring them together, configuring based on environment—factory methods and classes centralize this logic, preventing it from spreading throughout the codebase.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
// Factory class: Centralized construction logic
class ApplicationFactory {
    private config: ApplicationConfig;
    
    constructor(config: ApplicationConfig) {
        this.config = config;
    }
    
    // Build the entire application with proper wiring
    createApplication(): Application {
        // Create data layer components
        const database = this.createDatabase();
        const cache = this.createCache();
        const dataLayer = new DataLayer(database, cache);
        
        // Create service layer components
        const services = this.createServices(dataLayer);
        
        // Create API layer components
        const apiLayer = this.createApiLayer(services);
        
        // Create server
        const server = this.createServer(apiLayer);
        
        return new Application(server, apiLayer, services, dataLayer);
    }
    
    private createDatabase(): Database {
        switch (this.config.databaseType) {
            case 'postgres':
                return new PostgresDatabase(this.config.postgresConfig);
            case 'mysql':
                return new MySqlDatabase(this.config.mysqlConfig);
            case 'memory':
                return new InMemoryDatabase(); // For testing
            default:
                throw new Error(`Unknown database type: ${this.config.databaseType}`);
        }
    }
    
    private createCache(): CacheService {
        if (!this.config.cacheEnabled) {
            return new NoOpCache();
        }
        return new RedisCache(this.config.redisConfig);
    }
    
    private createServices(dataLayer: DataLayer): ServiceLayer {
        const userService = new UserService(dataLayer.userRepository);
        const orderService = new OrderService(
            dataLayer.orderRepository,
            this.createPriceCalculator(),
            this.createPaymentGateway()
        );
        return new ServiceLayer(userService, orderService);
    }
    
    private createPriceCalculator(): PriceCalculator {
        return new PriceCalculator(
            new TaxCalculator(this.config.taxRates),
            new ShippingCalculator(this.config.shippingRules)
        );
    }
    
    private createPaymentGateway(): PaymentGateway {
        switch (this.config.paymentProvider) {
            case 'stripe':
                return new StripeGateway(this.config.stripeConfig);
            case 'paypal':
                return new PayPalGateway(this.config.paypalConfig);
            case 'mock':
                return new MockPaymentGateway();
            default:
                throw new Error(`Unknown payment provider: ${this.config.paymentProvider}`);
        }
    }
    
    // ... more private factory methods
}
 
// Usage: Clean application bootstrap
const config = loadConfig(process.env.NODE_ENV);
const factory = new ApplicationFactory(config);
const app = factory.createApplication();
await app.start();

Factory patterns for different scenarios:

Factory Patterns for Compositional Construction
Pattern	Use Case	Example
Factory Method	Single product type, variations based on input	`createLogger(type): Logger`
Abstract Factory	Family of related products that work together	`UiFactory.createButton()`, `createDialog()`, etc.
Factory Class	Complex wiring of many components	The `ApplicationFactory` above
DI Container	Framework-managed dependency injection	Spring, Nest.js, Angular DI

Factory vs Builder

Builders and factories are complementary. Builders configure a single complex object step-by-step. Factories create and wire together multiple objects (potentially using builders for individual objects). A factory might use builders internally for complex component construction.

Dependency Injection Containers: Automated Composition

When applications grow large, manually wiring together hundreds of components becomes tedious and error-prone. Dependency Injection (DI) containers automate this process—you declare what each class needs, and the container figures out how to construct and wire everything together.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
// Without DI container: Manual wiring (tedious at scale)
const logger = new ConsoleLogger();
const database = new PostgresDatabase(dbConfig);
const userRepo = new UserRepository(database, logger);
const orderRepo = new OrderRepository(database, logger);
const taxCalc = new TaxCalculator(taxConfig);
const shipCalc = new ShippingCalculator(shippingConfig);
const priceCalc = new PriceCalculator(taxCalc, shipCalc);
const paymentGateway = new StripeGateway(stripeConfig);
const userService = new UserService(userRepo, logger);
const orderService = new OrderService(orderRepo, priceCalc, paymentGateway, logger);
const userController = new UserController(userService, logger);
const orderController = new OrderController(orderService, logger);
const app = new Application(userController, orderController, logger);
 
// With DI container (conceptual, syntax varies by framework)
// Just declare dependencies, container wires automatically
 
@Injectable()
class UserRepository {
    constructor(
        @Inject(Database) private database: Database,
        @Inject(Logger) private logger: Logger
    ) {}
}
 
@Injectable()
class UserService {
    constructor(
        @Inject(UserRepository) private repo: UserRepository,
        @Inject(Logger) private logger: Logger
    ) {}
}
 
@Injectable()
class UserController {
    constructor(
        @Inject(UserService) private service: UserService
    ) {}
}
 
// Container configuration
container.register(Logger, ConsoleLogger);
container.register(Database, PostgresDatabase);
// ... register all implementations
 
// Container creates entire object graph automatically
const app = container.resolve(Application);

How DI containers work:

Registration: You tell the container how to create each dependency (which concrete class implements each interface)
Resolution: When you request an object, the container examines its dependencies, recursively resolves each one, creates instances, and wires everything together
Lifecycle Management: Containers can manage singleton vs per-request instances, disposing of resources when appropriate

DI Container Trade-offs

DI containers are powerful but add complexity. They can make debugging harder (construction happens "magically"), create performance overhead, and require learning curved syntax. Use them when manual wiring becomes burdensome (50+ components), but understand that simple dependency injection (constructor injection) works without any framework.

Testing Composite Objects

One of composition's greatest practical benefits is testability. Because components are injected, you can substitute test doubles (mocks, stubs, fakes) to test each level of the composition hierarchy in isolation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
// Testing a composite with mock components
 
class OrderService {
    constructor(
        private priceCalculator: PriceCalculator,
        private paymentGateway: PaymentGateway,
        private inventory: InventoryService
    ) {}
    
    async createOrder(cart: Cart): Promise<Order> {
        const total = this.priceCalculator.calculateTotal(cart);
        await this.inventory.reserve(cart.items);
        await this.paymentGateway.charge(cart.userId, total);
        return new Order(cart.items, total);
    }
}
 
// Unit testing OrderService with mock components
describe('OrderService', () => {
    let orderService: OrderService;
    let mockPriceCalc: jest.Mocked<PriceCalculator>;
    let mockPayment: jest.Mocked<PaymentGateway>;
    let mockInventory: jest.Mocked<InventoryService>;
    
    beforeEach(() => {
        // Create mock components
        mockPriceCalc = {
            calculateTotal: jest.fn().mockReturnValue(100)
        } as any;
        
        mockPayment = {
            charge: jest.fn().mockResolvedValue({ success: true })
        } as any;
        
        mockInventory = {
            reserve: jest.fn().mockResolvedValue(true)
        } as any;
        
        // Compose with mocks
        orderService = new OrderService(
            mockPriceCalc,
            mockPayment,
            mockInventory
        );
    });
    
    it('should calculate price, reserve inventory, then charge', async () => {
        const cart = { userId: 'user1', items: [{ productId: 'p1', qty: 2 }] };
        
        await orderService.createOrder(cart);
        
        // Verify correct component interactions
        expect(mockPriceCalc.calculateTotal).toHaveBeenCalledWith(cart);
        expect(mockInventory.reserve).toHaveBeenCalledWith(cart.items);
        expect(mockPayment.charge).toHaveBeenCalledWith('user1', 100);
    });
    
    it('should not charge if inventory reservation fails', async () => {
        mockInventory.reserve.mockRejectedValue(new Error('Out of stock'));
        
        const cart = { userId: 'user1', items: [{ productId: 'p1', qty: 2 }] };
        
        await expect(orderService.createOrder(cart)).rejects.toThrow('Out of stock');
        expect(mockPayment.charge).not.toHaveBeenCalled();
    });
});

Testing Strategy for Composites

•Unit test leaf components with no dependencies or minimal stubs
•Unit test composites with mock components to verify coordination logic
•Integration test subsystems with real components wired together
•End-to-end test the full composition to verify real behavior
•Use builders/factories in tests to construct objects with controlled configurations

Summary: Building Complex from Simple

We've explored the art and science of building complex objects from simple components. Let's consolidate the key insights:

Key Takeaways

•Compositional construction manages complexity — Simple components combine into complex systems without any single part becoming overwhelming.
•Hierarchical composition creates abstraction layers — Each level hides the complexity of levels below, making large systems comprehensible.
•Bottom-up and top-down approaches complement each other — Design top-down for structure, build bottom-up for reusable components.
•Builders make complex construction readable — Step-by-step construction with named methods beats long constructor parameter lists.
•Factories centralize wiring logic — Keep construction complexity in dedicated factory classes, not scattered throughout code.
•DI containers automate at scale — For large applications, let frameworks wire dependencies automatically.
•Composition enables testing — Inject mock components to test each level of the hierarchy in isolation.

What's next:

With construction techniques covered, we'll examine composition from a conceptual angle—understanding composition as assembly. This perspective views object composition as the assembly of interchangeable parts, drawing lessons from manufacturing and exploring how this metaphor guides design decisions.

Page Complete

You now understand how to build complex objects from simple components—using hierarchical composition, builders, factories, and dependency injection. These techniques let you construct systems that are both sophisticated in capability and manageable in complexity. Next, we'll explore the assembly metaphor for understanding composition.