@eggjs/core 6.0.0-beta.0

package/dist/commonjs/loader/egg_loader.d.ts

@@ -0,0 +1,405 @@
+import type { Logger } from 'egg-logger';
+import { FileLoader, FileLoaderOptions } from './file_loader.js';
+import { ContextLoader, ContextLoaderOptions } from './context_loader.js';
+import { Timing } from '../utils/timing.js';
+import type { EggCore } from '../egg.js';
+export interface EggAppInfo {
+    /** package.json */
+    pkg: Record<string, any>;
+    /** the application name from package.json */
+    name: string;
+    /** current directory of application */
+    baseDir: string;
+    /** equals to serverEnv */
+    env: string;
+    /** equals to serverScope */
+    scope: string;
+    /** home directory of the OS */
+    HOME: string;
+    /** baseDir when local and unittest, HOME when other environment */
+    root: string;
+}
+export interface EggPluginInfo {
+    /** the plugin name, it can be used in `dep` */
+    name: string;
+    /** the package name of plugin */
+    package?: string;
+    version?: string;
+    /** whether enabled */
+    enable: boolean;
+    implicitEnable?: boolean;
+    /** the directory of the plugin package */
+    path?: string;
+    /** the dependent plugins, you can use the plugin name */
+    dependencies: string[];
+    /** the optional dependent plugins. */
+    optionalDependencies: string[];
+    dependents?: string[];
+    /** specify the serverEnv that only enable the plugin in it */
+    env: string[];
+    /** the file plugin config in. */
+    from: string;
+}
+export interface EggLoaderOptions {
+    /** server env */
+    env: string;
+    /** Application instance */
+    app: EggCore;
+    EggCoreClass?: typeof EggCore;
+    /** the directory of application */
+    baseDir: string;
+    /** egg logger */
+    logger: Logger;
+    /** server scope */
+    serverScope?: string;
+    /** custom plugins */
+    plugins?: Record<string, EggPluginInfo>;
+}
+export type EggDirInfoType = 'app' | 'plugin' | 'framework';
+export interface EggDirInfo {
+    path: string;
+    type: EggDirInfoType;
+}
+export declare class EggLoader {
+    #private;
+    readonly options: EggLoaderOptions;
+    readonly timing: Timing;
+    readonly pkg: Record<string, any>;
+    readonly eggPaths: string[];
+    readonly serverEnv: string;
+    readonly serverScope: string;
+    readonly appInfo: EggAppInfo;
+    dirs?: EggDirInfo[];
+    /**
+     * @class
+     * @param {Object} options - options
+     * @param {String} options.baseDir - the directory of application
+     * @param {EggCore} options.app - Application instance
+     * @param {Logger} options.logger - logger
+     * @param {Object} [options.plugins] - custom plugins
+     * @since 1.0.0
+     */
+    constructor(options: EggLoaderOptions);
+    get app(): EggCore;
+    get lifecycle(): import("../lifecycle.js").Lifecycle;
+    get logger(): Logger<import("egg-logger").EggLoggerOptions>;
+    /**
+     * Get {@link AppInfo#env}
+     * @return {String} env
+     * @see AppInfo#env
+     * @private
+     * @since 1.0.0
+     */
+    protected getServerEnv(): string;
+    /**
+     * Get {@link AppInfo#scope}
+     * @return {String} serverScope
+     * @private
+     */
+    protected getServerScope(): string;
+    /**
+     * Get {@link AppInfo#name}
+     * @return {String} appname
+     * @private
+     * @since 1.0.0
+     */
+    getAppname(): string;
+    /**
+     * Get home directory
+     * @return {String} home directory
+     * @since 3.4.0
+     */
+    getHomedir(): string;
+    /**
+     * Get app info
+     * @return {AppInfo} appInfo
+     * @since 1.0.0
+     */
+    protected getAppInfo(): EggAppInfo;
+    /**
+     * Get {@link EggLoader#eggPaths}
+     * @return {Array} framework directories
+     * @see {@link EggLoader#eggPaths}
+     * @private
+     * @since 1.0.0
+     */
+    protected getEggPaths(): string[];
+    /** start Plugin loader */
+    lookupDirs: Set<string>;
+    eggPlugins: Record<string, EggPluginInfo>;
+    appPlugins: Record<string, EggPluginInfo>;
+    customPlugins: Record<string, EggPluginInfo>;
+    allPlugins: Record<string, EggPluginInfo>;
+    orderPlugins: EggPluginInfo[];
+    /** enable plugins */
+    plugins: Record<string, EggPluginInfo>;
+    /**
+     * Load config/plugin.js from {EggLoader#loadUnits}
+     *
+     * plugin.js is written below
+     *
+     * ```js
+     * {
+     *   'xxx-client': {
+     *     enable: true,
+     *     package: 'xxx-client',
+     *     dep: [],
+     *     env: [],
+     *   },
+     *   // short hand
+     *   'rds': false,
+     *   'depd': {
+     *     enable: true,
+     *     path: 'path/to/depd'
+     *   }
+     * }
+     * ```
+     *
+     * If the plugin has path, Loader will find the module from it.
+     *
+     * Otherwise Loader will lookup follow the order by packageName
+     *
+     * 1. $APP_BASE/node_modules/${package}
+     * 2. $EGG_BASE/node_modules/${package}
+     *
+     * You can call `loader.plugins` that retrieve enabled plugins.
+     *
+     * ```js
+     * loader.plugins['xxx-client'] = {
+     *   name: 'xxx-client',                 // the plugin name, it can be used in `dep`
+     *   package: 'xxx-client',              // the package name of plugin
+     *   enable: true,                       // whether enabled
+     *   path: 'path/to/xxx-client',         // the directory of the plugin package
+     *   dep: [],                            // the dependent plugins, you can use the plugin name
+     *   env: [ 'local', 'unittest' ],       // specify the serverEnv that only enable the plugin in it
+     * }
+     * ```
+     *
+     * `loader.allPlugins` can be used when retrieve all plugins.
+     * @function EggLoader#loadPlugin
+     * @since 1.0.0
+     */
+    loadPlugin(): Promise<void>;
+    protected loadAppPlugins(): Promise<Record<string, EggPluginInfo>>;
+    protected loadEggPlugins(): Promise<Record<string, EggPluginInfo>>;
+    protected loadCustomPlugins(): Record<string, EggPluginInfo>;
+    protected readPluginConfigs(configPaths: string[] | string): Promise<Record<string, EggPluginInfo>>;
+    protected getOrderPlugins(allPlugins: Record<string, EggPluginInfo>, enabledPluginNames: string[], appPlugins: Record<string, EggPluginInfo>): EggPluginInfo[];
+    protected getLookupDirs(): Set<string>;
+    protected getPluginPath(plugin: EggPluginInfo): string;
+    /** end Plugin loader */
+    /** start Config loader */
+    configMeta: Record<string, any>;
+    config: Record<string, any>;
+    /**
+     * Load config/config.js
+     *
+     * Will merge config.default.js 和 config.${env}.js
+     *
+     * @function EggLoader#loadConfig
+     * @since 1.0.0
+     */
+    loadConfig(): Promise<void>;
+    /** end Config loader */
+    /** start Extend loader */
+    /**
+     * mixin Agent.prototype
+     * @function EggLoader#loadAgentExtend
+     * @since 1.0.0
+     */
+    loadAgentExtend(): Promise<void>;
+    /**
+     * mixin Application.prototype
+     * @function EggLoader#loadApplicationExtend
+     * @since 1.0.0
+     */
+    loadApplicationExtend(): Promise<void>;
+    /**
+     * mixin Request.prototype
+     * @function EggLoader#loadRequestExtend
+     * @since 1.0.0
+     */
+    loadRequestExtend(): Promise<void>;
+    /**
+     * mixin Response.prototype
+     * @function EggLoader#loadResponseExtend
+     * @since 1.0.0
+     */
+    loadResponseExtend(): Promise<void>;
+    /**
+     * mixin Context.prototype
+     * @function EggLoader#loadContextExtend
+     * @since 1.0.0
+     */
+    loadContextExtend(): Promise<void>;
+    /**
+     * mixin app.Helper.prototype
+     * @function EggLoader#loadHelperExtend
+     * @since 1.0.0
+     */
+    loadHelperExtend(): Promise<void>;
+    /**
+     * Find all extend file paths by name
+     * can be override in top level framework to support load `app/extends/{name}.js`
+     *
+     * @param {String} name - filename which may be `app/extend/{name}.js`
+     * @return {Array} filepaths extend file paths
+     * @private
+     */
+    protected getExtendFilePaths(name: string): string[];
+    /**
+     * Loader app/extend/xx.js to `prototype`,
+     * @function loadExtend
+     * @param {String} name - filename which may be `app/extend/{name}.js`
+     * @param {Object} proto - prototype that mixed
+     * @since 1.0.0
+     */
+    loadExtend(name: string, proto: object): Promise<void>;
+    /** end Extend loader */
+    /** start Custom loader */
+    /**
+     * load app.js
+     *
+     * @example
+     * - old:
+     *
+     * ```js
+     * module.exports = function(app) {
+     *   doSomething();
+     * }
+     * ```
+     *
+     * - new:
+     *
+     * ```js
+     * module.exports = class Boot {
+     *   constructor(app) {
+     *     this.app = app;
+     *   }
+     *   configDidLoad() {
+     *     doSomething();
+     *   }
+     * }
+     * @since 1.0.0
+     */
+    loadCustomApp(): Promise<void>;
+    /**
+     * Load agent.js, same as {@link EggLoader#loadCustomApp}
+     */
+    loadCustomAgent(): Promise<void>;
+    loadBootHook(): void;
+    /** end Custom loader */
+    /** start Service loader */
+    /**
+     * Load app/service
+     * @function EggLoader#loadService
+     * @param {Object} options - LoaderOptions
+     * @since 1.0.0
+     */
+    loadService(options?: Partial<ContextLoaderOptions>): Promise<void>;
+    /** end Service loader */
+    /** start Middleware loader */
+    /**
+     * Load app/middleware
+     *
+     * app.config.xx is the options of the middleware xx that has same name as config
+     *
+     * @function EggLoader#loadMiddleware
+     * @param {Object} opt - LoaderOptions
+     * @example
+     * ```js
+     * // app/middleware/status.js
+     * module.exports = function(options, app) {
+     *   // options == app.config.status
+     *   return async next => {
+     *     await next();
+     *   }
+     * }
+     * ```
+     * @since 1.0.0
+     */
+    loadMiddleware(opt?: Partial<FileLoaderOptions>): Promise<void>;
+    /** end Middleware loader */
+    /** start Controller loader */
+    /**
+     * Load app/controller
+     * @param {Object} opt - LoaderOptions
+     * @since 1.0.0
+     */
+    loadController(opt?: Partial<FileLoaderOptions>): Promise<void>;
+    /** end Controller loader */
+    /** start Router loader */
+    /**
+     * Load app/router.js
+     * @function EggLoader#loadRouter
+     * @since 1.0.0
+     */
+    loadRouter(): Promise<void>;
+    /** end Router loader */
+    /** start CustomLoader loader */
+    loadCustomLoader(): Promise<void>;
+    /** end CustomLoader loader */
+    /**
+     * Load single file, will invoke when export is function
+     *
+     * @param {String} filepath - fullpath
+     * @param {Array} inject - pass rest arguments into the function when invoke
+     * @return {Object} exports
+     * @example
+     * ```js
+     * app.loader.loadFile(path.join(app.options.baseDir, 'config/router.js'));
+     * ```
+     * @since 1.0.0
+     */
+    loadFile(filepath: string, ...inject: any[]): Promise<any>;
+    /**
+     * @param {String} filepath - fullpath
+     * @return {Object} exports
+     * @private
+     */
+    requireFile(filepath: string): Promise<any>;
+    /**
+     * Get all loadUnit
+     *
+     * loadUnit is a directory that can be loaded by EggLoader, it has the same structure.
+     * loadUnit has a path and a type(app, framework, plugin).
+     *
+     * The order of the loadUnits:
+     *
+     * 1. plugin
+     * 2. framework
+     * 3. app
+     *
+     * @return {Array} loadUnits
+     * @since 1.0.0
+     */
+    getLoadUnits(): EggDirInfo[];
+    /**
+     * Load files using {@link FileLoader}, inject to {@link Application}
+     * @param {String|Array} directory - see {@link FileLoader}
+     * @param {String} property - see {@link FileLoader}
+     * @param {Object} options - see {@link FileLoader}
+     * @since 1.0.0
+     */
+    loadToApp(directory: string | string[], property: string, options: FileLoaderOptions): Promise<void>;
+    /**
+     * Load files using {@link ContextLoader}
+     * @param {String|Array} directory - see {@link ContextLoader}
+     * @param {String} property - see {@link ContextLoader}
+     * @param {Object} options - see {@link ContextLoader}
+     * @since 1.0.0
+     */
+    loadToContext(directory: string | string[], property: string, options?: ContextLoaderOptions): Promise<void>;
+    /**
+     * @member {FileLoader} EggLoader#FileLoader
+     * @since 1.0.0
+     */
+    get FileLoader(): typeof FileLoader;
+    /**
+     * @member {ContextLoader} EggLoader#ContextLoader
+     * @since 1.0.0
+     */
+    get ContextLoader(): typeof ContextLoader;
+    getTypeFiles(filename: string): string[];
+    resolveModule(filepath: string): string | undefined;
+}