kuzzle 2.56.0 → 2.57.0-beta.2

package/dist/lib/core/plugin/pluginsManager.d.ts

@@ -1,38 +1,80 @@
-export = PluginsManager;
+import type { JSONObject } from "../../types/JSONObject";
+import { BaseController } from "../../api/controllers/baseController";
+import type { ApiRoute } from "../../types/ApiRoute";
+import Plugin from "./plugin";
+/**
+ * Any function a plugin exposes: a pipe, a hook, an action handler, a strategy
+ * method. A plugin's members are `unknown` by construction — it is a
+ * user-supplied object — so this is the type a `typeof … === "function"` check
+ * produces, and what `bindPluginMethod` answers.
+ */
+type PluginMethod = (...args: unknown[]) => unknown;
+/**
+ * A strategy as a plugin hands it over: `JSONObject`, not
+ * `StrategyDefinition[string]`, because nothing has checked its shape yet —
+ * `validateStrategy` is what does, at runtime, and it is the reason this
+ * parameter cannot claim the validated type.
+ */
+type StrategyEntry = JSONObject;
+/**
+ * A strategy once registered: the declaration, the plugin that owns it, and the
+ * methods resolved and bound from the names the declaration carries.
+ */
 /**
- * @class PluginsManager
- * @param {Kuzzle} kuzzle
+ * A strategy method, resolved from its name and bound to the plugin instance.
+ *
+ * The return is whatever the plugin's method answers — `exists` gives a boolean,
+ * `getInfo` an object — so `JSONObject` describes what the *callers* read off it
+ * rather than a promise the plugins make. That is the same latitude the JSDoc's
+ * `{object}` gave, kept rather than narrowed, because narrowing it is an API
+ * decision and this is a conversion.
  */
