@bsb/base 9.0.0

package/lib/base/PluginObservable.js

@@ -0,0 +1,250 @@
+"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.PluginObservable = void 0;
+const errorMessages_1 = require("./errorMessages");
+/**
+ * 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}
+ */
+class PluginObservable {
+    _trace;
+    _resource;
+    _attributes;
+    _backend;
+    _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, resource, backend, attributes = {}, span) {
+        this._trace = trace;
+        this._resource = resource;
+        this._backend = backend;
+        this._attributes = attributes;
+        this._span = span;
+    }
+    get trace() {
+        return this._trace;
+    }
+    get traceId() {
+        return this._trace.t;
+    }
+    get spanId() {
+        return this._trace.s;
+    }
+    get resource() {
+        return this._resource;
+    }
+    get attributes() {
+        return { ...this._attributes };
+    }
+    // Delegate logging to unified backend
+    log = {
+        debug: (message, ...meta) => this._backend.debug(this._trace, message, ...meta),
+        info: (message, ...meta) => this._backend.info(this._trace, message, ...meta),
+        warn: (message, ...meta) => this._backend.warn(this._trace, message, ...meta),
+        error: (messageOrError, ...meta) => {
+            if (messageOrError instanceof errorMessages_1.BSBError) {
+                this._backend.error(messageOrError);
+            }
+            else if (messageOrError instanceof Error) {
+                this._backend.error(this._trace, messageOrError.message);
+            }
+            else {
+                this._backend.error(this._trace, messageOrError, ...meta);
+            }
+        }
+    };
+    // Delegate metrics to unified backend
+    metrics = {
+        counter: (name, description, help, labels) => this._backend.createCounter(name, description, help, labels),
+        gauge: (name, description, help, labels) => this._backend.createGauge(name, description, help, labels),
+        histogram: (name, description, help, boundaries, labels) => this._backend.createHistogram(name, description, help, boundaries, labels),
+        timer: () => this._backend.createTimer()
+    };
+    /**
+     * 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, attributes) {
+        const mergedAttributes = { ...this._attributes, ...attributes };
+        const childSpan = this._backend.createSpan(this._trace, name, mergedAttributes);
+        return new PluginObservable(childSpan.trace, this._resource, this._backend, mergedAttributes, childSpan);
+    }
+    /**
+     * 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(key, value) {
+        return new PluginObservable(this._trace, this._resource, this._backend, { ...this._attributes, [key]: value }, this._span);
+    }
+    /**
+     * 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) {
+        return new PluginObservable(this._trace, this._resource, this._backend, { ...this._attributes, ...attrs }, this._span);
+    }
+    /**
+     * 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, attributes) {
+        const mergedAttrs = { ...this._attributes, ...attributes };
+        // Record to span
+        if (this._span) {
+            this._span.error(error, mergedAttrs);
+        }
+        // Record to logs
+        if (error instanceof errorMessages_1.BSBError) {
+            this._backend.error(error);
+        }
+        else {
+            this._backend.error(this._trace, error.message);
+        }
+    }
+    /**
+     * 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) {
+        if (this._span) {
+            const mergedAttrs = { ...this._attributes, ...attributes };
+            this._span.end(mergedAttrs);
+        }
+    }
+}
+exports.PluginObservable = PluginObservable;
+//# sourceMappingURL=PluginObservable.js.map

package/lib/base/PluginObservable.js.map

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

package/lib/base/ResourceContext.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 { MainBaseConfig } from "./base";
+/**
+ * Resource context following OpenTelemetry semantic conventions
+ * @group Observability
+ * @category Resource Context
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/interfaces/ResourceContext.html | API: ResourceContext}
+ */
+export interface ResourceContext {
+    /**
+     * Service name (plugin name)
+     */
+    'service.name': string;
+    /**
+     * Service version (plugin version)
+     */
+    'service.version': string;
+    /**
+     * Service instance ID (app ID)
+     */
+    'service.instance.id': string;
+    /**
+     * Deployment environment (mode)
+     */
+    'deployment.environment': string;
+    /**
+     * Deployment region (optional)
+     */
+    'deployment.region'?: string;
+}
+/**
+ * Builder for creating ResourceContext from MainBaseConfig
+ * @group Observability
+ * @category Resource Context
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ResourceContextBuilder.html | API: ResourceContextBuilder}
+ */
+export declare class ResourceContextBuilder {
+    /**
+     * Build a ResourceContext from MainBaseConfig
+     * @param config - The main base config
+     * @param region - Optional deployment region
+     * @returns ResourceContext object
+     */
+    static build(config: MainBaseConfig, region?: string): ResourceContext;
+}

package/lib/base/ResourceContext.js

