Artus Core

@artus/core uses jest for unit testing. You can run the test suite using npm, yarn, or pnpm.

npm run test
# Or
yarn test
# Or
pnpm run test

Since @artus/core is written in TypeScript, you must build the source code into Node.js modules before use. You can use npm, yarn, or pnpm to execute the build script.

npm run build
# Or
yarn build
# Or
pnpm run build

Plugin configurations can be mapped by environment. A PluginConfigEnvMap is a record where the keys are environment names (e.g., 'development', 'production') and the values are the corresponding PluginConfig objects.

// Key: Env => PluginName => Value: PluginConfigItem
type PluginConfigEnvMap = Record<string, PluginConfig>;

Artus uses an ExceptionFilterMapType to associate specific error types with their corresponding handlers. An ExceptionIdentifier can be a string, a symbol, or a Constructable<Error> (the error class itself). This allows you to target specific error classes or use unique identifiers for custom error logic.

import { ExceptionFilterMapType, ExceptionFilterType } from '@artus/core/exception';

// Example of a map associating an Error class with a filter implementation
const filterMap: ExceptionFilterMapType = new Map([
  [TypeError, MyTypeErrorFilterClass],
  ['MY_CUSTOM_ERROR_ID', MyCustomFilterClass]
]);

Artus uses a hierarchical merging strategy to resolve the final configuration:

1. Default Config: It starts with the configuration stored under the ARTUS_DEFAULT_CONFIG_ENV.DEFAULT key.
2. Environment List: It identifies the active environments. It first checks the EnvList provided via the dependency injection container. If not found, it checks the ARTUS_SERVER_ENV environment variable. If that is also missing, it defaults to ARTUS_DEFAULT_CONFIG_ENV.DEV.
3. Merging: It iterates through the active environment list and merges each environment's configuration onto the default configuration using mergeConfig.

This allows you to define base settings in a default file and override them specifically for dev, test, or prod environments.

When initializing or configuring a logger in Artus, you can provide a LoggerOptions object to specify the minimum logging threshold. The level property determines which log messages are processed based on their severity.

const options: LoggerOptions = {
  level: 'info' // or any valid LoggerLevel
};

A Manifest is the central configuration object used by the loader. It must specify a version of '2' and contains a refMap which maps reference names to their respective items. You can optionally provide extraPluginConfig to supply additional configuration to plugins.

interface Manifest {
  version: '2';
  refMap: RefMap;
  extraPluginConfig?: PluginConfig;
}

The Application interface is the central entry point for managing an Artus application. It provides access to core services like the dependency injection container, configurationHandler, lifecycleManager, loaderFactory, and logger.

To initialize and start an application, you typically call .load(manifest) followed by .run(). You can also intercept various stages of the application lifecycle by registering hooks using .registerHook(hookName, hookFn).

// Conceptual usage of the Application interface
const app: Application = // ... initialized application instance

await app.load(myManifest);
await app.run();

app.registerHook('didReady', () => {
  console.log('Application is ready!');
});

The ScannerType interface defines the primary method for performing a scan. A scanner instance is typically created via a ScannerConstructor and provides a scan method that returns a Manifest representing the scanned project structure.

// Assuming Scanner is the implementation of ScannerConstructor
const scanner = new Scanner({ 
  extensions: ['.ts'],
  configDir: './config',
  policy: ScanPolicy.DEFAULT
});

// Perform the scan on a specific root directory
const manifest = await scanner.scan('./my-project-root');

The LifecycleManager provides methods to modify the order of the lifecycle execution sequence:

• insertHook(existHookName: string, newHookName: string): Inserts a newHookName immediately after the existHookName in the execution sequence.
• appendHook(newHookName: string): Adds a newHookName to the end of the execution sequence.