+type StrategyMethod = (...args: unknown[]) => Promise<JSONObject>;
+interface RegisteredStrategy {
+    methods: JSONObject;
+    owner: string;
+    strategy: StrategyEntry;
+}
 declare class PluginsManager {
-    _plugins: Map<any, any>;
-    controllers: Map<any, any>;
-    strategies: {};
-    routes: any[];
+    private _plugins;
+    controllers: Map<string, BaseController>;
+    strategies: Record<string, RegisteredStrategy>;
+    routes: ApiRoute[];
     pluginsEnabledDir: string;
     pluginsAvailableDir: string;
+    authenticators: JSONObject;
+    config: JSONObject;
+    logger: ReturnType<typeof global.kuzzle.log.child>;
+    loadedPlugins: string[];
+    constructor();
+    set application(plugin: Plugin);
+    get plugins(): Plugin[];
     /**
-     * @example
-     * {
-     *   pluginName: {
-     *     authName: <constructor>,
-     *     authname2: <constructor>,
-     *     ...
-     *   },
-     *   pluginName2: {
-     *     ...
-     *   }
-     * }
-     *
-     * This structure prevents authenticator names collisions between
-     * multiple auth. plugins
-     */
-    authenticators: {};
-    config: import("../../..").PluginsConfiguration;
-    logger: import("../../kuzzle/Logger").Logger;
-    loadedPlugins: any[];
-    set application(plugin: any);
-    get application(): any;
-    get plugins(): any[];
+     * The application plugin, once `kuzzle.start` has registered one.
+     *
+     * `undefined` before that, and the shutdown path already read it that way —
+     * `pluginsManager?.application?.instance?.log?.flush?.()` defends against a
+     * start that failed before the assignment. The declared `Plugin` was the
+     * half of that the three eager readers assumed.
+     */
+    get application(): Plugin | undefined;
+    /**
+     * The plugin registered under `pluginName`, which is the only thing the
+     * strategy methods below can act on. Pre-Kaaf plugin names may carry upper
+     * case, hence the lowercasing every call site did for itself.
+     *
+     * The three callers dereferenced the map's answer unchecked — a strategy
+     * registered for an unknown plugin read `undefined.initCalled`. The error
+     * is the one `Backend.plugin.get` already raises for the same question.
+     */
+    private getPlugin;
+    /**
+     * The strategy registered under `strategyName`. Reading it off the record
+     * and dereferencing straight away is what `getStrategyFields` and
+     * `getStrategyMethod` did; `hasStrategyMethod` is the guard that existed,
+     * and only one of the two call sites used it.
+     */
+    private getStrategy;
     /**
      * Giving a controller name, tells if exists
      *
@@ -54,13 +96,13 @@ declare class PluginsManager {
      * @param {string} controller
      * @returns {Array}
      */
-    getActions(controller: string): any[];
+    getActions(controller: string): string[];
     /**
      * Returns an array filled with controller names
      *
      * @returns {Array}
      */
-    getControllerNames(): any[];
+    getControllerNames(): string[];
     /**
      * Giving a plugin name, tell if it exists
      *
@@ -73,7 +115,7 @@ declare class PluginsManager {
      *
      * @returns {object}
      */
-    getPluginsDescription(): object;
+    getPluginsDescription(): JSONObject;
     /**
      * Register plugins feature to Kuzzle
      *
@@ -81,7 +123,7 @@ declare class PluginsManager {
      *
      * @throws PluginImplementationError - Throws when an error occurs when registering a plugin
      */
-    init(plugins?: {}): Promise<any>;
+    init(plugins?: JSONObject): Promise<JSONObject>;
     /**
      * @param {string} strategyName
      * @returns {string[]}
@@ -98,7 +140,7 @@ declare class PluginsManager {
      * @param {string} methodName
      * @returns {function}
      */
-    getStrategyMethod(strategyName: string, methodName: string): Function;
+    getStrategyMethod(strategyName: string, methodName: string): StrategyMethod;
     /**
      * Returns the list of registered passport strategies
      * @returns {string[]}
@@ -112,7 +154,7 @@ declare class PluginsManager {
      * @param {object} strategy
      * @throws {PluginImplementationError} If the strategy is invalid
      */
-    validateStrategy(pluginName: string, strategyName: string, strategy: object): void;
+    validateStrategy(pluginName: string, strategyName: string, strategy: StrategyEntry): void;
     /**
      * Register a pipe function on an event
      *
@@ -123,8 +165,8 @@ declare class PluginsManager {
      *
      * @returns {string} pipeId
      */
-    registerPipe(plugin: object, event: string, handler: Function): string;
-    unregisterPipe(pipeId: any): void;
+    registerPipe(plugin: Plugin, event: string, handler: PluginMethod): string;
+    unregisterPipe(pipeId: string): void;
     /**
      * Registers an authentication strategy.
      * If the plugin init method has not been called yet, add the strategy to
@@ -136,7 +178,7 @@ declare class PluginsManager {
      * @throws {PluginImplementationError} If the strategy is invalid or if
      *                                     registration fails
      */
-    registerStrategy(pluginName: string, strategyName: string, strategy: object): void;
+    registerStrategy(pluginName: string, strategyName: string, strategy: StrategyEntry): void;
     /**
      * Unregister
      * @param {string} pluginName
@@ -149,35 +191,74 @@ declare class PluginsManager {
      * @param {object} plugin
      * @param {number} pipeWarnTime
      */
-    _initPipes(plugin: object): void;
+    _initPipes(plugin: Plugin): void;
+    /**
+     * Resolves one pipe or hook target — a function, or the name of a plugin
+     * method — into the handler to register.
+     *
+     * Shared by `_initPipes` and `_initHooks`, which carried the same twenty
+     * lines with two words changed. The `.js` → `.ts` rename re-scored both as
+     * new code, so the gate asked for the deduplication the files already wanted.
+     *
+     * @throws {PluginImplementationError} when the target names nothing callable
+     */
+    private resolveEventHandler;
     /**
      * @param {object} plugin
      */
-    _initHooks(plugin: object): void;
-    _initApi(plugin: any): Promise<void>;
+    _initHooks(plugin: Plugin): void;
+    _initApi(plugin: Plugin): Promise<void>;
     /**
      * Init plugin controllers
      *
      * @param {object} plugin
      * @returns {boolean}
      */
-    _initControllers(plugin: object): boolean;
+    _initControllers(plugin: Plugin): void;
+    /**
+     * Registers one action of the `api` object and answers the HTTP routes to
+     * bind for it — the declared ones, or the single default route built from the
+     * controller and action names.
+     *
+     * Lifted verbatim out of `_initApi` for the same gate reason as its siblings.
+     */
+    private registerApiAction;
+    /**
+     * Checks one entry of the deprecated `routes` object: its properties, the
+     * controller and action it names, and its HTTP verb.
+     *
+     * Lifted verbatim out of `_initControllers`, second half of the same
+     * gate-driven split as `registerLegacyAction`.
+     *
+     * @throws {PluginImplementationError}
+     */
+    private checkLegacyRoute;
+    /**
+     * Registers one action of the pre-Kaaf `controllers` object: a handler given
+     * either as a function or as the name of a plugin method.
+     *
+     * Lifted verbatim out of `_initControllers`, whose cognitive complexity the
+     * `.js` → `.ts` rename re-scored as new code.
+     *
+     * @throws {PluginImplementationError} when the target names nothing callable
+     */
+    private registerLegacyAction;
     /**
      * @param {object} plugin
      * @throws {PluginImplementationError} If strategies registration fails
      */
-    _initStrategies(plugin: object): void;
+    _initStrategies(plugin: Plugin): void;
     /**
      * @param {object} plugin
      * @throws {PluginImplementationError} If strategies registration fails
      */
-    _initAuthenticators(plugin: object): void;
+    _initAuthenticators(plugin: Plugin): void;
     /**
      * Load detected plugins in memory
      *
      * @returns {object} list of loaded plugin
      */
-    loadPlugins(plugins?: {}): object;
+    loadPlugins(plugins?: JSONObject): Map<string, Plugin>;
     /**
      * Wraps a strategy plugin's verify function.
      *
@@ -186,5 +267,6 @@ declare class PluginsManager {
      * @param {Function} verifyMethod - Strategy plugin's verify method
      * @returns {Function}
      */
-    wrapStrategyVerify(pluginName: string, strategyName: string, verifyMethod: Function): Function;
+    wrapStrategyVerify(pluginName: string, strategyName: string, verifyMethod: PluginMethod): (...args: unknown[]) => Promise<unknown>;
 }
+export = PluginsManager;