@bsb/base 9.0.0

package/lib/base/PluginConfig.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 { z } from "zod";
+/**
+ * The definition of the config with zod validation
+ * @example
+ * const configDefinition = z.object({
+ *  a: z.string(),
+ * });
+ */
+export type BSBPluginConfigType = z.ZodTypeAny | undefined;
+export type BSBPluginConfigDefinition = BSBPluginConfig<BSBPluginConfigType>;
+export type BSBPluginConfigClass<TSchema extends BSBPluginConfigType = BSBPluginConfigType> = {
+    new (cwd: string, packageCwd: string, pluginCwd: string, pluginName: string): BSBPluginConfig<TSchema>;
+    metadata: BSBPluginMetadata;
+};
+/**
+ * Config migration handler, allows for config migrations when the plugin version changes or a new plugin setup is done
+ * @example simple version change and basic setup
+ * const configMigration = async (versionFrom: string | null, versionTo: string, existingConfig?: z.infer<BSBConfigDefinition>) => {
+ * if (versionFrom === null) {
+ *  return {
+ *   a: "a",
+ *  };
+ * }
+ * return {
+ *  a: "b",
+ * };
+ * @example basic setup and no version change handling
+ * const configMigration = async (versionFrom: string | null, versionTo: string, existingConfig?: z.infer<BSBConfigDefinition>) => {
+ * if (versionFrom === null || existingConfig === undefined) {
+ *  return {
+ *   a: "a",
+ *  };
+ * }
+ * return existingConfig;
+ */
+export type BSBConfigMigration<T extends BSBPluginConfigType> = (versionFrom: string | null, versionTo: string, existingConfig?: z.infer<Exclude<T, undefined>>) => Promise<z.infer<Exclude<T, undefined>>>;
+/**
+ * Plugin metadata information for enhanced discoverability and documentation.
+ * Used for auto-generating PLUGIN_CLIENT and bsb-plugin.json.
+ *
+ * v9: This metadata is now the single source of truth for plugin information,
+ * used to auto-generate both PLUGIN_CLIENT (for ServiceClient) and bsb-plugin.json.
+ */
+export interface BSBPluginMetadata {
+    /** Plugin identifier (e.g., "service-demo-todo") */
+    name: string;
+    /** Short description of what the plugin does */
+    description: string;
+    /** Semantic version (e.g., "1.0.0") */
+    version?: string;
+    /** Author name or organization */
+    author?: string;
+    /** License type (e.g., "MIT", "AGPL-3.0") */
+    license?: string;
+    /** Documentation URL */
+    homepage?: string;
+    /** Source repository URL */
+    repository?: string;
+    /** Searchable tags for plugin discovery */
+    tags?: string[];
+    /** Relative paths to markdown documentation files (e.g., ["./docs/plugin.md"]) */
+    documentation?: string[];
+    /** Relative path to plugin image file (PNG recommended) */
+    image?: string;
+    /** This plugin must initialize before these plugins */
+    initBeforePlugins?: string[];
+    /** This plugin must initialize after these plugins */
+    initAfterPlugins?: string[];
+    /** This plugin must run before these plugins */
+    runBeforePlugins?: string[];
+    /** This plugin must run after these plugins */
+    runAfterPlugins?: string[];
+}
+export type BSBConfigDefintionReference<T extends BSBPluginConfigType, AS = undefined> = [T] extends [undefined] ? AS : z.infer<Exclude<T, undefined>>;
+export type BSBReferenceConfigType = BSBPluginConfigType | null;
+export type BSBReferencePluginConfigType = BSBPluginConfig<BSBPluginConfigType> | null;
+export type BSBReferenceConfigDefinition<ReferencedConfig extends BSBReferenceConfigType> = ReferencedConfig extends null ? null : ReferencedConfig;
+export type BSBReferencePluginConfigDefinition<ReferencedConfig extends BSBReferencePluginConfigType> = ReferencedConfig extends null ? null : ReferencedConfig extends BSBPluginConfig<infer TSchema> ? BSBConfigDefintionReference<TSchema, never> : null;
+/**
+ * Base class for plugin configuration.
+ *
+ * Define your Zod validation schema in {@link validationSchema}. Prefer
+ * versioned schemas using Zod unions and transforms to normalize old
+ * configs into the latest shape at parse time.
+ *
+ * Optionally provide {@link metadata} for enhanced plugin discoverability.
+ *
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBPluginConfig.html | API: BSBPluginConfig}
+ */
+export declare abstract class BSBPluginConfig<MyPluginConfig extends BSBPluginConfigType = undefined> {
+    constructor(cwd: string, packageCwd: string, pluginCwd: string, pluginName: string);
+    abstract validationSchema: MyPluginConfig;
+    /**
+     * Static plugin metadata for v9 auto-generation features.
+     * Set by createConfigSchema() helper.
+     */
+    static readonly metadata: BSBPluginMetadata;
+    /**
+     * Optional plugin metadata for enhanced discoverability and documentation.
+     * Provides information about the plugin's purpose.
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBPluginConfig.html#metadata | API: BSBPluginConfig#metadata}
+     */
+    metadata?: BSBPluginMetadata;
+}
+/**
+ * @hidden
+ * DO NOT REFERENCE/USE THIS CLASS - IT IS AN INTERNALLY REFERENCED CLASS
+ */
+export declare class BSBPluginConfigRef extends BSBPluginConfig<any> {
+    validationSchema: {};
+}
+/**
+ * Helper function to create a typed plugin configuration class with metadata.
+ *
+ * v9 Breaking Change: This replaces the manual Config class pattern.
+ * Instead of extending BSBPluginConfig directly, use this helper to create
+ * a Config class with built-in metadata support.
+ *
+ * The metadata is used to:
+ * - Auto-generate PLUGIN_CLIENT for ServiceClient usage
+ * - Auto-generate bsb-plugin.json during build
+ * - Provide plugin discovery and marketplace information
+ *
+ * @param metadata - Plugin metadata (name, description, version, dependencies, etc.)
+ * @param schema - Zod validation schema for the plugin configuration
+ * @returns A Config class that extends BSBPluginConfig with metadata
+ *
+ * @example
+ * ```typescript
+ * // v9 pattern:
+ * const TodoConfigSchema = z.object({
+ *   database: z.object({
+ *     host: z.string().default('localhost'),
+ *     port: z.number().default(5432),
+ *   }),
+ * });
+ *
+ * export const Config = createConfigSchema(
+ *   {
+ *     name: 'service-demo-todo',
+ *     description: 'Demo Todo Service',
+ *     version: '1.0.0',
+ *     author: 'BSB Team',
+ *     license: 'MIT',
+ *     category: 'service',
+ *     tags: ['demo', 'todo', 'example'],
+ *     initAfterPlugins: ['observable-default', 'events-default'],
+ *   },
+ *   TodoConfigSchema
+ * );
+ *
+ * // Usage in plugin:
+ * export class Plugin extends BSBService<typeof Config, typeof EventSchemas> {
+ *   static Config = Config; // Required for auto-generation
+ * }
+ * ```
+ *
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/functions/createConfigSchema.html | API: createConfigSchema}
+ */
+export declare function createConfigSchema<const TSchema extends z.ZodTypeAny>(metadata: BSBPluginMetadata, schema: TSchema): BSBPluginConfigClass<TSchema>;
+export declare function createConfigSchema(metadata: BSBPluginMetadata): BSBPluginConfigClass<undefined>;
+/**
+ * Extract category from plugin name based on directory prefix.
+ * Examples:
+ * - service-demo-todo -> service
+ * - observable-axiom -> observable
+ * - events-rabbitmq -> events
+ * - config-default -> config
+ */
+export declare function getCategoryFromPluginName(pluginName: string): 'service' | 'observable' | 'events' | 'config' | 'other';

