@bsb/base 9.0.0

package/LICENSE.commercial

@@ -0,0 +1,32 @@
+Commercial License
+
+This Commercial License (the "License") is a legal agreement between you (either an individual or a single entity) and the copyright holder(s) of this software.
+
+1. Definitions
+   "Software" refers to the software and associated documentation files.
+   "License" refers to this Commercial License agreement.
+   "Licensor" refers to the copyright holder(s).
+   "You" refers to the individual or entity exercising permissions granted by this License.
+
+2. Grant of License
+   Subject to the terms and conditions of this License, the Licensor hereby grants you a worldwide, non-exclusive, royalty-bearing license to use, reproduce, modify, display, perform, sublicense and distribute the Software.
+
+3. Redistribution
+   You may reproduce and distribute copies of the Software in any medium, with or without modifications, provided that you meet the following conditions:
+   a) You must give any recipients of the Software a copy of this License;
+   b) You must retain all copyright, patent, trademark, and attribution notices;
+   c) You must not distribute the Software under the AGPL or any other open source license.
+
+4. Patent License
+   Subject to the terms and conditions of this License, each Licensor hereby grants to you a perpetual, worldwide, non-exclusive, royalty-bearing patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Software.
+
+5. Disclaimer of Warranty
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+6. Limitation of Liability
+   IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+7. Termination
+   This License and the rights granted hereunder will terminate automatically if you fail to comply with its terms and conditions.
+
+For licensing terms, pricing, and other inquiries, please contact the copyright holder. 

package/README.md

