composition

Manage and query composite and component property structures.

Summary

This module facilitates the creation of composite and component relationships within TypeScript classes using decorators.

Installation

npm i @itrocks/composition

Example Use Case

Car, Engine and Wheels

Imagine a vehicle management system where a Car class is a composite containing those components:

1. An Engine class representing a single object component.
2. A collection of Wheel objects.

import { Composite, Component } from '@itrocks/composition'

class Engine {
	@Composite() car: Car
	constructor(
		public type: string,
		public serialNumber: string
	) {}
}

class Wheel {
	@Composite() car: Car
	constructor(
		public diameter: number,
		public serialNumber: string
	) {}
}

class Car {
	constructor(
		@Component() public engine: Engine,
		@Component() public wheels: Wheel[]
	) {
		engine.car = this
		wheels.forEach(wheel => wheel.car = this)
	}
}

const car = new Car(
	new Engine('V8', 'ENG12345'),
	[
		new Wheel(20, 'WHL001'),
		new Wheel(20, 'WHL002'),
		new Wheel(18, 'WHL003'),
		new Wheel(18, 'WHL004')
	]
)

Verifying Components and Composites

You can check if properties are marked as components or composites:

import { componentOf, compositeOf } from '@itrocks/composition'

console.log(componentOf(Car,    'engine')) // true
console.log(componentOf(Car,    'wheels')) // true
console.log(compositeOf(Engine, 'car'   )) // true
console.log(compositeOf(Wheel,  'car'   )) // true
console.log(componentOf(Engine, 'car'   )) // false
console.log(compositeOf(Car,    'engine')) // false

API Reference

@Component

@Component(value: boolean = true)

A decorator to mark a property as a component.

Parameters:

• value (boolean, default: true): Activates or deactives the property as a component. Setting this value to false overrides a true value on the same property on a parent class.

Usage:

class Car {
	@Component()
	engine: Engine
}

componentOf

componentOf<T extends object>(target: ObjectOrType<T>, property: KeyOf<T>): boolean

Checks whether a property is marked as a Component.

Parameters:

• target (ObjectOrType): The target class or object to check.
• property (KeyOf): The name of the property to verify.

Returns: boolean: true if the property is marked as a Component, false otherwise.

Usage:

console.log(componentOf(Car, 'engine')) // true

@Composite

@Composite(value: boolean = true)

A decorator to mark a property as a composite.

Parameters:

• value (boolean, default: true): Activates or deactivates the property as a composite. Setting this value to false overrides a true value on the same property on a parent class.

Usage:

class Engine {
	@Composite()
  car: Car
}

compositeOf

compositeOf<T extends object>(target: ObjectOrType<T>, property: KeyOf<T>): boolean

Checks whether a property is marked as a composite.

Parameters:

• target (ObjectOrType): The target class or object to check.
• property (KeyOf): The name of the property to verify.

Returns: boolean: true if the property is marked as a Composite, false otherwise.

Usage:

console.log(compositeOf(Engine, 'car')) // true