Module Management
Key Features
The Module Management system in Antelopejs, provided by the core interface, offers a robust set of tools for controlling the lifecycle of modules in your application. This system allows you to dynamically load, start, stop, and unload modules at runtime, giving you exceptional flexibility in managing your application's components.
- Dynamic loading: Load modules at runtime from various sources
- Lifecycle management: Control the complete lifecycle of modules from construction to destruction
- Configuration: Configure modules with custom settings
- Import control: Override import paths and disable specific exports
- Events: Receive notifications about module lifecycle changes
Module Lifecycle
Modules in Antelopejs go through several lifecycle states:
- Loaded: Module code has been loaded but not yet constructed
- Constructed: Module instance has been created but not started
- Active: Module is fully started and running
- Destroyed: Module instance has been destroyed (code may still be loaded)
Basic Usage
Listing Modules
The ListModules function returns an array of all currently loaded module IDs. This is useful for getting an overview of all modules in your application.
/**
* List all loaded modules.
*
* @returns Promise<string[]> Array of loaded module IDs
*/
function ListModules(): Promise<string[]>;
Usage Example
import { ListModules } from '@ajs/core/beta';
const modules: string[] = await ListModules();
console.log('Loaded modules:', modules);
Getting Module Information
The GetModuleInfo function retrieves detailed information about a specific module, including its current status and configuration.
/**
* Retrieve the configuration of a loaded module.
*
* @param module Module ID
* @returns Promise<ModuleInfo> Detailed module information
*/
function GetModuleInfo(module: string): Promise<ModuleInfo>;
Usage Example
import { GetModuleInfo, ModuleInfo } from '@ajs/core/beta';
const moduleInfo: ModuleInfo = await GetModuleInfo('database');
console.log('Module status:', moduleInfo.status);
console.log('Module configuration:', moduleInfo.config);
Loading a Module
The LoadModule function loads and optionally starts a new module with the specified configuration. This is the primary way to add new functionality to your application at runtime.
/**
* Load a new module with the given ID and configuration.
*
* @param module Module ID
* @param configuration Module configuration
* @param autostart Start immediately when loaded
* @returns Promise<void>
*/
function LoadModule(module: string, configuration: ModuleDefinition, autostart?: boolean): Promise<void>;
Usage Example
import { LoadModule, ModuleDefinition } from '@ajs/core/beta';
const moduleConfig: ModuleDefinition = {
source: {
type: 'package',
package: '@antelopejs/api',
version: '^0.0.1'
},
config: {
servers: [
{
protocol: "http",
host: "localhost",
port: 8080
}
],
}
};
await LoadModule('database', moduleConfig, true); // true = autostart
Starting a Module
The StartModule function activates a previously loaded module. This initializes the module and makes its functionality available to your application.
/**
* Start a loaded module.
*
* @param module Module ID
* @returns Promise<void>
*/
function StartModule(module: string): Promise<void>;
Usage Example
import { StartModule } from '@ajs/core/beta';
await StartModule('@antelopejs/api');
Stopping a Module
The StopModule function deactivates a running module. This temporarily disables the module's functionality while keeping it loaded in memory.
/**
* Stop a running module.
*
* @param module Module ID
* @returns Promise<void>
*/
function StopModule(module: string): Promise<void>;
Usage Example
import { StopModule } from '@ajs/core/beta';
await StopModule('@antelopejs/api');
Destroying a Module
The DestroyModule function destroys a module instance, freeing up resources. The module code remains loaded but would need to be constructed again before use.
/**
* Destroy a stopped module.
*
* @param module Module ID
* @returns Promise<void>
*/
function DestroyModule(module: string): Promise<void>;
Usage Example
import { DestroyModule } from '@ajs/core/beta';
await DestroyModule('@antelopejs/api');
Reloading a Module
The ReloadModule function unloads a module and triggers its source mechanism again, effectively performing a hot reload of the module.
/**
* Unload a module and retrigger its source mechanism.
*
* @param module Module ID
* @returns Promise<void>
*/
function ReloadModule(module: string): Promise<void>;
Usage Example
import { ReloadModule } from '@ajs/core/beta';
await ReloadModule('@antelopejs/api');
Module Definition
When loading a module, you provide a ModuleDefinition that specifies how to load and configure the module:
export interface ModuleDefinition {
// Source location and type information
source: { type: string } & Record<string, any>;
// Optional configuration data
config?: unknown;
// Optional mapping of import paths to alternative paths
importOverrides?: Record<string, string[]>;
// Optional list of exports that should not be exposed
disabledExports?: Array<string>;
}
Source Types
The source field can have different structures depending on the type:
Local Source
{
type: 'local',
path: '/absolute/path/to/module',
watchDir?: string | string[], // Optional directories to watch for changes
installCommand?: string | string[], // Optional commands to run during installation
ignoreCache?: boolean
}
Local Folder Source
{
type: 'local-folder',
path: '/path/to/parent/folder', // Will load each subdirectory as a separate module
watchDir?: string | string[], // Optional directories to watch for changes
installCommand?: string | string[], // Optional commands to run during installation
ignoreCache?: boolean
}
Package Source
{
type: 'package',
package: 'module-name',
version: '^1.0.0',
ignoreCache?: boolean
}
Git Source
{
type: 'git',
remote: 'https://github.com/user/repo.git',
branch?: 'main', // Optional branch name
commit?: 'abc123', // Optional commit hash
installCommand?: string | string[], // Optional commands to run after cloning
ignoreCache?: boolean
}
Module Information
The ModuleInfo type returned by GetModuleInfo contains detailed information about a module:
export type ModuleInfo = Required<ModuleDefinition> & {
// Current module lifecycle state
status: 'loaded' | 'constructed' | 'active' | 'unknown';
// Local filesystem path where the module is located
localPath: string;
};
Module Events
You can listen to module lifecycle events:
import { Events } from '@ajs/core/beta';
/**
* Event triggers when a module is constructed.
* @param module Module ID (string)
*/
Events.ModuleConstructed.register((moduleId: string) => {
console.log(`Module constructed: ${moduleId}`);
});
/**
* Event triggers when a module is started.
* @param module Module ID (string)
*/
Events.ModuleStarted.register((moduleId: string) => {
console.log(`Module started: ${moduleId}`);
});
/**
* Event triggers when a module is stopped.
* @param module Module ID (string)
*/
Events.ModuleStopped.register((moduleId: string) => {
console.log(`Module stopped: ${moduleId}`);
});
/**
* Event triggers when a module is destroyed.
* @param module Module ID (string)
*/
Events.ModuleDestroyed.register((moduleId: string) => {
console.log(`Module destroyed: ${moduleId}`);
});