@@ -0,0 +1,263 @@
+### BSB Node.js Service Base – Project Guide
+
+Better Service Base (BSB) is an event‑bus based microservice framework for Node.js/TypeScript. This package provides the Node.js implementation of the core runtime, plugin system, and developer tooling.
+
+**Version 9.0** introduces breaking changes with improved type safety, cross-language support, and automated code generation. See [Plugin Development Guide](./PLUGIN_DEVELOPMENT.md) for v9 patterns.
+
+### Intended Usage (Container‑first)
+- This project is designed to run standalone inside a Docker container and execute plugins authored and published separately.
+- It is not intended to be embedded or imported as a library into another application package.
+- Deploy the container and supply plugins via `BSB_PLUGIN_DIR` (recommended) or `BSB_PLUGINS` installation at container startup.
+
+#### Requirements
+- Node.js >= 23.0.0, npm >= 11.0.0
+- TypeScript 5.x for development
+
+### Project Structure
+- `src/`
+  - `index.ts`: Public exports for the package (base classes, interfaces, controllers).
+  - `cli.ts`: Production CLI entry (also exposed as `bin` → `bsb`).
+  - `dev.ts`: Development runner with hot-reload and restart controls.
+  - `client.ts`: Legacy helper for embedding a client; avoid in new code.
+  - `base/`: Core building blocks used by plugins and services
+    - `BSBService`, `BSBServiceClient`: Base classes for service plugins and their clients
+    - `PluginLogging`, `PluginMetrics`, `PluginEvents`: Per‑plugin facades into logging/metrics/events
+    - `BSBConfig`, `BSBLogging`, `BSBMetrics`, `BSBEvents`: Base plugin contracts
+    - `factory.ts`: Option resolution and presets for `ServiceBase`
+  - `interfaces/`: Strong TypeScript contracts for options, logging, metrics, events, results, tools
+  - `serviceBase/`: Runtime controllers that orchestrate the system
+    - `serviceBase.ts`: Main runtime (`ServiceBase`) – boot/init/run/dispose pipeline
+    - `config.ts`: Loads and initializes the configuration plugin
+    - `logging.ts`: Manages logging plugins and log dispatch
+    - `metrics.ts`: Manages metrics plugins via an internal event bus
+    - `events.ts`: Manages event plugins and exposes event APIs (broadcast, emit, return, streams)
+    - `plugins.ts`: Resolves and loads plugins from local build or external locations
+    - `services.ts`: Loads, orders, and runs service plugins + their clients
+  - `plugins/`: Built‑in plugins
+    - `config-default/`: Default configuration plugin
+    - `events-default/`: Default event bus
+    - `logging-default/`: Console logger with colors
+    - `metrics-default/`: Basic metrics implementation
+    - `service-default{0..4}/`, `service-benchmarkify/`: Example/demo service plugins
+  - `tests/`: Mocha + ts-node test suite
+- `lib/`: Compiled JavaScript output (generated by `tsc`)
+- `templates/`: Scaffolding for new plugins (`plugin.ts`, `pluginClient.ts`, `events.ts`, `logger.ts`)
+- `Dockerfile`, `entrypoint.sh`, `entrypoint.js`: Container build/runtime assets
+- `typedoc.json`, `docs.json`, `typedoc-theme/`: API docs generation configuration/theme
+
+### What's New in v9
+
+v9 introduces breaking changes focused on type safety, developer experience, and cross-language support:
+
+**Type Safety Improvements:**
+- `createEventSchemas()` - No more `as const` required, automatic type inference
+- Type branding - Compile-time validation that event types match categories
+- Duplicate name detection - Warns about confusing duplicate event names
+
+**Simplified Configuration:**
+- `createConfigSchema()` - Single function replaces class pattern
+- Plugin metadata - Define once, auto-generates PLUGIN_CLIENT and bsb-plugin.json
+- Centralized schemas - All generated JSON in lib/schemas/ with JSON $ref references
+
+**Cross-Language Support:**
+- Type helpers - int32, int64, uuid, datetime for precise type mapping
+- Schema export - Auto-generates JSON schemas for client code generation
+- Multi-language clients - Generate type-safe clients in TypeScript, C#, Go, Java
+- Cross-plugin events - Type-safe communication between plugins (no `any` types)
+
+See [Plugin Development Guide](./PLUGIN_DEVELOPMENT.md) for migration details and examples.
+
+### Runtime Architecture
+The `ServiceBase` class is the primary entry point. It coordinates the framework subsystems and plugin lifecycle.
+
+Boot flow (high level):
+1) Construct `ServiceBase` (select mode, cwd, and controller implementations)
+2) `init()` sequence
+   - `SBConfig.init()` → choose and init configuration plugin
+   - `SBLogging.init()` → load logging plugins
+   - `SBMetrics.init()` → load metrics plugins
+   - `SBEvents.init()` → load events plugins (+ always adds `events-default` first)
+   - `SBServices.setup()` → discover service plugins from config, create instances, and map dependencies; then `SBServices.init()` respecting declared ordering
+3) `run()` sequence
+   - Start logging, events, then `SBServices.run()` (ordered)
+   - Dispose config for safety, start heartbeat metric
+4) `dispose()`
+   - Disposes services, events, metrics, logging, and config; exits the process
+
+Timekeeping metrics are recorded for each step and logged as timers. A heartbeat counter runs hourly.
+
+### ServiceBase APIs (for BSB contributors only)
+- Construction (modern):
+  ```ts
+  import { ServiceBase, BSBPreset } from "@bettercorp/service-base";
+
+  // Simple defaults (local dev only)
+  const app = ServiceBase.development();
+
+  // Preset with overrides (local dev only)
+  const prod = ServiceBase.fromPreset(BSBPreset.PRODUCTION, { cwd: "/app" });
+
+  // Fully custom options (local dev only)
+  const custom = ServiceBase.create({ cwd: process.cwd(), plugins: ["logging-default", "events-default"] });
+  ```
+- Lifecycle:
+  ```ts
+  await app.init();
+  await app.run();
+  // app.dispose(code, reason) is called automatically on signals/errors
+  ```
+- Add a service plugin programmatically (local dev only, before services init):
+  ```ts
+  import { BSBService } from "@bettercorp/service-base";
+
+  class MyService extends BSBService<{ greeting: string }> { /* ... */ }
+  await app.addService("service-my", MyService as any, { greeting: "hi" });
+  ```
+
+### Subsystems
+- `SBConfig` (configuration)
+  - Defaults to `config-default` plugin; can be replaced via environment variables
+  - Provides resolved plugin lists: services, events, logging, metrics
+  - Exposes `getPluginConfig()` for per‑plugin configuration
+- `SBLogging` (logging)
+  - Manages logger plugins; routes debug/info/warn/error via an internal EventEmitter
+  - Supports rich filtering (all, by event, by plugin, detailed rules)
+- `SBMetrics` (metrics)
+  - Broadcasts metric operations (counters, gauges, histograms) and tracing (traces/spans) to all metrics plugins
+- `SBEvents` (events)
+  - Loads events plugins and always includes `events-default` as a fallback
+  - Offers APIs for broadcast, fire-and-forget, request/response, and streaming
+- `SBServices` (services)
+  - Loads service plugins from config, re-maps declared `init/run` before/after dependencies, and initializes/runs them in order
+
+### Plugin Resolution & Layout
+`SBPlugins` looks for plugins in the following order (container usage prefers the first external option):
+- Local project (dev): `src/plugins/<type>-<name>/index.ts`
+- Local build: `lib/plugins/<type>-<name>/index.js`
+- External plugin directory (`BSB_PLUGIN_DIR`) [preferred in container]: `<dir>/<npmPackage>/<version or latest>/lib/plugins/<type>-<name>/index.js`
+- Node modules: `node_modules/<npmPackage>/lib/plugins/<type>-<name>/index.js`
+
+Each plugin folder must export at least a `Plugin` class. Optionally export a `Config` class that extends `BSBPluginConfig` to provide validation and structured config.
+
+Built‑in plugin types include: `config-*`, `logging-*`, `metrics-*`, `events-*`, `service-*`.
+
+### Development vs Production
+- Container runtime (production): The container runs `lib/cli.js` (bin: `bsb`) and is the supported production path.
+  - Runs `new ServiceBase(false, true, CWD)` (legacy signature → optimized for production) inside the container entrypoint.
+- Development runner: `src/dev.ts`
+  - Runs `new ServiceBase(true, false, CWD)` with file watching
+  - Creates `.bsbdevwatch` on first run; supports include/exclude patterns
+  - Interactive controls:
+    - `Ctrl+R` or typing `rs` to restart
+    - `Ctrl+C`/`Ctrl+D` to dispose and exit
+
+### NPM Scripts
+- `npm run dev`: Start development runner with hot-reload
+- `npm start`: Run production CLI (`lib/cli.js` or `bsb`)
+- `npm run tsc`: Clean and compile TypeScript to `lib/`
+- `npm run build`: Clean → tsc → tests → generate docs → export schemas → generate plugin metadata
+- `npm run build-release`: Compile using `tsconfig-release.json`
+- `npm run lint`: ESLint over `src/`
+- `npm test`: Mocha + NYC coverage in TS mode
+- `npm run testDev`: Run tests without coverage (faster for development)
+- `npm run generate-docs`: Generate TypeDoc JSON to `docs.json`
+- `npm run docs`: Build static docs to `../docs/dist/languages/nodejs/types`
+- `npm run export-schemas`: Export event schemas to `lib/schemas/{plugin-name}.json`
+- `npm run generate-plugin-json`: Generate plugin metadata in `lib/schemas/`
+
+### Docker
+Multi‑stage build produces a minimal runtime image:
+- `ENV BSB_LIVE=true`, `ENV BSB_CONTAINER=true`, `ENV BSB_PLUGIN_DIR=/mnt/plugins`
+- Volumes: `/mnt/plugins` (external plugins), `/mnt/temp`
+- Entrypoint runs `node lib/cli.js` as an unprivileged `node` user
+- Optional plugin install/update at startup:
+  - `BSB_PLUGINS="@scope/plugin-a:1.2.3,@scope/plugin-b"` → installs/updates listed packages
+  - `BSB_PLUGIN_UPDATE=yes` → runs `npm update`
+
+Example run (with mounted plugins directory):
+```bash
+docker run --rm \
+  -e BSB_PLUGINS="@bettercorp/your-plugin" \
+  -v $(pwd)/plugins:/mnt/plugins \
+  bettercorp/bsb-node:latest
+```
+
+Recommended plugin directory layout (when using `BSB_PLUGIN_DIR`):
+```
+/mnt/plugins/
+  @org/plugin-a/
+    latest/
+      package.json            # version field used when resolving
+      lib/plugins/service-plugin-a/index.js
+      lib/plugins/logging-xyz/index.js
+    1.2.3/
+      package.json
+      lib/plugins/service-plugin-a/index.js
+  @org/plugin-b/
+    latest/
+      package.json
+      lib/plugins/events-abc/index.js
+```
+
+Notes
+- In container deployments, prefer placing prebuilt plugins under `BSB_PLUGIN_DIR` as above. This avoids network installs on boot and ensures deterministic versions via versioned folders or `latest`.
+- `BSB_PLUGINS` is available for dynamic `npm install` at startup, but mounting a curated plugin repository via `BSB_PLUGIN_DIR` is recommended for production.
+
+### Environment Variables
+- `APP_DIR`: Override working directory (mainly used in local development/testing)
+- `BSB_PLUGIN_DIR`: External plugin repository root (e.g., container volume `/mnt/plugins`)
+- `BSB_PLUGINS`: Comma‑separated list of npm packages to install at container start (entrypoint.js)
+- `BSB_PLUGIN_UPDATE`: `yes|y|true` to run `npm update` at container start
+- Config plugin override (advanced):
+  - `BSB_LOGGER_PLUGIN`: Name of config plugin (must start with `config-`)
+  - `BSB_LOGGER_PLUGIN_PACKAGE`: npm package name hosting the config plugin
+
+### Documentation
+
+#### Plugin Development (v9)
+- [Plugin Development Guide](./PLUGIN_DEVELOPMENT.md) - Complete guide for creating BSB plugins
+- [Type System Guide](./TYPE_SYSTEM.md) - Cross-language type system reference
+
+#### API Documentation
+- API docs are generated with TypeDoc (`typedoc.json`).
+  - `npm run generate-docs` → emits `docs.json`
+  - `npm run docs` → builds static site under `../docs/dist/languages/nodejs/types`
+
+### Testing
+- Tests: Mocha + ts-node with NYC coverage
+  - `npm test` → CI‑style JSON + lcov reports (`coverage/`)
+  - `npm run testDev` → dev‑friendly TS execution
+
+### Creating Plugins
+
+**For v9 plugin development, see the [Plugin Development Guide](./PLUGIN_DEVELOPMENT.md) for complete examples and best practices.**
+
+Quick reference:
+- Use `createEventSchemas()` to define typed events with compile-time validation
+- Use `createConfigSchema()` to define plugin configuration with metadata
+- Use cross-language type helpers (`uuid`, `int32`, `datetime`, etc.) for better code generation
+- Plugin metadata auto-generates `PLUGIN_CLIENT` and schema files during build
+
+Legacy templates are available under `templates/` but use outdated v8 patterns:
+- `templates/plugin.ts`, `templates/pluginClient.ts` (service plugin + client)
+- `templates/events.ts` (events plugin)
+- `templates/logger.ts` (logging plugin)
+
+At minimum, export a `Plugin` class in `lib/plugins/<type>-<name>/index.js` (or `src/plugins/.../index.ts` in dev). For configurable plugins, export a `Config` created with `createConfigSchema()`. Publish your plugin as an npm package or ship its prebuilt folder structure under `BSB_PLUGIN_DIR`.
+
+### Quick Start (Container)
+```bash
+# Provide prebuilt plugins under ./plugins, matching the recommended layout
+docker run --rm \
+  -v $(pwd)/plugins:/mnt/plugins:ro \
+  -e BSB_PLUGIN_DIR=/mnt/plugins \
+  bettercorp/bsb-node:latest
+```
+
+Local development (for contributors only):
+```bash
+npm install
+npm run dev
+```
+
+

