@bsb/base 9.0.0

package/lib/base/PluginEvents.js

@@ -0,0 +1,268 @@
+"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.BSBPluginEventsRef = exports.PluginEvents = void 0;
+const EventValidator_1 = require("./EventValidator");
+/**
+ * Schema-first plugin events handler with automatic validation and object parameters.
+ * @group Events
+ * @category Plugin Development Tools
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/PluginEvents.html | API: PluginEvents}
+ */
+class PluginEvents {
+    events;
+    service;
+    cachedPluginName;
+    validator;
+    eventSchemas;
+    constructor(mode, events, context, eventSchemas, observableBackend) {
+        this.events = events;
+        this.service = context;
+        this.cachedPluginName = context.pluginName;
+        this.eventSchemas = eventSchemas;
+        this.validator = new EventValidator_1.EventValidator({}, observableBackend);
+    }
+    /**
+     * Helper to extract DTrace from Observable | DTrace
+     * @hidden
+     */
+    extractTrace(obs) {
+        if ('trace' in obs && typeof obs.trace === 'object') {
+            return obs.trace;
+        }
+        return obs;
+    }
+    /**
+     * Helper to create Observable from DTrace if needed
+     * @hidden
+     */
+    ensureObservable(obsOrTrace) {
+        if ('trace' in obsOrTrace && 'log' in obsOrTrace) {
+            return obsOrTrace;
+        }
+        // Create Observable from DTrace
+        return this.service.createObservable(obsOrTrace);
+    }
+    /**
+     * Listen for broadcast events emitted by other plugins with full type safety.
+     * @param eventName - Name of the event to listen for (strongly typed)
+     * @param obs - Observable context (v9 BREAKING: Observable only, no longer accepts DTrace)
+     * @param listener - Function to call when event is received (receives Observable and validated input object)
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/PluginEvents.html#onBroadcast | API: PluginEvents#onBroadcast}
+     */
+    async onBroadcast(eventName, obs, listener) {
+        const trace = this.extractTrace(obs);
+        const wrappedListener = async (handlerTrace, rawInput) => {
+            let validatedInput = rawInput;
+            // Validate input if schema exists
+            const schema = this.eventSchemas.onBroadcast?.[eventName];
+            if (schema) {
+                const result = this.validator.validateInput(eventName, rawInput, schema.input, handlerTrace);
+                if (!result.success) {
+                    throw result.error;
+                }
+                validatedInput = result.data;
+            }
+            // Create Observable for handler
+            const handlerObs = this.ensureObservable(handlerTrace);
+            await listener(handlerObs, validatedInput);
+        };
+        return this.events.onBroadcast(this.service, trace, this.cachedPluginName, eventName, wrappedListener);
+    }
+    /**
+     * Emit broadcast events to all listening plugins with full type safety.
+     * @param eventName - Name of the event to emit (strongly typed)
+     * @param obs - Observable context (v9 BREAKING: Observable only, no longer accepts DTrace)
+     * @param input - Event input object (will be validated against schema)
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/PluginEvents.html#emitBroadcast | API: PluginEvents#emitBroadcast}
+     */
+    async emitBroadcast(eventName, obs, input) {
+        const trace = this.extractTrace(obs);
+        let validatedInput = input;
+        // Validate input if schema exists
+        const schema = this.eventSchemas.emitBroadcast?.[eventName];
+        if (schema) {
+            const result = this.validator.validateInput(eventName, input, schema.input, trace);
+            if (!result.success) {
+                throw result.error;
+            }
+            validatedInput = result.data;
+        }
+        return this.events.emitBroadcast(trace, this.cachedPluginName, eventName, [validatedInput]);
+    }
+    /**
+     * Listen for fire-and-forget events from other plugins with full type safety.
+     * @param eventName - Name of the event to listen for (strongly typed)
+     * @param obs - Observable context (v9 BREAKING: Observable only, no longer accepts DTrace)
+     * @param listener - Function to call when event is received (receives Observable and validated input object)
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/PluginEvents.html#onEvent | API: PluginEvents#onEvent}
+     */
+    async onEvent(eventName, obs, listener) {
+        const trace = this.extractTrace(obs);
+        const wrappedListener = async (handlerTrace, rawInput) => {
+            let validatedInput = rawInput;
+            // Validate input if schema exists
+            const schema = this.eventSchemas.onEvents?.[eventName];
+            if (schema) {
+                const result = this.validator.validateInput(eventName, rawInput, schema.input, handlerTrace);
+                if (!result.success) {
+                    throw result.error;
+                }
+                validatedInput = result.data;
+            }
+            // Create Observable for handler
+            const handlerObs = this.ensureObservable(handlerTrace);
+            await listener(handlerObs, validatedInput);
+        };
+        return this.events.onEvent(trace, this.service, this.cachedPluginName, eventName, wrappedListener);
+    }
+    /**
+     * Emit fire-and-forget events to other plugins with full type safety.
+     * @param eventName - Name of the event to emit (strongly typed)
+     * @param obs - Observable context (v9 BREAKING: Observable only, no longer accepts DTrace)
+     * @param input - Event input object (will be validated against schema)
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/PluginEvents.html#emitEvent | API: PluginEvents#emitEvent}
+     */
+    async emitEvent(eventName, obs, input) {
+        const trace = this.extractTrace(obs);
+        let validatedInput = input;
+        // Validate input if schema exists
+        const schema = this.eventSchemas.emitEvents?.[eventName];
+        if (schema) {
+            const result = this.validator.validateInput(eventName, input, schema.input, trace);
+            if (!result.success) {
+                throw result.error;
+            }
+            validatedInput = result.data;
+        }
+        return this.events.emitEvent(trace, this.cachedPluginName, eventName, validatedInput);
+    }
+    /**
+     * Listen for returnable events from other plugins with full type safety.
+     * @param eventName - Name of the event to listen for (strongly typed)
+     * @param obs - Observable context (v9 BREAKING: Observable only, no longer accepts DTrace)
+     * @param listener - Function to call when event is received (receives Observable), must return a value
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/PluginEvents.html#onReturnableEvent | API: PluginEvents#onReturnableEvent}
+     */
+    async onReturnableEvent(eventName, obs, listener) {
+        const trace = this.extractTrace(obs);
+        const wrappedListener = async (handlerTrace, rawInput) => {
+            let validatedInput = rawInput;
+            const schema = this.eventSchemas.onReturnableEvents?.[eventName];
+            // Validate input if schema exists
+            if (schema) {
+                const inputResult = this.validator.validateInput(eventName, rawInput, schema.input, handlerTrace);
+                if (!inputResult.success) {
+                    throw inputResult.error;
+                }
+                validatedInput = inputResult.data;
+            }
+            // Create Observable for handler
+            const handlerObs = this.ensureObservable(handlerTrace);
+            const result = await listener(handlerObs, validatedInput);
+            // Validate output if schema exists
+            if (schema) {
+                const outputResult = this.validator.validateOutput(eventName, result, schema.output, handlerTrace);
+                if (!outputResult.success) {
+                    throw outputResult.error;
+                }
+                return outputResult.data;
+            }
+            return result;
+        };
+        return this.events.onReturnableEvent(trace, this.service, this.cachedPluginName, eventName, wrappedListener);
+    }
+    /**
+     * Emit returnable events and wait for response with full type safety.
+     * @param eventName - Name of the event to emit (strongly typed)
+     * @param obs - Observable context (v9 BREAKING: Observable only, no longer accepts DTrace)
+     * @param input - Event input object (will be validated against schema)
+     * @param timeoutSeconds - Optional timeout in seconds (default: 5)
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/PluginEvents.html#emitEventAndReturn | API: PluginEvents#emitEventAndReturn}
+     */
+    async emitEventAndReturn(eventName, obs, input, timeoutSeconds = 5) {
+        const trace = this.extractTrace(obs);
+        let validatedInput = input;
+        const schema = this.eventSchemas.emitReturnableEvents?.[eventName];
+        // Validate input if schema exists
+        if (schema) {
+            const inputResult = this.validator.validateInput(eventName, input, schema.input, trace);
+            if (!inputResult.success) {
+                throw inputResult.error;
+            }
+            validatedInput = inputResult.data;
+        }
+        const result = await this.events.emitEventAndReturn(trace, this.cachedPluginName, eventName, timeoutSeconds, validatedInput);
+        // Validate output if schema exists
+        if (schema) {
+            const outputResult = this.validator.validateOutput(eventName, result, schema.output, trace);
+            if (!outputResult.success) {
+                throw outputResult.error;
+            }
+            return outputResult.data;
+        }
+        return result;
+    }
+    /**
+     * Get stream ID for receiving streamed data from another plugin.
+     * @param trace - Trace for logging context
+     * @param eventName - Name of the stream event
+     * @param listener - Function called when stream is received
+     * @param timeoutSeconds - Optional timeout in seconds
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/PluginEvents.html#receiveStream | API: PluginEvents#receiveStream}
+     */
+    async receiveStream(trace, eventName, listener, timeoutSeconds) {
+        return this.events.receiveStream(trace, this.service, this.cachedPluginName, eventName, listener, timeoutSeconds);
+    }
+    /**
+     * Send stream data to another plugin.
+     * @param trace - Trace for logging context
+     * @param eventName - Name of the stream event
+     * @param streamId - ID of the stream to send to
+     * @param stream - The readable stream to send
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/PluginEvents.html#sendStream | API: PluginEvents#sendStream}
+     */
+    async sendStream(trace, eventName, streamId, stream) {
+        return this.events.sendStream(trace, this.cachedPluginName, eventName, streamId, stream);
+    }
+}
+exports.PluginEvents = PluginEvents;
+/**
+ * @hidden
+ * DO NOT REFERENCE/USE THIS CLASS - IT IS AN INTERNALLY REFERENCED CLASS
+ */
+class BSBPluginEventsRef {
+    emitEvents = {};
+    onEvents = {};
+    emitReturnableEvents = {};
+    onReturnableEvents = {};
+    emitBroadcast = {};
+    onBroadcast = {};
+}
+exports.BSBPluginEventsRef = BSBPluginEventsRef;
+//# sourceMappingURL=PluginEvents.js.map

