@bsb/base 9.0.0

package/lib/serviceBase/plugins.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SBPlugins = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const interfaces_1 = require("../interfaces");
+/**
+ * @hidden
+ */
+function internalTrace(span) {
+    return (0, interfaces_1.createFakeDTrace)("serviceBase/SBPlugins", span);
+}
+/**
+ * BSB Plugins Controller
+ *
+ * This class is responsible for loading the plugins in the BSB framework.
+ * If you have a specific way of loading plugins, you can extend this class and then use your own class when creating the ServiceBase instance.
+ *
+ * @group Plugins
+ * @category Core
+ */
+class SBPlugins {
+    /**
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/SBPlugins.html | API: SBPlugins}
+     */
+    cwd;
+    nodeModulesPluginDir;
+    referencedPluginDir = null;
+    devMode;
+    constructor(cwd, devMode) {
+        this.cwd = cwd;
+        this.devMode = devMode;
+        this.nodeModulesPluginDir = (0, node_path_1.join)(this.cwd, "./node_modules/");
+        if (typeof process.env.BSB_PLUGIN_DIR == "string" &&
+            process.env.BSB_PLUGIN_DIR.length > 3) {
+            if (!(0, node_fs_1.existsSync)(process.env.BSB_PLUGIN_DIR)) {
+                throw new Error(`Plugin directory ${process.env.BSB_PLUGIN_DIR} does not exist`);
+            }
+            this.referencedPluginDir = process.env.BSB_PLUGIN_DIR;
+        }
+    }
+    async loadPlugin(log, npmPackage, plugin, name) {
+        const tTrace = internalTrace(`loadPlugin:${npmPackage}:${plugin}`);
+        log.debug(tTrace, `Plugin {name} from {package} try load as {pluginName}`, {
+            name: plugin,
+            pluginName: name,
+            package: npmPackage ?? "self",
+        });
+        const nodeModulesLib = npmPackage !== null;
+        let pluginPath = "";
+        let packageCwd = this.cwd;
+        let version = "1.0.0";
+        if (!nodeModulesLib) {
+            // If no package is defined in the config, we will not look anywhere else except for the local plugins
+            if (this.devMode) {
+                pluginPath = (0, node_path_1.join)(this.cwd, "./src/plugins/" + plugin);
+                if (!(0, node_fs_1.existsSync)(pluginPath)) {
+                    pluginPath = "";
+                }
+            }
+            if (pluginPath == "") {
+                pluginPath = (0, node_path_1.join)(this.cwd, "./lib/plugins/" + plugin);
+            }
+            const packageJsonPath = (0, node_path_1.join)(packageCwd, "./package.json");
+            if ((0, node_fs_1.existsSync)(packageJsonPath)) {
+                const packageJSON = JSON.parse((0, node_fs_1.readFileSync)(packageJsonPath, "utf-8")
+                    .toString());
+                version = packageJSON.version ?? '0.0.0';
+            }
+        }
+        else {
+            // If a package is defined in the config, we will look for the plugin in the BSB_PLUGIN_DIR env, followed by the node_modules directory. Local plugins are not used.
+            if (this.referencedPluginDir) {
+                const T1packageCwd = (0, node_path_1.join)(this.referencedPluginDir, npmPackage, version);
+                const T1pluginPath = (0, node_path_1.join)(this.referencedPluginDir, npmPackage, version, "./lib/plugins/" + plugin);
+                if ((0, node_fs_1.existsSync)(T1pluginPath)) {
+                    pluginPath = T1pluginPath;
+                    packageCwd = T1packageCwd;
+                }
+                else {
+                    const T2pluginPath = (0, node_path_1.join)(this.referencedPluginDir, npmPackage, "latest", "./lib/plugins/" + plugin);
+                    const T2packageCwd = (0, node_path_1.join)(this.referencedPluginDir, npmPackage, "latest");
+                    if ((0, node_fs_1.existsSync)(T2pluginPath)) {
+                        pluginPath = T2pluginPath;
+                        packageCwd = T2packageCwd;
+                    }
+                }
+            }
+            if (pluginPath == '') {
+                const T3pluginPath = (0, node_path_1.join)(this.nodeModulesPluginDir, npmPackage, "./lib/plugins/" + plugin);
+                const T3packageCwd = (0, node_path_1.join)(this.nodeModulesPluginDir, npmPackage);
+                if ((0, node_fs_1.existsSync)(T3pluginPath)) {
+                    pluginPath = T3pluginPath;
+                    packageCwd = T3packageCwd;
+                }
+            }
+            if ((0, node_fs_1.existsSync)(packageCwd) && (0, node_fs_1.existsSync)((0, node_path_1.join)(packageCwd, "./package.json"))) {
+                const packageJSON = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(packageCwd, "./package.json"), "utf-8")
+                    .toString());
+                version = packageJSON.version ?? '0.0.0';
+            }
+        }
+        if (!(0, node_fs_1.existsSync)(pluginPath)) {
+            log.error(tTrace, `Plugin {name} in {package} not found`, {
+                name: plugin,
+                package: npmPackage ?? "self",
+            });
+            return (0, interfaces_1.Err)(new Error(`Plugin ${plugin} in ${npmPackage ?? "self"} not found`));
+        }
+        log.debug(tTrace, `Plugin {name}: attempt to load from {path} as {pluginName}`, {
+            name: plugin,
+            path: pluginPath,
+            pluginName: name,
+        });
+        const loadResult = await (0, interfaces_1.fromPromise)(this.loadPluginFile(pluginPath, name, packageCwd, version));
+        if (!loadResult.success) {
+            log.error(tTrace, `Failed to load plugin {name}: {error}`, {
+                name: plugin,
+                error: loadResult.error.message,
+            });
+            return (0, interfaces_1.Err)(new Error(`Failed to load plugin ${name}: ${loadResult.error.message}`));
+        }
+        log.info(tTrace, `Successfully loaded plugin {name}`, { name: plugin });
+        return (0, interfaces_1.Ok)(loadResult.data);
+    }
+    async loadPluginFile(pluginPath, pluginName, packageCwd, version) {
+        let pluginFile = (0, node_path_1.join)(pluginPath, './index.js');
+        if (this.devMode) {
+            const tsPluginFile = (0, node_path_1.join)(pluginPath, './index.ts');
+            if ((0, node_fs_1.existsSync)(tsPluginFile)) {
+                pluginFile = tsPluginFile;
+            }
+        }
+        if (!(0, node_fs_1.existsSync)(pluginFile)) {
+            throw new Error(`Plugin ${pluginName} not found at ${pluginFile}`);
+        }
+        const pluginExports = await Promise.resolve(`${pluginFile}`).then(s => require(s));
+        if (!pluginExports.Plugin) {
+            throw new Error(`Plugin ${pluginName} does not export a Plugin class`);
+        }
+        let serviceConfigDef = null;
+        if (pluginExports.Config) {
+            serviceConfigDef = new pluginExports.Config(process.cwd(), packageCwd, pluginPath, pluginName);
+        }
+        return {
+            name: pluginName,
+            ref: pluginName,
+            version: version,
+            serviceConfig: serviceConfigDef,
+            plugin: pluginExports.Plugin,
+            packageCwd: packageCwd,
+            pluginCwd: pluginPath,
+            pluginPath: pluginPath,
+        };
+    }
+}
+exports.SBPlugins = SBPlugins;
+//# sourceMappingURL=plugins.js.map