package/bsb-plugin.json

@@ -0,0 +1,62 @@
+{
+  "nodejs": [
+    {
+      "id": "config-default",
+      "name": "config-default",
+      "basePath": "./",
+      "description": "Default configuration plugin for profile and plugin resolution",
+      "tags": [
+        "core",
+        "config",
+        "default"
+      ],
+      "documentation": [
+        "./docs/core-plugins/config-default.md"
+      ],
+      "pluginPath": "src/plugins/config-default/",
+      "image": "../docs/public/assets/images/bsb-logo.png",
+      "links": {
+        "github": "git+https://github.com/BetterCorp/better-service-base.git"
+      }
+    },
+    {
+      "id": "events-default",
+      "name": "events-default",
+      "basePath": "./",
+      "description": "Default in-process events plugin for BSB event routing",
+      "tags": [
+        "core",
+        "events",
+        "default"
+      ],
+      "documentation": [
+        "./docs/core-plugins/events-default.md"
+      ],
+      "pluginPath": "src/plugins/events-default/",
+      "image": "../docs/public/assets/images/bsb-logo.png",
+      "links": {
+        "github": "git+https://github.com/BetterCorp/better-service-base.git"
+      }
+    },
+    {
+      "id": "observable-default",
+      "name": "observable-default",
+      "basePath": "./",
+      "description": "Default console observable plugin for logging output",
+      "tags": [
+        "core",
+        "observable",
+        "default",
+        "console"
+      ],
+      "documentation": [
+        "./docs/core-plugins/observable-default.md"
+      ],
+      "pluginPath": "src/plugins/observable-default/",
+      "image": "../docs/public/assets/images/bsb-logo.png",
+      "links": {
+        "github": "git+https://github.com/BetterCorp/better-service-base.git"
+      }
+    }
+  ]
+}

