web-node/pluginAPI.d.ts

High level javaScript backend plugin system and configuration merger.

import { Encoding, Mapping, RecursiveEvaluateable } from 'clientnode';
import { BaseState, Configuration, EvaluateablePartialConfiguration, HookPromiseResult, MetaPluginConfiguration, PackageConfiguration, Plugin, PluginChange, ServicePromisesState } from './type';
export declare const currentRequire: typeof require;
/**
 * Calls all plugin methods for given trigger description asynchronous and
 * waits for their resolved promises.
 * @param givenState - Contains runtime information about current hook.
 * @param parameters - Additional parameters to forward into plugin api.
 * @returns A promise which resolves when all callbacks have resolved their
 * promise holding given potentially modified data.
 */
export declare const callStack: <State extends BaseState<unknown> = ServicePromisesState, Output = undefined>(givenState: Omit<State, "pluginAPI">, ...parameters: Array<unknown>) => HookPromiseResult<Output>;
/**
 * Calls all plugin methods for given trigger description synchronous.
 * @param givenState - Contains runtime information about current hook.
 * @param parameters - Additional parameters to forward into plugin api.
 * @returns Given potentially modified data.
 */
export declare const callStackSynchronous: <State extends BaseState<unknown> = ServicePromisesState, Output = void>(givenState: Omit<State, "pluginAPI">, ...parameters: Array<unknown>) => Output;
/**
 * Converts given plugin name into the corresponding internal representation.
 * @param name - Name to convert.
 * @param regularExpression - Regular expression pattern which extracts
 * relevant name path as first match group.
 * @returns Transformed name.
 */
export declare const determineInternalName: (name: string, regularExpression: RegExp) => string;
/**
 * Evaluates given configuration object by letting plugins package sub
 * structure untouched.
 * @param configuration - Evaluable configuration structure.
 * @returns Resolved configuration.
 */
export declare const evaluateConfiguration: <Type extends Mapping<unknown> = Configuration>(configuration: RecursiveEvaluateable<Type> | Type) => Type;
/**
 * Checks for changed plugin api file in given plugins and reloads them if
 * necessary (new timestamp).
 * @param plugins - List of plugins to search for updates in.
 * @returns A list with plugins which have a changed api scope.
 */
export declare const hotReloadAPIFile: (plugins: Array<Plugin>) => Array<Plugin>;
/**
 * Checks for changed plugin configurations in given plugins and reloads them
 * if necessary (new timestamp).
 * @param plugins - List of plugins to search for updates in.
 * @param configurationPropertyNames - Property names to search for to use as
 * entry in plugin configuration file.
 * @returns A list with plugins which have a changed configurations.
 */
export declare const hotReloadConfigurationFile: (plugins: Array<Plugin>, configurationPropertyNames: Array<string>) => Array<Plugin>;
/**
 * Checks for changed plugin file type in given plugins and reloads them if
 * necessary (timestamp has changed).
 * @param type - Plugin file type to search for updates.
 * @param target - Property name existing in plugin meta information objects
 * which should be updated.
 * @param plugins - List of plugins to search for updates in.
 * @returns A list with plugin changes.
 */
export declare const hotReloadFiles: (type: "api" | "configuration", target: "packageConfiguration" | "scope", plugins: Array<Plugin>) => Array<PluginChange>;
/**
 * Extends given configuration object with given plugin specific ones and
 * returns a plugin specific meta information object.
 * @param name - Name of plugin to extend.
 * @param internalName - Internal name of plugin to extend.
 * @param plugins - List of all yet determined plugin information.
 * @param metaConfiguration - Configuration file configuration.
 * @param pluginPath - Path to given plugin.
 * @param encoding - Encoding to use to read and write from child process's.
 * @returns An object of plugin specific meta information.
 */
export declare const load: (name: string, internalName: string, plugins: Mapping<Plugin>, metaConfiguration: MetaPluginConfiguration, pluginPath: string, encoding?: Encoding) => Promise<Plugin>;
/**
 * Load given plugin api file in given path and generates a plugin specific
 * data structure with useful meta information.
 * @param relativeFilePaths - Paths to file to load relatively from given
 * plugin path.
 * @param pluginPath - Path to plugin directory.
 * @param name - Plugin name to use for proper error messages.
 * @param internalName - Internal plugin name to use for proper error messages.
 * @param plugins - List of plugins to search for trigger callbacks in.
 * @param encoding - Encoding to use to read and write from child process.
 * @param configuration - Plugin specific configurations.
 * @param configurationFilePaths - Plugin specific configuration file paths.
 * @returns Plugin meta information object.
 */
export declare const loadAPI: (relativeFilePaths: Array<string>, pluginPath: string, name: string, internalName: string, plugins: Mapping<Plugin>, encoding?: Encoding, configuration?: EvaluateablePartialConfiguration | null, configurationFilePaths?: Array<string>) => Promise<Plugin>;
/**
 * Loads plugin specific configuration object.
 * @param name - Property name where to inject resolved configuration into
 * global one.
 * @param packageConfiguration - Plugin specific package configuration object.
 * @param configurationPropertyNames - Property names to search for to use as
 * entry in plugin configuration file.
 * @returns Determined configuration object.
 */
