AbstractStaticConfigStatic reference to the Config class created with createConfigSchema(). Required for auto-generating PLUGIN_CLIENT from metadata.
v9: This must be set on your plugin class for PLUGIN_CLIENT auto-generation to work.
StaticEventStatic reference to EventSchemas created with createEventSchemas(). Required for schema export functionality.
v9: Set this on your plugin class to enable schema export.
Optional Abstract ReadonlyinitOptional Abstract ReadonlyinitOptional Abstract ReadonlyrunOptional Abstract ReadonlyrunReadonlyeventsSchema-first event API for this plugin with automatic validation
ReadonlyappThe unique app id of the app that is running
ReadonlymodeThe mode the app is running in
ReadonlycwdThe current working directory of the app
ReadonlypackageThe current working directory of the plugin
ReadonlypluginThe current working directory of the service
ReadonlypluginThe name of the plugin This is also the mapped name, or the name defined in the config rather than it's original defined name
Optional ReadonlyregionThe deployment region for resource context
ReadonlyconfigThe config of the plugin
StaticPLUGIN_Auto-generated from Config.metadata. Do not set this manually - it will be ignored and replaced with auto-generated value.
v9 Breaking Change: This is now a getter that derives from Config.metadata. If you have a manual PLUGIN_CLIENT property, remove it and set static Config instead.
StaticexportExport event schemas to JSON format for cross-language client generation.
v9: Call this static method to generate JSON schemas for your plugin's events. The generated JSON can be consumed by code generators in other languages to create type-safe clients.
EventSchemaExport object with plugin metadata and event definitions
// In your plugin class:
export class Plugin extends BSBService<typeof Config, typeof EventSchemas> {
static Config = Config;
static EventSchemas = EventSchemas;
}
// Export schemas (typically in build script):
const schemas = Plugin.exportSchemas();
fs.writeFileSync('schemas.json', JSON.stringify(schemas, null, 2));
ProtectedcreateCreate an Observable from a DTrace with plugin's resource context
This method wraps a DTrace object in an Observable that provides:
DTrace object
Optionalattributes: Record<string, string | number | boolean>Optional initial attributes
Optionalspan: TraceOptional Trace/Span object for lifecycle management (enables end() to work)
Observable wrapping the trace
// Create observable from DTrace
const obs = this.createObservable(trace, { "user.id": "123" });
obs.log.info("Processing request");
// Create observable from Trace with span lifecycle
const trace = this.__internalObservable.createTrace("http.request");
const obs = this.createObservable(trace.trace, {}, trace);
// ... do work ...
obs.end(); // Properly ends the span
Create a new trace for distributed tracing
Creates a new root trace with the given name and attributes. This is useful for creating new traces in contexts like HTTP handlers where you want to start a new trace for each request.
Name for the trace (e.g., "http.request", "background.job")
Optionalattributes: Record<string, string | number | boolean>Optional initial attributes
Observable with a new trace and span that can be ended
// In an HTTP handler
async handleRequest(request: Request) {
const obs = this.createTrace("http.request", {
"http.method": request.method,
"http.url": request.url
});
try {
await this.processRequest(obs, request);
obs.end({ "http.status": 200 });
} catch (error) {
obs.error(error);
obs.end({ "http.status": 500 });
}
}
ProtectedcreateCreate a self-client for calling this service's own events.
Use this when you need to call your own event handlers from within the service (e.g., HTTP handler calling the service's event-based API). This makes self-invocation explicit in the code and avoids confusion about event flow.
Call this method in the constructor and store the result if you need self-invocation. Only create it if needed to minimize startup overhead.
The self-client uses the runtime mapped plugin name from the instantiated plugin, avoiding dependency on compile-time metadata or config. It's registered in the _clients array and handled normally by the BSB lifecycle.
Self-client with events property for calling own events
export class Plugin extends BSBService<typeof Config, typeof EventSchemas> {
private self;
constructor(config: BSBServiceConstructor<typeof Config, typeof EventSchemas>) {
super({ ...config, eventSchemas: EventSchemas });
// Create self-client for HTTP handler to call own events
this.self = this.createSelf();
}
async handleHttpRequest(obs: Observable, body: any) {
// Explicitly call own event handler
const result = await this.self.events.emitEventAndReturn('todo.create', obs, body);
return { status: 201, data: result };
}
}
Optional AbstractdisposeDispose Optional function to be called when the plugin is being disposed
Optional AbstractinitInit Optional function to be called when the plugin is being initialized Can be sync or async
Observable context with logging, metrics, and trace information
v9 BREAKING CHANGE: Now requires Observable instead of DTrace. Observable provides unified access to logging, metrics, and tracing with automatic context propagation.
Optional AbstractrunRun Optional function to be called when the plugin is being run Can be sync or async
Observable context with logging, metrics, and trace information
v9 BREAKING CHANGE: Now requires Observable instead of DTrace. Observable provides unified access to logging, metrics, and tracing with automatic context propagation.
Base class for implementing a service plugin.
v9 Breaking Change: PLUGIN_CLIENT is now auto-generated from Config.metadata. You must provide a static Config property pointing to your Config class.
Lifecycle:
See
API: BSBService * *
Example