@bsb/base 9.0.0

package/lib/base/ObservableBackend.d.ts

@@ -0,0 +1,281 @@
+/**
+ * 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 { Counter, DEBUG_MODE, DTrace, Gauge, Histogram, SmartLogMeta, Timer, Trace } from "../interfaces";
+import { BSBError } from "./errorMessages";
+/**
+ * Observable bus interface - unified for both logging and metrics
+ * @hidden
+ */
+interface ObservableBus {
+    readonly isReady: boolean;
+    debug(plugin: string, trace: DTrace, message: string, ...meta: any[]): void;
+    info(plugin: string, trace: DTrace, message: string, ...meta: any[]): void;
+    warn(plugin: string, trace: DTrace, message: string, ...meta: any[]): void;
+    error(plugin: string, trace: DTrace, message: string | BSBError<any>, ...meta: any[]): void;
+    createCounter(timestamp: number, pluginName: string, name: string, description: string, help: string, labels?: string[]): void;
+    incrementCounter(timestamp: number, pluginName: string, name: string, value: number, labels?: Record<string, string>): void;
+    createGauge(timestamp: number, pluginName: string, name: string, description: string, help: string, labels?: string[]): void;
+    setGauge(timestamp: number, pluginName: string, name: string, value: number, labels?: Record<string, string>): void;
+    createHistogram(timestamp: number, pluginName: string, name: string, description: string, help: string, boundaries?: number[], labels?: string[]): void;
+    observeHistogram(timestamp: number, pluginName: string, name: string, value: number, labels?: Record<string, string>): void;
+    startSpan(timestamp: number, appId: string, pluginName: string, traceId: string, parentSpanId: string | null, spanId: string, name: string, attributes?: Record<string, string | number | boolean>): void;
+    endSpan(timestamp: number, appId: string, pluginName: string, traceId: string, spanId: string, attributes?: Record<string, string | number | boolean>): void;
+    errorSpan(timestamp: number, appId: string, pluginName: string, traceId: string, spanId: string, error: Error, attributes?: Record<string, string | number | boolean>): void;
+}
+/**
+ * Observable Backend - Unified backend for logging and metrics
+ *
+ * This is the internal backend that handles both logging and metrics operations.
+ * It replaces the separate PluginLogging and PluginMetrics classes with a single
+ * unified implementation.
+ *
+ * @group Observable
+ * @category Plugin Development Tools
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * // Internal use only - plugins use Observable interface
+ * const backend = new ObservableBackend(
+ *   'development',
+ *   'my-app',
+ *   'my-plugin',
+ *   sbObservable
+ * );
+ * ```
+ */
+export declare class ObservableBackend {
+    private bus;
+    private pluginName;
+    private appId;
+    private canDebug;
+    /**
+     * Create an ObservableBackend instance
+     * @param mode - Debug mode setting
+     * @param appId - Application ID
+     * @param pluginName - Plugin name
+     * @param bus - Observable bus for emitting events
+     */
+    constructor(mode: DEBUG_MODE, appId: string, pluginName: string, bus: ObservableBus);
+    /**
+     * Logs a debug message
+     *
+     * @param trace - The trace to associate with the log
+     * @param message - The message to log
+     * @param meta - Additional information to log with the message
+     * @returns nothing
+     *
+     * @example
+     * ```ts
+     * backend.debug(trace, "This is a debug log");
+     * backend.debug(trace, "This is a debug {key}", {"key": "log"});
+     * ```
+     */
+    debug<T extends string>(trace: DTrace, message: T, ...meta: SmartLogMeta<T>): void;
+    /**
+     * Logs an info message
+     *
+     * @param trace - The trace to associate with the log
+     * @param message - The message to log
+     * @param meta - Additional information to log with the message
+     * @returns nothing
+     *
+     * @example
+     * ```ts
+     * backend.info(trace, "This is an info log");
+     * backend.info(trace, "This is an info {key}", {"key": "log"});
+     * ```
+     */
+    info<T extends string>(trace: DTrace, message: T, ...meta: SmartLogMeta<T>): void;
+    /**
+     * Logs a warn message
+     *
+     * @param trace - The trace to associate with the log
+     * @param message - The message to log
+     * @param meta - Additional information to log with the message
+     * @returns nothing
+     *
+     * @example
+     * ```ts
+     * backend.warn(trace, "This is a warn log");
+     * backend.warn(trace, "This is a warn {key}", {"key": "log"});
+     * ```
+     */
+    warn<T extends string>(trace: DTrace, message: T, ...meta: SmartLogMeta<T>): void;
+    /**
+     * Logs an error message
+     *
+     * @param trace - The trace to associate with the log
+     * @param message - The message to log
+     * @param meta - Additional information to log with the message
+     * @returns nothing
+     *
+     * @example
+     * ```ts
+     * backend.error(trace, "This is an error log");
+     * backend.error(trace, "This is an error {key}", {"key": "log"});
+     * ```
+     * ```ts
+     * backend.error(new BSBError(trace, "error-key", "This is an error log"));
+     * backend.error(new BSBError(trace, "error-key", "This is an error {key}", {"key": "log"}));
+     * ```
+     */
+    error<T extends string>(trace: DTrace, message: T, ...meta: SmartLogMeta<T>): void;
+    error<T extends string>(error: BSBError<T>): void;
+    /**
+     * Create a counter metric
+     *
+     * Counters are monotonically increasing values used to track cumulative totals.
+     * Common uses: request counts, error counts, bytes processed.
+     *
+     * @param name - Metric name (e.g., "requests_total")
+     * @param description - Short description
+     * @param help - Detailed help text
+     * @param labels - Optional label names for dimensional metrics
+     * @returns Counter instance with increment method
+     *
+     * @example
+     * ```typescript
+     * const requests = backend.createCounter(
+     *   "http_requests_total",
+     *   "Total HTTP requests",
+     *   "Count of all HTTP requests received",
+     *   ["method", "status"]
+     * );
+     * requests.increment(1, { method: "GET", status: "200" });
+     * ```
+     */
+    createCounter<LABELS extends string | undefined>(name: string, description: string, help: string, labels?: LABELS[]): Counter<LABELS>;
+    /**
+     * Create a gauge metric
+     *
+     * Gauges represent point-in-time values that can go up or down.
+     * Common uses: memory usage, active connections, queue depth, temperature.
+     *
+     * @param name - Metric name (e.g., "active_connections")
+     * @param description - Short description
+     * @param help - Detailed help text
+     * @param labels - Optional label names for dimensional metrics
+     * @returns Gauge instance with set, increment, and decrement methods
+     *
+     * @example
+     * ```typescript
+     * const activeConns = backend.createGauge(
+     *   "active_connections",
+     *   "Active connections",
+     *   "Number of currently active connections"
+     * );
+     * activeConns.set(42);
+     * activeConns.increment(1);
+     * activeConns.decrement(1);
+     * ```
+     */
+    createGauge<LABELS extends string | undefined>(name: string, description: string, help: string, labels?: LABELS[]): Gauge<LABELS>;
+    /**
+     * Create a histogram metric
+     *
+     * Histograms track the distribution of values over time.
+     * Common uses: request duration, response size, batch size.
+     *
+     * @param name - Metric name (e.g., "request_duration_ms")
+     * @param description - Short description
+     * @param help - Detailed help text
+     * @param boundaries - Optional bucket boundaries (default: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10])
+     * @param labels - Optional label names for dimensional metrics
+     * @returns Histogram instance with record method
+     *
+     * @example
+     * ```typescript
+     * const duration = backend.createHistogram(
+     *   "request_duration_ms",
+     *   "Request duration",
+     *   "Duration of HTTP requests in milliseconds",
+     *   [10, 50, 100, 500, 1000, 5000],
+     *   ["method"]
+     * );
+     * duration.record(125, { method: "GET" });
+     * ```
+     */
+    createHistogram<LABELS extends string | undefined>(name: string, description: string, help: string, boundaries?: number[], labels?: LABELS[]): Histogram<LABELS>;
+    /**
+     * Create a new distributed trace
+     *
+     * Creates a root trace with no parent. Use this when starting a new
+     * request or operation that should be tracked independently.
+     *
+     * @param name - Name of the trace/span (e.g., "http-request")
+     * @param attributes - Optional attributes to attach to the trace
+     * @returns Trace instance
+     *
+     * @example
+     * ```typescript
+     * const trace = backend.createTrace("process-batch", {
+     *   "batch.size": 100
+     * });
+     * // ... do work ...
+     * trace.end({ "batch.processed": 100 });
+     * ```
+     */
+    createTrace(name: string, attributes?: Record<string, string | number | boolean>): Trace;
+    /**
+     * Create a child span within an existing trace
+     *
+     * Creates a child span that inherits the trace ID from the parent.
+     * This is used internally by Observable.startSpan().
+     *
+     * @param trace - Parent DTrace object
+     * @param name - Name of the span (e.g., "database-query")
+     * @param attributes - Optional attributes to attach to the span
+     * @returns Trace instance representing the child span
+     *
+     * @example
+     * ```typescript
+     * // Usually accessed via Observable
+     * const childSpan = backend.createSpan(trace, "database-query");
+     * // ... do work ...
+     * childSpan.end();
+     * ```
+     */
+    createSpan(trace: DTrace, name: string, attributes?: Record<string, string | number | boolean>): Trace;
+    /**
+     * Create a high-resolution timer
+     *
+     * Returns a timer that can measure elapsed time in milliseconds with
+     * sub-millisecond precision using Node.js hrtime.
+     *
+     * @returns Timer instance with stop method
+     *
+     * @example
+     * ```typescript
+     * const timer = backend.createTimer();
+     * await performOperation();
+     * const elapsed = timer.stop();
+     * ```
+     */
+    createTimer(): Timer;
+}
+export {};