package/lib/base/PluginConfig.js

@@ -0,0 +1,96 @@
+"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.BSBPluginConfigRef = exports.BSBPluginConfig = void 0;
+exports.createConfigSchema = createConfigSchema;
+exports.getCategoryFromPluginName = getCategoryFromPluginName;
+/**
+ * Base class for plugin configuration.
+ *
+ * Define your Zod validation schema in {@link validationSchema}. Prefer
+ * versioned schemas using Zod unions and transforms to normalize old
+ * configs into the latest shape at parse time.
+ *
+ * Optionally provide {@link metadata} for enhanced plugin discoverability.
+ *
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBPluginConfig.html | API: BSBPluginConfig}
+ */
+class BSBPluginConfig {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    constructor(cwd, packageCwd, pluginCwd, pluginName) {
+    }
+    /**
+     * Static plugin metadata for v9 auto-generation features.
+     * Set by createConfigSchema() helper.
+     */
+    static metadata;
+    /**
+     * Optional plugin metadata for enhanced discoverability and documentation.
+     * Provides information about the plugin's purpose.
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBPluginConfig.html#metadata | API: BSBPluginConfig#metadata}
+     */
+    metadata;
+}
+exports.BSBPluginConfig = BSBPluginConfig;
+/**
+ * @hidden
+ * DO NOT REFERENCE/USE THIS CLASS - IT IS AN INTERNALLY REFERENCED CLASS
+ */
+class BSBPluginConfigRef extends BSBPluginConfig {
+    validationSchema = {};
+}
+exports.BSBPluginConfigRef = BSBPluginConfigRef;
+function createConfigSchema(metadata, schema) {
+    const ConfigClass = class extends BSBPluginConfig {
+        validationSchema = schema;
+        static metadata = metadata;
+        // Also expose metadata on instance for backward compatibility
+        metadata = metadata;
+    };
+    return ConfigClass;
+}
+/**
+ * Extract category from plugin name based on directory prefix.
+ * Examples:
+ * - service-demo-todo -> service
+ * - observable-axiom -> observable
+ * - events-rabbitmq -> events
+ * - config-default -> config
+ */
+function getCategoryFromPluginName(pluginName) {
+    if (pluginName.startsWith('service-'))
+        return 'service';
+    if (pluginName.startsWith('observable-'))
+        return 'observable';
+    if (pluginName.startsWith('events-'))
+        return 'events';
+    if (pluginName.startsWith('config-'))
+        return 'config';
+    return 'other';
+}
+//# sourceMappingURL=PluginConfig.js.map