package/lib/base/BSBConfig.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 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 { Observable, EventsConfig, ObservableConfig, PluginDefinition, PluginType } from "../interfaces";
+import { BaseWithObservable, BaseWithObservableConfig } from "./base";
+import { BSBReferencePluginConfigDefinition, BSBReferencePluginConfigType } from "./PluginConfig";
+/**
+ * @hidden
+ */
+type BSBConfigResolvedConfig<ReferencedConfig extends BSBReferencePluginConfigType> = ReferencedConfig extends null ? null : BSBReferencePluginConfigDefinition<ReferencedConfig>;
+type BSBConfigPropertyTypeSafe<T> = [T] extends [never] ? never : T extends undefined | null ? never : T;
+type BSBConfigConstructorTypeSafe<T> = [T] extends [never] ? undefined : T extends undefined | null ? undefined : T;
+/**
+ * @hidden
+ */
+export interface BSBConfigConstructor<ReferencedConfig extends BSBReferencePluginConfigType = any> extends BaseWithObservableConfig {
+    config: BSBConfigConstructorTypeSafe<BSBConfigResolvedConfig<ReferencedConfig>>;
+}
+/**
+ * @group Config
+ * @category Plugins
+ * @template T - The type of config for the plugin
+ * Abstract class representing the configuration for the Better Service Base.
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBConfig.html | API: BSBConfig}
+ */
+export declare abstract class BSBConfig<ReferencedConfig extends BSBReferencePluginConfigType = any> extends BaseWithObservable {
+    readonly config: BSBConfigPropertyTypeSafe<BSBConfigResolvedConfig<ReferencedConfig>>;
+    constructor(config: BSBConfigConstructor<ReferencedConfig>);
+    /**
+     * Run lifecycle method for configuration plugins.
+     *
+     * This method is inherited from the base plugin class but is not used by configuration plugins.
+     * Configuration plugins are initialized during the init phase and provide configuration data
+     * to other plugins. They do not require a separate run phase.
+     *
+     * @remarks
+     * Configuration plugins are typically disposed after all other plugins have been initialized
+     * to free up memory, as configuration data is cached by individual plugins. Therefore, this
+     * method intentionally performs no operation.
+     *
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * // Configuration plugins do not need to implement run()
+     * // The base class provides this no-op implementation
+     * export class MyConfigPlugin extends BSBConfig {
+     *   // No run() override needed
+     * }
+     * ```
+     *
+     * @see {@link BSBConfig.init} for the initialization lifecycle method
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBConfig.html#run | API: BSBConfig#run}
+     */
+    run(): void;
+    /**
+     * Returns the observable plugins configuration (unified logging, metrics, tracing).
+     * @returns Promise resolving to an object containing the observable configuration for each plugin.
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBConfig.html#getObservablePlugins | API: BSBConfig#getObservablePlugins}
+     */
+    abstract getObservablePlugins(obs: Observable): Promise<Record<string, ObservableConfig>>;
+    /**
+     * Returns the events plugins configuration.
+     * @returns Promise resolving to an object containing the events configuration for each plugin.
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBConfig.html#getEventsPlugins | API: BSBConfig#getEventsPlugins}
+     */
+    abstract getEventsPlugins(obs: Observable): Promise<Record<string, EventsConfig>>;
+    /**
+     * Returns the service plugins configuration.
+     * @returns Promise resolving to an object containing the configuration for each plugin.
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBConfig.html#getServicePlugins | API: BSBConfig#getServicePlugins}
+     */
+    abstract getServicePlugins(obs: Observable): Promise<Record<string, PluginDefinition>>;
+    /**
+     * Returns a mapped plugin name and whether the plugin is enabled or not
+     * @returns string of the plugin name and if it is enabled or not
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBConfig.html#getServicePluginDefinition | API: BSBConfig#getServicePluginDefinition}
+     */
+    abstract getServicePluginDefinition(obs: Observable, pluginName: string): Promise<{
+        name: string;
+        enabled: boolean;
+    }>;
+    /**
+     * Returns the configuration for a specific plugin.
+     * @template T - The type of the configuration object.
+     * @param plugin - The name of the plugin to retrieve the configuration for.
+     * @returns Promise resolving to the configuration object for the specified plugin, or null if the plugin is not found.
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBConfig.html#getPluginConfig | API: BSBConfig#getPluginConfig}
+     */
+    abstract getPluginConfig(obs: Observable, pluginType: PluginType, plugin: string): Promise<object | null>;
+}
+/**
+ * @hidden
+ */
+export declare class BSBConfigRef extends BSBConfig<null> {
+    getObservablePlugins(obs: Observable): Promise<Record<string, ObservableConfig>>;
+    getEventsPlugins(obs: Observable): Promise<Record<string, EventsConfig>>;
+    getServicePlugins(obs: Observable): Promise<Record<string, PluginDefinition>>;
+    getPluginConfig(obs: Observable, pluginType: PluginType, plugin: string): Promise<object | null>;
+    getServicePluginDefinition(obs: Observable, pluginName: string): Promise<{
+        name: string;
+        enabled: boolean;
+    }>;
+    dispose?(): void;
+    init?(obs: Observable): void;
+}
+export {};