@@ -0,0 +1,54 @@
+"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.ResourceContextBuilder = void 0;
+/**
+ * Builder for creating ResourceContext from MainBaseConfig
+ * @group Observability
+ * @category Resource Context
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ResourceContextBuilder.html | API: ResourceContextBuilder}
+ */
+class ResourceContextBuilder {
+    /**
+     * Build a ResourceContext from MainBaseConfig
+     * @param config - The main base config
+     * @param region - Optional deployment region
+     * @returns ResourceContext object
+     */
+    static build(config, region) {
+        return {
+            'service.name': config.pluginName,
+            'service.version': config.pluginVersion,
+            'service.instance.id': config.appId,
+            'deployment.environment': config.mode,
+            ...(region && { 'deployment.region': region })
+        };
+    }
+}
+exports.ResourceContextBuilder = ResourceContextBuilder;
+//# sourceMappingURL=ResourceContext.js.map

package/lib/base/ResourceContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResourceContext.js","sourceRoot":"","sources":["../../src/base/ResourceContext.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAiCH;;;;;GAKG;AACH,MAAa,sBAAsB;IACjC;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,MAAsB,EAAE,MAAe;QAClD,OAAO;YACL,cAAc,EAAE,MAAM,CAAC,UAAU;YACjC,iBAAiB,EAAE,MAAM,CAAC,aAAa;YACvC,qBAAqB,EAAE,MAAM,CAAC,KAAK;YACnC,wBAAwB,EAAE,MAAM,CAAC,IAAI;YACrC,GAAG,CAAC,MAAM,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,CAAC;SAC/C,CAAC;IACJ,CAAC;CACF;AAhBD,wDAgBC"}

package/lib/base/base.d.ts

