@bsb/base 9.0.0

package/lib/base/BSBEvents.d.ts

@@ -0,0 +1,207 @@
+/**
+ * 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 { Readable } from "node:stream";
+import { BaseWithObservableAndConfig, BaseWithObservableAndConfigConfig } from "./base";
+import { BSBReferencePluginConfigDefinition, BSBReferencePluginConfigType, BSBReferenceConfigType } from "./PluginConfig";
+import { Observable } from '../interfaces/observable';
+export interface BSBEventsConstructor<ReferencedConfig extends BSBReferencePluginConfigType = any> extends BaseWithObservableAndConfigConfig<ReferencedConfig extends null ? null : BSBReferencePluginConfigDefinition<ReferencedConfig> & BSBReferenceConfigType> {
+}
+/**
+ * @group Events
+ * @category Plugins
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBEvents.html | API: BSBEvents}
+ */
+export declare abstract class BSBEvents<ReferencedConfig extends BSBReferencePluginConfigType = any> extends BaseWithObservableAndConfig<ReferencedConfig extends null ? null : BSBReferencePluginConfigDefinition<ReferencedConfig> & BSBReferenceConfigType> {
+    constructor(config: BSBEventsConstructor<ReferencedConfig>);
+    /**
+     * Run lifecycle method for events plugins.
+     *
+     * This method is inherited from the base plugin class but is not used by events plugins.
+     * Events plugins are initialized during the init phase and begin processing events
+     * immediately. They do not require a separate run phase.
+     *
+     * @remarks
+     * Events plugins establish their event bus connections and listeners during initialization.
+     * The event routing is active as soon as init completes. Therefore, this method
+     * intentionally performs no operation.
+     *
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * // Events plugins do not need to implement run()
+     * // The base class provides this no-op implementation
+     * export class MyEventsPlugin extends BSBEvents<MyConfig> {
+     *   // No run() override needed
+     * }
+     * ```
+     *
+     * @see {@link BSBEvents.init} for the initialization lifecycle method
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBEvents.html#run | API: BSBEvents#run}
+     */
+    run(): void;
+    /**
+     * Listens for events that are emitted by other plugins
+     * Broadcast events are emitted and received by all plugins
+     *
+     * @param trace - The trace object for tracking the operation
+     * @param pluginName - The name of the plugin that is being listened to
+     * @param event - The event to listen for
+     * @param listener - The function to call when the event is received
+     * @returns Promise that resolves when the event listener has been registered
+     *
+     * @see BSB events-default plugin for an example of how to use this function
+     * @see {@link https://github.com/BetterCorp/better-service-base/tree/master/nodejs/src/plugins/events-default | Default Events Plugin}
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBEvents.html#onBroadcast | API: BSBEvents#onBroadcast}
+     */
+    abstract onBroadcast(trace: Observable, pluginName: string, event: string, listener: {
+        (trace: Observable, args: Array<any>): Promise<void>;
+    }): Promise<void>;
+    /**
+     * Emits an event that is received by all plugins
+     *
+     * @param trace - The trace object for tracking the operation
+     * @param pluginName - The name of the plugin that is emitting the event
+     * @param event - The event to emit
+     * @param args - The arguments to pass to the event listener
+     * @returns Promise that resolves when the event has been emitted
+     *
+     * @see BSB events-default plugin for an example of how to use this function
+     * @see {@link https://github.com/BetterCorp/better-service-base/tree/master/nodejs/src/plugins/events-default | Default Events Plugin}
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBEvents.html#emitBroadcast | API: BSBEvents#emitBroadcast}
+     */
+    abstract emitBroadcast(trace: Observable, pluginName: string, event: string, args: Array<any>): Promise<void>;
+    /**
+     * Listens for events that are emitted by other plugins
+     * Events are emitted and received by a single plugin
+     *
+     * @param trace - The trace object for tracking the operation
+     * @param pluginName - The name of the plugin that is being listened to
+     * @param event - The event to listen for
+     * @param listener - The function to call when the event is received
+     * @returns Promise that resolves when the event listener has been registered
+     *
+     * @see BSB events-default plugin for an example of how to use this function
+     * @see {@link https://github.com/BetterCorp/better-service-base/tree/master/nodejs/src/plugins/events-default | Default Events Plugin}
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBEvents.html#onEvent | API: BSBEvents#onEvent}
+     */
+    abstract onEvent(trace: Observable, pluginName: string, event: string, listener: {
+        (trace: Observable, args: Array<any>): Promise<void>;
+    }): Promise<void>;
+    /**
+     * Emits an event that is received by a single plugin
+     *
+     * @param trace - The trace object for tracking the operation
+     * @param pluginName - The name of the plugin that is emitting the event
+     * @param event - The event to emit
+     * @param args - The arguments to pass to the event listener
+     * @returns Promise that resolves when the event has been emitted
+     *
+     * @see BSB events-default plugin for an example of how to use this function
+     * @see {@link https://github.com/BetterCorp/better-service-base/tree/master/nodejs/src/plugins/events-default | Default Events Plugin}
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBEvents.html#emitEvent | API: BSBEvents#emitEvent}
+     */
+    abstract emitEvent(trace: Observable, pluginName: string, event: string, args: Array<any>): Promise<void>;
+    /**
+     * Listens for events that are emitted by other plugins and return a value
+     * Events are emitted and received by a single plugin
+     *
+     * @param trace - The trace object for tracking the operation
+     * @param pluginName - The name of the plugin that is being listened to
+     * @param event - The event to listen for
+     * @param listener - The function to call when the event is received
+     * @returns Promise that resolves when the event listener has been registered
+     *
+     * @see BSB events-default plugin for an example of how to use this function
+     * @see {@link https://github.com/BetterCorp/better-service-base/tree/master/nodejs/src/plugins/events-default | Default Events Plugin}
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBEvents.html#onReturnableEvent | API: BSBEvents#onReturnableEvent}
+     */
+    abstract onReturnableEvent(trace: Observable, pluginName: string, event: string, listener: {
+        (trace: Observable, args: Array<any>): Promise<any>;
+    }): Promise<void>;
+    /**
+     * Emits an event that is received by a single plugin and returns a value
+     *
+     * @param trace - The trace object for tracking the operation
+     * @param pluginName - The name of the plugin that is emitting the event
+     * @param event - The event to emit
+     * @param timeoutSeconds - The number of seconds to wait for the value to be returned
+     * @param args - The arguments to pass to the event listener
+     * @returns Promise that resolves when the event has been emitted and the value has been returned
+     *
+     * @see BSB events-default plugin for an example of how to use this function
+     * @see {@link https://github.com/BetterCorp/better-service-base/tree/master/nodejs/src/plugins/events-default | Default Events Plugin}
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBEvents.html#emitEventAndReturn | API: BSBEvents#emitEventAndReturn}
+     */
+    abstract emitEventAndReturn(trace: Observable, pluginName: string, event: string, timeoutSeconds: number, args: Array<any>): Promise<any>;
+    /**
+     * Sets up a receive stream to receive a stream from another plugin
+     *
+     * @param trace - The trace object for tracking the operation
+     * @param pluginName - The name of the plugin that is emitting the event
+     * @param event - The event to listen for
+     * @param listener - The function to call when the stream is received
+     * @param timeoutSeconds - The number of seconds to wait for the stream to be received
+     * @returns Promise that resolves with the stream id that can be used to stream data to the listener
+     *
+     * @see BSB events-default plugin for an example of how to use this function
+     * @see {@link https://github.com/BetterCorp/better-service-base/tree/master/nodejs/src/plugins/events-default | Default Events Plugin}
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBEvents.html#receiveStream | API: BSBEvents#receiveStream}
+     */
+    abstract receiveStream(trace: Observable, pluginName: string, event: string, listener: (trace: Observable, error: Error | null, stream: Readable) => Promise<void>, timeoutSeconds?: number): Promise<string>;
+    /**
+     * Sets up a send stream to send a stream to another plugin that created a receive stream
+     *
+     * @param trace - The trace object for tracking the operation
+     * @param pluginName - The name of the plugin that is emitting the event
+     * @param event - The event to listen for
+     * @param streamId - The id of the stream to send data to
+     * @param stream - The stream to send data from
+     * @returns Promise that resolves when the stream has been sent
+     *
+     * @see BSB events-default plugin for an example of how to use this function
+     * @see {@link https://github.com/BetterCorp/better-service-base/tree/master/nodejs/src/plugins/events-default | Default Events Plugin}
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBEvents.html#sendStream | API: BSBEvents#sendStream}
+     */
+    abstract sendStream(trace: Observable, pluginName: string, event: string, streamId: string, stream: Readable): Promise<void>;
+}
+/**
+ * @hidden
+ * DO NOT REFERENCE/USE THIS CLASS - IT IS AN INTERNALLY REFERENCED CLASS
+ */
+export declare class BSBEventsRef extends BSBEvents {
+    onBroadcast(trace: Observable, pluginName: string, event: string, listener: (trace: Observable, args: any[]) => Promise<void>): Promise<void>;
+    emitBroadcast(trace: Observable, pluginName: string, event: string, args: any[]): Promise<void>;
+    onEvent(trace: Observable, pluginName: string, event: string, listener: (trace: Observable, args: any[]) => Promise<void>): Promise<void>;
+    emitEvent(trace: Observable, pluginName: string, event: string, args: any[]): Promise<void>;
+    onReturnableEvent(trace: Observable, pluginName: string, event: string, listener: (trace: Observable, args: any[]) => Promise<any>): Promise<void>;
+    emitEventAndReturn(trace: Observable, pluginName: string, event: string, timeoutSeconds: number, args: any[]): Promise<any>;
+    receiveStream(trace: Observable, pluginName: string, event: string, listener: (trace: Observable, error: Error | null, stream: Readable) => Promise<void>, timeoutSeconds?: number | undefined): Promise<string>;
+    sendStream(trace: Observable, pluginName: string, event: string, streamId: string, stream: Readable): Promise<void>;
+    dispose?(): void;
+    init?(obs: Observable): void | Promise<void>;
+}

