node-pluginsmanager 3.7.1 → 3.8.0

package/README.md

@@ -25,6 +25,7 @@ $ npm install node-pluginsmanager
 
   * simply manage plugins (extended from [node-pluginsmanager-plugin](https://github.com/Psychopoulet/node-pluginsmanager-plugin)) to interact with specifics hardwares / API / whatever
   * install plugins manually or via github & initialize them
+  * load external plugins from absolute directories (outside the plugins directory)
   * update plugins via github
   * uninstall plugins and release there resources
   * run plugins' middlewares for server, to create specifics rules
@@ -70,9 +71,36 @@ $ npm install node-pluginsmanager
 
   * ``` on("uninstalled", (pluginName: string, ...unknown[]) => void) : this ``` fires if a plugin is uninstalled
 
+## External plugins
+
+External plugins are loaded from absolute directories registered **before** `loadAll()`. They are added to `plugins` and initialized like local plugins, but cannot be updated or uninstalled by the manager.
+
+```typescript
+import { join } from "node:path";
+import PluginsManager from "node-pluginsmanager";
+
+const manager = new PluginsManager({
+  "directory": "/path/to/local/plugins",
+  "externalResourcesDirectory": "/path/to/resources"
+});
+
+await manager.addExternalPluginDirectory("/path/to/external/my-plugin");
+await manager.setOrder([ "my-plugin", "other-plugin" ]); // optional
+await manager.loadAll();
+await manager.initAll();
+```
+
+Rules:
+
+  * each path must be an **absolute** directory pointing to a plugin root
+  * registration must happen **before** `loadAll()`
+  * a plugin name cannot exist both locally and externally
+  * external plugins cannot be updated (`updateViaGithub`) or uninstalled (`uninstall`)
+  * `releaseAll()` and `destroyAll()` still apply to external plugins
+
 ## Examples
 
-[check the TypeScript compilation tests](https://github.com/Psychopoulet/node-pluginsmanager/blob/master/test/typescript/compilation.ts)
+[check the TypeScript compilation tests](https://github.com/Psychopoulet/node-pluginsmanager/blob/master/test/typescript/compilation.cts)
 
 ## Tests
 

package/lib/cjs/PluginsManager.d.ts

@@ -30,11 +30,14 @@ export default class PluginsManager extends EventEmitter<{
     protected _beforeInitAll: tBeforeAllMethodCallback | null;
     protected _logger: tLogger | null;
     protected _orderedPluginsNames: string[];
+    protected _externalPluginDirectories: string[];
+    protected _externalPluginNames: Set<string>;
     directory: string;
     externalResourcesDirectory: string;
     plugins: Orchestrator[];
     constructor(options?: iPluginManagerOptions);
     getPluginsNames(): string[];
+    addExternalPluginDirectory(directory: string): Promise<void>;
     setOrder(pluginsNames: string[]): Promise<void>;
     getOrder(): string[];
     checkAllModules(): Promise<void>;
@@ -49,6 +52,7 @@ export default class PluginsManager extends EventEmitter<{
     releaseAll(...data: unknown[]): Promise<void>;
     getLatestGithubTag(plugin: Orchestrator): Promise<string>;
     installViaGithub(user: string, repo: string, ...data: unknown[]): Promise<Orchestrator>;
+    private _isExternalPlugin;
     private _updateWithoutGit;
     updateViaGithub(plugin: Orchestrator, ...data: unknown[]): Promise<Orchestrator>;
     uninstall(plugin: Orchestrator, ...data: unknown[]): Promise<string>;

package/lib/cjs/PluginsManager.js

@@ -46,6 +46,8 @@ class PluginsManager extends node_events_1.default {
     _beforeInitAll;
     _logger;
     _orderedPluginsNames;
+    _externalPluginDirectories;
+    _externalPluginNames;
     // public
     directory; // plugins location (must be writable). default : join(homedir(), "node-pluginsmanager-plugins")
     externalResourcesDirectory; // external resources locations (sqlite, files, cache, etc...) (must be writable). default : join(homedir(), "node-pluginsmanager-resources")
@@ -61,6 +63,8 @@ class PluginsManager extends node_events_1.default {
         this._beforeLoadAll = null;
         this._beforeInitAll = null;
         this._orderedPluginsNames = [];
+        this._externalPluginDirectories = [];
+        this._externalPluginNames = new Set();
         this._logger = "function" === typeof options.logger ? options.logger : null;
         // public
         this.plugins = [];
@@ -73,6 +77,25 @@ class PluginsManager extends node_events_1.default {
             return plugin.name;
         });
     }
+    addExternalPluginDirectory(directory) {
+        return (0, checkAbsoluteDirectory_1.default)("addExternalPluginDirectory/directory", directory).then(() => {
+            if (this._externalPluginDirectories.includes(directory)) {
+                throw new Error("\"" + directory + "\" is already registered as external plugin directory");
+            }
+            const pluginName = (0, node_path_1.basename)(directory);
+            if (this._externalPluginNames.has(pluginName)) {
+                throw new Error("External plugin \"" + pluginName + "\" is already registered");
+            }
+            return (0, isDirectory_1.default)((0, node_path_1.join)(this.directory, pluginName));
+        }).then((existsAsLocal) => {
+            const pluginName = (0, node_path_1.basename)(directory);
+            if (existsAsLocal) {
+                throw new Error("Plugin \"" + pluginName + "\" already exists as a local plugin and cannot be added as external");
+            }
+            this._externalPluginDirectories.push(directory);
+            this._externalPluginNames.add(pluginName);
+        });
+    }
     // create a forced order to synchronously initialize plugins. not ordered plugins are asynchronously initialized after.
     setOrder(pluginsNames) {
         return (0, checkNonEmptyArray_1.default)("setOrder/pluginsNames", pluginsNames).then(() => {
@@ -201,7 +224,28 @@ class PluginsManager extends node_events_1.default {
             return (0, promises_1.readdir)(this.directory);
             // load all
         }).then((files) => {
-            return (0, loadSortedPlugins_1.default)(this.directory, this.externalResourcesDirectory, files, this.plugins, this._orderedPluginsNames, this.emit.bind(this), this._logger, ...data);
+            const conflictingNames = files.filter((fileName) => {
+                return this._externalPluginNames.has(fileName);
+            });
+            if (conflictingNames.length) {
+                throw new Error("Cannot load plugins: name conflict between local and external plugins (\""
+                    + conflictingNames.join("\", \"") + "\")");
+            }
+            const pluginsToLoad = [
+                ...files.map((pluginName) => {
+                    return {
+                        "name": pluginName,
+                        "directory": (0, node_path_1.join)(this.directory, pluginName)
+                    };
+                }),
+                ...this._externalPluginDirectories.map((directory) => {
+                    return {
+                        "name": (0, node_path_1.basename)(directory),
+                        "directory": directory
+                    };
+                })
+            ];
+            return (0, loadSortedPlugins_1.default)(pluginsToLoad, this.externalResourcesDirectory, this.plugins, this._orderedPluginsNames, this.emit.bind(this), this._logger, ...data);
             // sort plugins
         }).then(() => {
             this.plugins.sort((a, b) => {
@@ -291,6 +335,9 @@ class PluginsManager extends node_events_1.default {
         }).then(() => {
             return (0, checkNonEmptyString_1.default)("installViaGithub/repo", pluginName);
         }).then(() => {
+            if (this._externalPluginNames.has(pluginName)) {
+                throw new Error("Plugin \"" + pluginName + "\" is already registered as external and cannot be installed");
+            }
             const directory = (0, node_path_1.join)(this.directory, pluginName);
             return new Promise((resolve, reject) => {
                 (0, checkAbsoluteDirectory_1.default)("installViaGithub/plugindirectory", directory).then(() => {
@@ -428,6 +475,9 @@ class PluginsManager extends node_events_1.default {
             });
         });
     }
+    _isExternalPlugin(plugin) {
+        return this._externalPluginNames.has(plugin.name);
+    }
     _updateWithoutGit(directory, githubRepository) {
         return (0, promises_1.rm)(directory, {
             "recursive": true,
@@ -453,6 +503,9 @@ class PluginsManager extends node_events_1.default {
             if (!this.getPluginsNames().includes(pluginName)) {
                 throw new Error("Plugin \"" + pluginName + "\" is not registered");
             }
+            if (this._isExternalPlugin(plugin)) {
+                throw new Error("Plugin \"" + pluginName + "\" is external and cannot be updated");
+            }
             // check plugin directory
         }).then(() => {
             return (0, checkAbsoluteDirectory_1.default)("updateViaGithub/directory", this.directory).then(() => {
@@ -551,6 +604,9 @@ class PluginsManager extends node_events_1.default {
                 if (!this.getPluginsNames().includes(pluginName)) {
                     throw new Error("Plugin \"" + pluginName + "\" is not registered");
                 }
+                if (this._isExternalPlugin(plugin)) {
+                    throw new Error("Plugin \"" + pluginName + "\" is external and cannot be uninstalled");
+                }
             });
             // check plugin directory
         }).then(() => {

package/lib/cjs/loadSortedPlugins.d.ts

@@ -1,2 +1,6 @@
 import type { Orchestrator, tLogger } from "node-pluginsmanager-plugin";
-export default function loadSortedPlugins(globalDirectory: string, externalResourcesDirectory: string, files: string[], loadedPlugins: Orchestrator[], orderedPluginsNames: string[], emit: (eventName: string, ...subdata: unknown[]) => void, logger: tLogger | null, ...data: unknown[]): Promise<void>;
+export interface PluginToLoad {
+    "name": string;
+    "directory": string;
+}
+export default function loadSortedPlugins(pluginsToLoad: PluginToLoad[], externalResourcesDirectory: string, loadedPlugins: Orchestrator[], orderedPluginsNames: string[], emit: (eventName: string, ...subdata: unknown[]) => void, logger: tLogger | null, ...data: unknown[]): Promise<void>;

package/lib/cjs/loadSortedPlugins.js

@@ -5,22 +5,19 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = loadSortedPlugins;
-// natives
-const node_path_1 = require("node:path");
 // locals
 const createPluginByDirectory_1 = __importDefault(require("./createPluginByDirectory"));
 // private
 // methods
-function _loadPlugin(globalDirectory, externalResourcesDirectory, pluginFileName, loadedPlugins, emit, logger, ...data) {
+function _loadPlugin(pluginToLoad, externalResourcesDirectory, loadedPlugins, emit, logger, ...data) {
     // is already loaded ?
     const plugin = loadedPlugins.find((p) => {
-        return pluginFileName === p.name;
+        return pluginToLoad.name === p.name;
     });
     // is already exists ?
     return plugin ? Promise.resolve() : Promise.resolve().then(() => {
-        emit("loading", pluginFileName, ...data);
-        const directory = (0, node_path_1.join)(globalDirectory, pluginFileName);
-        return (0, createPluginByDirectory_1.default)(directory, externalResourcesDirectory, logger, ...data);
+        emit("loading", pluginToLoad.name, ...data);
+        return (0, createPluginByDirectory_1.default)(pluginToLoad.directory, externalResourcesDirectory, logger, ...data);
         // emit event
     }).then((createdPlugin) => {
         emit("loaded", createdPlugin, ...data);
@@ -28,40 +25,40 @@ function _loadPlugin(globalDirectory, externalResourcesDirectory, pluginFileName
         return Promise.resolve();
     });
 }
-function _loadPlugins(globalDirectory, externalResourcesDirectory, pluginsToLoad, loadedPlugins, emit, logger, i, ...data) {
+function _loadPlugins(pluginsToLoad, externalResourcesDirectory, loadedPlugins, emit, logger, i, ...data) {
     return i < pluginsToLoad.length ? Promise.resolve().then(() => {
-        return _loadPlugin(globalDirectory, externalResourcesDirectory, pluginsToLoad[i], loadedPlugins, emit, logger, ...data);
+        return _loadPlugin(pluginsToLoad[i], externalResourcesDirectory, loadedPlugins, emit, logger, ...data);
         // loop
     }).then(() => {
-        return _loadPlugins(globalDirectory, externalResourcesDirectory, pluginsToLoad, loadedPlugins, emit, logger, i + 1, ...data);
+        return _loadPlugins(pluginsToLoad, externalResourcesDirectory, loadedPlugins, emit, logger, i + 1, ...data);
     }) : Promise.resolve();
 }
 // module
-function loadSortedPlugins(globalDirectory, externalResourcesDirectory, files, loadedPlugins, orderedPluginsNames, emit, logger, ...data) {
-    // if no files, does not run
-    return !files.length ? Promise.resolve() : Promise.resolve().then(() => {
-        const sortedPluginsNames = [];
+function loadSortedPlugins(pluginsToLoad, externalResourcesDirectory, loadedPlugins, orderedPluginsNames, emit, logger, ...data) {
+    // if no plugins, does not run
+    return !pluginsToLoad.length ? Promise.resolve() : Promise.resolve().then(() => {
+        const sortedPlugins = [];
         orderedPluginsNames.forEach((pluginName) => {
-            const plugin = files.find((p) => {
-                return p === pluginName;
+            const plugin = pluginsToLoad.find((p) => {
+                return p.name === pluginName;
             });
-            if ("string" === typeof plugin) {
-                sortedPluginsNames.push(pluginName);
+            if (plugin) {
+                sortedPlugins.push(plugin);
             }
         });
         // first, sorted plugins
-        return sortedPluginsNames.length
-            ? _loadPlugins(globalDirectory, externalResourcesDirectory, sortedPluginsNames, loadedPlugins, emit, logger, 0, ...data)
+        return sortedPlugins.length
+            ? _loadPlugins(sortedPlugins, externalResourcesDirectory, loadedPlugins, emit, logger, 0, ...data)
             : Promise.resolve();
     }).then(() => {
-        const unsortedPluginsNames = [
-            ...files.filter((pluginName) => {
-                return !orderedPluginsNames.includes(pluginName);
+        const unsortedPlugins = [
+            ...pluginsToLoad.filter((plugin) => {
+                return !orderedPluginsNames.includes(plugin.name);
             }).sort((a, b) => {
-                if (a < b) {
+                if (a.name < b.name) {
                     return -1;
                 }
-                else if (a > b) {
+                else if (a.name > b.name) {
                     return 1;
                 }
                 else {
@@ -69,9 +66,9 @@ function loadSortedPlugins(globalDirectory, externalResourcesDirectory, files, l
                 }
             })
         ];
-        // then, all other plugins, asynchronously
-        return unsortedPluginsNames.length
-            ? _loadPlugins(globalDirectory, externalResourcesDirectory, unsortedPluginsNames, loadedPlugins, emit, logger, 0, ...data)
+        // then, all other plugins
+        return unsortedPlugins.length
+            ? _loadPlugins(unsortedPlugins, externalResourcesDirectory, loadedPlugins, emit, logger, 0, ...data)
             : Promise.resolve();
     });
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 
   "name": "node-pluginsmanager",
-  "version": "3.7.1",
+  "version": "3.8.0",
   "description": "A plugins manager.",
 
   "type": "commonjs",
@@ -43,32 +43,32 @@
     "/lib/cjs"
   ],
   "engines": {
-    "node": ">=22.23.1"
+    "node": ">=22.23.2"
   },
 
   "dependencies": {
-    "check-node-engine": "1.1.0",
+    "check-node-engine": "1.2.0",
     "check-version-modules": "2.5.0",
     "semver": "7.8.5"
   },
   "devDependencies": {
     "@types/express": "5.0.6",
-    "@types/node": "26.1.1",
-    "@types/semver": "7.7.1",
+    "@types/node": "26.4.1",
+    "@types/semver": "7.8.0",
     "@types/socket.io": "3.0.2",
     "@types/ws": "8.18.1",
     "eslint-plugin-personnallinter": "git+ssh://git@github.com/Psychopoulet/eslint-plugin-personnallinter",
     "express": "5.2.1",
     "husky": "9.1.7",
-    "mocha": "11.7.6",
-    "node-pluginsmanager-plugin": "7.4.3",
+    "mocha": "12.0.0",
+    "node-pluginsmanager-plugin": "7.4.4",
     "nyc": "18.0.0",
     "proxyquire": "2.1.3",
     "rimraf": "6.1.3",
     "socket.io": "4.8.3",
     "typescript": "5.9.3",
     "used-deps-analyzer": "0.4.0",
-    "ws": "8.21.1"
+    "ws": "8.21.3"
   },
 
   "keywords": [