@@ -0,0 +1,264 @@
+/**
+ * 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 { DEBUG_MODE, IPluginObservable, Observable } from "../interfaces";
+import { SBObservable } from "../serviceBase";
+import { BSBReferenceConfigType } from "./PluginConfig";
+/**
+ * Main base config
+ * @property appId - The unique app id of the app that is running
+ * @property mode - The mode the app is running in
+ * @property pluginName - The name of the plugin
+ * @property cwd - The current working directory of the app
+ * @property packageCwd - The directory of the package that contains the plugin
+ * @property pluginCwd - The directory of the plugin (src/plugins/{pluginName} or lib/plugins/{pluginName})
+ * @property region - The deployment region for resource context
+ */
+export interface MainBaseConfig {
+    appId: string;
+    mode: DEBUG_MODE;
+    pluginName: string;
+    cwd: string;
+    packageCwd: string;
+    pluginCwd: string;
+    pluginVersion: string;
+    region?: string;
+}
+/**
+ * @hidden
+ */
+export declare abstract class MainBase {
+    /**
+     * The unique app id of the app that is running
+     * @readonly
+     * @type {string}
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/MainBase.html#appId | API: MainBase.appId}
+     */
+    readonly appId: string;
+    /**
+     * The mode the app is running in
+     * @readonly
+     * @type {DEBUG_MODE}
+     * @example production (production mode - no debug)
+     * @example production-debug (production mode - debug)
+     * @example development (development mode - debug)
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/MainBase.html#mode | API: MainBase.mode}
+     */
+    readonly mode: DEBUG_MODE;
+    /**
+     * The current working directory of the app
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/MainBase.html#cwd | API: MainBase.cwd}
+     */
+    readonly cwd: string;
+    /**
+     * The current working directory of the plugin
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/MainBase.html#packageCwd | API: MainBase.packageCwd}
+     */
+    readonly packageCwd: string;
+    /**
+     * The current working directory of the service
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/MainBase.html#pluginCwd | API: MainBase.pluginCwd}
+     */
+    readonly pluginCwd: string;
+    /**
+     * The name of the plugin
+     * This is also the mapped name, or the name defined in the config rather than it's original defined name
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/MainBase.html#pluginName | API: MainBase.pluginName}
+     */
+    readonly pluginName: string;
+    /**
+     * The deployment region for resource context
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/MainBase.html#region | API: MainBase.region}
+     */
+    readonly region?: string;
+    constructor(config: MainBaseConfig);
+    /**
+     * Dispose
+     * Optional function to be called when the plugin is being disposed
+     *
+     * @example dispose?(): void; //to not use it
+     * @example dispose() { your code here };
+     */
+    dispose?(): void;
+}
+/**
+ * @hidden
+ */
+export declare abstract class Base extends MainBase {
+    /**
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Base.html | API: Base}
+     */
+    constructor(config: MainBaseConfig);
+    /**
+     * Dispose
+     * Optional function to be called when the plugin is being disposed
+     *
+     * @example dispose?(): void; //to not use it
+     * @example dispose() { your code here };
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Base.html#dispose | API: Base.dispose}
+     */
+    abstract dispose?(): void;
+    /**
+     * Init
+     * Optional function to be called when the plugin is being initialized
+     * Can be sync or async
+     *
+     * @remarks
+     * **v9 BREAKING CHANGE**: Now requires Observable instead of DTrace.
+     * Observable provides unified access to logging, metrics, and tracing with automatic context propagation.
+     *
+     * @param obs - Observable context with logging, metrics, and trace information
+     *
+     * @example
+     * ```typescript
+     * async init(obs: Observable) {
+     *   obs.log.info("Initializing plugin");
+     *   // Set attributes for all child operations
+     *   const withVersion = obs.setAttribute("plugin.version", "1.0.0");
+     * }
+     * ```
+     *
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Base.html#init | API: Base.init}
+     */
+    abstract init?(obs: Observable): Promise<void> | void;
+    /**
+     * Run
+     * Optional function to be called when the plugin is being run
+     * Can be sync or async
+     *
+     * @remarks
+     * **v9 BREAKING CHANGE**: Now requires Observable instead of DTrace.
+     * Observable provides unified access to logging, metrics, and tracing with automatic context propagation.
+     *
+     * @param obs - Observable context with logging, metrics, and trace information
+     *
+     * @example
+     * ```typescript
+     * async run(obs: Observable) {
+     *   obs.log.info("Running plugin");
+     *   // Create child span for work
+     *   const workObs = obs.startSpan("do-work");
+     *   // ... do work ...
+     *   workObs.end();
+     * }
+     * ```
+     *
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/Base.html#run | API: Base.run}
+     */
+    abstract run?(obs: Observable): Promise<void> | void;
+}
+/**
+ * @hidden
+ */
+export type ConfigPropertyTypeSafe<ReferencedConfig extends BSBReferenceConfigType> = [ReferencedConfig] extends [never] ? never : ReferencedConfig extends undefined | null ? never : ReferencedConfig;
+/**
+ * @hidden
+ */
+export type ConfigConstructorTypeSafe<ReferencedConfig extends BSBReferenceConfigType> = [ReferencedConfig] extends [never] ? undefined : ReferencedConfig extends undefined | null ? undefined : ReferencedConfig;
+/**
+ * @hidden
+ */
+export interface BaseWithConfigConfig<ReferencedConfig extends BSBReferenceConfigType> extends MainBaseConfig {
+    config: ConfigConstructorTypeSafe<ReferencedConfig>;
+}
+/**
+ * @hidden
+ * used by logging plugins (does not need events or logging since logging logs its own logs)
+ */
+export declare abstract class BaseWithConfig<ReferencedConfig extends BSBReferenceConfigType> extends Base {
+    /**
+     * The config of the plugin
+     * @type {PluginConfig}
+     * @readonly
+     */
+    readonly config: ConfigPropertyTypeSafe<ReferencedConfig>;
+    constructor(config: BaseWithConfigConfig<ReferencedConfig>);
+}
+/**
+ * BaseWithObservableConfig
+ * @property sbObservable - Passed in observable base - can be used to create new plugin observable backend
+ */
+export interface BaseWithObservableConfig extends MainBaseConfig {
+    sbObservable: SBObservable;
+}
+/**
+ * @hidden
+ * Base class with internal observable support for Observable creation.
+ *
+ * **v9 Architecture:**
+ * - Logging and metrics accessed via Observable: `obs.log.info("message")`, `obs.metrics.counter(...)`
+ * - Use `this.createObservable()` to create new root traces
+ * - Pass Observable through all methods for trace context
+ *
+ * @see {@link Observable} for the unified observable interface
+ * @see {@link BSBService.createObservable} for creating Observables
+ */
+export declare abstract class BaseWithObservable extends Base {
+    /**
+     * @hidden
+     * Internal ObservableBackend instance for creating Observables.
+     * NOT accessible to plugin code - use Observable instead.
+     */
+    private _observable;
+    constructor(config: BaseWithObservableConfig);
+    /**
+     * @hidden
+     * Get internal observable backend for Observable creation.
+     * NOT for direct plugin use.
+     */
+    protected get __internalObservable(): IPluginObservable;
+}
+/**
+ * @hidden
+ */
+export interface BaseWithObservableAndConfigConfig<ReferencedConfig extends BSBReferenceConfigType> extends BaseWithObservableConfig, BaseWithConfigConfig<ReferencedConfig> {
+}
+/**
+ * @hidden
+ * Base class with config and internal observable support.
+ * Use Observable for all logging and metrics operations.
+ */
+export declare abstract class BaseWithObservableAndConfig<ReferencedConfig extends BSBReferenceConfigType> extends BaseWithConfig<ReferencedConfig> {
+    /**
+     * @hidden
+     * Internal ObservableBackend instance for creating Observables.
+     */
+    private _observable;
+    constructor(config: BaseWithObservableAndConfigConfig<ReferencedConfig>);
+    /**
+     * @hidden
+     * Get internal observable backend for Observable creation.
+     */
+    protected get __internalObservable(): IPluginObservable;
+}
+/**
+ * @hidden
+ */
+export declare const NS_PER_SEC = 1000000000;
+/**
+ * @hidden
+ */
+export declare const MS_PER_NS = 0.000001;