package/lib/base/BSBEvents.js

@@ -0,0 +1,101 @@
+"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.BSBEventsRef = exports.BSBEvents = void 0;
+const base_1 = require("./base");
+const errorMessages_1 = require("./errorMessages");
+/**
+ * @group Events
+ * @category Plugins
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBEvents.html | API: BSBEvents}
+ */
+class BSBEvents extends base_1.BaseWithObservableAndConfig {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Run lifecycle method for events plugins.
+     *
+     * This method is inherited from the base plugin class but is not used by events plugins.
+     * Events plugins are initialized during the init phase and begin processing events
+     * immediately. They do not require a separate run phase.
+     *
+     * @remarks
+     * Events plugins establish their event bus connections and listeners during initialization.
+     * The event routing is active as soon as init completes. Therefore, this method
+     * intentionally performs no operation.
+     *
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * // Events plugins do not need to implement run()
+     * // The base class provides this no-op implementation
+     * export class MyEventsPlugin extends BSBEvents<MyConfig> {
+     *   // No run() override needed
+     * }
+     * ```
+     *
+     * @see {@link BSBEvents.init} for the initialization lifecycle method
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBEvents.html#run | API: BSBEvents#run}
+     */
+    run() { }
+}
+exports.BSBEvents = BSBEvents;
+/**
+ * @hidden
+ * DO NOT REFERENCE/USE THIS CLASS - IT IS AN INTERNALLY REFERENCED CLASS
+ */
+class BSBEventsRef extends BSBEvents {
+    onBroadcast(trace, pluginName, event, listener) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBEventsRef", "onBroadcast");
+    }
+    emitBroadcast(trace, pluginName, event, args) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBEventsRef", "emitBroadcast");
+    }
+    onEvent(trace, pluginName, event, listener) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBEventsRef", "onEvent");
+    }
+    emitEvent(trace, pluginName, event, args) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBEventsRef", "emitEvent");
+    }
+    onReturnableEvent(trace, pluginName, event, listener) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBEventsRef", "onReturnableEvent");
+    }
+    emitEventAndReturn(trace, pluginName, event, timeoutSeconds, args) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBEventsRef", "emitEventAndReturn");
+    }
+    receiveStream(trace, pluginName, event, listener, timeoutSeconds) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBEventsRef", "receiveStream");
+    }
+    sendStream(trace, pluginName, event, streamId, stream) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBEventsRef", "sendStream");
+    }
+}
+exports.BSBEventsRef = BSBEventsRef;
+//# sourceMappingURL=BSBEvents.js.map

package/lib/base/BSBEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BSBEvents.js","sourceRoot":"","sources":["../../src/base/BSBEvents.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAIH,iCAAwF;AACxF,mDAAmE;AAcnE;;;;GAIG;AACH,MAAsB,SAGlB,SAAQ,kCAIP;IACD,YAAY,MAA8C;QACtD,KAAK,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACI,GAAG,KAAU,CAAC;CA0KxB;AAhND,8BAgNC;AAED;;;GAGG;AACH,MAAa,YACT,SAAQ,SAAS;IACV,WAAW,CACd,KAAiB,EACjB,UAAkB,EAClB,KAAa,EACb,QAA2D;QAE3D,MAAM,IAAA,gDAAgC,EAAC,cAAc,EAAE,aAAa,CAAC,CAAC;IAC1E,CAAC;IAEM,aAAa,CAChB,KAAiB,EACjB,UAAkB,EAClB,KAAa,EACb,IAAW;QAEX,MAAM,IAAA,gDAAgC,EAAC,cAAc,EAAE,eAAe,CAAC,CAAC;IAC5E,CAAC;IAEM,OAAO,CACV,KAAiB,EACjB,UAAkB,EAClB,KAAa,EACb,QAA2D;QAE3D,MAAM,IAAA,gDAAgC,EAAC,cAAc,EAAE,SAAS,CAAC,CAAC;IACtE,CAAC;IAEM,SAAS,CACZ,KAAiB,EACjB,UAAkB,EAClB,KAAa,EACb,IAAW;QAEX,MAAM,IAAA,gDAAgC,EAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IACxE,CAAC;IAEM,iBAAiB,CACpB,KAAiB,EACjB,UAAkB,EAClB,KAAa,EACb,QAA0D;QAE1D,MAAM,IAAA,gDAAgC,EAAC,cAAc,EAAE,mBAAmB,CAAC,CAAC;IAChF,CAAC;IAEM,kBAAkB,CACrB,KAAiB,EACjB,UAAkB,EAClB,KAAa,EACb,cAAsB,EACtB,IAAW;QAEX,MAAM,IAAA,gDAAgC,EAClC,cAAc,EACd,oBAAoB,CACvB,CAAC;IACN,CAAC;IAEM,aAAa,CAChB,KAAiB,EACjB,UAAkB,EAClB,KAAa,EACb,QAAqF,EACrF,cAAmC;QAEnC,MAAM,IAAA,gDAAgC,EAAC,cAAc,EAAE,eAAe,CAAC,CAAC;IAC5E,CAAC;IAEM,UAAU,CACb,KAAiB,EACjB,UAAkB,EAClB,KAAa,EACb,QAAgB,EAChB,MAAgB;QAEhB,MAAM,IAAA,gDAAgC,EAAC,cAAc,EAAE,YAAY,CAAC,CAAC;IACzE,CAAC;CAKJ;AAnFD,oCAmFC"}

package/lib/base/BSBObservable.d.ts

@@ -0,0 +1,178 @@
+/**
+ * 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 { DTrace, LogMeta } from "../interfaces";
+import { BaseWithConfig, BaseWithConfigConfig } from "./base";
+import { BSBError } from "./errorMessages";
+import { BSBReferencePluginConfigDefinition, BSBReferencePluginConfigType } from "./PluginConfig";
+export interface BSBObservableConstructor<ReferencedConfig extends BSBReferencePluginConfigType = any> extends BaseWithConfigConfig<ReferencedConfig extends null ? null : BSBReferencePluginConfigDefinition<ReferencedConfig> & any> {
+}
+/**
+ * Unified Observable plugin base class for logging, metrics, and tracing
+ * @group Observable
+ * @category Plugins
+ * @template ReferencedConfig - The type of configuration for the plugin
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBObservable.html | API: BSBObservable}
+ */
+export declare abstract class BSBObservable<ReferencedConfig extends BSBReferencePluginConfigType = any> extends BaseWithConfig<ReferencedConfig extends null ? null : BSBReferencePluginConfigDefinition<ReferencedConfig> & any> {
+    constructor(config: BSBObservableConstructor<ReferencedConfig>);
+    /**
+     * Logging: Debug level
+     * @param trace - Trace for tracking the operation
+     * @param pluginName - Name of the plugin emitting the log
+     * @param message - Log message
+     * @param meta - Metadata
+     */
+    debug?(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void;
+    /**
+     * Logging: Info level
+     * @param trace - Trace for tracking the operation
+     * @param pluginName - Name of the plugin emitting the log
+     * @param message - Log message
+     * @param meta - Metadata
+     */
+    info?(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void;
+    /**
+     * Logging: Warn level
+     * @param trace - Trace for tracking the operation
+     * @param pluginName - Name of the plugin emitting the log
+     * @param message - Log message
+     * @param meta - Metadata
+     */
+    warn?(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void;
+    /**
+     * Logging: Error level
+     * @param trace - Trace for tracking the operation
+     * @param pluginName - Name of the plugin emitting the log
+     * @param message - Log message or error object
+     * @param meta - Metadata
+     */
+    error?(trace: DTrace, pluginName: string, message: string | BSBError<any>, meta?: LogMeta<any>): void;
+    /**
+     * Metrics: Counter creation
+     * @param timestamp - Timestamp of the metric
+     * @param pluginName - Name of the plugin emitting the metric
+     * @param name - Metric name
+     * @param description - Metric description
+     * @param help - Help text
+     * @param labels - Optional labels
+     */
+    createCounter?(timestamp: number, pluginName: string, name: string, description: string, help: string, labels?: string[]): void | Promise<void>;
+    /**
+     * Metrics: Gauge creation
+     * @param timestamp - Timestamp of the metric
+     * @param pluginName - Name of the plugin emitting the metric
+     * @param name - Metric name
+     * @param description - Metric description
+     * @param help - Help text
+     * @param labels - Optional labels
+     */
+    createGauge?(timestamp: number, pluginName: string, name: string, description: string, help: string, labels?: string[]): void | Promise<void>;
+    /**
+     * Metrics: Histogram creation
+     * @param timestamp - Timestamp of the metric
+     * @param pluginName - Name of the plugin emitting the metric
+     * @param name - Metric name
+     * @param description - Metric description
+     * @param help - Help text
+     * @param boundaries - Histogram boundaries
+     * @param labels - Optional labels
+     */
+    createHistogram?(timestamp: number, pluginName: string, name: string, description: string, help: string, boundaries?: number[], labels?: string[]): void | Promise<void>;
+    /**
+     * Metrics: Counter increment
+     * @param timestamp - Timestamp of the metric
+     * @param pluginName - Name of the plugin emitting the metric
+     * @param name - Metric name
+     * @param value - Increment value
+     * @param labels - Optional label values
+     */
+    incrementCounter?(timestamp: number, pluginName: string, name: string, value: number, labels?: Record<string, string>): void | Promise<void>;
+    /**
+     * Metrics: Gauge set
+     * @param timestamp - Timestamp of the metric
+     * @param pluginName - Name of the plugin emitting the metric
+     * @param name - Metric name
+     * @param value - Gauge value
+     * @param labels - Optional label values
+     */
+    setGauge?(timestamp: number, pluginName: string, name: string, value: number, labels?: Record<string, string>): void | Promise<void>;
+    /**
+     * Metrics: Histogram observe
+     * @param timestamp - Timestamp of the metric
+     * @param pluginName - Name of the plugin emitting the metric
+     * @param name - Metric name
+     * @param value - Observed value
+     * @param labels - Optional label values
+     */
+    observeHistogram?(timestamp: number, pluginName: string, name: string, value: number, labels?: Record<string, string>): void | Promise<void>;
+    /**
+     * Tracing: Span start
+     * @param trace - Span trace (contains trace ID and new span ID)
+     * @param pluginName - Name of the plugin creating the span
+     * @param spanName - Name of the span
+     * @param parentSpanId - Parent span ID (null for root spans)
+     * @param attributes - Span attributes
+     */
+    spanStart?(trace: DTrace, pluginName: string, spanName: string, parentSpanId: string | null, attributes?: Record<string, string | number | boolean>): void | Promise<void>;
+    /**
+     * Tracing: Span end
+     * @param trace - Span trace
+     * @param pluginName - Name of the plugin ending the span
+     * @param attributes - Final attributes
+     */
+    spanEnd?(trace: DTrace, pluginName: string, attributes?: Record<string, string | number | boolean>): void | Promise<void>;
+    /**
+     * Tracing: Span error
+     * @param trace - Span trace
+     * @param pluginName - Name of the plugin recording the error
+     * @param error - Error object
+     * @param attributes - Error attributes
+     */
+    spanError?(trace: DTrace, pluginName: string, error: Error, attributes?: Record<string, string | number | boolean>): void | Promise<void>;
+}
+/**
+ * @hidden
+ * DO NOT REFERENCE/USE THIS CLASS - IT IS AN INTERNALLY REFERENCED CLASS
+ */
+export declare class BSBObservableRef extends BSBObservable {
+    dispose?(): void;
+    init?(): void | Promise<void>;
+    run?(): void | Promise<void>;
+    debug(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void;
+    info(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void;
+    warn(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void;
+    error(trace: DTrace, pluginName: string, message: string | BSBError<any>, meta?: LogMeta<any>): void;
+    createCounter(timestamp: number, pluginName: string, name: string, description: string, help: string, labels?: string[]): void;
+    createGauge(timestamp: number, pluginName: string, name: string, description: string, help: string, labels?: string[]): void;
+    createHistogram(timestamp: number, pluginName: string, name: string, description: string, help: string, boundaries?: number[], labels?: string[]): void;
+    incrementCounter(timestamp: number, pluginName: string, name: string, value: number, labels?: Record<string, string>): void;
+    setGauge(timestamp: number, pluginName: string, name: string, value: number, labels?: Record<string, string>): void;
+    observeHistogram(timestamp: number, pluginName: string, name: string, value: number, labels?: Record<string, string>): void;
+    spanStart(trace: DTrace, pluginName: string, spanName: string, parentSpanId: string | null, attributes?: Record<string, string | number | boolean>): void;
+    spanEnd(trace: DTrace, pluginName: string, attributes?: Record<string, string | number | boolean>): void;
+    spanError(trace: DTrace, pluginName: string, error: Error, attributes?: Record<string, string | number | boolean>): void;
+}

package/lib/base/BSBObservable.js

@@ -0,0 +1,91 @@
+"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.BSBObservableRef = exports.BSBObservable = void 0;
+const base_1 = require("./base");
+const errorMessages_1 = require("./errorMessages");
+/**
+ * Unified Observable plugin base class for logging, metrics, and tracing
+ * @group Observable
+ * @category Plugins
+ * @template ReferencedConfig - The type of configuration for the plugin
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBObservable.html | API: BSBObservable}
+ */
+class BSBObservable extends base_1.BaseWithConfig {
+    constructor(config) {
+        super(config);
+    }
+}
+exports.BSBObservable = BSBObservable;
+/**
+ * @hidden
+ * DO NOT REFERENCE/USE THIS CLASS - IT IS AN INTERNALLY REFERENCED CLASS
+ */
+class BSBObservableRef extends BSBObservable {
+    debug(trace, pluginName, message, meta) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBObservableRef", "debug");
+    }
+    info(trace, pluginName, message, meta) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBObservableRef", "info");
+    }
+    warn(trace, pluginName, message, meta) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBObservableRef", "warn");
+    }
+    error(trace, pluginName, message, meta) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBObservableRef", "error");
+    }
+    createCounter(timestamp, pluginName, name, description, help, labels) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBObservableRef", "createCounter");
+    }
+    createGauge(timestamp, pluginName, name, description, help, labels) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBObservableRef", "createGauge");
+    }
+    createHistogram(timestamp, pluginName, name, description, help, boundaries, labels) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBObservableRef", "createHistogram");
+    }
+    incrementCounter(timestamp, pluginName, name, value, labels) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBObservableRef", "incrementCounter");
+    }
+    setGauge(timestamp, pluginName, name, value, labels) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBObservableRef", "setGauge");
+    }
+    observeHistogram(timestamp, pluginName, name, value, labels) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBObservableRef", "observeHistogram");
+    }
+    spanStart(trace, pluginName, spanName, parentSpanId, attributes) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBObservableRef", "spanStart");
+    }
+    spanEnd(trace, pluginName, attributes) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBObservableRef", "spanEnd");
+    }
+    spanError(trace, pluginName, error, attributes) {
+        throw (0, errorMessages_1.BSB_ERROR_METHOD_NOT_IMPLEMENTED)("BSBObservableRef", "spanError");
+    }
+}
+exports.BSBObservableRef = BSBObservableRef;
+//# sourceMappingURL=BSBObservable.js.map

package/lib/base/BSBObservable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BSBObservable.js","sourceRoot":"","sources":["../../src/base/BSBObservable.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAIH,iCAA8D;AAC9D,mDAA6E;AAY7E;;;;;;GAMG;AACH,MAAsB,aAEpB,SAAQ,qBAIT;IACC,YAAY,MAAkD;QAC5D,KAAK,CAAC,MAAM,CAAC,CAAC;IAChB,CAAC;CAuLF;AAhMD,sCAgMC;AAED;;;GAGG;AACH,MAAa,gBAAiB,SAAQ,aAAa;IAMjD,KAAK,CAAC,KAAa,EAAE,UAAkB,EAAE,OAAe,EAAE,IAAkB;QAC1E,MAAM,IAAA,gDAAgC,EAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;IACtE,CAAC;IAED,IAAI,CAAC,KAAa,EAAE,UAAkB,EAAE,OAAe,EAAE,IAAkB;QACzE,MAAM,IAAA,gDAAgC,EAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;IACrE,CAAC;IAED,IAAI,CAAC,KAAa,EAAE,UAAkB,EAAE,OAAe,EAAE,IAAkB;QACzE,MAAM,IAAA,gDAAgC,EAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;IACrE,CAAC;IAED,KAAK,CAAC,KAAa,EAAE,UAAkB,EAAE,OAA+B,EAAE,IAAmB;QAC3F,MAAM,IAAA,gDAAgC,EAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;IACtE,CAAC;IAED,aAAa,CACX,SAAiB,EACjB,UAAkB,EAClB,IAAY,EACZ,WAAmB,EACnB,IAAY,EACZ,MAAiB;QAEjB,MAAM,IAAA,gDAAgC,EAAC,kBAAkB,EAAE,eAAe,CAAC,CAAC;IAC9E,CAAC;IAED,WAAW,CACT,SAAiB,EACjB,UAAkB,EAClB,IAAY,EACZ,WAAmB,EACnB,IAAY,EACZ,MAAiB;QAEjB,MAAM,IAAA,gDAAgC,EAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;IAC5E,CAAC;IAED,eAAe,CACb,SAAiB,EACjB,UAAkB,EAClB,IAAY,EACZ,WAAmB,EACnB,IAAY,EACZ,UAAqB,EACrB,MAAiB;QAEjB,MAAM,IAAA,gDAAgC,EAAC,kBAAkB,EAAE,iBAAiB,CAAC,CAAC;IAChF,CAAC;IAED,gBAAgB,CACd,SAAiB,EACjB,UAAkB,EAClB,IAAY,EACZ,KAAa,EACb,MAA+B;QAE/B,MAAM,IAAA,gDAAgC,EAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC;IACjF,CAAC;IAED,QAAQ,CACN,SAAiB,EACjB,UAAkB,EAClB,IAAY,EACZ,KAAa,EACb,MAA+B;QAE/B,MAAM,IAAA,gDAAgC,EAAC,kBAAkB,EAAE,UAAU,CAAC,CAAC;IACzE,CAAC;IAED,gBAAgB,CACd,SAAiB,EACjB,UAAkB,EAClB,IAAY,EACZ,KAAa,EACb,MAA+B;QAE/B,MAAM,IAAA,gDAAgC,EAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC;IACjF,CAAC;IAED,SAAS,CACP,KAAa,EACb,UAAkB,EAClB,QAAgB,EAChB,YAA2B,EAC3B,UAAsD;QAEtD,MAAM,IAAA,gDAAgC,EAAC,kBAAkB,EAAE,WAAW,CAAC,CAAC;IAC1E,CAAC;IAED,OAAO,CACL,KAAa,EACb,UAAkB,EAClB,UAAsD;QAEtD,MAAM,IAAA,gDAAgC,EAAC,kBAAkB,EAAE,SAAS,CAAC,CAAC;IACxE,CAAC;IAED,SAAS,CACP,KAAa,EACb,UAAkB,EAClB,KAAY,EACZ,UAAsD;QAEtD,MAAM,IAAA,gDAAgC,EAAC,kBAAkB,EAAE,WAAW,CAAC,CAAC;IAC1E,CAAC;CACF;AAhHD,4CAgHC"}