@matrix/core-engine

This package houses the core engine logic of the Matrix Component Framework (MCF).

Purpose

The @matrix/core-engine is responsible for:

• Event Routing: Managing the flow of events within the framework.
• Registries: Maintaining registries for components, instances, and bindings.
• Lifecycle Orchestration: Coordinating the lifecycle of components.
• Component Registration: Auto-generating definition variants for DSL tags.

This package is a foundational piece of MCF, enabling the dynamic and modular nature of applications built with the framework.

Component Registration

Automatic Definition Tag Generation

When you register a component, the ComponentRegistry automatically creates TWO tag mappings:

// Registering a component with dslTag = 'my-component'
ComponentRegistry.register(MyComponent);

// Results in:
// 1. 'my-component' → MyComponent
// 2. 'my-component-definition' → MyComponent (auto-generated)

This enables flexible DSL patterns:

Self-Contained Components

<!-- Uses 'my-component' tag directly -->
<my-component id="comp1" />

Composed Components with Definitions

<!-- Uses auto-generated 'my-component-definition' tag -->
<my-component-definition>
    <child-component />
</my-component-definition>

Component Requirements

For a class to be registered as a Matrix component:

class MyComponent extends BaseCommunicationComponent {
    static isMatrixComponent = true;  // Required marker
    static dslTag = 'my-component';   // DSL tag name
}

If dslTag is not provided, it's derived from the class name:

• FooBarComponent → foo-bar
• MyService → my-service

Event Routing

Event Flow

1. Component Events → EventBus → BindingCoordinator → Target Component
2. Engine Events → EngineEventRouter → Appropriate Handler

Key Event Types

• InstantiateComponent: Create a component instance
• BindingRequested: Establish event/command binding
• ComponentLifecycle: Manage component states

Registries

ComponentRegistry

Maps DSL tags to component constructors:

• Stores component classes by tag name
• Auto-generates definition variants
• Validates component requirements

InstanceRegistry

Tracks component instances:

• Maps instance IDs to component instances
• Maintains parent-child relationships
• Handles instance lifecycle

BindingRegistry

Manages event/command bindings:

• Stores binding configurations
• Routes events between components
• Supports dynamic binding updates

Usage

import { 
    EngineEventRouter,
    ComponentRegistry,
    InstanceRegistry,
    BindingRegistry,
    RuntimeEngine
} from '@matrix/core-engine';

// Initialize the engine
const engine = new RuntimeEngine();

// Register a component
engine.getComponentRegistry().register(MyComponent);

// Start the engine
engine.start();