@serenityjs/plugins 0.3.0-beta-20240602214627 → 0.3.0

package/dist/index.d.ts

@@ -1,59 +1,30 @@
 import { Logger } from '@serenityjs/logger';
 import Emitter from '@serenityjs/emitter';
 
-/**
- * Represents a base plugin that can be loaded into the Serenity server.
- */
-declare abstract class BasePlugin<T = unknown> {
-    /**
-     * The serenity instance.
-     */
-    readonly serenity: T;
-    /**
-     * The logger instance.
-     */
-    readonly logger: Logger;
-    /**
-     * Constructs a new base plugin instance.
-     *
-     * @param serenity - The serenity instance.
-     * @param logger - The logger instance.
-     */
-    constructor(serenity: T, logger: Logger);
-    /**
-     * Called when the plugin is started.
-     */
-    startup(): void;
-    /**
-     * Called when the plugin is stopped.
-     */
-    shutdown(): void;
-}
-
-interface PluginPackage {
-    name: string;
-    version: string;
-    main: string;
-    development: boolean;
-    scripts: {
-        build: string;
-    };
-}
 interface Plugin {
-    instance: BasePlugin;
-    typescript: boolean;
-    package: PluginPackage;
-    path: string;
-    plugin: unknown;
+    logger: Logger;
+    config: PluginConfig;
+    module: PluginModule;
 }
 interface PluginEvents {
     register: [Plugin];
+    ready: [];
 }