package/lib/serviceBase/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.js","sourceRoot":"","sources":["../../src/serviceBase/plugins.ts"],"names":[],"mappings":"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"}

package/lib/serviceBase/serviceBase.d.ts

@@ -0,0 +1,228 @@
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import { BSBService } from "../base";
+import { BSBOptions, SimpleBSBOptions, BSBPreset } from "../interfaces";
+/**
+ * @hidden
+ */
+export declare const BOOT_STAT_KEYS: {
+    readonly BSB: "BSB";
+    readonly SELF: "SELF";
+    readonly CONFIG: "CONFIG";
+    readonly OBSERVABLE: "OBSERVABLE";
+    readonly EVENTS: "EVENTS";
+    readonly SERVICES: "SERVICES";
+    readonly INIT: "INIT";
+    readonly RUN: "RUN";
+};
+/**
+ * @hidden
+ */
+export type BootStatKeys = (typeof BOOT_STAT_KEYS)[keyof typeof BOOT_STAT_KEYS];
+/**
+ * Main entry point for the BSB framework.
+ *
+ * This class is responsible for initializing and running the BSB framework.
+ * You can override the default behaviour of the framework by passing in your own classes for the plugins, logging, metrics, events and services.
+ * The passed in classes are not the plugins themselves, but rather the classes that handle the plugin creation, setup and running.
+ *
+ * @group Main
+ * @category Core
+ */
+export declare class ServiceBase {
+    /**
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ServiceBase.html | API: ServiceBase}
+     */
+    private readonly mode;
+    /**
+     * Create a ServiceBase instance with simple configuration
+     *
+     * @param simple - Simple configuration options
+     * @returns New ServiceBase instance
+     *
+     * @group Main
+     * @category Factory
+     * @example
+     * ```typescript
+     * const app = ServiceBase.create({
+     *   cwd: './my-app',
+     *   plugins: ['logging-default', 'events-default']
+     * });
+     * ```
+     */
+    static create(simple?: SimpleBSBOptions): ServiceBase;
+    /**
+     * Create a ServiceBase instance from a preset
+     *
+     * @param preset - Preset configuration type
+     * @param overrides - Additional options to override preset defaults
+     * @returns New ServiceBase instance
+     *
+     * @group Main
+     * @category Factory
+     * @example
+     * ```typescript
+     * const app = ServiceBase.fromPreset(BSBPreset.DEVELOPMENT, {
+     *   cwd: './my-app'
+     * });
+     * ```
+     */
+    static fromPreset(preset: BSBPreset, overrides?: Partial<BSBOptions>): ServiceBase;
+    /**
+     * Create a minimal ServiceBase instance for quick prototyping
+     *
+     * @param cwd - Working directory (defaults to process.cwd())
+     * @returns New ServiceBase instance with minimal configuration
+     *
+     * @group Main
+     * @category Factory
+     * @example
+     * ```typescript
+     * const app = ServiceBase.minimal('./my-app');
+     * await app.init();
+     * await app.run();
+     * ```
+     */
+    static minimal(cwd?: string): ServiceBase;
+    /**
+     * Create a development ServiceBase instance with debug logging
+     *
+     * @param cwd - Working directory (defaults to process.cwd())
+     * @returns New ServiceBase instance configured for development
+     *
+     * @group Main
+     * @category Factory
+     */
+    static development(cwd?: string): ServiceBase;
+    /**
+     * Create a production ServiceBase instance with optimized settings
+     *
+     * @param cwd - Working directory (defaults to process.cwd())
+     * @returns New ServiceBase instance configured for production
+     *
+     * @group Main
+     * @category Factory
+     */
+    static production(cwd?: string): ServiceBase;
+    private readonly _CORE_PLUGIN_NAME;
+    private readonly _appId;
+    private readonly observable;
+    private readonly plugins;
+    private readonly config;
+    private readonly events;
+    private readonly observableBackend;
+    private readonly services;
+    private readonly cwd;
+    private coreMetrics;
+    private heartBeatMetric;
+    private bsbBootTimeMetric;
+    private _keeps?;
+    private _heartbeat;
+    private _startKeep;
+    private _outputKeep;
+    /**
+     * Creates a new ServiceBase instance to orchestrate the BSB framework.
+     *
+     * The ServiceBase is the main entry point for running BSB applications. It initializes
+     * and coordinates all subsystems including configuration, logging, metrics, events,
+     * and service plugins.
+     *
+     * @param options - Configuration options for the ServiceBase instance
+     * @param options.debug - Enable debug mode with verbose logging (default: true)
+     * @param options.live - Enable production/live mode optimizations (default: false)
+     * @param options.cwd - Working directory for the application (default: process.cwd())
+     * @param options.config - Custom configuration controller class
+     * @param options.plugins - Custom plugin loader class
+     * @param options.logging - Custom logging controller class
+     * @param options.metrics - Custom metrics controller class
+     * @param options.events - Custom events controller class
+     * @param options.services - Custom services controller class
+     *
+     * @example
+     * ```typescript
+     * // Basic usage with defaults
+     * const app = new ServiceBase();
+     * await app.init();
+     * await app.run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Production configuration
+     * const app = new ServiceBase({
+     *   debug: false,
+     *   live: true,
+     *   cwd: '/app'
+     * });
+     * await app.init();
+     * await app.run();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Development configuration
+     * const app = new ServiceBase({
+     *   debug: true,
+     *   live: false,
+     *   cwd: process.cwd()
+     * });
+     * await app.init();
+     * await app.run();
+     * ```
+     *
+     * @see {@link ServiceBase.create} for factory method with simple options
+     * @see {@link ServiceBase.fromPreset} for preset-based configuration
+     * @see {@link ServiceBase.init} for initialization
+     * @see {@link ServiceBase.run} for starting the application
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ServiceBase.html | API: ServiceBase}
+     */
+    private readonly _region?;
+    constructor(options?: BSBOptions);
+    /**
+     * Initialize all subsystems and plugins
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ServiceBase.html#init | API: ServiceBase.init}
+     */
+    init(): Promise<void>;
+    /**
+     * Run the application after initialization
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ServiceBase.html#run | API: ServiceBase.run}
+     */
+    run(): Promise<void>;
+    private heartBeat;
+    private _disposing;
+    /**
+     * Dispose all subsystems and exit process with code
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ServiceBase.html#dispose | API: ServiceBase.dispose}
+     */
+    dispose(eCode: number | undefined, reason: string, extraData?: any): Promise<void>;
+    /**
+     * Add a service plugin programmatically
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ServiceBase.html#addService | API: ServiceBase.addService}
+     */
+    addService(name: string, plugin: typeof BSBService<any, any>, config: object | any): Promise<import("../base").BSBServiceRef>;
+}
+export default ServiceBase;