export declare const loadConfiguration: (name: string, packageConfiguration: PackageConfiguration, configurationPropertyNames: Array<string>) => EvaluateablePartialConfiguration;
/**
 * Loads given plugin configurations into global configuration.
 * @param plugins - Topological sorted list of plugins to check for
 * configurations.
 * @param configuration - Global configuration to extend with.
 * @returns Updated given configuration object.
 */
export declare const loadConfigurations: (plugins: Array<Plugin>, configuration: Configuration) => Configuration;
/**
 * Load given api file path and returns exported scope.
 * @param filePath - Path to file to load.
 * @param name - Plugin name to use for proper error messages.
 * @param fallbackScope - Scope to return if an error occurs during loading.
 * If a "null" is given an error will be thrown.
 * @param log - Enables logging.
 * @returns Exported api file scope.
 */
export declare const loadFile: (filePath: string, name: string, fallbackScope?: null | object, log?: boolean) => object;
/**
 * Extends given configuration object with all plugin specific ones and returns
 * a topological sorted list of plugins with plugins specific meta information
 * stored.
 * @param configuration - Configuration object to extend and use.
 * @returns A topological sorted list of plugins objects.
 */
export declare const loadAll: (configuration: Configuration) => Promise<{
    configuration: Configuration;
    plugins: Array<Plugin>;
}>;
/**
 * Transform a list of absolute paths respecting the application context.
 * @param configuration - Configuration object.
 * @param configuration.core - Sub configuration web-node.
 * @param configuration.core.context - Sub web-node context configurations.
 * @param configuration.core.context.path - Current web-nodes path.
 * @param locations - Locations to process.
 * @returns Given and processed locations.
 */
export declare const determineLocations: ({ core: { context: { path: contextPath } } }: Configuration, locations?: Array<string> | string) => Array<string>;
/**
 * Ignore absolute defined locations (relativ to application context) and
 * relative defined in each loaded plugin location.
 * @param configuration - Configuration object.
 * @param plugins - List of active plugins.
 * @param filePath - Path to search for.
 * @param locations - Locations to search in.
 * @returns A boolean indicating whether given file path is in provided
 * locations.
 */
export declare const isInLocations: (configuration: Configuration, plugins: Array<Plugin>, filePath: string, locations: Array<string> | string) => boolean;
export declare const pluginAPI: {
    readonly callStack: <State extends BaseState<unknown> = ServicePromisesState<undefined, Configuration<Mapping<unknown>>, Mapping<unknown>, import("./type").ServicePromises<Mapping<unknown>>>, Output = undefined>(givenState: Omit<State, "pluginAPI">, ...parameters: Array<unknown>) => HookPromiseResult<Output>;
    readonly callStackSynchronous: <State extends BaseState<unknown> = ServicePromisesState<undefined, Configuration<Mapping<unknown>>, Mapping<unknown>, import("./type").ServicePromises<Mapping<unknown>>>, Output = void>(givenState: Omit<State, "pluginAPI">, ...parameters: Array<unknown>) => Output;
    readonly determineInternalName: (name: string, regularExpression: RegExp) => string;
    readonly determineLocations: ({ core: { context: { path: contextPath } } }: Configuration, locations?: Array<string> | string) => Array<string>;
    readonly evaluateConfiguration: <Type extends Mapping<unknown> = Configuration>(configuration: RecursiveEvaluateable<Type> | Type) => Type;
    readonly hotReloadAPIFile: (plugins: Array<Plugin>) => Array<Plugin>;
    readonly hotReloadConfigurationFile: (plugins: Array<Plugin>, configurationPropertyNames: Array<string>) => Array<Plugin>;
    readonly hotReloadFiles: (type: "api" | "configuration", target: "packageConfiguration" | "scope", plugins: Array<Plugin>) => Array<PluginChange>;
    readonly isInLocations: (configuration: Configuration, plugins: Array<Plugin>, filePath: string, locations: Array<string> | string) => boolean;
    readonly load: (name: string, internalName: string, plugins: Mapping<Plugin>, metaConfiguration: MetaPluginConfiguration, pluginPath: string, encoding?: Encoding) => Promise<Plugin>;
    readonly loadAll: (configuration: Configuration) => Promise<{
        configuration: Configuration;
        plugins: Array<Plugin>;
    }>;
    readonly loadAPI: (relativeFilePaths: Array<string>, pluginPath: string, name: string, internalName: string, plugins: Mapping<Plugin>, encoding?: Encoding, configuration?: EvaluateablePartialConfiguration | null, configurationFilePaths?: Array<string>) => Promise<Plugin>;
    readonly loadConfiguration: (name: string, packageConfiguration: PackageConfiguration, configurationPropertyNames: Array<string>) => EvaluateablePartialConfiguration;
    readonly loadConfigurations: (plugins: Array<Plugin>, configuration: Configuration) => Configuration;
    readonly loadFile: (filePath: string, name: string, fallbackScope?: null | object, log?: boolean) => object;
};
export default pluginAPI;