-declare class Plugins<T> extends Emitter<PluginEvents> {
-    /**
-     * The serenity instance.
-     */
-    protected readonly serenity: T;
+interface PluginModule {
+    onRegister?(plugin: Plugin): void;
+    onStartup?(...arguments_: Array<unknown>): void;
+    onShutdown?(...arguments_: Array<unknown>): void;
+}
+interface PluginConfig {
+    name: string;
+    version: string;
+    mode: "development" | "production";
+    color: string;
+    entry: string;
+    node?: boolean;
+    typescript?: boolean;
+}
+declare class Plugins extends Emitter<PluginEvents> {
     /**
      * The logger instance.
      */
@@ -67,30 +38,17 @@ declare class Plugins<T> extends Emitter<PluginEvents> {
      */
     readonly entries: Map<string, Plugin>;
     /**
-     * Constructs a new plugins instance.
-     *
-     * @param serenity - The serenity instance.
+     * Whether the plugins are ready.
      */
-    constructor(serenity: T, path: string, enabled?: boolean);
+    ready: boolean;
     /**
-     * Get a plugin from the plugins map.
+     * Constructs a new plugins instance.
      *
-     * @param name - The name of the plugin.
-     * @param version - The version of the plugin.
-     * @returns The plugin instance.
-     */
-    get<T = BasePlugin>(name: string, version?: string): T;
-    /**
-     * Get all the plugins from the plugins map.
-     */
-    getAll(): Array<BasePlugin>;
-    reload(name: string): void;
-    /**
-     * Start loading the plugins.
+     * @param serenity - The serenity instance.
      */
-    private start;
-    private validatePackage;
-    private validateTsconfig;
+    constructor(path: string, enabled?: boolean);
+    private load;
+    import<T = PluginModule>(name: string): T;
 }
 
-export { BasePlugin, Plugins };
+export { type Plugin, Plugins };

package/dist/index.js

@@ -30,44 +30,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  BasePlugin: () => BasePlugin,
   Plugins: () => Plugins
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/base.ts
-var BasePlugin = class {
-  /**
-   * The serenity instance.
-   */
-  serenity;
-  /**
-   * The logger instance.
-   */
-  logger;
-  /**
-   * Constructs a new base plugin instance.
-   *
-   * @param serenity - The serenity instance.
-   * @param logger - The logger instance.
-   */
-  constructor(serenity, logger) {
-    this.serenity = serenity;
-    this.logger = logger;
-    this.startup();
-  }
-  /**
-   * Called when the plugin is started.
-   */
-  startup() {
-  }
-  /**
-   * Called when the plugin is stopped.
-   */
-  shutdown() {
-  }
-};
-
 // src/plugins.ts
 var import_node_child_process = require("child_process");
 var import_node_fs = require("fs");
@@ -75,11 +41,40 @@ var import_node_path = require("path");
 var import_node_process = __toESM(require("process"));
 var import_logger = require("@serenityjs/logger");
 var import_emitter = __toESM(require("@serenityjs/emitter"));
+
+// src/templates/plugin-json.ts
+var PLUGIN_TEMPLATE = (
+  /* json */
+  `{
+  "name": "plugin-name",
+  "version": "1.0.0",
+  "mode": "development",
+  "color": "blue",
+  "entry": "index.js",
+  "node": false,
+  "typescript": false
+}
+`
+);
+
+// src/templates/tsconfig-json.ts
+var TSCONFIG_TEMPLATE = (
+  /* json */
+  `{
+  "extends": "@serenityjs/typescript-config/base.json",
+  "compilerOptions": {
+    "lib": ["es2022"],
+    "outDir": "./dist",
+    "types": ["node"]
+  },
+  "include": ["."],
+  "exclude": ["node_modules", "dist"],
+}
+`
+);
+
+// src/plugins.ts
 var Plugins = class extends import_emitter.default {
-  /**
-   * The serenity instance.
-   */
-  serenity;
   /**
    * The logger instance.
    */
@@ -92,230 +87,145 @@ var Plugins = class extends import_emitter.default {
    * A collection registry of all plugins.
    */
   entries;
+  /**
+   * Whether the plugins are ready.
+   */
+  ready = false;
   /**
    * Constructs a new plugins instance.
    *
    * @param serenity - The serenity instance.
    */
-  constructor(serenity, path, enabled = true) {
+  constructor(path, enabled = true) {
     super();
-    this.serenity = serenity;
     this.logger = new import_logger.Logger("Plugins", import_logger.LoggerColors.CyanBright);
     this.path = (0, import_node_path.resolve)(import_node_process.default.cwd(), path);
     this.entries = /* @__PURE__ */ new Map();
     if (enabled) {
       if (!(0, import_node_fs.existsSync)(this.path)) {
-        (0, import_node_fs.mkdirSync)(this.path);
-        this.logger.success(`Created plugins folder at "${this.path}"`);
-      }
-      this.logger.info(`Attempting to load plugins from "${this.path}"`);
-      void this.start();
-    }
-  }
-  /**
-   * Get a plugin from the plugins map.
-   *
-   * @param name - The name of the plugin.
-   * @param version - The version of the plugin.
-   * @returns The plugin instance.
-   */
-  get(name, version) {
-    const filtered = [...this.entries.values()].filter((plugin2) => {
-      return plugin2.package.name === name;
-    });
-    const plugin = filtered.find((plugin2) => {
-      return version ? plugin2.package.version === version : filtered[0];
-    });
-    if (!plugin) {
-      throw new Error(
-        `Plugin "${name}" with version "${version}" does not exist.`
-      );
-    }
-    return plugin.instance;
-  }
-  /**
-   * Get all the plugins from the plugins map.
-   */
-  getAll() {
-    const plugins = [...this.entries.values()].map((plugin) => {
-      return plugin.instance;
-    });
-    return plugins;
-  }
-  reload(name) {
-    const plugin = this.entries.get(name);
-    if (!plugin) {
-      throw new Error(`Plugin "${name}" does not exist.`);
-    }
-    plugin.instance.shutdown();
-    if (plugin.typescript) {
-      try {
-        if (plugin.package.scripts.build) {
-          (0, import_node_child_process.execSync)("npm run build", { cwd: plugin.path });
-        } else {
-          (0, import_node_child_process.execSync)("tsc", { cwd: plugin.path });
+        try {
+          (0, import_node_fs.mkdirSync)(this.path);
+        } catch (reason) {
+          this.logger.error(`Failed to create plugins directory!`, reason);
         }
-      } catch (reason) {
-        this.logger.error(
-          `Failed to compile plugin "${name}" before reloading.`,
-          reason
-        );
-        return;
       }
-    }
-    const path = require.resolve(plugin.path);
-    if (path) {
-      delete require.cache[path];
-    }
-    const pluginMain = require(`${(0, import_node_path.resolve)(plugin.path, plugin.package.main)}`);
-    if (!pluginMain.default) {
-      throw new Error(`Plugin "${name}" does not have a default export.`);
-    }
-    const pluginInstance = new pluginMain.default(
-      this.serenity,
-      new import_logger.Logger(`${name}@${plugin.package.version}`, import_logger.LoggerColors.Blue)
-    );
-    plugin.instance = pluginInstance;
-    this.emit("register", plugin);
-    this.logger.success(`Reloaded plugin "${name}".`);
-  }
-  /**
-   * Start loading the plugins.
-   */
-  async start() {
-    const files = (0, import_node_fs.readdirSync)(this.path, { withFileTypes: true });
-    for (const file of files) {
-      if (!file.isDirectory())
-        continue;
-      const files2 = (0, import_node_fs.readdirSync)((0, import_node_path.resolve)(file.path, file.name), {
+      const directories = (0, import_node_fs.readdirSync)(this.path, {
         withFileTypes: true
-      });
-      const packExsist = files2.find((file2) => file2.name === "package.json");
-      if (!packExsist) {
-        this.logger.error(
-          `Plugin "${file.name}" does not contain a package.json file.`
-        );
-        continue;
-      }
-      const pack = JSON.parse(
-        (0, import_node_fs.readFileSync)((0, import_node_path.resolve)(packExsist.path, packExsist.name), "utf8")
-      );
-      if (!this.validatePackage(file.name, pack))
-        continue;
-      const needModules = (0, import_node_fs.existsSync)(
-        (0, import_node_path.resolve)(file.path, file.name, "node_modules")
-      );
-      if (!needModules) {
-        try {
-          (0, import_node_child_process.execSync)("npm install", { cwd: import_node_process.default.cwd() });
-        } catch (reason) {
-          this.logger.error(
-            `Failed to install node_modules for plugin "${file.name}".`,
-            reason
-          );
-          continue;
+      }).filter((dirent) => dirent.isDirectory());
+      for (const directory of directories) {
+        const path2 = (0, import_node_path.resolve)(this.path, directory.name);
+        if (!(0, import_node_fs.existsSync)((0, import_node_path.resolve)(path2, "plugin.json"))) {
+          try {
+            const config2 = PLUGIN_TEMPLATE.replace(
+              "plugin-name",
+              directory.name
+            );
+            (0, import_node_fs.writeFileSync)((0, import_node_path.resolve)(path2, "plugin.json"), config2);
+          } catch {
+            this.logger.error(
+              `Failed to create plugin.json for ${directory.name}`
+            );
+          }
         }
-        this.logger.success(
-          `Installed node_modules for plugin "${file.name}".`
+        const config = JSON.parse(
+          (0, import_node_fs.readFileSync)((0, import_node_path.resolve)(path2, "plugin.json"), "utf8")
         );
-      }
-      const typescript = files2.find((file2) => file2.name === "tsconfig.json");
-      const tsconfig = typescript ? JSON.parse(
-        (0, import_node_fs.readFileSync)((0, import_node_path.resolve)(typescript.path, typescript.name), "utf8")
-      ) : null;
-      if (typescript && !this.validateTsconfig(file.name, tsconfig))
-        continue;
-      const needToCompile = Boolean(
-        typescript && !(0, import_node_fs.existsSync)(
-          (0, import_node_path.resolve)(file.path, file.name, tsconfig.compilerOptions.outDir)
-        ) || Boolean(pack?.development ?? false) === true
-      );
-      if (needToCompile) {
-        try {
-          if (pack?.scripts?.build) {
-            (0, import_node_child_process.execSync)("npm run build", { cwd: (0, import_node_path.resolve)(file.path, file.name) });
-          } else {
-            (0, import_node_child_process.execSync)("tsc", { cwd: (0, import_node_path.resolve)(file.path, file.name) });
+        if (config.node === true) {
+          if (!(0, import_node_fs.existsSync)((0, import_node_path.resolve)(path2, "package.json"))) {
+            try {
+              (0, import_node_child_process.execSync)("npm init -y", { stdio: "ignore", cwd: path2 });
+            } catch (reason) {
+              this.logger.error(
+                `Failed to create package.json for ${config.name}@${config.version}!`,
+                reason
+              );
+            }
+          }
+          if (!(0, import_node_fs.existsSync)((0, import_node_path.resolve)(path2, "package-lock.json"))) {
+            try {
+              this.logger.info(
+                `Installing dependencies for ${config.name}@${config.version}...`
+              );
+              (0, import_node_child_process.execSync)("npm install", { stdio: "ignore", cwd: path2 });
+            } catch (reason) {
+              this.logger.error(
+                `Failed to install dependencies for ${config.name}@${config.version}!`,
+                reason
+              );
+            }
+          }
+        }
+        if (config.typescript === true) {
+          if (!(0, import_node_fs.existsSync)((0, import_node_path.resolve)(path2, "tsconfig.json"))) {
+            try {
+              (0, import_node_fs.writeFileSync)((0, import_node_path.resolve)(path2, "tsconfig.json"), TSCONFIG_TEMPLATE);
+              (0, import_node_child_process.execSync)("npm pkg set scripts.build=tsc", {
+                stdio: "ignore",
+                cwd: path2
+              });
+            } catch (reason) {
+              this.logger.error(
+                `Failed to create tsconfig.json for ${config.name}@${config.version}`,
+                reason
+              );
+            }
+          }
+          if (!(0, import_node_fs.existsSync)((0, import_node_path.resolve)(path2, "dist")) || config.mode === "development") {
+            try {
+              this.logger.info(
+                `Building typescript files for ${config.name}@${config.version}...`
+              );
+              (0, import_node_child_process.execSync)("npm run build", { stdio: "ignore", cwd: path2 });
+            } catch (reason) {
+              this.logger.error(
+                `Failed to build typescript files for ${config.name}@${config.version}!`,
+                reason
+              );
+            }
           }
-          this.logger.success(`Compiled plugin "${file.name}".`);
-        } catch (reason) {
-          this.logger.error(`Failed to compile plugin "${file.name}".`, reason);
-          continue;
         }
       }
+      void this.load(directories);
+    }
+  }
+  async load(directories) {
+    for await (const directory of directories) {
       try {
-        const plugin = require(`${(0, import_node_path.resolve)(file.path, file.name, pack.main)}`);
-        if (!plugin.default)
-          continue;
-        const instance = new plugin.default(
-          this.serenity,
-          new import_logger.Logger(`${file.name}@${pack.version}`, import_logger.LoggerColors.Blue)
+        const path = (0, import_node_path.resolve)(this.path, directory.name);
+        const config = JSON.parse(
+          (0, import_node_fs.readFileSync)((0, import_node_path.resolve)(path, "plugin.json"), "utf8")
         );
-        const pluginEntry = {
-          instance,
-          typescript: Boolean(typescript),
-          package: pack,
-          path: (0, import_node_path.resolve)(file.path, file.name),
-          plugin
-        };
-        this.entries.set(file.name, pluginEntry);
-        this.emit("register", pluginEntry);
+        const instance = await import(`file://${(0, import_node_path.resolve)(path, config.entry)}`);
+        const module2 = instance["default"];
+        const adjustedColor = config.color.split("_").map((part) => {
+          return part.charAt(0).toUpperCase() + part.slice(1);
+        }).join("");
+        const color = import_logger.LoggerColors[adjustedColor] ?? import_logger.LoggerColors.White;
+        const logger = new import_logger.Logger(`${config.name}@${config.version}`, color);
+        const plugin = { config, module: module2, logger };
+        this.entries.set(config.name, plugin);
+        logger.success(`Successfully loaded at ${path}`);
+        try {
+          module2.onRegister?.(plugin);
+        } catch {
+        }
+        this.emit("register", plugin);
       } catch (reason) {
-        this.logger.error(`Failed to import plugin "${file.name}".`, reason);
-        continue;
+        this.logger.error(`Failed to load plugin! ${directory.name}`, reason);
       }
     }
+    this.ready = true;
+    this.emit("ready");
   }
-  validatePackage(path, pack) {
-    if (!pack?.name) {
-      this.logger.error(
-        `Plugin package.json "${path}" does not contain a "name" property.`
-      );
-      return false;
-    }
-    if (!pack?.version) {
-      this.logger.error(
-        `Plugin package.json "${path}" does not contain a "version" property.`
-      );
-      return false;
-    }
-    if (!pack?.type) {
-      this.logger.error(
-        `Plugin package.json "${path}" does not contain a "type" property.`
-      );
-      return false;
-    } else if (pack.type !== "commonjs") {
-      this.logger.error(
-        `Plugin package.json "${path}" type is not set to "commonjs".`
-      );
-      return false;
-    }
-    if (!pack?.main) {
-      this.logger.error(
-        `Plugin package.json "${path}" does not contain a "main" property.`
-      );
-      return false;
-    }
-    return true;
-  }
-  validateTsconfig(path, tsconfig) {
-    if (!tsconfig?.compilerOptions) {
-      this.logger.error(
-        `Plugin tsconfig.json "${path}" does not contain a "compilerOptions" property.`
-      );
-      return false;
-    }
-    if (!tsconfig?.compilerOptions?.outDir) {
-      this.logger.error(
-        `Plugin tsconfig.json "${path}" does not contain a "outDir" property.`
-      );
-      return false;
+  import(name) {
+    const plugin = this.entries.get(name);
+    if (!plugin) {
+      throw new Error(`Plugin ${name} not found!`);
     }
-    return true;
+    return plugin.module;
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  BasePlugin,
   Plugins
 });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serenityjs/plugins",
-	"version": "0.3.0-beta-20240602214627",
+	"version": "0.3.0",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"repository": "https://github.com/SerenityJS/serenity",
@@ -18,9 +18,9 @@
 		"preset": "@serenityjs/jest-presets/jest/node"
 	},
 	"devDependencies": {
-		"@serenityjs/eslint-config": "0.3.0-beta-20240602214627",
-		"@serenityjs/jest-presets": "0.3.0-beta-20240602214627",
-		"@serenityjs/typescript-config": "0.3.0-beta-20240602214627",
+		"@serenityjs/eslint-config": "*",
+		"@serenityjs/jest-presets": "*",
+		"@serenityjs/typescript-config": "*",
 		"@types/jest": "^29.5.12",
 		"@types/node": "^20.11.24",
 		"jest": "^29.7.0",
@@ -28,7 +28,7 @@
 		"typescript": "^5.4.2"
 	},
 	"dependencies": {
-		"@serenityjs/emitter": "0.3.0-beta-20240602214627",
-		"@serenityjs/logger": "0.3.0-beta-20240602214627"
+		"@serenityjs/emitter": "*",
+		"@serenityjs/logger": "*"
 	}
 }