package/lib/base/BSBConfig.js

@@ -0,0 +1,95 @@
+"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.BSBConfigRef = exports.BSBConfig = void 0;
+const base_1 = require("./base");
+const errorMessages_1 = require("./errorMessages");
+/**
+ * @group Config
+ * @category Plugins
+ * @template T - The type of config for the plugin
+ * Abstract class representing the configuration for the Better Service Base.
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBConfig.html | API: BSBConfig}
+ */
+class BSBConfig extends base_1.BaseWithObservable {
+    config;
+    constructor(config) {
+        super(config);
+        this.config = config.config;
+    }
+    /**
+     * Run lifecycle method for configuration plugins.
+     *
+     * This method is inherited from the base plugin class but is not used by configuration plugins.
+     * Configuration plugins are initialized during the init phase and provide configuration data
+     * to other plugins. They do not require a separate run phase.
+     *
+     * @remarks
+     * Configuration plugins are typically disposed after all other plugins have been initialized
+     * to free up memory, as configuration data is cached by individual plugins. Therefore, this
+     * method intentionally performs no operation.
+     *
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * // Configuration plugins do not need to implement run()
+     * // The base class provides this no-op implementation
+     * export class MyConfigPlugin extends BSBConfig {
+     *   // No run() override needed
+     * }
+     * ```
+     *
+     * @see {@link BSBConfig.init} for the initialization lifecycle method
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBConfig.html#run | API: BSBConfig#run}
+     */
+    run() { }
+}
+exports.BSBConfig = BSBConfig;
+/**
+ * @hidden
+ */
+class BSBConfigRef extends BSBConfig {
+    getObservablePlugins(obs) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBConfigRef", "getObservablePlugins");
+    }
+    getEventsPlugins(obs) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBConfigRef", "getEventsPlugins");
+    }
+    getServicePlugins(obs) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBConfigRef", "getServicePlugins");
+    }
+    getPluginConfig(obs, pluginType, plugin) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBConfigRef", "getPluginConfig");
+    }
+    getServicePluginDefinition(obs, pluginName) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBConfigRef", "getServicePluginName");
+    }
+}
+exports.BSBConfigRef = BSBConfigRef;
+//# sourceMappingURL=BSBConfig.js.map