package/lib/base/PluginEvents.js.map

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

package/lib/base/PluginObservable.d.ts

@@ -0,0 +1,196 @@
+/**
+ * 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 } from '../interfaces/observable';
+import { DTrace, Trace, IPluginObservable } from '../interfaces/metrics';
+import { ResourceContext } from './ResourceContext';
+import { BSBError } from './errorMessages';
+import { SmartLogMeta } from '../interfaces/logging';
+import { z } from 'zod';
+/**
+ * Implementation of Observable interface that wraps DTrace with observability features
+ *
+ * @group Observability
+ * @category Plugin Development Tools
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/PluginObservable.html | API: PluginObservable}
+ */
+export declare class PluginObservable<TAttributeSchema extends z.ZodSchema = z.ZodAny> implements Observable<TAttributeSchema> {
+    private readonly _trace;
+    private readonly _resource;
+    private readonly _attributes;
+    private readonly _backend;
+    private readonly _span?;
+    /**
+     * Create a PluginObservable
+     * @param trace - DTrace object
+     * @param resource - Resource context
+     * @param backend - IPluginObservable instance (unified logging and metrics backend)
+     * @param attributes - Initial attributes
+     * @param span - Optional Trace/Span object (if created via startSpan())
+     */
+    constructor(trace: DTrace, resource: ResourceContext, backend: IPluginObservable, attributes?: Record<string, string | number | boolean>, span?: Trace);
+    get trace(): DTrace;
+    get traceId(): string;
+    get spanId(): string;
+    get resource(): ResourceContext;
+    get attributes(): Record<string, string | number | boolean>;
+    log: {
+        debug: <T extends string>(message: T, ...meta: SmartLogMeta<T>) => void;
+        info: <T extends string>(message: T, ...meta: SmartLogMeta<T>) => void;
+        warn: <T extends string>(message: T, ...meta: SmartLogMeta<T>) => void;
+        error: <T extends string>(messageOrError: T | Error, ...meta: SmartLogMeta<T>) => void;
+    };
+    metrics: {
+        counter: <LABELS extends string | undefined>(name: string, description: string, help: string, labels?: LABELS[]) => import("../interfaces/metrics").Counter<LABELS>;
+        gauge: <LABELS extends string | undefined>(name: string, description: string, help: string, labels?: LABELS[]) => import("../interfaces/metrics").Gauge<LABELS>;
+        histogram: <LABELS extends string | undefined>(name: string, description: string, help: string, boundaries?: number[], labels?: LABELS[]) => import("../interfaces/metrics").Histogram<LABELS>;
+        timer: () => import("../interfaces/metrics").Timer;
+    };
+    /**
+     * Create a child span with inherited attributes
+     *
+     * Creates a new Observable representing a child span for distributed tracing.
+     * All attributes from the parent are automatically inherited by the child.
+     *
+     * @param name - Name of the span (e.g., "database-query", "api-call")
+     * @param attributes - Additional attributes to add to this span
+     * @returns New Observable instance representing the child span
+     *
+     * @example
+     * ```typescript
+     * public async processOrder(obs: Observable) {
+     *   // Create child span for database operation
+     *   const dbSpan = obs.startSpan("fetch-order", { "order.id": "123" });
+     *   try {
+     *     const order = await this.db.getOrder("123");
+     *     dbSpan.end({ "order.status": order.status });
+     *   } catch (error) {
+     *     dbSpan.error(error);
+     *     dbSpan.end();
+     *   }
+     * }
+     * ```
+     */
+    startSpan(name: string, attributes?: Record<string, string | number | boolean>): Observable<TAttributeSchema>;
+    /**
+     * Create a new Observable with an additional attribute
+     *
+     * Observables are immutable - this returns a new instance with the added attribute.
+     * The attribute is propagated to all child operations (logs, spans, etc.).
+     *
+     * @param key - Attribute key (e.g., "user.id", "transaction.type")
+     * @param value - Attribute value (string, number, or boolean)
+     * @returns New Observable instance with the added attribute
+     *
+     * @example
+     * ```typescript
+     * public async handleRequest(obs: Observable, userId: string) {
+     *   // Add user ID to all subsequent operations
+     *   const withUser = obs.setAttribute("user.id", userId);
+     *
+     *   withUser.log.info("Processing request");  // Log includes user.id
+     *   const span = withUser.startSpan("process");    // Span includes user.id
+     * }
+     * ```
+     */
+    setAttribute<K extends string, V extends string | number | boolean>(key: K, value: V): Observable<TAttributeSchema>;
+    /**
+     * Create a new Observable with multiple attributes
+     *
+     * Observables are immutable - this returns a new instance with the added attributes.
+     * All attributes are propagated to child operations.
+     *
+     * @param attrs - Object containing attributes to add
+     * @returns New Observable instance with the added attributes
+     *
+     * @example
+     * ```typescript
+     * public async handleRequest(obs: Observable, context: RequestContext) {
+     *   // Add multiple attributes at once
+     *   const withContext = obs.setAttributes({
+     *     "user.id": context.userId,
+     *     "request.id": context.requestId,
+     *     "request.method": context.method
+     *   });
+     *
+     *   withContext.log.info("Processing request");
+     * }
+     * ```
+     */
+    setAttributes(attrs: Record<string, string | number | boolean>): Observable<TAttributeSchema>;
+    /**
+     * Record an error to both logs and traces
+     *
+     * This method automatically records the error to both the logging system and
+     * the active span (if this Observable was created via startSpan()). This ensures
+     * errors are captured in both systems for complete observability.
+     *
+     * @param error - Error or BSBError instance to record
+     * @param attributes - Additional attributes to attach to the error
+     *
+     * @example
+     * ```typescript
+     * public async processData(obs: Observable) {
+     *   const span = obs.startSpan("process-data");
+     *   try {
+     *     await this.riskyOperation();
+     *   } catch (error) {
+     *     // Record error to both logs and span
+     *     span.error(error as Error, { "operation": "riskyOperation" });
+     *     span.end();
+     *     throw error;
+     *   }
+     * }
+     * ```
+     */
+    error(error: Error | BSBError<any>, attributes?: Record<string, string | number | boolean>): void;
+    /**
+     * End the span (only applies if this Observable was created via startSpan())
+     *
+     * Completes the span and records the final state. If this Observable was not
+     * created via startSpan(), this method does nothing. Always call end() when the
+     * operation is complete to ensure proper trace completion.
+     *
+     * @param attributes - Final attributes to attach before ending the span
+     *
+     * @example
+     * ```typescript
+     * public async fetchData(obs: Observable) {
+     *   const span = obs.startSpan("fetch-data");
+     *   try {
+     *     const data = await this.api.fetch();
+     *     span.end({ "data.size": data.length, "status": "success" });
+     *     return data;
+     *   } catch (error) {
+     *     span.error(error as Error);
+     *     span.end({ "status": "failed" });
+     *     throw error;
+     *   }
+     * }
+     * ```
+     */
+    end(attributes?: Record<string, string | number | boolean>): void;
+}