package/lib/base/PluginConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginConfig.js","sourceRoot":"","sources":["../../src/base/PluginConfig.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAgNH,gDAYC;AAUD,8DAMC;AAhID;;;;;;;;;;GAUG;AACH,MAAsB,eAAe;IAGnC,6DAA6D;IAC7D,YAAY,GAAW,EAAE,UAAkB,EAAE,SAAiB,EAAE,UAAkB;IAClF,CAAC;IAID;;;OAGG;IACH,MAAM,CAAU,QAAQ,CAAoB;IAE5C;;;;OAIG;IACI,QAAQ,CAAqB;CACrC;AArBD,0CAqBC;AAED;;;GAGG;AACH,MAAa,kBACT,SAAQ,eAAoB;IACvB,gBAAgB,GAAG,EAAE,CAAC;CAC9B;AAHD,gDAGC;AA2DD,SAAgB,kBAAkB,CAChC,QAA2B,EAC3B,MAAgB;IAEhB,MAAM,WAAW,GAAG,KAAM,SAAQ,eAAwB;QACxD,gBAAgB,GAAG,MAAiB,CAAC;QACrC,MAAM,CAAU,QAAQ,GAAG,QAAQ,CAAC;QAEpC,8DAA8D;QACrD,QAAQ,GAAG,QAAQ,CAAC;KAC9B,CAAC;IACF,OAAO,WAA4C,CAAC;AACtD,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,yBAAyB,CAAC,UAAkB;IAC1D,IAAI,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,SAAS,CAAC;IACxD,IAAI,UAAU,CAAC,UAAU,CAAC,aAAa,CAAC;QAAE,OAAO,YAAY,CAAC;IAC9D,IAAI,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,QAAQ,CAAC;IACtD,IAAI,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,QAAQ,CAAC;IACtD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/lib/base/PluginEvents.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 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 { DEBUG_MODE, DTrace, BSBEventSchemas, EventInputType, EventOutputType, Observable, IPluginObservable } from "../interfaces";
+import { SBEvents } from "../serviceBase";
+import { BSBService } from "./BSBService";
+import { BSBServiceClient } from "./BSBServiceClient";
+/**
+ * Plugin event schema definition.
+ * Define event schemas once and get both TypeScript types and runtime validation.
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/modules.html#BSBPluginEvents | API: BSBPluginEvents}
+ */
+export type BSBPluginEvents<T extends BSBEventSchemas = BSBEventSchemas> = T;
+/**
+ * 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}
+ */
+export declare class PluginEvents<TEventSchemas extends BSBEventSchemas = BSBEventSchemas, TClientApi extends boolean = false> {
+    private events;
+    private service;
+    private cachedPluginName;
+    private validator;
+    private eventSchemas;
+    constructor(mode: DEBUG_MODE, events: SBEvents, context: BSBService | BSBServiceClient, eventSchemas: TEventSchemas, observableBackend?: IPluginObservable);
+    /**
+     * Helper to extract DTrace from Observable | DTrace
+     * @hidden
+     */
+    private extractTrace;
+    /**
+     * Helper to create Observable from DTrace if needed
+     * @hidden
+     */
+    private ensureObservable;
+    /**
+     * 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}
+     */
+    onBroadcast<TBroadcast extends NonNullable<TEventSchemas['onBroadcast']>, K extends keyof TBroadcast>(eventName: K, obs: Observable, listener: (handlerObs: Observable, input: EventInputType<TBroadcast[K]>) => Promise<void>): Promise<void>;
+    /**
+     * 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}
+     */
+    emitBroadcast<TBroadcast extends NonNullable<TEventSchemas['emitBroadcast']>, K extends keyof TBroadcast>(eventName: K, obs: Observable, input: EventInputType<TBroadcast[K]>): Promise<void>;
+    /**
+     * 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}
+     */
+    onEvent<TEvents extends NonNullable<TEventSchemas['onEvents']>, K extends keyof TEvents>(eventName: K, obs: Observable, listener: (handlerObs: Observable, input: EventInputType<TEvents[K]>) => Promise<void>): Promise<void>;
+    /**
+     * 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}
+     */
+    emitEvent<TEvents extends NonNullable<TEventSchemas['emitEvents']>, K extends keyof TEvents>(eventName: K, obs: Observable, input: EventInputType<TEvents[K]>): Promise<void>;
+    /**
+     * 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}
+     */
+    onReturnableEvent<TEvents extends NonNullable<TEventSchemas['onReturnableEvents']>, K extends keyof TEvents>(eventName: K, obs: Observable, listener: (handlerObs: Observable, input: EventInputType<TEvents[K]>) => Promise<EventOutputType<TEvents[K]>>): Promise<void>;
+    /**
+     * 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}
+     */
+    emitEventAndReturn<TEvents extends NonNullable<TEventSchemas['emitReturnableEvents']>, K extends keyof TEvents>(eventName: K, obs: Observable, input: EventInputType<TEvents[K]>, timeoutSeconds?: number): Promise<EventOutputType<TEvents[K]>>;
+    /**
+     * 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}
+     */
+    receiveStream(trace: DTrace, eventName: string, listener: (error: Error | null, stream: Readable) => Promise<void>, timeoutSeconds?: number): Promise<string>;
+    /**
+     * 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}
+     */
+    sendStream(trace: DTrace, eventName: string, streamId: string, stream: Readable): Promise<void>;
+}
+/**
+ * @hidden
+ * DO NOT REFERENCE/USE THIS CLASS - IT IS AN INTERNALLY REFERENCED CLASS
+ */
+export declare class BSBPluginEventsRef {
+    emitEvents: {};
+    onEvents: {};
+    emitReturnableEvents: {};
+    onReturnableEvents: {};
+    emitBroadcast: {};
+    onBroadcast: {};
+}