package/lib/base/BSBConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BSBConfig.js","sourceRoot":"","sources":["../../src/base/BSBConfig.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAIH,iCAAsE;AACtE,mDAAmE;AAkCnE;;;;;;GAMG;AACH,MAAsB,SAEpB,SAAQ,yBAAkB;IACV,MAAM,CAAuE;IAE7F,YAAY,MAA8C;QACxD,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAA8E,CAAC;IACtG,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACI,GAAG,KAAU,CAAC;CA6CtB;AAjFD,8BAiFC;AAED;;GAEG;AACH,MAAa,YACX,SAAQ,SAAe;IACvB,oBAAoB,CAAC,GAAe;QAClC,MAAM,IAAA,gDAAgC,EAAC,cAAc,EAAE,sBAAsB,CAAC,CAAC;IACjF,CAAC;IAED,gBAAgB,CAAC,GAAe;QAC9B,MAAM,IAAA,gDAAgC,EAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;IAC7E,CAAC;IAED,iBAAiB,CAAC,GAAe;QAC/B,MAAM,IAAA,gDAAgC,EAAC,cAAc,EAAE,mBAAmB,CAAC,CAAC;IAC9E,CAAC;IAED,eAAe,CACb,GAAe,EACf,UAAsB,EACtB,MAAc;QAEd,MAAM,IAAA,gDAAgC,EAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC;IAC5E,CAAC;IAED,0BAA0B,CACxB,GAAe,EACf,UAAkB;QAElB,MAAM,IAAA,gDAAgC,EACpC,cAAc,EACd,sBAAsB,CACvB,CAAC;IACJ,CAAC;CAKF;AAnCD,oCAmCC"}