Core

A framework designed to support application clustering, configuration management, and service location.

OBS!

Current version is in beta release

Features

• Cluster Support: Scale horizontally using the cluster module with worker management.
• Graceful Shutdown: Handles system signals (SIGINT, SIGTERM) and unexpected errors (unhandledRejection, uncaughtException) to support a graceful shutdown.
• Service Locator: Locate and initialize services based on configuration.
• Bootstrap Support: Initialize resources and services based on configurations.
• Configuration Manager: Manage configurations for different environments or branches.

Installation

npm install @superhero/core

Usage

Basic Example

import Core from '@superhero/core'

const core = new Core()

// Add configuration paths
await core.add('./path/to/config.json')

// Bootstrap core
await core.bootstrap()

// Locate a service
const myService = core.locate('myService')

// Graceful shutdown
await core.destroy()

Clustering Example

import Core from '@superhero/core'

const core = new Core()

// Cluster into 4 workers
await core.cluster(4)

// Add configuration paths
await core.add('./path/to/config.js')

// Bootstrap core
await core.bootstrap()

// Destroy core when done
await core.destroy()

Configuration

The core reads configurations from JSON files and supports environment-specific overrides. Example structure:

config.json:

{
  "bootstrap": { "myService": true },
  "locator": { "myService": "./path/to/myService.js" }
}

config-dev.json:

{
  "myService": { "debug": true }
}

Testing

Prerequisites

Ensure the required dependencies are installed:

npm install

Run Tests

npm test

Test Coverage

▶ @superhero/core
  ✔ Plain core bootstrap (2.792737ms)
  ✔ Bootstraps a service successfully (9.447829ms)
  ✔ Bootstraps a service with a branch variable (4.01927ms)
  ✔ Can cluster the core and bootstrap a service (479.701512ms)
✔ @superhero/core (511.980508ms)

tests 4
pass 4

---------------------------------------------------------------------------------------------------
file            | line % | branch % | funcs % | uncovered lines
---------------------------------------------------------------------------------------------------
index.js        |  74.21 |    67.03 |   74.51 | 19-24 97-100 121-123 131-136 139-141 185-190 201-2…
index.test.js   | 100.00 |   100.00 |  100.00 | 
worker.js       | 100.00 |   100.00 |  100.00 | 
---------------------------------------------------------------------------------------------------
all files       |  77.46 |    70.00 |   77.59 | 
---------------------------------------------------------------------------------------------------

API

Core

Constructor

new Core(branch: string = undefined)

• branch: The configuration branch to load additional configurations (e.g., dev for config-dev.json).

Methods

• add(configPaths: string | string[] | object): Promise<Core>
  Add configuration paths to the core.

• bootstrap(freeze: boolean = true): Promise<Core>
  Initialize the core and its dependencies.

• cluster(forks: number, branch?: number, version?: number): Promise<number>
  Start clustering with the specified number of workers.

• destroy(): Promise<void>
  Gracefully shutdown the core, its workers, and services.

Properties

• basePath: string
  The base path used to resolve file paths.

• branch: string
  The branch used for environment-specific configurations.

• workers: object
  Access to clustered workers.

License

This project is licensed under the MIT License.

Contributing

Feel free to submit issues or pull requests for improvements or additional features.